Documentation/canton-network-docs/Splice APIsSplice Daml PackagesToken Standard v2splice-api-token-allocation-instruction-v2View on canton-network-docs ↗
canton-network-docs/Splice APIsSplice Daml PackagesToken Standard v2splice-api-token-allocation-instruction-v2

Splice.Api.Token.AllocationInstructionV2

​
Splice.Api.Token.AllocationInstructionV2

V2 interfaces to enable wallets to instruct the registry to create allocations.

​
Interfaces

​
Interface AllocationFactory

Contracts implementing AllocationFactory are retrieved from the registry app and are used by the wallet to create allocation instructions (or allocations directly). View Type: AllocationFactoryView Choices:

​
Choice AllocationFactory_Allocate

Request the creation of an allocation for a particular settlement. It depends on the registry whether this results in the allocation being created directly or in an allocation instruction being created instead. Controllers: actors Returns: AllocationInstructionResult Arguments:
​
settlement
SettlementInfo
The settlement for which this allocation is made.
​
allocation
AllocationSpecification
The allocation which should be created.Implementations MUST validate that the allocation’s admin partymatches the admin of the factory.
​
requestedAt
Time
The time at which the allocation was requested.
​
inputHoldingCids
[ContractId Holding]
The holdings to use to fund the allocation.Implementations MUST return change and all input holdings not used for fundingin the authorizerChangeCids field of the AllocationInstructionResult.
​
extraArgs
ExtraArgs
Additional choice arguments.
​
actors
[Party]
Set of parties executing the allocation.Implementations MUST check their concrete values to avoid unauthorized allocation creation.Implementations SHOULD allow the initiation of the allocation if the actorsis equal to the authorizer of the allocation. Likewise, for accountswhere the account provider has the right to allocate funds, the registrySHOULD allow the initiation of the allocation if the actors areequal to the account provider.

​
Choice AllocationFactory_PublicFetch

Controllers: actors Returns: AllocationFactoryView Arguments:
​
actors
[Party]
Set of parties executing the fetch.

​
Choice Archive

Controllers: Signatories of implementing template Returns: () Methods:

​
Method allocationFactory_allocateExtraObservers

Type: AllocationFactory_Allocate -> [Party]

​
Method allocationFactory_allocateImpl

Type: ContractId AllocationFactory -> AllocationFactory_Allocate -> Update AllocationInstructionResult

​
Method allocationFactory_publicFetchImpl

Type: ContractId AllocationFactory -> AllocationFactory_PublicFetch -> Update AllocationFactoryView

​
Interface AllocationInstruction

An interface for tracking the status of an allocation instruction, i.e., a request to a registry app to create an allocation. Registries MAY evolve the allocation instruction in multiple steps. They SHOULD do so using only the choices on this interface, so that wallets can reliably parse the transaction history and determine whether the creation of the allocation ultimately succeeded or failed. View Type: AllocationInstructionView Choices:

​
Choice AllocationInstruction_Accept

Accept the allocation instruction as someone that needs to authorize it. Controllers: actors Returns: AllocationInstructionResult Arguments:
​
actors
[Party]
Set of parties executing the acceptance.Registries are free to decide on the required authorization foracceptance. They MUST however report the parties that can acceptunilaterally via the AllocationInstructionView.availableActionsfield, so that wallets can show the accept option to the user.
​
extraArgs
ExtraArgs
Additional context required in order to exercise the choice.

​
Choice AllocationInstruction_Withdraw

Withdraw the allocation instruction. Controllers: actors Returns: AllocationInstructionResult Arguments:
​
actors
[Party]
Set of parties executing the withdrawal.Implementations MUST check these parties to avoid unauthorized withdrawal.Registries are free to decide on the required authorization forwithdrawal. They MUST however report the parties that can withdrawunilaterally via the AllocationInstructionView.availableActionsfield, so that wallets can show the withdrawal option to the user.
​
extraArgs
ExtraArgs
Additional context required in order to exercise the choice.

​
Choice Archive

Controllers: Signatories of implementing template Returns: () Methods:

​
Method allocationInstruction_acceptExtraObservers

Type: AllocationInstruction_Accept -> [Party]

​
Method allocationInstruction_acceptImpl

Type: ContractId AllocationInstruction -> AllocationInstruction_Accept -> Update AllocationInstructionResult

​
Method allocationInstruction_withdrawExtraObservers

Type: AllocationInstruction_Withdraw -> [Party]

​
Method allocationInstruction_withdrawImpl

Type: ContractId AllocationInstruction -> AllocationInstruction_Withdraw -> Update AllocationInstructionResult

​
Data Types

​
data AllocationFactoryView

View for AllocationFactory. Constructors:
  • AllocationFactoryView
​
admin
Party
The party representing the registry app that administers the instrumentsfor which this allocation factory can be used.
​
meta
Metadata
Additional metadata specific to the allocation factory, used for extensibility.
Instances:

​
data AllocationInstructionAction

Actions to advance the state of an allocation instruction. Constructors:
  • AIA_Withdraw
  • AIA_Accept
  • AIA_Custom
​
id
Text
Identifier of the action. Namespaced analogously to metadata keys.
Used to represent registry-specific actions that need to happen for the allocation to be created. Instances:

​
data AllocationInstructionResult

The result of instructing an allocation or advancing the state of an allocation instruction. Constructors:
  • AllocationInstructionResult
​
output
AllocationInstructionResult_Output
The output of the step.
​
authorizerChangeCids
TextMap [ContractId Holding]
Holdings owned by the authorizer that were not used to fund theallocation or that were created to return “change”, keyed byinstrumentId.id. Can be used by callers to batch creating orupdating multiple allocation instructions in a single Daml transaction.
​
meta
Metadata
Additional metadata specific to the allocation instruction, used for extensibility; e.g., fees charged.
Instances:

​
data AllocationInstructionResult_Output

The output of instructing an allocation or advancing the state of an allocation instruction. Constructors:
  • AllocationInstructionResult_Pending
​
allocationInstructionCid
ContractId AllocationInstruction
Contract id of the allocation instruction representing the pending state.
Use this result to communicate that the creation of the allocation is pending further steps.
  • AllocationInstructionResult_Completed
​
allocationCid
ContractId Allocation
The newly created allocation.
Use this result to communicate that the allocation was created.
  • AllocationInstructionResult_Failed
Use this result to communicate that the creation of the allocation did not succeed and all holdings reserved for funding the allocation have been released. Instances:

​
data AllocationInstructionView

View for AllocationInstruction. Constructors:
  • AllocationInstructionView
​
originalInstructionCid
Optional (ContractId AllocationInstruction)
The contract id of the first allocation instruction contract of thisallocation instruction workflow, if this is not the first step of the workflow.This SHOULD be used by wallets to correlate the same allocation instruction acrossupdates to its state. It should not be used to correlate different allocationinstructions for the same settlement. That can be done using the allocation.settlement field.
​
settlement
SettlementInfo
The settlement for which this allocation is made.
​
allocation
AllocationSpecification
The allocation that this instruction should create.
​
requestedAt
Time
The time at which the allocation was originally requested.
​
inputHoldingCids
[ContractId Holding]
The holdings to be used to fund the allocation.Empty for allocations that do not require funding.MAY be empty for registries that do not represent their holdings on-ledger.
​
expiresAt
Optional Time
The time at which the allocation instruction expires if inactive.Registries MAY expire the allocation instruction after this time.Thereby recovering storage resources and protecting themselves fromdenial-of-service attacks.Registries SHOULD avoid unnecessary expiries by
  • making the expiry time as close to the allocation’s settlement deadline as possible
  • bumping expiry on every action on the allocation instruction
​
availableActions
Map AllocationInstructionAction [[Party]]
What actions are available to which groups of parties. The list of listsis interpreted as a set of sets and represents a disjunction ofconjunctions of parties, i.e., each inner list represents a group ofparties that can act jointly to execute the action.This field can be used to inform wallet users whether they can take an action or not;and which other parties they might be waiting on to take their action.Supports multiple parties for actions that require joint authorization. Executing themwill require appropriate, registry-specific delegation contracts to be in place.
​
meta
Metadata
Additional metadata specific to the allocation instruction, used forextensibility; e.g., more detailed status information.
Instances:

​
Functions

​
allocationInstruction_withdrawImpl

allocationInstruction_withdrawImpl : AllocationInstruction -> ContractId AllocationInstruction -> AllocationInstruction_Withdraw -> Update AllocationInstructionResult

​
allocationInstruction_withdrawExtraObservers

allocationInstruction_withdrawExtraObservers : AllocationInstruction -> AllocationInstruction_Withdraw -> [Party]

​
allocationInstruction_acceptImpl

allocationInstruction_acceptImpl : AllocationInstruction -> ContractId AllocationInstruction -> AllocationInstruction_Accept -> Update AllocationInstructionResult

​
allocationInstruction_acceptExtraObservers

allocationInstruction_acceptExtraObservers : AllocationInstruction -> AllocationInstruction_Accept -> [Party]

​
allocationFactory_allocateExtraObservers

allocationFactory_allocateExtraObservers : AllocationFactory -> AllocationFactory_Allocate -> [Party]

​
allocationFactory_allocateImpl

allocationFactory_allocateImpl : AllocationFactory -> ContractId AllocationFactory -> AllocationFactory_Allocate -> Update AllocationInstructionResult

​
allocationFactory_publicFetchImpl

allocationFactory_publicFetchImpl : AllocationFactory -> ContractId AllocationFactory -> AllocationFactory_PublicFetch -> Update AllocationFactoryView