Module Prelude¶
The pieces that make up the Daml language.
Typeclasses¶
class Action m => CanAssert m where
Constraint that determines whether an assertion can be made in this context.
 assertFail
: Text > m t
Abort since an assertion has failed. In an Update, Scenario, Script, or Trigger context this will throw an AssertionFailed exception. In an
Either Text
context, this will return the message as an error.
class HasInterfaceTypeRep i where
(1.dev only) Exposes theinterfaceTypeRep
function. Available only for interfaces.
class HasToInterface t i where
(1.dev only) Exposes thetoInterface
andtoInterfaceContractId
functions.
class HasFromInterface t i where
(1.dev only) Exposes
fromInterface
andfromInterfaceContractId
functions.
 fromInterface
: i > Optional t
(1.dev only) Attempt to convert an interface value back into a template value. A
None
indicates that the expected template type doesn’t match the underyling template type for the interface value.For example,
fromInterface @MyTemplate value
will try to convert the interface valuevalue
into the template typeMyTemplate
.
class HasInterfaceView i v where
 _view
 : i > v
class HasTime m where
class Action m => CanAbort m where
class HasSubmit m cmds where
 submit
: HasCallStack => Party > cmds a > m a
submit p cmds
submits the commandscmds
as a single transaction from partyp
and returns the value returned bycmds
.If the transaction fails,
submit
also fails.
 submitMustFail
: HasCallStack => Party > cmds a > m ()
submitMustFail p cmds
submits the commandscmds
as a single transaction from partyp
.It only succeeds if the submitting the transaction fails.
class Functor f => Applicative f where
 pure
: a > f a
Lift a value.
 (<*>)
: f (a > b) > f a > f b
Sequentially apply the function.
A few functors support an implementation of
<*>
that is more efficient than the default one.
 liftA2
: (a > b > c) > f a > f b > f c
Lift a binary function to actions.
Some functors support an implementation of
liftA2
that is more efficient than the default one. In particular, iffmap
is an expensive operation, it is likely better to useliftA2
than tofmap
over the structure and then use<*>
.
 (*>)
: f a > f b > f b
Sequence actions, discarding the value of the first argument.
 (<*)
: f a > f b > f a
Sequence actions, discarding the value of the second argument.
instance Applicative ((>) r)
instance Applicative (State s)
instance Applicative Down
instance Applicative Scenario
instance Applicative Update
instance Applicative Optional
instance Applicative Formula
instance Applicative NonEmpty
instance Applicative (Validation err)
instance Applicative (Either e)
instance Applicative ([])
class Applicative m => Action m where
class Action m => ActionFail m where
This class exists to desugar pattern matches in donotation. Polymorphic usage, or calling
fail
directly, is not recommended. Instead consider usingCanAbort
.instance ActionFail Scenario
instance ActionFail Update
instance ActionFail Optional
instance ActionFail (Either Text)
instance ActionFail ([])
class Semigroup a where
The class of semigroups (types with an associative binary operation).
 (<>)
: a > a > a
An associative operation.
instance Ord k => Semigroup (Map k v)
instance Semigroup (TextMap b)
instance Multiplicative a => Semigroup (Product a)
instance Additive a => Semigroup (Sum a)
instance Semigroup (NonEmpty a)
instance Ord a => Semigroup (Max a)
instance Ord a => Semigroup (Min a)
instance Ord k => Semigroup (Set k)
instance Semigroup [a]
class Semigroup a => Monoid a where
The class of monoids (types with an associative binary operation that has an identity).
 mempty
: a
Identity of
(<>)
 mconcat
: [a] > a
Fold a list using the monoid. For example using
mconcat
on a list of strings would concatenate all strings to one lone string.instance Ord k => Monoid (Map k v)
instance Multiplicative a => Monoid (Product a)
instance Additive a => Monoid (Sum a)
instance Ord k => Monoid (Set k)
instance Monoid [a]
class HasSignatory t where
class HasObserver t where
class HasEnsure t where
class HasAgreement t where
class HasCreate t where
Exposes
create
function. Part of theTemplate
constraint.
 create
: t > Update (ContractId t)
Create a contract based on a template
t
.
class HasFetch t where
Exposes
fetch
function. Part of theTemplate
constraint.
 fetch
: ContractId t > Update t
Fetch the contract data associated with the given contract ID. If the
ContractId t
supplied is not the contract ID of an active contract, this fails and aborts the entire transaction.
class HasArchive t where
Exposes
archive
function. Part of theTemplate
constraint.
 archive
: ContractId t > Update ()
Archive the contract with the given contract ID.
class HasTemplateTypeRep t where
ExposestemplateTypeRep
function in DamlLF 1.7 or later. Part of theTemplate
constraint.
class HasToAnyTemplate t where
ExposestoAnyTemplate
function in DamlLF 1.7 or later. Part of theTemplate
constraint.
class HasFromAnyTemplate t where
ExposesfromAnyTemplate
function in DamlLF 1.7 or later. Part of theTemplate
constraint.
class HasExercise t c r where
Exposes
exercise
function. Part of theChoice
constraint.
 exercise
: ContractId t > c > Update r
Exercise a choice on the contract with the given contract ID.
class HasExerciseGuarded t c r where
(1.dev only) Exposes
exerciseGuarded
function. Only available for interface choices.
 exerciseGuarded
: (t > Bool) > ContractId t > c > Update r
(1.dev only) Exercise a choice on the contract with the given contract ID, only if the predicate returns
True
.
class HasToAnyChoice t c r where
ExposestoAnyChoice
function for DamlLF 1.7 or later. Part of theChoice
constraint.
class HasFromAnyChoice t c r where
ExposesfromAnyChoice
function for DamlLF 1.7 or later. Part of theChoice
constraint.
class HasKey t k where
Exposes
key
function. Part of theTemplateKey
constraint.
 key
: t > k
The key of a contract.
class HasLookupByKey t k where
Exposes
lookupByKey
function. Part of theTemplateKey
constraint.
 lookupByKey
: k > Update (Optional (ContractId t))
Look up the contract ID
t
associated with a given contract keyk
.You must pass the
t
using an explicit type application. For instance, if you want to look up a contract of templateAccount
by its keyk
, you must calllookupByKey @Account k
.
class HasFetchByKey t k where
Exposes
fetchByKey
function. Part of theTemplateKey
constraint.
 fetchByKey
: k > Update (ContractId t, t)
Fetch the contract ID and contract data associated with a given contract key.
You must pass the
t
using an explicit type application. For instance, if you want to fetch a contract of templateAccount
by its keyk
, you must callfetchByKey @Account k
.
class HasMaintainer t k where
Exposesmaintainer
function. Part of theTemplateKey
constraint.
class HasToAnyContractKey t k where
ExposestoAnyContractKey
function in DamlLF 1.7 or later. Part of theTemplateKey
constraint.
class HasFromAnyContractKey t k where
ExposesfromAnyContractKey
function in DamlLF 1.7 or later. Part of theTemplateKey
constraint.
class HasExerciseByKey t k c r where
ExposesexerciseByKey
function.
class IsParties a where
class Functor f where
A
Functor
is a typeclass for things that can be mapped over (using itsfmap
function. Examples includeOptional
,[]
andUpdate
).
 fmap
: (a > b) > f a > f b
fmap
takes a function of typea > b
, and turns it into a function of typef a > f b
, wheref
is the type which is an instance ofFunctor
.For example,
map
is anfmap
that only works on lists. It takes a functiona > b
and a[a]
, and returns a[b]
.
 (<$)
: a > f b > f a
Replace all locations in the input
f b
with the same valuea
. The default definition isfmap . const
, but you can override this with a more efficient version.
class Eq a where
The
Eq
class defines equality (==
) and inequality (/=
). All the basic datatypes exported by the "Prelude" are instances ofEq
, andEq
may be derived for any datatype whose constituents are also instances ofEq
.Usually,
==
is expected to implement an equivalence relationship where two values comparing equal are indistinguishable by "public" functions, with a "public" function being one not allowing to see implementation details. For example, for a type representing nonnormalised natural numbers modulo 100, a "public" function doesn’t make the difference between 1 and 201. It is expected to have the following properties:Reflexivity:
x == x
=True
Symmetry:
x == y
=y == x
Transitivity: if
x == y && y == z
=True
, thenx == z
=True
Substitutivity: if
x == y
=True
andf
is a "public" function whose return type is an instance ofEq
, thenf x == f y
=True
Negation:
x /= y
=not (x == y)
Minimal complete definition: either
==
or/=
.instance (Eq a, Eq b) => Eq (Either a b)
instance Eq BigNumeric
instance Eq RoundingMode
instance Eq ()
instance (Eq a, Eq b) => Eq (a, b)
instance (Eq a, Eq b, Eq c) => Eq (a, b, c)
instance (Eq a, Eq b, Eq c, Eq d) => Eq (a, b, c, d)
instance (Eq a, Eq b, Eq c, Eq d, Eq e) => Eq (a, b, c, d, e)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f) => Eq (a, b, c, d, e, f)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g) => Eq (a, b, c, d, e, f, g)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h) => Eq (a, b, c, d, e, f, g, h)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i) => Eq (a, b, c, d, e, f, g, h, i)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j) => Eq (a, b, c, d, e, f, g, h, i, j)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k) => Eq (a, b, c, d, e, f, g, h, i, j, k)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l) => Eq (a, b, c, d, e, f, g, h, i, j, k, l)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m, Eq n) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
instance (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f, Eq g, Eq h, Eq i, Eq j, Eq k, Eq l, Eq m, Eq n, Eq o) => Eq (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
The
Ord
class is used for totally ordered datatypes.Instances of
Ord
can be derived for any userdefined datatype whose constituent types are inOrd
. The declared order of the constructors in the data declaration determines the ordering in derivedOrd
instances. TheOrdering
datatype allows a single comparison to determine the precise ordering of two objects.The Haskell Report defines no laws for
Ord
. However,<=
is customarily expected to implement a nonstrict partial order and have the following properties:Transitivity: if
x <= y && y <= z
=True
, thenx <= z
=True
Reflexivity:
x <= x
=True
Antisymmetry: if
x <= y && y <= x
=True
, thenx == y
=True
Note that the following operator interactions are expected to hold:
x >= y
=y <= x
x < y
=x <= y && x /= y
x > y
=y < x
x < y
=compare x y == LT
x > y
=compare x y == GT
x == y
=compare x y == EQ
min x y == if x <= y then x else y
= ‘True’max x y == if x >= y then x else y
= ‘True’Minimal complete definition: either
compare
or<=
. Usingcompare
can be more efficient for complex types.
 max
 : a > a > a
 min
 : a > a > a
instance (Ord a, Ord b) => Ord (Either a b)
instance Ord BigNumeric
instance Ord RoundingMode
instance Ord ()
instance (Ord a, Ord b) => Ord (a, b)
instance (Ord a, Ord b, Ord c) => Ord (a, b, c)
instance (Ord a, Ord b, Ord c, Ord d) => Ord (a, b, c, d)
instance (Ord a, Ord b, Ord c, Ord d, Ord e) => Ord (a, b, c, d, e)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f) => Ord (a, b, c, d, e, f)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g) => Ord (a, b, c, d, e, f, g)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h) => Ord (a, b, c, d, e, f, g, h)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i) => Ord (a, b, c, d, e, f, g, h, i)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j) => Ord (a, b, c, d, e, f, g, h, i, j)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k) => Ord (a, b, c, d, e, f, g, h, i, j, k)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l) => Ord (a, b, c, d, e, f, g, h, i, j, k, l)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m, Ord n) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
instance (Ord a, Ord b, Ord c, Ord d, Ord e, Ord f, Ord g, Ord h, Ord i, Ord j, Ord k, Ord l, Ord m, Ord n, Ord o) => Ord (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
class NumericScale n where
Is this a valid scale for the
Numeric
type?This typeclass is used to prevent the creation of Numeric values with too large a scale. The scale controls the number of digits available after the decimal point, and it must be between 0 and 37 inclusive.
Thus the only available instances of this typeclass are
NumericScale 0
throughNumericScale 37
. This cannot be extended without additional compiler and runtime support. You cannot implement a custom instance of this typeclass.If you have an error message in your code of the form "No instance for
(NumericScale n)
", this is probably caused by having a numeric literal whose scale cannot be inferred by the compiler. You can usually fix this by adding a type signature to the definition, or annotating the numeric literal directly (for example, instead of writing3.14159
you can write(3.14159 : Numeric 5)
).
 numericScale
: proxy n > Int
Get the scale of a
Numeric
as an integer. For example,numericScale (3.14159 : Numeric 5)
equals5
.instance NumericScale 0
instance NumericScale 1
instance NumericScale 10
instance NumericScale 11
instance NumericScale 12
instance NumericScale 13
instance NumericScale 14
instance NumericScale 15
instance NumericScale 16
instance NumericScale 17
instance NumericScale 18
instance NumericScale 19
instance NumericScale 2
instance NumericScale 20
instance NumericScale 21
instance NumericScale 22
instance NumericScale 23
instance NumericScale 24
instance NumericScale 25
instance NumericScale 26
instance NumericScale 27
instance NumericScale 28
instance NumericScale 29
instance NumericScale 3
instance NumericScale 30
instance NumericScale 31
instance NumericScale 32
instance NumericScale 33
instance NumericScale 34
instance NumericScale 35
instance NumericScale 36
instance NumericScale 37
instance NumericScale 4
instance NumericScale 5
instance NumericScale 6
instance NumericScale 7
instance NumericScale 8
instance NumericScale 9
class IsNumeric t where
Types that can be represented by decimal literals in Daml.
 fromNumeric
: NumericScale m => Numeric m > t
Convert from
Numeric
. Raises an error if the number can’t be represented exactly in the target type.
 fromBigNumeric
: BigNumeric > t
Convert from
BigNumeric
. Raises an error if the number can’t be represented exactly in the target type.instance IsNumeric BigNumeric
instance NumericScale n => IsNumeric (Numeric n)
class Bounded a where
Use the
Bounded
class to name the upper and lower limits of a type.You can derive an instance of the
Bounded
class for any enumeration type.minBound
is the first constructor listed in thedata
declaration andmaxBound
is the last.You can also derive an instance of
Bounded
for singleconstructor data types whose constituent types are inBounded
.
Ord
is not a superclass ofBounded
because types that are not totally ordered can still have upper and lower bounds.
 minBound
 : a
 maxBound
 : a
class Enum a where
Use the
Enum
class to define operations on sequentially ordered types: that is, types that can be enumerated.Enum
members have defined successors and predecessors, which you can get with thesucc
andpred
functions.Types that are an instance of class
Bounded
as well asEnum
should respect the following laws:
 Both
succ maxBound
andpred minBound
should result in a runtime error.fromEnum
andtoEnum
should give a runtime error if the result value is not representable in the result type. For example,toEnum 7 : Bool
is an error.enumFrom
andenumFromThen
should be defined with an implicit bound, like this:enumFrom x = enumFromTo x maxBound enumFromThen x y = enumFromThenTo x y bound where bound  fromEnum y >= fromEnum x = maxBound  otherwise = minBound
 succ
: a > a
Returns the successor of the given value. For example, for numeric types,
succ
adds 1.If the type is also an instance of
Bounded
,succ maxBound
results in a runtime error.
 pred
: a > a
Returns the predecessor of the given value. For example, for numeric types,
pred
subtracts 1.If the type is also an instance of
Bounded
,pred minBound
results in a runtime error.
 toEnum
: Int > a
Convert a value from an
Int
to anEnum
value: ie,toEnum i
returns the item at thei
th position of (the instance of)Enum
 enumFrom
: a > [a]
Return a list of the
Enum
values starting at theInt
position. For example:
enumFrom 6 : [Int] = [6,7,8,9,...,maxBound : Int]
 enumFromThen
: a > a > [a]
Returns a list of the
Enum
values with the first value at the firstInt
position, the second value at the secondInt
position, and further values with the same distance between them.For example:
enumFromThen 4 6 : [Int] = [4,6,8,10...]
enumFromThen 6 2 : [Int] = [6,2,2,6,...,minBound :: Int]
 enumFromTo
: a > a > [a]
Returns a list of the
Enum
values with the first value at the firstInt
position, and the last value at the lastInt
position.This is what’s behind the language feature that lets you write
[n,m..]
.For example:
enumFromTo 6 10 : [Int] = [6,7,8,9,10]
 enumFromThenTo
: a > a > a > [a]
Returns a list of the
Enum
values with the first value at the firstInt
position, the second value at the secondInt
position, and further values with the same distance between them, with the final value at the finalInt
position.This is what’s behind the language feature that lets you write
[n,n'..m]
.For example:
enumFromThenTo 4 2 6 : [Int] = [4,2,0,2,4,6]
enumFromThenTo 6 8 2 : [Int] = []
class Additive a where
Use the
Additive
class for types that can be added. Instances have to respect the following laws:
(+)
must be associative, ie:(x + y) + z
=x + (y + z)
(+)
must be commutative, ie:x + y
=y + x
x + aunit
=x
negate
gives the additive inverse, ie:x + negate x
=aunit
 (+)
: a > a > a
Add the two arguments together.
 aunit
: a
The additive identity for the type. For example, for numbers, this is 0.
 ()
: a > a > a
Subtract the second argument from the first argument, ie.
x  y
=x + negate y
 negate
: a > a
Negate the argument:
x + negate x
=aunit
instance Additive BigNumeric
class Multiplicative a where
Use the
Multiplicative
class for types that can be multiplied. Instances have to respect the following laws:
(*)
is associative, ie:(x * y) * z
=x * (y * z)
(*)
is commutative, ie:x * y
=y * x
x * munit
=x
 (*)
: a > a > a
Multipy the arguments together
 munit
: a
The multiplicative identity for the type. For example, for numbers, this is 1.
instance Multiplicative BigNumeric
instance Multiplicative Int
instance Multiplicative (Numeric n)
class (Additive a, Multiplicative a) => Number a where
Number
is a class for numerical types. As well as the rules forAdditive
andMultiplicative
, instances also have to respect the following law:
(*)
is distributive with respect to(+)
. That is:a * (b + c)
=(a * b) + (a * c)
and(b + c) * a
=(b * a) + (c * a)
instance Number BigNumeric
class Signed a where
class Multiplicative a => Divisible a where
class Divisible a => Fractional a where
Use the
Fractional
class for types that can be divided and where the reciprocal is well defined. Instances have to respect the following laws:
 When
recip x
is defined, it must be the inverse ofx
with respect to multiplication:x * recip x = munit
 When
recip y
is defined, thenx / y = x * recip y
 recip
: a > a
Calculates the reciprocal:
recip x
is1/x
.instance Fractional (Numeric n)
class Show a where
Use the
Show
class for values that can be converted to a readableText
value.Derived instances of
Show
have the following properties:
 The result of
show
is a syntactically correct expression that only contains constants (given the fixity declarations in force at the point where the type is declared). It only contains the constructor names defined in the data type, parentheses, and spaces. When labelled constructor fields are used, braces, commas, field names, and equal signs are also used. If the constructor is defined to be an infix operator, then
showsPrec
produces infix applications of the constructor. If the precedence of the toplevel constructor in
x
is less thand
(associativity is ignored), the representation will be enclosed in parentheses. For example, ifd
is0
then the result is never surrounded in parentheses; ifd
is11
it is always surrounded in parentheses, unless it is an atomic expression. If the constructor is defined using record syntax, then
show
will produce the recordsyntax form, with the fields given in the same order as the original declaration.
 showsPrec
Convert a value to a readable
Text
value. Unlikeshow
,showsPrec
should satisfy the ruleshowsPrec d x r ++ s == showsPrec d x (r ++ s)
instance (Show a, Show b) => Show (Either a b)
instance Show BigNumeric
instance Show RoundingMode
instance Show ()
instance (Show a, Show b) => Show (a, b)
instance (Show a, Show b, Show c) => Show (a, b, c)
instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d)
instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e)
Data Types¶
data AnyChoice
data AnyContractKey
Existential contract key type that can wrap an arbitrary contract key.
Field Type Description getAnyContractKey Any getAnyContractKeyTemplateTypeRep TemplateTypeRep instance Eq AnyContractKey
instance Ord AnyContractKey
data AnyTemplate
Existential template type that can wrap an arbitrary template.
Field Type Description getAnyTemplate Any instance Eq AnyTemplate
instance Ord AnyTemplate
data TemplateTypeRep
Unique textual representation of a template Id.
Field Type Description getTemplateTypeRep TypeRep instance Eq TemplateTypeRep
instance Ord TemplateTypeRep
data Down a
 type Implements t i
= (HasInterfaceTypeRep i, HasToInterface t i, HasFromInterface t i)
(1.dev only) Constraint that indicates that a template implements an interface.
data AnyException
A wrapper for all exception types.
instance HasFromAnyException AnyException
instance HasMessage AnyException
instance HasToAnyException AnyException
data ContractId a
The
ContractId a
type represents an ID for a contract created from a templatea
. You can use the ID to fetch the contract, among other things.instance Eq (ContractId a)
instance Ord (ContractId a)
instance Show (ContractId a)
data Date
data Map a b
The
Map a b
type represents an associative array from keys of typea
to values of typeb
. It uses the builtin equality for keys. ImportDA.Map
to use it.instance Ord k => Foldable (Map k)
instance Ord k => Monoid (Map k v)
instance Ord k => Semigroup (Map k v)
instance Ord k => Traversable (Map k)
instance Ord k => Functor (Map k)
instance (Ord k, Eq v) => Eq (Map k v)
data Party
data Scenario a
The
Scenario
type is for simulating ledger interactions. The typeScenario a
describes a set of actions taken by various parties during the simulated scenario, before returning a value of typea
.instance ActionThrow Scenario
instance HasSubmit Scenario Update
instance ActionFail Scenario
instance Applicative Scenario
data TextMap a
data Time
data Update a
The
Update a
type represents anAction
to update or query the ledger, before returning a value of typea
. Examples includecreate
andfetch
.instance ActionCatch Update
instance ActionThrow Update
instance HasSubmit Scenario Update
instance ActionFail Update
instance Applicative Update
data Optional a
The
Optional
type encapsulates an optional value. A value of typeOptional a
either contains a value of typea
(represented asSome a
), or it is empty (represented asNone
). UsingOptional
is a good way to deal with errors or exceptional cases without resorting to drastic measures such aserror
.The
Optional
type is also anAction
. It is a simple kind of errorAction
, where all errors are represented byNone
. A richer errorAction
could be built using theData.Either.Either
type.Some a
instance ActionFail Optional
instance Applicative Optional
instance IsParties (Optional Party)
instance Traversable Optional
instance Eq a => Eq (Optional a)
data Archive
 type Choice t c r
= (TemplateOrInterface t, HasExercise t c r, HasToAnyChoice t c r, HasFromAnyChoice t c r)
Constraint satisfied by choices.
 type Template t
= (HasSignatory t, HasObserver t, HasEnsure t, HasAgreement t, HasCreate t, HasFetch t, HasArchive t, HasTemplateTypeRep t, HasToAnyTemplate t, HasFromAnyTemplate t)
Constraint satisfied by templates.
 type TemplateKey t k
= (Template t, HasKey t k, HasLookupByKey t k, HasFetchByKey t k, HasMaintainer t k, HasToAnyContractKey t k, HasFromAnyContractKey t k)
Constraint satisfied by template keys.
 type TemplateOrInterface t
 = (HasTemplateTypeRep t, HasToAnyTemplate t, HasFromAnyTemplate t)
data Either a b
The
Either
type represents values with two possibilities: a value of typeEither a b
is eitherLeft a
orRight b
.The
Either
type is sometimes used to represent a value which is either correct or an error; by convention, theLeft
constructor is used to hold an error value and theRight
constructor is used to hold a correct value (mnemonic: "right" also means "correct").Left a
Right b
instance (Eq a, Eq b) => Eq (Either a b)
 type ShowS

showS
should represent some text, and applying it to some argument should prepend the argument to the represented text.
data BigNumeric
A big numeric type, capable of holding large decimal values with many digits.
BigNumeric
represents any positive or negative decimal number with up to 2^15 digits before the decimal point, and up to 2^15 digits after the decimal point.
BigNumeric
is not serializable, it is only intended for intermediate computation. You must round and convertBigNumeric
to a fixedwidth numeric (Numeric n
) in order to store it in a template. The rounding operations areround
anddiv
from theDA.BigNumeric
module. The casting operations arefromNumeric
andfromBigNumeric
from theIsNumeric
typeclass.instance Eq BigNumeric
instance IsNumeric BigNumeric
instance Ord BigNumeric
instance Additive BigNumeric
instance Multiplicative BigNumeric
instance Number BigNumeric
instance Signed BigNumeric
instance Show BigNumeric
data Bool
data Int
data Nat
(Kind) This is the kind of typelevel naturals.
data Numeric n
A type for fixedpoint decimal numbers, with the scale being passed as part of the type.
Numeric n
represents a fixedpoint decimal number with a fixed precision of 38 (i.e. 38 digits not including a leading zero) and a scale ofn
, i.e.,n
digits after the decimal point.
n
must be between 0 and 37 (bounds inclusive).Examples:
0.01 : Numeric 2 0.0001 : Numeric 4instance NumericScale n => IsNumeric (Numeric n)
instance Divisible (Numeric n)
instance Fractional (Numeric n)
instance Multiplicative (Numeric n)
data Ordering
data RoundingMode
Rounding modes for
BigNumeric
operations likediv
andround
fromDA.BigNumeric
.Round away from zero.Round towards zero.Round towards positive infinity.Round towards negative infinity.Round towards the nearest neighbor unless both neighbors are equidistant, in which case round away from zero.Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards zero.Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards the even neighbor.Do not round. Raises an error if the result cannot be represented without rounding at the targeted scale.instance Eq RoundingMode
instance Ord RoundingMode
instance Show RoundingMode
data Text
data [] a
Functions¶
 assert

Check whether a condition is true. If it’s not, abort the transaction.
 assertMsg
: CanAssert m => Text > Bool > m ()
Check whether a condition is true. If it’s not, abort the transaction with a message.
 assertAfter
: (CanAssert m, HasTime m) => Time > m ()
Check whether the given time is in the future. If it’s not, abort the transaction.
 assertBefore
: (CanAssert m, HasTime m) => Time > m ()
Check whether the given time is in the past. If it’s not, abort the transaction.
 daysSinceEpochToDate

Convert from number of days since epoch (i.e. the number of days since January 1, 1970) to a date.
 dateToDaysSinceEpoch

Convert from a date to number of days from epoch (i.e. the number of days since January 1, 1970).
 interfaceTypeRep
: HasInterfaceTypeRep i => i > TemplateTypeRep
(1.dev only) Obtain the
TemplateTypeRep
for the template given in the interface value.
 toInterface
: HasToInterface t i => t > i
(1.dev only) Convert a template value into an interface value. For example
toInterface @MyInterface value
converts a templatevalue
into aMyInterface
type.
 toInterfaceContractId
: HasToInterface t i => ContractId t > ContractId i
(1.dev only) Convert a template contract id into an interface contract id. For example,
toInterfaceContractId @MyInterface cid
.
 fromInterfaceContractId
: HasFromInterface t i => ContractId i > ContractId t
(1.dev only) Convert an interface contract id into a template contract id. For example,
fromInterfaceContractId @MyTemplate cid
.Can also be used to convert an interface contract id into a contract id of one of its requiring interfaces.
This function does not verify that the interface contract id actually points to a template of the given type. This means that a subsequent
fetch
,exercise
, orarchive
may fail, if, for example, the contract id points to a contract that implements the interface but is of a different template type than expected.Therefore, you should only use
fromInterfaceContractId
in situations where you already know that the contract id points to a contract of the right template type. You can also use it in situations where you will fetch, exercise, or archive the contract right away, when a transaction failure is the appropriate response to the contract having the wrong template type.In all other cases, consider using
fetchFromInterface
instead.
 fetchFromInterface
: (HasFromInterface t i, HasFetch i) => ContractId i > Update (Optional (ContractId t, t))
(1.dev only) Fetch an interface and convert it to a specific template type. If conversion is succesful, this function returns the converted contract and its converted contract id. Otherwise, this function returns
None
.Can also be used to fetch and convert an interface contract id into a contract and contract id of one of its requiring interfaces.
Example:
do fetchResult < fetchFromInterface @MyTemplate ifaceCid case fetchResult of None > abort "Failed to convert interface to appropriate template type" Some (tplCid, tpl) > do ... do something with tpl and tplCid ...
 _exerciseInterfaceGuard
 : a > b > c > Bool
 view
 : HasInterfaceView i v => i > v
 partyToText

Convert the
Party
toText
, giving back what you passed togetParty
. In most cases, you should useshow
instead.show
wraps the party in'ticks'
making it clear it was aParty
originally.
 partyFromText

Converts a
Text
toParty
. It returnsNone
if the provided text contains any forbidden characters. See DamlLF spec for a specification on which characters are allowed in parties. Note that this function accepts text without single quotes.This function does not check on whether the provided text corresponds to a party that "exists" on a given ledger: it merely converts the given
Text
to aParty
. The only way to guarantee that a givenParty
exists on a given ledger is to involve it in a contract.This function, together with
partyToText
, forms an isomorphism between valid party strings and parties. In other words, the following equations hold:∀ p. partyFromText (partyToText p) = Some p ∀ txt p. partyFromText txt = Some p ==> partyToText p = txt
This function will crash at runtime if you compile Daml to DamlLF < 1.2.
 getParty

Get the party with the given name. Party names must be nonempty and only contain alphanumeric charaters, space,

(dash) or_
(underscore).
 curry
: ((a, b) > c) > a > b > c
Turn a function that takes a pair into a function that takes two arguments.
 uncurry
: (a > b > c) > (a, b) > c
Turn a function that takes two arguments into a function that takes a pair.
 (>>)
: Action m => m a > m b > m b
Sequentially compose two actions, discarding any value produced by the first. This is like sequencing operators (such as the semicolon) in imperative languages.
 ap
: Applicative f => f (a > b) > f a > f b
Synonym for
<*>
.
 return
: Applicative m => a > m a
Inject a value into the monadic type. For example, for
Update
and a value of typea
,return
would give you anUpdate a
.
 identity
: a > a
The identity function.
 guard
 : ActionFail m => Bool > m ()
 foldl
: (b > a > b) > b > [a] > b
This function is a left fold, which you can use to inspect/analyse/consume lists.
foldl f i xs
performs a left fold over the listxs
using the functionf
, using the starting valuei
.Examples:
>>> foldl (+) 0 [1,2,3] 6 >>> foldl (^) 10 [2,3] 1000000
Note that foldl works from lefttoright over the list arguments.
 find
: (a > Bool) > [a] > Optional a
find p xs
finds the first element of the listxs
where the predicatep
is true. There might not be such an element, which is why this function returns anOptional a
.
 any

Are there any elements in the list where the predicate is true?
any p xs
isTrue
ifp
holds for at least one element ofxs
.
 all

Is the predicate true for all of the elements in the list?
all p xs
isTrue
ifp
holds for every element ofxs
.
 or

Is at least one of elements in a list of
Bool
true?or bs
isTrue
if at least one element ofbs
isTrue
.
 and

Is every element in a list of Bool true?
and bs
isTrue
if every element ofbs
isTrue
.
 elem

Does this value exist in this list?
elem x xs
isTrue
ifx
is an element of the listxs
.
 notElem

Negation of
elem
:elem x xs
isTrue
ifx
is not an element of the listxs
.
 optional
: b > (a > b) > Optional a > b
The
optional
function takes a default value, a function, and aOptional
value. If theOptional
value isNone
, the function returns the default value. Otherwise, it applies the function to the value inside theSome
and returns the result.Basic usage examples:
>>> optional False (> 2) (Some 3) True
>>> optional False (> 2) None False
>>> optional 0 (*2) (Some 5) 10 >>> optional 0 (*2) None 0
This example applies
show
to aOptional Int
. If you haveSome n
, this shows the underlyingInt
,n
. But if you haveNone
, this returns the empty string instead of (for example)None
:>>> optional "" show (Some 5) "5" >>> optional "" show (None : Optional Int) ""
 either
: (a > c) > (b > c) > Either a b > c
The
either
function provides case analysis for theEither
type. If the value isLeft a
, it applies the first function toa
; if it isRight b
, it applies the second function tob
.Examples:
This example has two values of type
Either [Int] Int
, one using theLeft
constructor and another using theRight
constructor. Then it applieseither
thelength
function (if it has a[Int]
) or the "timestwo" function (if it has anInt
):>>> let s = Left [1,2,3] : Either [Int] Int in either length (*2) s 3 >>> let n = Right 3 : Either [Int] Int in either length (*2) n 6
 concat
: [[a]] > [a]
Take a list of lists and concatenate those lists into one list.
 (++)
: [a] > [a] > [a]
Concatenate two lists.
 flip
: (a > b > c) > b > a > c
Flip the order of the arguments of a two argument function.
 reverse
: [a] > [a]
Reverse a list.
 mapA
: Applicative m => (a > m b) > [a] > m [b]
Apply an applicative function to each element of a list.
 forA
: Applicative m => [a] > (a > m b) > m [b]
forA
ismapA
with its arguments flipped.
 sequence
: Applicative m => [m a] > m [a]
Perform a list of actions in sequence and collect the results.
 concatMap
: (a > [b]) > [a] > [b]
Map a function over each element of a list, and concatenate all the results.
 partition
: (a > Bool) > [a] > ([a], [a])
The
partition
function takes a predicate, a list and returns the pair of lists of elements which do and do not satisfy the predicate, respectively; i.e.,> partition p xs == (filter p xs, filter (not . p) xs)
>>> partition (<0) [1, 2, 3, 4, 5, 6] ([2, 3, 5], [1, 4, 6])
 break
: (a > Bool) > [a] > ([a], [a])
Break a list into two, just before the first element where the predicate holds.
break p xs
is equivalent tospan (not . p) xs
.
 zip
: [a] > [b] > [(a, b)]
zip
takes two lists and returns a list of corresponding pairs. If one list is shorter, the excess elements of the longer list are discarded.
 zip3
: [a] > [b] > [c] > [(a, b, c)]
zip3
takes three lists and returns a list of triples, analogous tozip
.
 zipWith
: (a > b > c) > [a] > [b] > [c]
zipWith
takes a function and two lists. It generaliseszip
by combining elements using the function, instead of forming pairs. If one list is shorter, the excess elements of the longer list are discarded.
 zipWith3
: (a > b > c > d) > [a] > [b] > [c] > [d]
zipWith3
generaliseszip3
by combining elements using the function, instead of forming triples.
 unzip
: [(a, b)] > ([a], [b])
Turn a list of pairs into a pair of lists.
 unzip3
: [(a, b, c)] > ([a], [b], [c])
Turn a list of triples into a triple of lists.
 traceRaw
: Text > a > a
traceRaw msg a
printsmsg
and returnsa
, for debugging purposes.Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use
loglevel=debug
to include them.
 trace
: Show b => b > a > a
trace b a
printsb
and returnsa
, for debugging purposes.Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use
loglevel=debug
to include them.
 traceId
: Show b => b > b
traceId a
printsa
and returnsa
, for debugging purposes.Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use
loglevel=debug
to include them.
 debug
: (Show b, Action m) => b > m ()
debug x
printsx
for debugging purposes.Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use
loglevel=debug
to include them.
 debugRaw

debugRaw msg
printsmsg
for debugging purposes.Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use
loglevel=debug
to include them.
 fst
: (a, b) > a
Return the first element of a tuple.
 snd
: (a, b) > b
Return the second element of a tuple.
 intToNumeric

Convert an
Int
to aNumeric
.
 intToDecimal

Convert an
Int
to aDecimal
.
 roundBankers
: Int > Numeric n > Numeric n
Bankers’ Rounding:
roundBankers dp x
roundsx
todp
decimal places, where a.5
is rounded to the nearest even digit.
 roundCommercial
: NumericScale n => Int > Numeric n > Numeric n
Commercial Rounding:
roundCommercial dp x
roundsx
todp
decimal places, where a.5
is rounded away from zero.
 round

Round a
Decimal
to the nearest integer, where a.5
is rounded away from zero.
 filter
: (a > Bool) > [a] > [a]
Filters the list using the function: keep only the elements where the predicate holds.
 product
: Multiplicative a => [a] > a
Multiply all the elements in the list together.
 undefined
: a
A convenience function that can be used to mark something not implemented. Always throws an error with "Not implemented."
 stakeholder
: (HasSignatory t, HasObserver t) => t > [Party]
The stakeholders of a contract: its signatories and observers.
 maintainer
: HasMaintainer t k => k > [Party]
The list of maintainers of a contract key.
 exerciseByKey
: HasExerciseByKey t k c r => k > c > Update r
Exercise a choice on the contract associated with the given key.
You must pass the
t
using an explicit type application. For instance, if you want to exercise a choiceWithdraw
on a contract of templateAccount
given by its keyk
, you must callexerciseByKey @Account k Withdraw
.
 createAndExercise
: (HasCreate t, HasExercise t c r) => t > c > Update r
Create a contract and exercise the choice on the newly created contract.
 templateTypeRep
: HasTemplateTypeRep t => TemplateTypeRep
Generate a unique textual representation of the template id.
 toAnyTemplate
: HasToAnyTemplate t => t > AnyTemplate
Wrap the template in
AnyTemplate
.Only available for DamlLF 1.7 or later.
 fromAnyTemplate
: HasFromAnyTemplate t => AnyTemplate > Optional t
Extract the underlying template from
AnyTemplate
if the type matches or returnNone
.Only available for DamlLF 1.7 or later.
 toAnyChoice
: (HasTemplateTypeRep t, HasToAnyChoice t c r) => c > AnyChoice
Wrap a choice in
AnyChoice
.You must pass the template type
t
using an explicit type application. For exampletoAnyChoice @Account Withdraw
.Only available for DamlLF 1.7 or later.
 fromAnyChoice
: (HasTemplateTypeRep t, HasFromAnyChoice t c r) => AnyChoice > Optional c
Extract the underlying choice from
AnyChoice
if the template and choice types match, or returnNone
.You must pass the template type
t
using an explicit type application. For examplefromAnyChoice @Account choice
.Only available for DamlLF 1.7 or later.
 toAnyContractKey
: (HasTemplateTypeRep t, HasToAnyContractKey t k) => k > AnyContractKey
Wrap a contract key in
AnyContractKey
.You must pass the template type
t
using an explicit type application. For exampletoAnyContractKey @Proposal k
.Only available for DamlLF 1.7 or later.
 fromAnyContractKey
: (HasTemplateTypeRep t, HasFromAnyContractKey t k) => AnyContractKey > Optional k
Extract the underlying key from
AnyContractKey
if the template and choice types match, or returnNone
.You must pass the template type
t
using an explicit type application. For examplefromAnyContractKey @Proposal k
.Only available for DamlLF 1.7 or later.
 visibleByKey
: HasLookupByKey t k => k > Update Bool
True if contract exists, submitter is a stakeholder, and all maintainers authorize. False if contract does not exist and all maintainers authorize. Fails otherwise.
 map
: (a > b) > [a] > [b]
map f xs
applies the functionf
to all elements of the listxs
and returns the list of results (in the same order asxs
).
 foldr
: (a > b > b) > b > [a] > b
This function is a right fold, which you can use to manipulate lists.
foldr f i xs
performs a right fold over the listxs
using the functionf
, using the starting valuei
.Note that foldr works from righttoleft over the list elements.
 (.)
: (b > c) > (a > b) > a > c
Composes two functions, i.e.,
(f . g) x = f (g x)
.
 const
: a > b > a
const x
is a unary function which evaluates tox
for all inputs.>>> const 42 "hello" 42
>>> map (const 42) [0..3] [42,42,42,42]
 ($)
: (a > b) > a > b
Take a function from
a
tob
and a value of typea
, and apply the function to the value of typea
, returning a value of typeb
. This function has a very low precedence, which is why you might want to use it instead of regular function application.
 (&&)

Boolean "and". This function has shortcircuiting semantics, i.e., when both arguments are present and the first arguments evaluates to ‘False’, the second argument is not evaluated at all.
 ()

Boolean "or". This function has shortcircuiting semantics, i.e., when both arguments are present and the first arguments evaluates to ‘True’, the second argument is not evaluated at all.
 subtract
: Additive a => a > a > a
subtract x y
is equivalent toy  x
.This is useful for partial application, e.g., in
subtract 1
since( 1)
is interpreted as the number1
and not a function that subtracts1
from its argument.
 showParen

Utility function that surrounds the inner show function with parentheses when the ‘Bool’ parameter is ‘True’.
 showString

Utility function converting a ‘String’ to a show function that simply prepends the string unchanged.
 showCommaSpace
: ShowS
Prepends a comma and a single space to the front of the string.