Module Daml.Script

Data Types

data Commands a

This is used to build up the commands send as part of submit. If you enable the ApplicativeDo extension by adding {-# LANGUAGE ApplicativeDo #-} at the top of your file, you can use do-notation but the individual commands must not depend on each other and the last statement in a do block must be of the form return expr or pure expr.

instance Functor Commands

instance HasSubmit Script Commands

instance Applicative Commands

instance HasField "commands" (SubmitCmd a) (Commands a)

instance HasField "commands" (SubmitMustFailCmd a) (Commands a)

instance HasField "commands" (SubmitTreePayload a) (Commands ())

data InvalidUserId

Thrown if text for a user identifier does not conform to the format restriction.

InvalidUserId

Field Type Description
m Text  

instance Eq InvalidUserId

instance Show InvalidUserId

instance HasFromAnyException InvalidUserId

instance HasMessage InvalidUserId

instance HasThrow InvalidUserId

instance HasToAnyException InvalidUserId

instance HasField "m" InvalidUserId Text

data ParticipantName

ParticipantName

Field Type Description
participantName Text  

instance HasField "participantName" ParticipantName Text

data PartyDetails

The party details returned by the party management service.

PartyDetails

Field Type Description
party Party Party id
displayName Optional Text Optional display name
isLocal Bool True if party is hosted by the backing participant.

instance Eq PartyDetails

instance Ord PartyDetails

instance Show PartyDetails

instance HasField "continue" (ListKnownPartiesPayload a) ([PartyDetails] -> a)

instance HasField "displayName" PartyDetails (Optional Text)

instance HasField "isLocal" PartyDetails Bool

instance HasField "party" PartyDetails Party

data PartyIdHint

A hint to the backing participant what party id to allocate. Must be a valid PartyIdString (as described in @value.proto@).

PartyIdHint

Field Type Description
partyIdHint Text  

instance HasField "partyIdHint" PartyIdHint Text

data Script a

This is the type of A Daml script. Script is an instance of Action, so you can use do notation.

instance Functor Script

instance CanAssert Script

instance ActionCatch Script

instance ActionThrow Script

instance CanAbort Script

instance HasSubmit Script Commands

instance HasTime Script

instance Action Script

instance ActionFail Script

instance Applicative Script

instance HasField "dummy" (Script a) ()

instance HasField "runScript" (Script a) (() -> Free ScriptF (a, ()))

data User

User-info record for a user in the user management service.

User

Field Type Description
userId UserId  
primaryParty Optional Party  

instance Eq User

instance Ord User

instance Show User

instance HasField "continue" (GetUserPayload a) (Optional User -> a)

instance HasField "continue" (ListAllUsersPayload a) ([User] -> a)

instance HasField "primaryParty" User (Optional Party)

instance HasField "user" (CreateUserPayload a) User

instance HasField "userId" User UserId

data UserAlreadyExists

Thrown if a user to be created already exists.

UserAlreadyExists

Field Type Description
userId UserId  

instance Eq UserAlreadyExists

instance Show UserAlreadyExists

instance HasFromAnyException UserAlreadyExists

instance HasMessage UserAlreadyExists

instance HasThrow UserAlreadyExists

instance HasToAnyException UserAlreadyExists

instance HasField "userId" UserAlreadyExists UserId

data UserId

Identifier for a user in the user management service.

instance Eq UserId

instance Ord UserId

instance Show UserId

instance HasField "userId" (DeleteUserPayload a) UserId

instance HasField "userId" (GetUserPayload a) UserId

instance HasField "userId" (GrantUserRightsPayload a) UserId

instance HasField "userId" (ListUserRightsPayload a) UserId

instance HasField "userId" (RevokeUserRightsPayload a) UserId

instance HasField "userId" User UserId

instance HasField "userId" UserAlreadyExists UserId

instance HasField "userId" UserNotFound UserId

data UserNotFound

Thrown if a user cannot be located for a given user identifier.

UserNotFound

Field Type Description
userId UserId  

instance Eq UserNotFound

instance Show UserNotFound

instance HasFromAnyException UserNotFound

instance HasMessage UserNotFound

instance HasThrow UserNotFound

instance HasToAnyException UserNotFound

instance HasField "userId" UserNotFound UserId

data UserRight

The rights of a user.

ParticipantAdmin

CanActAs Party

CanReadAs Party

instance Eq UserRight

instance Show UserRight

instance HasField "continue" (GrantUserRightsPayload a) (Optional [UserRight] -> a)

instance HasField "continue" (ListUserRightsPayload a) (Optional [UserRight] -> a)

instance HasField "continue" (RevokeUserRightsPayload a) (Optional [UserRight] -> a)

instance HasField "rights" (CreateUserPayload a) [UserRight]

instance HasField "rights" (GrantUserRightsPayload a) [UserRight]

instance HasField "rights" (RevokeUserRightsPayload a) [UserRight]

Functions

query

: (Template t, IsParties p) => p -> Script [(ContractId t, t)]

Query the set of active contracts of the template that are visible to the given party.

queryFilter

: (Template c, IsParties p) => p -> (c -> Bool) -> Script [(ContractId c, c)]

Query the set of active contracts of the template that are visible to the given party and match the given predicate.

queryContractId

: (Template t, IsParties p, HasCallStack) => p -> ContractId t -> Script (Optional t)

Query for the contract with the given contract id.

Returns None if there is no active contract the party is a stakeholder on.

WARNING: Over the gRPC and with the JSON API in-memory backend this performs a linear search so only use this if the number of active contracts is small.

This is semantically equivalent to calling query and filtering on the client side.

queryInterface

: (Template i, HasInterfaceView i v, IsParties p) => p -> Script [(ContractId i, Optional v)]

Query the set of active contract views for an interface that are visible to the given party. If the view function fails for a given contract id, The Optional v will be None.

WARNING: Information about instances with failed-views is not currently returned over the JSON API: the Optional v will be Some _ for every element in the returned list.

queryInterfaceContractId

: (Template i, HasInterfaceView i v, IsParties p, HasCallStack) => p -> ContractId i -> Script (Optional v)

Query for the contract view with the given contract id.

Returns None if there is no active contract the party is a stakeholder on.

Returns None if the view function fails for the given contract id.

WARNING: Over the gRPC and with the JSON API in-memory backend this performs a linear search so only use this if the number of active contracts is small.

This is semantically equivalent to calling queryInterface and filtering on the client side.

queryContractKey

: (HasCallStack, TemplateKey t k, IsParties p) => p -> k -> Script (Optional (ContractId t, t))

Returns None if there is no active contract with the given key that the party is a stakeholder on.

WARNING: Over the gRPC and with the JSON API in-memory backend this performs a linear search so only use this if the number of active contracts is small.

This is semantically equivalent to calling query and filtering on the client side.

setTime

: HasCallStack => Time -> Script ()

Set the time via the time service.

This is only supported in static time mode when running over the gRPC API and in Daml Studio.

Note that the ledger time service does not support going backwards in time. However, you can go back in time in Daml Studio.

passTime

: RelTime -> Script ()

Advance ledger time by the given interval.

Only supported in static time mode when running over the gRPC API and in Daml Studio. Note that this is not an atomic operation over the gRPC API so no other clients should try to change time while this is running.

Note that the ledger time service does not support going backwards in time. However, you can go back in time in Daml Studio.

allocateParty

: HasCallStack => Text -> Script Party

Allocate a party with the given display name using the party management service.

allocatePartyWithHint

: HasCallStack => Text -> PartyIdHint -> Script Party

Allocate a party with the given display name and id hint using the party management service.

allocatePartyOn

: Text -> ParticipantName -> Script Party

Allocate a party with the given display name on the specified participant using the party management service.

allocatePartyWithHintOn

: Text -> PartyIdHint -> ParticipantName -> Script Party

Allocate a party with the given display name and id hint on the specified participant using the party management service.

listKnownParties

: HasCallStack => Script [PartyDetails]

List the parties known to the default participant.

listKnownPartiesOn

: HasCallStack => ParticipantName -> Script [PartyDetails]

List the parties known to the given participant.

sleep

: HasCallStack => RelTime -> Script ()

Sleep for the given duration.

This is primarily useful in tests where you repeatedly call query until a certain state is reached.

Note that this will sleep for the same duration in both wallcock and static time mode.

submitMulti

: HasCallStack => [Party] -> [Party] -> Commands a -> Script a

submitMulti actAs readAs cmds submits cmds as a single transaction authorized by actAs. Fetched contracts must be visible to at least one party in the union of actAs and readAs.

submitMultiMustFail

: HasCallStack => [Party] -> [Party] -> Commands a -> Script ()

submitMultiMustFail actAs readAs cmds behaves like submitMulti actAs readAs cmds but fails when submitMulti succeeds and the other way around.

createCmd

: Template t => t -> Commands (ContractId t)

Create a contract of the given template.

exerciseCmd

: Choice t c r => ContractId t -> c -> Commands r

Exercise a choice on the given contract.

exerciseByKeyCmd

: (TemplateKey t k, Choice t c r) => k -> c -> Commands r

Exercise a choice on the contract with the given key.

createAndExerciseCmd

: (Template t, Choice t c r) => t -> c -> Commands r

Create a contract and exercise a choice on it in the same transaction.

archiveCmd

: Choice t Archive () => ContractId t -> Commands ()

Archive the given contract.

archiveCmd cid is equivalent to exerciseCmd cid Archive.

script

: Script a -> Script a

Convenience helper to declare you are writing a Script.

This is only useful for readability and to improve type inference. Any expression of type Script a is a valid script regardless of whether it is implemented using script or not.

userIdToText

: UserId -> Text

Extract the name-text from a user identitifer.

validateUserId

: HasCallStack => Text -> Script UserId

Construct a user identifer from text. May throw InvalidUserId.

createUser

: HasCallStack => User -> [UserRight] -> Script ()

Create a user with the given rights. May throw UserAlreadyExists.

createUserOn

: HasCallStack => User -> [UserRight] -> ParticipantName -> Script ()

Create a user with the given rights on the given participant. May throw UserAlreadyExists.

getUser

: HasCallStack => UserId -> Script User

Fetch a user record by user id. May throw UserNotFound.

getUserOn

: HasCallStack => UserId -> ParticipantName -> Script User

Fetch a user record by user id from the given participant. May throw UserNotFound.

listAllUsers

: Script [User]

List all users. This function may make multiple calls to underlying paginated ledger API.

listAllUsersOn

: ParticipantName -> Script [User]

List all users on the given participant. This function may make multiple calls to underlying paginated ledger API.

grantUserRights

: HasCallStack => UserId -> [UserRight] -> Script [UserRight]

Grant rights to a user. Returns the rights that have been newly granted. May throw UserNotFound.

grantUserRightsOn

: HasCallStack => UserId -> [UserRight] -> ParticipantName -> Script [UserRight]

Grant rights to a user on the given participant. Returns the rights that have been newly granted. May throw UserNotFound.

revokeUserRights

: HasCallStack => UserId -> [UserRight] -> Script [UserRight]

Revoke rights for a user. Returns the revoked rights. May throw UserNotFound.

revokeUserRightsOn

: HasCallStack => UserId -> [UserRight] -> ParticipantName -> Script [UserRight]

Revoke rights for a user on the given participant. Returns the revoked rights. May throw UserNotFound.

deleteUser

: HasCallStack => UserId -> Script ()

Delete a user. May throw UserNotFound.

deleteUserOn

: HasCallStack => UserId -> ParticipantName -> Script ()

Delete a user on the given participant. May throw UserNotFound.

listUserRights

: HasCallStack => UserId -> Script [UserRight]

List the rights of a user. May throw UserNotFound.

listUserRightsOn

: HasCallStack => UserId -> ParticipantName -> Script [UserRight]

List the rights of a user on the given participant. May throw UserNotFound.

submitUser

: HasCallStack => UserId -> Commands a -> Script a

Submit the commands with the actAs and readAs claims granted to a user. May throw UserNotFound.

submitUserOn

: HasCallStack => UserId -> ParticipantName -> Commands a -> Script a

Submit the commands with the actAs and readAs claims granted to the user on the given participant. May throw UserNotFound.