This page gives reference information on Updates:
For the structure around them, see Overview: template structure.
Updateis ledger update. There are many different kinds of these, and they’re listed below.
- They are what can go in a choice body.
boundVariable <- UpdateExpression1
- One of the things you can do in a choice body is bind (assign) an Update expression to a variable. This works for any of the Updates below.
do updateExpression1 updateExpression2
docan be used to group
Updateexpressions. You can only have one update expression in a choice, so any choice beyond the very simple will use a
Anything you can put into a choice body, you can put into a
doreturns whatever is returned by the last expression in the block.
So if you want to return something else, you’ll need to use
returnexplicitly - see return for an example.
create NameOfTemplate with exampleParty; exampleParty2; exampleParty3
Creates an instance of that contract on the ledger. When a contract is committed to the ledger, it is given a unique contract identifier of type
ContractId <name of template>.
Creating the contract returns that
withto specify the template parameters.
Requires authorization from the signatories of the contract being created. This is given by being signatories of the contract from which the other contract is created, being the controller, or explicitly creating the contract itself.
If the required authorization is not given, the transaction fails. For more detail on authorization, see Signatory parties.
exercise IdOfContract NameOfChoiceOnContract with choiceArgument1 = value1
- Exercises the specified choice on the specified contract.
withto specify the choice parameters.
- Requires authorization from the controller(s) of the choice. If the authorization is not given, the transaction fails.
fetchedContract <- fetch IdOfContract
- Fetches the contract instance with that ID. Usually used with a bound variable, as in the example above.
- Often used to check the details of a contract before exercising a choice on that contract. Also used when referring to some reference data.
fetch cidfails if
cidis not the contract id of an active contract, and thus causes the entire transaction to abort.
- Fails the transaction - nothing in it will be committed to the ledger.
errorMessageis of type
Text. Use the error message to provide more context to an external system (e.g., it gets displayed in DAML Studio scenario results).
- You could use
assert Falseas an alternative.
assert (condition == True)
- Fails the transaction if the condition is false. So the choice can only be exercised if the boolean expression evaluates to
- Often used to restrict the arguments that can be supplied to a contract choice.
Here’s an example of using
assert to prevent a choice being exercised if the
Party passed as a parameter is on a blacklist:
Transfer : ContractId RestrictedPayout with newReceiver : Party do assert (newReceiver /= blacklisted) create RestrictedPayout with receiver = newReceiver; giver; blacklisted; qty
currentTime <- getTime
- Gets the ledger effective time. (You will usually want to immediately bind it to a variable in order to be able to access the value.)
- Used to restrict when a choice can be made. For example, with an
assertthat the time is later than a certain time.
Here’s an example of a choice that uses a check on the current time:
Complete : () do -- bind the ledger effective time to the tchoose variable using getTime tchoose <- getTime
- Used to return a value from
doblock that is not of type
Here’s an example where two contracts are created in a choice and both their ids are returned as a tuple:
do firstContract <- create SomeContractTemplate with arg1; arg2 secondContract <- create SomeContractTemplate with arg1; arg2 return (firstContract, secondContract)
See the documentation on Let.
Let looks similar to binding variables, but it’s very different! This code example shows how:
do -- defines a function, createdContract, taking a single argument that when -- called _will_ create the new contract using argument for issuer and owner let createContract x = create NameOfContract with issuer = x; owner = x createContract party1 createContract party2