Daml Language Reference

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview: Template Structure

​

Template Outline Structure

template NameOfTemplate
  with
    exampleParty : Party
    exampleParty2 : Party
    exampleParty3 : Party
    exampleParameter : Text
    -- more parameters here
  where
    signatory exampleParty
    observer exampleParty2
    ensure
      -- boolean condition
      True
    key (exampleParty, exampleParameter) : (Party, Text)
    maintainer (exampleFunction key)
    -- a choice goes here; see next section

​

Choice Structure

choice NameOfChoice
  : () -- replace () with the actual return type
  with
    party : Party -- parameters here
  controller party
  do
    return () -- replace this line with the choice body

​

Choice Body Structure

​

Reference: Templates

​

Template Name

template NameOfTemplate

• This is the name of the template. It’s preceded by template keyword. Must begin with a capital letter.
• This is the highest level of nesting.
• The name is used when creating a contract of this template (usually, from within a choice).

​

Template Parameters

with
  exampleParty : Party
  exampleParty2 : Party
  exampleParty3 : Party
  exampleParam : Text
  -- more parameters here

• with keyword. The parameters are in the form of a record type.
• Passed in when creating a contract from this template. These are then in scope inside the template body.
• A template parameter can’t have the same name as any choice arguments inside the template.
• For all parties involved in the contract (whether they’re a signatory, observer, or controller) you must pass them in as parameters to the contract, whether individually or as a list ([Party]).

​

Implicit Record

​

this and self

​

Template-local Definitions (Deprecated)

• let keyword. Starts a block and is followed by any number of definitions, just like any other let block.
• Template parameters as well as this are in scope, but self is not.
• Definitions from the let block can be used anywhere else in the template’s where block.

Template-local binding syntax ("template-let") is deprecated,
it will be removed in a future version of Daml.
Instead, use plain top level definitions, taking parameters
for the contract fields or body ("this") if necessary.

​

Migration

template Person
  with
    owner : Party
    first : Text
    last : Text
  where
    signatory owner
    let fullName = last <> ", " <> first
    nonconsuming choice GetDescription : ()
      controller owner
      do
        let desc = "An account owned by " <> fullName <> "."
        debug desc

fullName : Person -> Text
fullName Person {first, last} = last <> ", " <> first
-- takes 'Person' as an explicit parameter and unpacks required fields

template Person
  with
    owner : Party
    first : Text
    last : Text
  where
    signatory owner
    nonconsuming choice GetDescriptionV3 : ()
      controller owner
      do
        -- let bindings in choice bodies are unaffected
        let desc = "An account owned by " <> fullName this <> "."
                                             -- 'this' is passed explicitly
        debug desc

​

Turning off the warning

{-# OPTIONS_GHC -Wno-template-let #-}

build-options:
- --ghc-option=-Wno-template-let

{-# OPTIONS_GHC -Wtemplate-let #-}

​

Signatory Parties

signatory exampleParty

• signatory keyword. After where. Followed by at least one Party.
• Signatories are the parties (see the Party type) who must consent to the creation of this contract. They are the parties who would be put into an obligable position when this contract is created. Daml won’t let you put someone into an obligable position without their consent. So if the contract will cause obligations for a party, they must be a signatory. If they haven’t authorized it, you won’t be able to create the contract. In this situation, you may see errors like: NameOfTemplate requires authorizers Party1,Party2,Party, but only Party1 were given.
• When a signatory consents to the contract creation, this means they also authorize the consequences of choices that can be exercised on this contract.
• The contract is visible to all signatories (as well as the other stakeholders of the contract). That is, the compiler automatically adds signatories as observers.
• Each template must have at least one signatory. A signatory declaration consists of the signatory keyword followed by a comma-separated list of one or more expressions, each expression denoting a Party or collection thereof.

​

Observers

observer exampleParty2

• observer keyword. After where. Followed by at least one Party.
• Observers are additional stakeholders, so the contract is visible to these parties (see the Party type).
• Optional. You can have many, either as a comma-separated list or reusing the keyword. You could pass in a list (of type [Party]).
• Use when a party needs visibility on a contract, or be informed or contract events, but is not a signatory or controller.
• If you start your choice with choice rather than controller (see daml-ref-choices below), you must make sure to add any potential controller as an observer. Otherwise, they will not be able to exercise the choice, because they won’t be able to see the contract.

​

Choices

choice NameOfChoice
  : ()  -- replace () with the actual return type
  with
    exampleParameter : Text -- parameters here
  controller exampleParty
  do
    return () -- replace this line with the choice body

• A right that the contract gives the controlling party. Can be exercised.
• This is essentially where all the logic of the template goes.
• By default, choices are consuming: that is, exercising the choice archives the contract, so no further choices can be exercised on it. You can make a choice non-consuming using the nonconsuming keyword.
• See choices for full reference information.

​

Serializable Types

1. Offer a stable means to store ledger values permanently.
2. Provide a sensible encoding of them over the ledger-api.
3. Provide sensible types that directly match their Daml counterparts in languages like Java for language codegen.

• Function types.
• Record types with any non-serializable field.
• Variant types with any non-serializable value case.
• Variant and enum types with no constructors.
• References to a parameterized data type with any non-serializable type argument. This applies whether or not the data type definition uses the type parameter.
• Defined data types with any type parameter of kind Nat, or any kind other than *. This means higher-kinded types, and types that take a parameter just to pass to Numeric, are not serializable.

​

Migration

​

Preconditions

ensure
  True -- a boolean condition goes here

• ensure keyword, followed by a boolean condition.
• Used on contract creation. ensure limits the values on parameters that can be passed to the contract: the contract can only be created if the boolean condition is true.

​

Contract Keys and Maintainers

key (exampleParty, exampleParam) : (Party, Text)
maintainer (exampleFunction key)

• key and maintainer keywords.
• This feature lets you specify a “key” that you can use to uniquely identify this contract as an instance of this template.
• If you specify a key, you must also specify a maintainer. This is a Party that will ensure the uniqueness of all the keys it is aware of. Because of this, the key must include the maintainer Party or parties (for example, as part of a tuple or record), and the maintainer must be a signatory.
• For a full explanation, see contractkeys.

​

Interface Instances

interface instance MyInterface for NameOfTemplate where
  view = MyInterfaceViewType "NameOfTemplate" 100
  method1 = field1
  method2 = field2
  method3 False _ _ = 0
  method3 True x y
    | x > 0 = x + y
    | otherwise = y

• Used to make a template an instance of an existing interface.
• The clause must start with the keywords interface instance, followed by the name of the interface, then the keyword for and the name of the template (which must match the enclosing declaration), and finally the keyword where, which introduces a block where all the methods of the interface must be implemented.
• See interfaces for full reference information on interfaces, or section interface-instances for interface instances specifically.

​

Reference: Choices

​

Choice Name

choice ExampleChoice
  : () -- replace () with the actual return type

• choice keyword
• The name of the choice. Must begin with a capital letter.
• Must be unique in the module. Different templates defined in the same module cannot share a choice name.

​

Controllers

controller exampleParty

• controller keyword
• The controller is a comma-separated list of values, where each value is either a party or a collection of parties. The conjunction of all the parties are required to authorize when this choice is exercised.

​

Choice Observers

choice NameOfChoiceWithObserver
  : () -- replace () with the actual return type
  with
    party : Party -- parameters here
  observer party -- optional specification of choice observers
  controller exampleParty
  do
    return () -- replace this line with the choice body

​

Contract Consumption

​

Preconsuming Choices

preconsuming choice ExamplePreconsumingChoice
  : () -- replace () with the actual return type

• preconsuming keyword. Optional.
• Makes a choice pre-consuming: the contract is archived before the body of the exercise is executed.
• The create arguments of the contract can still be used in the body of the exercise, but cannot be fetched by its contract id.
• The archival behavior is analogous to the consuming default behavior.
• Only the controllers and signatories of the contract see all consequences of the action. Other stakeholders merely see an archive action.
• Can be thought as a non-consuming choice that implicitly archives the contract before anything else happens

​

Postconsuming Choices

postconsuming choice ExamplePostconsumingChoice
  : () -- replace () with the actual return type

• postconsuming keyword. Optional.
• Makes a choice post-consuming: the contract is archived after the body of the exercise is executed.
• The create arguments of the contract can still be used in the body of the exercise as well as the contract id for fetching it.
• Only the controllers and signatories of the contract see all consequences of the action. Other stakeholders merely see an archive action.
• Can be thought as a non-consuming choice that implicitly archives the contract after the choice has been exercised

​

Non-consuming Choices

nonconsuming choice ExampleNonconsumingChoice
  : () -- replace () with the actual return type

• nonconsuming keyword. Optional.
• Makes a choice non-consuming: that is, exercising the choice does not archive the contract.
• Only the controllers and signatories of the contract see all consequences of the action.
• Useful in the many situations when you want to be able to exercise a choice more than once.

​

Return Type

• Return type is written immediately after choice name.
• All choices have a return type. A contract returning nothing should be marked as returning a “unit”, ie ().
• If a contract is/contracts are created in the choice body, usually you would return the contract ID(s) (which have the type ContractId <name of template>). This is returned when the choice is exercised, and can be used in a variety of ways.

​

Choice Arguments

with
  exampleParameter : Text

• with keyword.
• Choice arguments are similar in structure to daml-ref-template-parameters: a record type.
• A choice argument can’t have the same name as any parameter to the template the choice is in.
• Optional - only if you need extra information passed in to exercise the choice.

​

Choice Body

• Introduced with do
• The logic in this section is what is executed when the choice gets exercised.
• The choice body contains Update expressions. For detail on this, see updates.
• By default, the last expression in the choice is returned. You can return multiple updates in tuple form or in a custom data type. To return something that isn’t of type Update, use the return keyword.

​

Reference: Updates

​

Background

• An Update is ledger update. There are many different kinds of these, and they’re listed below.
• They are what can go in a choice body.

​

Binding Variables

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

do
   updateExpression1
   updateExpression2

• do can be used to group Update expressions. You can only have one update expression in a choice, so any choice beyond the very simple will use a do block.
• Anything you can put into a choice body, you can put into a do block.
• By default, do returns whatever is returned by the last expression in the block. So if you want to return something else, you’ll need to use return explicitly - see daml-ref-return for an example.

​

archive

archive ContractId

• archive function.
• 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 daml-ref-signatories.
• All templates implicitly have an Archive choice that cannot be removed, which is equivalent to:

choice Archive : ()
  controller (signatory this)
  do return ()

​

create

create NameOfTemplate with exampleParameters

• create function.
• 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 ContractId.
• Use with to 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 daml-ref-signatories.

​

exercise

exercise IdOfContract NameOfChoiceOnContract with choiceArgument1 = value1

• exercise function.
• Exercises the specified choice on the specified contract.
• Use with to specify the choice parameters.
• Requires authorization from the controller(s) of the choice. If the authorization is not given, the transaction fails.

​

exerciseByKey

exerciseByKey @ContractType contractKey NameOfChoiceOnContract with choiceArgument1 = value1

• exerciseByKey function.
• Like exercise, but the contract is specified by contract key, instead of contract ID.
• For details see Reference: Contract Keys: exerciseByKey

​

fetch

fetchedContract <- fetch IdOfContract

• fetch function.
• 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 cid fails if cid is 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 fetch fails, and similarly causes the entire transaction to abort.

​

fetchByKey

fetchedContract <- fetchByKey @ContractType contractKey

• fetchByKey function.
• Like fetch, but fetches the contract with that contract key, instead of the contract ID.
• For details see Reference: Contract Keys: fetchByKey.

​

visibleByKey

isVisible <- visibleByKey @ContractType contractKey

• visibleByKey function.
• Use this to check whether a contract with the given contract key exists.
• For details see Reference: Contract Keys: visibleByKey

​

lookupByKey

fetchedContractId <- lookupByKey @ContractType contractKey

• lookupByKey function.
• Use this to confirm that a contract with the given contract key exists.
• For details see Reference: Contract Keys: lookupByKey

​

abort

abort errorMessage

• abort function.
• Fails the transaction - nothing in it will be committed to the ledger.
• errorMessage is 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 False as an alternative.

​

assert

assert (condition == True)

• assert keyword.
• Fails the transaction if the condition is false. So the choice can only be exercised if the boolean expression evaluates to True.
• Often used to restrict the arguments that can be supplied to a contract choice.

choice Transfer : ContractId RestrictedPayout
  with newReceiver : Party
  controller receiver
  do
    assert (newReceiver /= blacklisted)
    create RestrictedPayout with receiver = newReceiver; giver; blacklisted; qty

​

getTime

currentTime <- getTime

• getTime keyword.
• 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 assert that the time is later than a certain time.

choice Complete : ()
  controller party
  do
    -- 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)

​

return

return ()

• return keyword.
• Used to return a value from do block that is not of type Update.

do
  firstContract <- create SomeContractTemplate with arg1; arg2
  secondContract <- create SomeContractTemplate with arg1; arg2
  return (firstContract, secondContract)

​

let

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

​

this

​

Reference: Data Types

​

Built-in Types

​

Table of built-in primitive types

​

Escaping Characters

​

Time

​

Lists

twoEquivalentListConstructions =
  script do
    assert ( [1, 2, 3] == 1 :: 2 :: 3 :: [] )

​

Sum a List

​

Records and Record Types

data MyRecord = MyRecord
  with
    label1 : type1
    label2 : type2
    ...
    labelN : typeN
  deriving (Eq, Show)

• label1, label2, …, labelN are labels, which must be unique in the record type
• type1, type2, …, typeN are the types of the fields

data MyRecord = MyRecord { label1 : type1; label2 : type2; ...; labelN : typeN }
  deriving (Eq, Show)

-- This is a record type with two fields, called first and second,
-- both of type `Int`
data MyRecord = MyRecord with first : Int; second : Int
  deriving (Eq, Show)

-- An example value of this type is:
newRecord = MyRecord with first = 1; second = 2

-- You can also write:
newRecord = MyRecord 1 2

​

Data Constructors

​

Access Record Fields

-- Access the value of the field `first`
val.first

-- Access the value of the field `second`
val.second

​

Update Record Fields

myRecord = MyRecord with first = 1; second = 2

myRecord2 = myRecord with second = 5

-- if you have a variable called `second` equal to 5
second = 5

-- you could construct the same value as before with
myRecord2 = myRecord with second = second

-- or with
myRecord3 = MyRecord with first = 1; second = second

-- but Daml has a nicer way of putting this:
myRecord4 = MyRecord with first = 1; second

-- or even
myRecord5 = r with second

​

Parameterized Data Types

-- Here, a and b are type parameters.
-- The Coordinate after the data keyword is a type constructor.
data Coordinate a b = Coordinate with first : a; second : b

​

Type Synonyms

type IntegerTuple = (Int, Int)

​

Function Types

​

Algebraic Data Types

​

Product Types

​

Sum Types

​

Pattern Matching

import Daml.Script
import DA.Assert

optionalIntegerToText (x : Optional Int) : Text =
  case x of
    None -> "Box is empty"
    Some val -> "The content of the box is " <> show val

optionalIntegerToTextTest =
  script do

tmp =
  let
    l = [1, 2, 3]
  in case l of

​

Reference: Expressions

​

Definitions

​

Values

-- Copyright (c) 2025 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
-- SPDX-License-Identifier: Apache-2.0

-- The TubeSurfaceArea example.

module TubeSurfaceArea where


pi = 3.1415926535

tubeSurfaceArea2 (r : Decimal) (h : Decimal) : Decimal =
  2.0 * pi * r * h

tubeSurfaceArea : Decimal -> Decimal -> Decimal 
tubeSurfaceArea r h  =
  2.0 * pi * r * h

tubeSurfaceArea3 = \ (r : Decimal) (h : Decimal) -> 2.0 * pi * r * h

-- Copyright (c) 2025 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
-- SPDX-License-Identifier: Apache-2.0

-- The TubeSurfaceArea example.

module TubeSurfaceArea2 where

-- Type synonym for Decimal -> Decimal -> Decimal
type BinaryDecimalFunction = Decimal -> Decimal -> Decimal

pi : Decimal = 3.1415926535

tubeSurfaceArea : BinaryDecimalFunction =
  \ (r : Decimal) (h : Decimal) -> 2.0 * pi * r * h

​

Functions

tubeSurfaceArea : Decimal -> Decimal -> Decimal 
tubeSurfaceArea r h  =
  2.0 * pi * r * h

• the name of the function
• the function’s type signature Decimal -> Decimal -> Decimal This means it takes two Decimals and returns another Decimal.
• the definition = 2.0 * pi * r * h (which uses the previously defined pi)

​

Arithmetic Operators

• 7 / 3 and (-7) / (-3) evaluate to 2
• (-7) / 3 and 7 / (-3) evaluate to -2
• 7 % 3 and 7 % (-3) evaluate to 1
• (-7) % 3 and (-7) % (-3) evaluate to -1

​

Comparison Operators

​

Logical Operators

• not for negation, e.g., not True == False
• && for conjunction, where a && b == and a b
• || for disjunction, where a || b == or a b

​

If-then-else

if owner == scroogeMcDuck then "sell" else "buy"

​

Let

doubled =
  -- let binds values or functions to be in scope beneath the expression
  let
    double (x : Int) = 2 * x
    up = 5
  in double up

blah = script
  do
    let
      x = 1
      y = 2
      -- x and y are in scope for all subsequent expressions of the do block,
      -- so can be used in expression1 and expression2.
    expression1
    expression2

​

Reference: Functions

​

Defining Functions

tubeSurfaceArea : Decimal -> Decimal -> Decimal 
tubeSurfaceArea r h  =
  2.0 * pi * r * h

tubeSurfaceArea : BinaryDecimalFunction =
  \ (r : Decimal) (h : Decimal) -> 2.0 * pi * r * h

​

Partial Application

multiplyThreeNumbers : Int -> Int -> Int -> Int
multiplyThreeNumbers xx yy zz =
  xx * yy * zz

multiplyTwoNumbersWith7 = multiplyThreeNumbers 7

multiplyWith21 = multiplyTwoNumbersWith7 3

multiplyWith18 = multiplyThreeNumbers 3 6

multiplyWith18_v2 : Int -> Int
multiplyWith18_v2 xx =
  multiplyThreeNumbers 3 6 xx

​

Functions are Values

-- Type synonym for Decimal -> Decimal -> Decimal
type BinaryDecimalFunction = Decimal -> Decimal -> Decimal

pi : Decimal = 3.1415926535

tubeSurfaceArea : BinaryDecimalFunction =
  \ (r : Decimal) (h : Decimal) -> 2.0 * pi * r * h

applyFilter (filter : Int -> Int -> Bool)
    (x : Int)
    (y : Int) = filter x y

compute = script do
    applyFilter (<) 3 2 === False
    applyFilter (/=) 3 2 === True

    round (2.5 : Decimal) === 3
    round (3.5 : Decimal) === 4

    explode "me" === ["m", "e"]

    applyFilter (\a b -> a /= b) 3 2 === True

​

Generic Functions

compose (f : b -> c) (g : a -> b) (x : a) : c = f (g x)

​

Reference: Daml File Structure

​

File Structure

• This file’s module name (module NameOfThisFile where). Part of a hierarchical module system to facilitate code reuse. Must be the same as the Daml file name, without the file extension. For a file with path ./Scenarios/Demo.daml, use module Scenarios.Demo where.

​

Imports

• You can import other modules (import OtherModuleName), including qualified imports (import qualified AndYetOtherModuleName, import qualified AndYetOtherModuleName as Signifier). Can’t have circular import references.
• To import the Prelude module of ./Prelude.daml, use import Prelude.
• To import a module of ./Scenarios/Demo.daml, use import Scenarios.Demo.
• If you leave out qualified, and a module alias is specified, top-level declarations of the imported module are imported into the module’s namespace as well as the namespace specified by the given alias.

​

Libraries

​

Comments

​

Contract Identifiers

​

Reference: Daml Packages

​

Building Daml Archives

dpm build -o foo.dar

The rest of this page will focus on how to import a Daml package in other Daml projects.

​

Inspecting DARs

​

Import Daml Packages

• dependencies allow you to import a Daml archive as a library. The definitions in the dependency will all be made available to the importing project. However, the dependency must be compiled with the same SDK version, so this method is only suitable for breaking up large projects into smaller projects that depend on each other, or to reuse existing libraries.
• data-dependencies allow you to import a Daml archive (.dar) or a Daml-LF package (.dalf), including packages that have already been deployed to a ledger. These packages can be compiled with any previous SDK version. On the other hand, not all definitions can be carried over perfectly, since the Daml interface needs to be reconstructed from the binary.

​

Import a Daml package via Dependencies

dependencies:
  - daml-prim
  - daml-stdlib
  - ../foo/foo.dar

- /home/user/foo/foo.dar

import Foo

exposed-modules:
- Foo

​

Import a Daml Archive via data-dependencies

dependencies:
- daml-prim
- daml-stdlib
data-dependencies:
- ../foo/foo.dar

1. Export lists cannot be recovered, so imports via data-dependencies can access definitions that were originally hidden. This means it is up to the importing module to respect the data abstraction of the original module. Note that this is the same for all code that runs on the ledger, since the ledger does not provide special support for data abstraction.
2. If you have a dependency that limits the modules that can be accessed via exposed-modules, you can get an error if you also have a data-dependency that references something from the hidden modules (even if it is only reexported). Since exposed-modules are not available on the ledger in general, we recommend to not make use of them and instead rely on naming conventions (e.g., suffix module names with .Internal) to make it clear which modules are part of the public API.
3. Prior to Daml-LF version 1.8, typeclasses could not be reconstructed. This means if you have a package that is compiled with an older version of Daml-LF, typeclasses and typeclass instances will not be carried over via data-dependencies, and you won’t be able to call functions that rely on typeclass instances. This includes the template functions, such as create, signatory, and exercise, as these rely on typeclass instances.
4. Starting from Daml-LF version 1.8, when possible, typeclass instances will be reconstructed by re-using the typeclass definitions from dependencies, such as the typeclasses exported in daml-stdlib. However, if the typeclass signature has changed, you will get an instance for a reconstructed typeclass instead, which will not interoperate with code from dependencies.

​

Transitive dependency management

• Have identical contents if they have the same name and version specified in their Daml project’s daml.yaml file, or
• Have a different value for the version entry in their respective daml.yaml files.

• Daml project X (top-level) has dependencies DarA and DarB.
• DarA and DarB both contain DAR dependency DarC

​

Reference Daml Packages Already On the Ledger

ledger:
  host: localhost
  port: 6865
dependencies:
- daml-prim
- daml-stdlib
data-dependencies:
- foo:1.0.0

dependencies:
- pkgId: 51255efad65a1751bcee749d962a135a65d12b87eb81ac961142196d8bbca535
  name: foo
  version: 1.0.0

​

Handling Module Name Collisions

import "foo" X

import "bar" X

import "foo" X as FooX
import "bar" X as BarX

build-options:
- '--package'
- 'foo-1.0.0 with (X as Foo1.X)'
- '--package'
- 'foo-2.0.0 with (X as Foo2.X)'

import qualified Foo1.X
import qualified Foo2.X

module-prefixes:
  foo-1.0.0: Foo1
  foo-2.0.0: Foo2

​

Reference: Contract Keys

​

Unsupported feature

type AccountKey = (Party, Text)

template Account with
    bank : Party
    number : Text
    owner : Party
    balance : Decimal
    observers : [Party]
  where
    signatory [bank, owner]
    observer observers

    key (bank, number) : AccountKey
    maintainer key._1

​

What Can Be a Contract Key

​

Specify Maintainers

​

Contract Lookups

​

fetchByKey

• The submitting Party is not a stakeholder on a contract with the given key, or
• A contract was found, but the fetchByKey violates the authorization rule, meaning no stakeholder authorized the fetch.

​

visibleByKey

1. visibleByKey will return True if all of these are true: there exists a contract for the given key, the submitter is a stakeholder on that contract, and at the point of call we have the authorization of all of the maintainers of the key.
2. visibleByKey will return False if all of those are true: there is no contract for the given key, and at the point of call we have authorization from all the maintainers of the key.
3. visibleByKey will abort the transaction at interpretation time if, at the point of call, we are missing the authorization from any one maintainer of the key.
4. visibleByKey will fail at validation time (after returning False at interpretation time) if all of these are true: at the point of call, we have the authorization of all the maintainers, and a valid contract exists for the given key, but the submitter is not a stakeholder on that contract.

​

lookupByKey

lookupByKey : forall c k. (HasFetchByKey c k) => k -> Update (Optional (ContractId c))
lookupByKey k = do
  visible <- visibleByKey @c k
  if visible then do
    (contractId, _ignoredContract) <- fetchByKey @c k
    return $ Some contractId
  else
    return None

​

exerciseByKey

​

Example

-- Copyright (c) 2025 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
-- SPDX-License-Identifier: Apache-2.0

module Keys where

import Daml.Script
import DA.Assert
import DA.Optional

template Keyed
  with
    sig : Party
    obs : Party
  where
    signatory sig
    observer obs

    key sig : Party
    maintainer key

template Divulger
  with
    divulgee : Party
    sig : Party
  where
    signatory divulgee
    observer sig

    nonconsuming choice DivulgeKeyed
      : Keyed
      with
        keyedCid : ContractId Keyed
      controller sig
      do
        fetch keyedCid

template Delegation
  with
    sig : Party
    delegees : [Party]
  where
    signatory sig
    observer delegees

    nonconsuming choice CreateKeyed
      : ContractId Keyed
      with
        delegee : Party
        obs : Party
      controller delegee
      do
        create Keyed with sig; obs

    nonconsuming choice ArchiveKeyed
      : ()
      with
        delegee : Party
        keyedCid : ContractId Keyed
      controller delegee
      do
        archive keyedCid

    nonconsuming choice UnkeyedFetch
      : Keyed
      with
        cid : ContractId Keyed
        delegee : Party
      controller delegee
      do
        fetch cid

    nonconsuming choice VisibleKeyed
      : Bool
      with
        key : Party
        delegee : Party
      controller delegee
      do
        visibleByKey @Keyed key

    nonconsuming choice LookupKeyed
      : Optional (ContractId Keyed)
      with
        lookupKey : Party
        delegee : Party
      controller delegee
      do
        lookupByKey @Keyed lookupKey

    nonconsuming choice FetchKeyed
      : (ContractId Keyed, Keyed)
      with
        lookupKey : Party
        delegee : Party
      controller delegee
      do
        fetchByKey @Keyed lookupKey

template Helper
  with
    p : Party
  where
    signatory p

    choice FetchByKey : (ContractId Keyed, Keyed)
      with
        keyedKey : Party
      controller p
      do fetchByKey @Keyed keyedKey

    choice VisibleByKey : Bool
      with
        keyedKey : Party
      controller p
      do visibleByKey @Keyed keyedKey

    choice LookupByKey : (Optional (ContractId Keyed))
      with
        keyedKey : Party
      controller p
      do lookupByKey @Keyed keyedKey

    choice AssertNotVisibleKeyed : ()
      with
        delegationCid : ContractId Delegation
        delegee : Party
        key : Party
      controller p
      do
        b <- exercise delegationCid VisibleKeyed with
          delegee
          key
        assert $ not b

    choice AssertLookupKeyedIsNone : ()
      with
        delegationCid : ContractId Delegation
        delegee : Party
        lookupKey : Party
      controller p
      do
        b <- exercise delegationCid LookupKeyed with
          delegee
          lookupKey
        assert $ isNone b

    choice AssertFetchKeyedEqExpected : ()
      with
        delegationCid : ContractId Delegation
        delegee : Party
        lookupKey : Party
        expectedCid : ContractId Keyed
      controller p
      do
        (cid, keyed) <- exercise delegationCid FetchKeyed with
          delegee
          lookupKey
        cid === expectedCid


lookupTest = script do

  -- Put four parties in the four possible relationships with a `Keyed`
  sig <- allocateParty "s" -- Signatory
  obs <- allocateParty "o" -- Observer
  divulgee <- allocateParty "d" -- Divulgee
  blind <- allocateParty "b" -- Blind

  keyedCid <- submit sig do createCmd Keyed with ..
  divulgercid <- submit divulgee do createCmd Divulger with ..
  submit sig do exerciseCmd divulgercid DivulgeKeyed with ..

  -- Now the signatory and observer delegate their choices
  sigDelegationCid <- submit sig do
    createCmd Delegation with
      sig
      delegees = [obs, divulgee, blind]
  obsDelegationCid <- submit obs do
    createCmd Delegation with
      sig = obs
      delegees = [divulgee, blind]

  -- TESTING LOOKUPS AND FETCHES

  -- Maintainer can fetch
  (cid, keyed) <- submit sig do
    Helper sig `createAndExerciseCmd` FetchByKey sig
  cid === keyedCid
  -- Maintainer can see
  b <- submit sig do
    Helper sig `createAndExerciseCmd` VisibleByKey sig
  assert b
  -- Maintainer can lookup
  mcid <- submit sig do
    Helper sig `createAndExerciseCmd` LookupByKey sig
  mcid === Some keyedCid


  -- Stakeholder can fetch
  (cid, l) <- submit obs do
    Helper obs `createAndExerciseCmd` FetchByKey sig
  keyedCid === cid
  -- Stakeholder can't see without authorization
  submitMustFail obs do
    Helper obs `createAndExerciseCmd` VisibleByKey sig

  -- Stakeholder can see with authorization
  b <- submit obs do
    exerciseCmd sigDelegationCid VisibleKeyed with
      delegee = obs
      key = sig
  assert b
  -- Stakeholder can't lookup without authorization
  submitMustFail obs do
    Helper obs `createAndExerciseCmd` LookupByKey sig
  -- Stakeholder can lookup with authorization
  mcid <- submit obs do
    exerciseCmd sigDelegationCid LookupKeyed with
      delegee = obs
      lookupKey = sig
  mcid === Some keyedCid

  -- Divulgee can't fetch the contract directly
  submitMustFail divulgee do
    exerciseCmd obsDelegationCid UnkeyedFetch with
        delegee = divulgee
        cid = keyedCid
  -- Divulgee can't fetch through the key
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` FetchByKey sig
  -- Divulgee can't see
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` VisibleByKey sig
  -- Divulgee can't see with stakeholder authority
  submitMustFail divulgee do
    exerciseCmd obsDelegationCid VisibleKeyed with
        delegee = divulgee
        key = sig
  -- Divulgee can't lookup
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` LookupByKey sig
  -- Divulgee can't lookup with stakeholder authority
  submitMustFail divulgee do
    exerciseCmd obsDelegationCid LookupKeyed with
        delegee = divulgee
        lookupKey = sig
  -- Divulgee can't do positive lookup with maintainer authority.
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` AssertNotVisibleKeyed with
      delegationCid = sigDelegationCid
      delegee = divulgee
      key = sig
  -- Divulgee can't do positive lookup with maintainer authority.
  -- Note that the lookup returns `None` so the assertion passes.
  -- If the assertion is changed to `isSome`, the assertion fails,
  -- which means the error message changes. The reason is that the
  -- assertion is checked at interpretation time, before the lookup
  -- is checked at validation time.
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` AssertLookupKeyedIsNone with
      delegationCid = sigDelegationCid
      delegee = divulgee
      lookupKey = sig
  -- Divulgee can't fetch with stakeholder authority
  submitMustFail divulgee do
    Helper divulgee `createAndExerciseCmd` AssertFetchKeyedEqExpected with
      delegationCid = obsDelegationCid
      delegee = divulgee
      lookupKey = sig
      expectedCid = keyedCid

  -- Blind party can't fetch
  submitMustFail blind do
    Helper blind `createAndExerciseCmd` FetchByKey sig
  -- Blind party can't see
  submitMustFail blind do
    Helper blind `createAndExerciseCmd` VisibleByKey sig
  -- Blind party can't see with stakeholder authority
  submitMustFail blind do
    exerciseCmd obsDelegationCid VisibleKeyed with
      delegee = blind
      key = sig
  -- Blind party can't see with maintainer authority
  submitMustFail blind do
    Helper blind `createAndExerciseCmd` AssertNotVisibleKeyed with
      delegationCid = sigDelegationCid
      delegee = blind
      key = sig
  -- Blind party can't lookup
  submitMustFail blind do
    Helper blind `createAndExerciseCmd` LookupByKey sig
  -- Blind party can't lookup with stakeholder authority
  submitMustFail blind do
    exerciseCmd obsDelegationCid LookupKeyed with
      delegee = blind
      lookupKey = sig
  -- Blind party can't lookup with maintainer authority.
  -- The lookup initially returns `None`, but is rejected at
  -- validation time
  submitMustFail blind do
    Helper blind `createAndExerciseCmd` AssertLookupKeyedIsNone with
      delegationCid = sigDelegationCid
      delegee = blind
      lookupKey = sig
  -- Blind party can't fetch with stakeholder authority as lookup is negative
  submitMustFail blind do
    exerciseCmd obsDelegationCid FetchKeyed with
      delegee = blind
      lookupKey = sig
  -- Blind party can see nonexistence of a contract
  submit blind do
    Helper blind `createAndExerciseCmd` AssertNotVisibleKeyed with
      delegationCid = obsDelegationCid
      delegee = blind
      key = obs
  -- Blind can do a negative lookup on a truly nonexistant contract
  submit blind do
    Helper blind `createAndExerciseCmd` AssertLookupKeyedIsNone with
      delegationCid = obsDelegationCid
      delegee = blind
      lookupKey = obs

  -- TESTING CREATES AND ARCHIVES

  -- Divulgee can't archive
  submitMustFail divulgee do
    exerciseCmd sigDelegationCid ArchiveKeyed with
      delegee = divulgee
      keyedCid

  submit sig do
     exerciseCmd keyedCid Archive

  -- Divulgee can create
  keyedCid2 <- submit divulgee do
    exerciseCmd sigDelegationCid CreateKeyed with
      delegee = divulgee
      obs

  -- Stakeholder can archive
  submit obs do
    exerciseCmd sigDelegationCid ArchiveKeyed with
      delegee = obs
      keyedCid = keyedCid2
  -- Stakeholder can create
  keyedCid3 <- submit obs do
    exerciseCmd sigDelegationCid CreateKeyed with
      delegee = obs
      obs

  return ()

​

Reference: Interfaces

​

Configuration

​

Interface Declaration

​

Interface Name

interface MyInterface where

• This is the name of the interface.
• It’s preceded by the keyword interface and followed by the keyword where.
• It must begin with a capital letter, like any other type name.

​

Implicit abstract type

• Whenever an interface is defined, an abstract type is defined with the same name. “Abstract” here means:
  • Values of this type cannot be created using a data constructor. Instead, they are constructed by applying the function toInterface to a template value.
  • Values of this type cannot be inspected directly via case analysis. Instead, use functions such as fromInterface.
  • See daml-ref-interface-functions for more information on these and other functions for interacting with interface values.
• An interface value carries inside it the type and parameters of the template value from which it was constructed.
• As for templates, the existence of a local binding b of type I, where I is an interface does not necessarily imply the existence on the ledger of a contract with the template type and parameters used to construct b. This can only be assumed if b the result of a fetch from the ledger within the same transaction.

​

Interface Methods

method1 : Party
method2 : Int
method3 : Bool -> Int -> Int -> Int

• An interface may define any number of methods.
• A method definition consists of the method name and the method type, separated by a single colon :. The name of the method must be a valid identifier beginning with a lowercase letter or an underscore.
• A method definition introduces a top level function of the same name:
  • If the interface is called I, the method is called m, and the method type is M (which might be a function type), this introduces the function m : I -> M:

<DamlInterfacesINTERFACEMETHODSTOPLEVEL />

• The first argument’s type I means that the function can only be applied to values of the interface type I itself. Methods cannot be applied to template values, even if there exists an interface instance of I for that template. To use an interface method on a template value, first convert it using the toInterface function.
• Applying the function to such argument results in a value of type M, corresponding to the implementation of m in the interface instance of I for the underlying template type t (the type of the template value from which the interface value was constructed).
• One special method, view, must be defined for the viewtype. (see interface-viewtype below).

​

Interface View Type

data MyInterfaceViewType =
  MyInterfaceViewType { name : Text, value : Int }

viewtype MyInterfaceViewType

• All interface instances must implement a special view method which returns a value of the type declared by viewtype.
• The type must be a record.
• This type is returned by subscriptions on interfaces.

​

Interface Choices

choice MyChoice : (ContractId MyInterface, Int)
  with
    argument1 : Bool
    argument2 : Int
  controller method1 this
  do
    let n0 = method2 this
    let n1 = method3 this argument1 argument2 n0
    pure (self, n1)

nonconsuming choice MyNonConsumingChoice : Int
  controller method1 this
  do
    pure $ method2 this