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.
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.
- Archives a contract already created and residing on the ledger. The contract is fetched by its unique contract identifier
ContractId <name of template>and then exercises the Archive choice on it.
- Returns unit.
- Requires authorization from the contract controllers/signatories. Without the required authorization, the transaction fails. For more detail on authorization, see Signatory Parties.
- All templates implicitly have an Archive choice that cannot be removed, which is equivalent to:
choice Archive : ()
controller (signatory this)
do return ()
create NameOfTemplate with exampleParameters
Creates a 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.
exerciseByKey @ContractType contractKey NameOfChoiceOnContract with choiceArgument1 = value1
fetchedContract <- fetch IdOfContract
- Fetches the contract 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.
- The submitting party must be an observer or signatory on the contract, otherwise
fetchfails, and similarly causes the entire transaction to abort.
fetchedContract <- fetchByKey @ContractType contractKey
isVisible <- visibleByKey @ContractType contractKey
fetchedContractId <- lookupByKey @ContractType contractKey
- 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 script 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:
choice Transfer : ContractId RestrictedPayout
with newReceiver : Party
assert (newReceiver /= blacklisted)
create RestrictedPayout with receiver = newReceiver; giver; blacklisted; qty
currentTime <- getTime
- Gets the ledger 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:
choice Complete : ()
-- bind the ledger effective time to the tchoose variable using getTime
tchoose <- getTime
-- assert that tchoose is no earlier than the begin time
assert (begin <= tchoose && tchoose < addRelTime begin period)
- 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:
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:
-- 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
this lets you refer to the current contract from within the choice body. This refers to the contract, not the contract ID.
It’s useful, for example, if you want to pass the current contract to a helper function outside the template.