# 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.

instance CanAssert Scenario

instance CanAssert Update

instance CanAssert (Either Text)

class HasInterfaceTypeRep i where

_interfaceTypeRep
: i -> TypeRep

class HasToInterface t i where

_toInterface
: t -> i

class HasFromInterface t i where

class HasTime m where

The HasTime class is for where the time is available: Scenario and Update.

getTime

: HasCallStack => m Time

Get the current time.

instance HasTime Scenario

instance HasTime Update

class Action m => CanAbort m where

The CanAbort class is for Action s that can be aborted.

abort

: Text -> m a

Abort the current action with a message.

instance CanAbort Scenario

instance CanAbort Update

instance CanAbort (Either Text)

class HasSubmit m cmds where

submit

: HasCallStack => Party -> cmds a -> m a

submit p cmds submits the commands cmds as a single transaction from party p and returns the value returned by cmds.

If the transaction fails, submit also fails.

submitMustFail

: HasCallStack => Party -> cmds a -> m ()

submitMustFail p cmds submits the commands cmds as a single transaction from party p.

It only succeeds if the submitting the transaction fails.

instance HasSubmit Scenario Update

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, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap 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

(>>=)

: m a -> (a -> m b) -> m b

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

instance Action ((->) r)

instance Action (State s)

instance Action Down

instance Action Scenario

instance Action Update

instance Action Optional

instance Action Formula

instance Action NonEmpty

instance Action (Either e)

instance Action ([])

class Action m => ActionFail m where

This class exists to desugar pattern matches in do-notation. Polymorphic usage, or calling fail directly, is not recommended. Instead consider using CanAbort.

fail

: Text -> m a

Fail with an error message.

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 Semigroup All

instance Semigroup Any

instance Semigroup (Endo a)

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 Ordering

instance Semigroup Text

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 Monoid (TextMap b)

instance Monoid All

instance Monoid Any

instance Monoid (Endo a)

instance Multiplicative a => Monoid (Product a)

instance Additive a => Monoid (Sum a)

instance Ord k => Monoid (Set k)

instance Monoid Ordering

instance Monoid Text

instance Monoid [a]

class HasSignatory t where

Exposes signatory function. Part of the Template constraint.

signatory

: t -> [Party]

The signatories of a contract.

class HasObserver t where

Exposes observer function. Part of the Template constraint.

observer

: t -> [Party]

The observers of a contract.

class HasEnsure t where

Exposes ensure function. Part of the Template constraint.

ensure

: t -> Bool

A predicate that must be true, otherwise contract creation will fail.

class HasAgreement t where

Exposes agreement function. Part of the Template constraint.

agreement

: t -> Text

The agreement text of a contract.

class HasCreate t where

Exposes create function. Part of the Template constraint.

create

: t -> Update (ContractId t)

Create a contract based on a template t.

class HasFetch t where

Exposes fetch function. Part of the Template 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 the Template constraint.

archive

: ContractId t -> Update ()

Archive the contract with the given contract ID.

class HasTemplateTypeRep t where

Exposes templateTypeRep function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasToAnyTemplate t where

Exposes toAnyTemplate function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasFromAnyTemplate t where

Exposes fromAnyTemplate function in Daml-LF 1.7 or later. Part of the Template constraint.

class HasExercise t c r where

Exposes exercise function. Part of the Choice constraint.

exercise

: ContractId t -> c -> Update r

Exercise a choice on the contract with the given contract ID.

class HasExerciseGuarded t c r where

Exposes exerciseGuarded function.

exerciseGuarded

: (t -> Bool) -> ContractId t -> c -> Update r

Exercise a choice on the contract with the given contract ID, only if the predicate returns True.

class HasToAnyChoice t c r where

Exposes toAnyChoice function for Daml-LF 1.7 or later. Part of the Choice constraint.

class HasFromAnyChoice t c r where

Exposes fromAnyChoice function for Daml-LF 1.7 or later. Part of the Choice constraint.

Exposes key function. Part of the TemplateKey constraint.

key

: t -> k

The key of a contract.

class HasLookupByKey t k where

Exposes lookupByKey function. Part of the TemplateKey constraint.

lookupByKey

: k -> Update (Optional (ContractId t))

Look up the contract ID t associated with a given contract key k.

You must pass the t using an explicit type application. For instance, if you want to look up a contract of template Account by its key k, you must call lookupByKey @Account k.

class HasFetchByKey t k where

Exposes fetchByKey function. Part of the TemplateKey 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 template Account by its key k, you must call fetchByKey @Account k.

class HasMaintainer t k where

Exposes maintainer function. Part of the TemplateKey constraint.

class HasToAnyContractKey t k where

Exposes toAnyContractKey function in Daml-LF 1.7 or later. Part of the TemplateKey constraint.

class HasFromAnyContractKey t k where

Exposes fromAnyContractKey function in Daml-LF 1.7 or later. Part of the TemplateKey constraint.

class HasExerciseByKey t k c r where

Exposes exerciseByKey function.

class IsParties a where

Accepted ways to specify a list of parties: either a single party, or a list of parties.

toParties

: a -> [Party]

Convert to list of parties.

instance IsParties Party

instance IsParties (Optional Party)

instance IsParties (NonEmpty Party)

instance IsParties (Set Party)

instance IsParties [Party]

class Functor f where

A Functor is a typeclass for things that can be mapped over (using its fmap function. Examples include Optional, [] and Update).

fmap

: (a -> b) -> f a -> f b

fmap takes a function of type a -> b, and turns it into a function of type f a -> f b, where f is the type which is an instance of Functor.

For example, map is an fmap that only works on lists. It takes a function a -> b and a [a], and returns a [b].

(<$) : a -> f b -> f a Replace all locations in the input f b with the same value a. The default definition is fmap . 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 of Eq, and Eq may be derived for any datatype whose constituents are also instances of Eq. 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 non-normalised 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, then x == z = True Substitutivity: if x == y = True and f is a “public” function whose return type is an instance of Eq, then f x == f y = True Negation: x /= y = not (x == y) Minimal complete definition: either == or /=. (==) : a -> a -> Bool (/=) : a -> a -> Bool instance (Eq a, Eq b) => Eq (Either a b) instance Eq BigNumeric instance Eq Bool instance Eq Int instance Eq (Numeric n) instance Eq Ordering instance Eq RoundingMode instance Eq Text instance Eq a => Eq [a] 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) class Eq a => Ord a where The Ord class is used for totally ordered datatypes. Instances of Ord can be derived for any user-defined datatype whose constituent types are in Ord. The declared order of the constructors in the data declaration determines the ordering in derived Ord instances. The Ordering 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 non-strict partial order and have the following properties: Transitivity: if x <= y && y <= z = True, then x <= z = True Reflexivity: x <= x = True Antisymmetry: if x <= y && y <= x = True, then x == y = True Note that the following operator interactions are expected to hold: 1. x >= y = y <= x 2. x < y = x <= y && x /= y 3. x > y = y < x 4. x < y = compare x y == LT 5. x > y = compare x y == GT 6. x == y = compare x y == EQ 7. min x y == if x <= y then x else y = ‘True’ 8. max x y == if x >= y then x else y = ‘True’ Minimal complete definition: either compare or <=. Using compare can be more efficient for complex types. compare : a -> a -> Ordering (<) : a -> a -> Bool (<=) : a -> a -> Bool (>) : a -> a -> Bool (>=) : a -> a -> Bool max : a -> a -> a min : a -> a -> a instance (Ord a, Ord b) => Ord (Either a b) instance Ord BigNumeric instance Ord Bool instance Ord Int instance Ord (Numeric n) instance Ord Ordering instance Ord RoundingMode instance Ord Text instance Ord a => Ord [a] 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 through NumericScale 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 writing 3.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) equals 5. 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 the data declaration and maxBound is the last. You can also derive an instance of Bounded for single-constructor data types whose constituent types are in Bounded. Ord is not a superclass of Bounded because types that are not totally ordered can still have upper and lower bounds. minBound : a maxBound : a instance Bounded Bool instance Bounded Int 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 the succ and pred functions. Types that are an instance of class Bounded as well as Enum should respect the following laws: • Both succ maxBound and pred minBound should result in a runtime error. • fromEnum and toEnum 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 and enumFromThen 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 an Enum value: ie, toEnum i returns the item at the i th position of (the instance of) Enum fromEnum : a -> Int Convert a value from an Enum value to an Int: ie, returns the Int position of the element within the Enum. If fromEnum is applied to a value that’s too large to fit in an Int, what is returned is up to your implementation. enumFrom : a -> [a] Return a list of the Enum values starting at the Int 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 first Int position, the second value at the second Int 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 first Int position, and the last value at the last Int 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 first Int position, the second value at the second Int position, and further values with the same distance between them, with the final value at the final Int 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] = [] instance Enum Bool instance Enum 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 instance Additive Int instance Additive (Numeric n) 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. (^) : a -> Int -> a x ^ n raises x to the power of n. 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 for Additive and Multiplicative, 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 instance Number Int instance Number (Numeric n) class Signed a where The Signed is for the sign of a number. signum : a -> a Sign of a number. For real numbers, the ‘signum’ is either -1 (negative), 0 (zero) or 1 (positive). abs : a -> a The absolute value: that is, the value without the sign. instance Signed BigNumeric instance Signed Int instance Signed (Numeric n) class Multiplicative a => Divisible a where Use the Divisible class for types that can be divided. Instances should respect that division is the inverse of multiplication, i.e. x * y / y is equal to x whenever it is defined. (/) : a -> a -> a x / y divides x by y instance Divisible Int instance Divisible (Numeric n) 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 of x with respect to multiplication: x * recip x = munit • When recip y is defined, then x / y = x * recip y recip : a -> a Calculates the reciprocal: recip x is 1/x. instance Fractional (Numeric n) class Show a where Use the Show class for values that can be converted to a readable Text 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 top-level constructor in x is less than d (associativity is ignored), the representation will be enclosed in parentheses. For example, if d is 0 then the result is never surrounded in parentheses; if d is 11 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 record-syntax form, with the fields given in the same order as the original declaration. showsPrec : Int -> a -> ShowS Convert a value to a readable Text value. Unlike show, showsPrec should satisfy the rule showsPrec d x r ++ s == showsPrec d x (r ++ s) show : a -> Text Convert a value to a readable Text value. showList : [a] -> ShowS Allows you to show lists of values. instance (Show a, Show b) => Show (Either a b) instance Show BigNumeric instance Show Bool instance Show Int instance Show (Numeric n) instance Show Ordering instance Show RoundingMode instance Show Text instance Show a => Show [a] 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 Existential choice type that can wrap an arbitrary choice. AnyChoice Field Type Description getAnyChoice Any getAnyChoiceTemplateTypeRep TemplateTypeRep instance Eq AnyChoice instance Ord AnyChoice data AnyContractKey Existential contract key type that can wrap an arbitrary contract key. AnyContractKey Field Type Description getAnyContractKey Any getAnyContractKeyTemplateTypeRep TemplateTypeRep instance Eq AnyContractKey instance Ord AnyContractKey data AnyTemplate Existential template type that can wrap an arbitrary template. AnyTemplate Field Type Description getAnyTemplate Any instance Eq AnyTemplate instance Ord AnyTemplate data TemplateTypeRep Unique textual representation of a template Id. TemplateTypeRep Field Type Description getTemplateTypeRep TypeRep instance Eq TemplateTypeRep instance Ord TemplateTypeRep data Down a The Down type can be used for reversing sorting order. For example, sortOn (\x -> Down x.field) would sort by descending field. Down a instance Action Down instance Applicative Down instance Functor Down instance Eq a => Eq (Down a) instance Ord a => Ord (Down a) instance Show a => Show (Down a) type Implements t i = (HasInterfaceTypeRep i, HasToInterface t i, HasFromInterface t i) 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 template a. 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 The Date type represents a date, for example date 2007 Apr 5. instance Eq Date instance Ord Date instance Bounded Date instance Enum Date instance Show Date data Map a b The Map a b type represents an associative array from keys of type a to values of type b. It uses the built-in equality for keys. Import DA.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) instance (Ord k, Ord v) => Ord (Map k v) instance (Show k, Show v) => Show (Map k v) data Party The Party type represents a party to a contract. instance IsParties Party instance IsParties (Optional Party) instance IsParties (NonEmpty Party) instance IsParties (Set Party) instance IsParties [Party] instance Eq Party instance Ord Party instance Show Party data Scenario a The Scenario type is for simulating ledger interactions. The type Scenario a describes a set of actions taken by various parties during the simulated scenario, before returning a value of type a. instance CanAssert Scenario instance ActionThrow Scenario instance CanAbort Scenario instance HasSubmit Scenario Update instance HasTime Scenario instance Action Scenario instance ActionFail Scenario instance Applicative Scenario instance Functor Scenario data TextMap a The TextMap a type represents an associative array from keys of type Text to values of type a. instance Foldable TextMap instance Monoid (TextMap b) instance Semigroup (TextMap b) instance Traversable TextMap instance Functor TextMap instance Eq a => Eq (TextMap a) instance Ord a => Ord (TextMap a) instance Show a => Show (TextMap a) data Time The Time type represents a specific datetime in UTC, for example time (date 2007 Apr 5) 14 30 05. instance Eq Time instance Ord Time instance Show Time data Update a The Update a type represents an Action to update or query the ledger, before returning a value of type a. Examples include create and fetch. instance CanAssert Update instance ActionCatch Update instance ActionThrow Update instance CanAbort Update instance HasSubmit Scenario Update instance HasTime Update instance Action Update instance ActionFail Update instance Applicative Update instance Functor Update data Optional a The Optional type encapsulates an optional value. A value of type Optional a either contains a value of type a (represented as Some a), or it is empty (represented as None). Using Optional is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error. The Optional type is also an Action. It is a simple kind of error Action, where all errors are represented by None. A richer error Action could be built using the Data.Either.Either type. None Some a instance Foldable Optional instance Action Optional instance ActionFail Optional instance Applicative Optional instance IsParties (Optional Party) instance Traversable Optional instance Functor Optional instance Eq a => Eq (Optional a) instance Ord a => Ord (Optional a) instance Show a => Show (Optional a) data Archive The data type corresponding to the implicit Archive choice in every template. Archive instance Eq Archive instance Show 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 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 type Either a b is either Left a or Right b. The Either type is sometimes used to represent a value which is either correct or an error; by convention, the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value (mnemonic: “right” also means “correct”). Left a instance (Eq a, Eq b) => Eq (Either a b) instance (Ord a, Ord b) => Ord (Either a b) instance (Show a, Show b) => Show (Either a b) type ShowS = Text -> Text 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 convert BigNumeric to a fixed-width numeric (Numeric n) in order to store it in a template. The rounding operations are round and div from the DA.BigNumeric module. The casting operations are fromNumeric and fromBigNumeric from the IsNumeric 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 A type for Boolean values, ie True and False. False True instance Eq Bool instance Ord Bool instance Bounded Bool instance Enum Bool instance Show Bool type Decimal = Numeric 10 data Int A type representing a 64-bit integer. instance Eq Int instance Ord Int instance Bounded Int instance Enum Int instance Additive Int instance Divisible Int instance Multiplicative Int instance Number Int instance Signed Int instance Show Int data Nat (Kind) This is the kind of type-level naturals. data Numeric n A type for fixed-point decimal numbers, with the scale being passed as part of the type. Numeric n represents a fixed-point decimal number with a fixed precision of 38 (i.e. 38 digits not including a leading zero) and a scale of n, 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 4  instance Eq (Numeric n) instance NumericScale n => IsNumeric (Numeric n) instance Ord (Numeric n) instance Additive (Numeric n) instance Divisible (Numeric n) instance Fractional (Numeric n) instance Multiplicative (Numeric n) instance Number (Numeric n) instance Signed (Numeric n) instance Show (Numeric n) data Ordering A type for giving information about ordering: being less than (LT), equal to (EQ), or greater than (GT) something. LT EQ GT instance Eq Ordering instance Ord Ordering instance Show Ordering data RoundingMode Rounding modes for BigNumeric operations like div and round from DA.BigNumeric. RoundingUp Round away from zero. RoundingDown Round towards zero. RoundingCeiling Round towards positive infinity. RoundingFloor Round towards negative infinity. RoundingHalfUp Round towards the nearest neighbor unless both neighbors are equidistant, in which case round away from zero. RoundingHalfDown Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards zero. RoundingHalfEven Round towards the nearest neighbor unless both neighbors are equidistant, in which case round towards the even neighbor. RoundingUnnecessary 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 A type for text strings, that can represent any unicode code point. For example "Hello, world". instance Eq Text instance Ord Text instance Show Text data [] a A type for lists, for example [1,2,3]. ([]) (:) _ _ ## Functions¶ assert : CanAssert m => Bool -> m () 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 : Int -> Date Convert from number of days since epoch (i.e. the number of days since January 1, 1970) to a date. dateToDaysSinceEpoch : Date -> Int 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 toInterface : HasToInterface t i => t -> i toInterfaceContractId : HasToInterface t i => ContractId t -> ContractId i fromInterfaceContractId : (HasFromInterface t i, HasFetch i) => ContractId i -> Update (Optional (ContractId t)) partyToText : Party -> Text Convert the Party to Text, giving back what you passed to getParty. In most cases, you should use show instead. show wraps the party in 'ticks' making it clear it was a Party originally. partyFromText Converts a Text to Party. It returns None if the provided text contains any forbidden characters. See Daml-LF 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 a Party. The only way to guarantee that a given Party 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 Daml-LF < 1.2. getParty Get the party with the given name. Party names must be non-empty and only contain alphanumeric charaters, space, - (dash) or _ (underscore). scenario : Scenario a -> Scenario a Declare you are building a scenario. 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 type a, return would give you an Update a. join : Action m => m (m a) -> m a Collapses nested actions into a single action. 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 list xs using the function f, using the starting value i. Examples: >>> foldl (+) 0 [1,2,3] 6 >>> foldl (^) 10 [2,3] 1000000  Note that foldl works from left-to-right over the list arguments. find : (a -> Bool) -> [a] -> Optional a find p xs finds the first element of the list xs where the predicate p is true. There might not be such an element, which is why this function returns an Optional a. length : [a] -> Int Gives the length of the list. any : (a -> Bool) -> [a] -> Bool Are there any elements in the list where the predicate is true? any p xs is True if p holds for at least one element of xs. all : (a -> Bool) -> [a] -> Bool Is the predicate true for all of the elements in the list? all p xs is True if p holds for every element of xs. or : [Bool] -> Bool Is at least one of elements in a list of Bool true? or bs is True if at least one element of bs is True. and : [Bool] -> Bool Is every element in a list of Bool true? and bs is True if every element of bs is True. elem : Eq a => a -> [a] -> Bool Does this value exist in this list? elem x xs is True if x is an element of the list xs. notElem : Eq a => a -> [a] -> Bool Negation of elem: elem x xs is True if x is not an element of the list xs. (<$>)

: Functor f => (a -> b) -> f a -> f b

Synonym for fmap.

optional

: b -> (a -> b) -> Optional a -> b

The optional function takes a default value, a function, and a Optional value. If the Optional value is None, the function returns the default value. Otherwise, it applies the function to the value inside the Some 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 a Optional Int. If you have Some n, this shows the underlying Int, n. But if you have None, 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 the Either type. If the value is Left a, it applies the first function to a; if it is Right b, it applies the second function to b.

Examples:

This example has two values of type Either [Int] Int, one using the Left constructor and another using the Right constructor. Then it applies either the length function (if it has a [Int]) or the “times-two” function (if it has an Int):

>>> 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 is mapA with its arguments flipped.

sequence

: Applicative m => [m a] -> m [a]

Perform a list of actions in sequence and collect the results.

(=<<)

: Action m => (a -> m b) -> m a -> m b

=<< is >>= with its arguments flipped.

concatMap

: (a -> [b]) -> [a] -> [b]

Map a function over each element of a list, and concatenate all the results.

replicate

: Int -> a -> [a]

replicate i x gives the list [x, x, x, ..., x] with i copies of x.

take

: Int -> [a] -> [a]

Take the first n elements of a list.

drop

: Int -> [a] -> [a]

Drop the first n elements of a list.

splitAt

: Int -> [a] -> ([a], [a])

Split a list at a given index.

takeWhile

: (a -> Bool) -> [a] -> [a]

Take elements from a list while the predicate holds.

dropWhile

: (a -> Bool) -> [a] -> [a]

Drop elements from a list while the predicate holds.

span

: (a -> Bool) -> [a] -> ([a], [a])

span p xs is equivalent to (takeWhile p xs, dropWhile p xs).

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 to span (not . p) xs.

lookup

: Eq a => a -> [(a, b)] -> Optional b

Look up the first element with a matching key.

enumerate

: (Enum a, Bounded a) => [a]

Generate a list containing all values of a given enumeration.

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 to zip.

zipWith

: (a -> b -> c) -> [a] -> [b] -> [c]

zipWith takes a function and two lists. It generalises zip 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 generalises zip3 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 prints msg and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

trace

: Show b => b -> a -> a

trace b a prints b and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

traceId

: Show b => b -> b

traceId a prints a and returns a, for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

debug

: (Show b, Action m) => b -> m ()

debug x prints x for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=debug to include them.

debugRaw

: Action m => Text -> m ()

debugRaw msg prints msg for debugging purposes.

Note that on some ledgers, those messages are not displayed at the default log level. For Sandbox, you can use --log-level=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.

truncate

: Numeric n -> Int

truncate x rounds x toward zero.

intToNumeric

: Int -> Numeric n

Convert an Int to a Numeric.

intToDecimal

: Int -> Decimal

Convert an Int to a Decimal.

roundBankers

: Int -> Numeric n -> Numeric n

Bankers’ Rounding: roundBankers dp x rounds x to dp 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 rounds x to dp decimal places, where a .5 is rounded away from zero.

round

: Numeric n -> Int

Round a Decimal to the nearest integer, where a .5 is rounded away from zero.

floor

: Numeric n -> Int

Round a Decimal down to the nearest integer.

ceiling

: Numeric n -> Int

Round a Decimal up to the nearest integer.

null

: [a] -> Bool

Is the list empty? null xs is true if xs is the empty list.

filter

: (a -> Bool) -> [a] -> [a]

Filters the list using the function: keep only the elements where the predicate holds.

sum

: Additive a => [a] -> a

Add together all the elements in the list.

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 choice Withdraw on a contract of template Account given by its key k, you must call exerciseByKey @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

Generate a unique textual representation of the template id.

toAnyTemplate

: HasToAnyTemplate t => t -> AnyTemplate

Wrap the template in AnyTemplate.

Only available for Daml-LF 1.7 or later.

fromAnyTemplate

Extract the underlying template from AnyTemplate if the type matches or return None.

Only available for Daml-LF 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 example toAnyChoice @Account Withdraw.

Only available for Daml-LF 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 return None.

You must pass the template type t using an explicit type application. For example fromAnyChoice @Account choice.

Only available for Daml-LF 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 example toAnyContractKey @Proposal k.

Only available for Daml-LF 1.7 or later.

fromAnyContractKey

Extract the underlying key from AnyContractKey if the template and choice types match, or return None.

You must pass the template type t using an explicit type application. For example fromAnyContractKey @Proposal k.

Only available for Daml-LF 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.

otherwise

: Bool

Used as an alternative in conditions.

map

: (a -> b) -> [a] -> [b]

map f xs applies the function f to all elements of the list xs and returns the list of results (in the same order as xs).

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 list xs using the function f, using the starting value i.

Note that foldr works from right-to-left 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 to x 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 to b and a value of type a, and apply the function to the value of type a, returning a value of type b. This function has a very low precedence, which is why you might want to use it instead of regular function application.

(&&)

: Bool -> Bool -> Bool

Boolean “and”. This function has short-circuiting semantics, i.e., when both arguments are present and the first arguments evaluates to ‘False’, the second argument is not evaluated at all.

(||)

: Bool -> Bool -> Bool

Boolean “or”. This function has short-circuiting semantics, i.e., when both arguments are present and the first arguments evaluates to ‘True’, the second argument is not evaluated at all.

not

: Bool -> Bool

Boolean “not”

error

: Text -> a

error stops execution and displays the given error message.

If called within a transaction, it will abort the current transaction. Outside of a transaction (scenarios, Daml Script or Daml Triggers) it will stop the whole scenario/script/trigger.

Throws a GeneralError exception.

subtract

: Additive a => a -> a -> a

subtract x y is equivalent to y - x.

This is useful for partial application, e.g., in subtract 1 since (- 1) is interpreted as the number -1 and not a function that subtracts 1 from its argument.

(%)

: Int -> Int -> Int

x % y calculates the remainder of x by y

showParen

: Bool -> ShowS -> ShowS

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

showString

: Text -> ShowS

Utility function converting a ‘String’ to a show function that simply prepends the string unchanged.

showSpace

Prepends a single space to the front of the string.

showCommaSpace

Prepends a comma and a single space to the front of the string.