Splice.Api.Token.AllocationInstructionV1

Documentation for Splice.Api.Token.AllocationInstructionV1

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

viewtype AllocationFactoryView

• Choice AllocationFactory_Allocate

  Generic choice for the sender’s wallet to request the allocation of assets to a specific leg of a settlement. It depends on the registry whether this results in the allocation being created directly or in an allocation instruction being created instead.

  Controller: (DA.Internal.Record.getField @“sender” (DA.Internal.Record.getField @“transferLeg” allocation))

  Returns: AllocationInstructionResult

  Field	Type	Description
  expectedAdmin	Party	The expected admin party issuing the factory. Implementations MUST validate that this matches the admin of the factory. Callers should ensure they get expectedAdmin from a trusted source, e.g., a read against their own participant. That way they can ensure that it is safe to exercise a choice on a factory contract acquired from an untrusted source provided all vetted Daml packages only contain interface implementations that check the expected admin party.
  allocation	AllocationSpecification	The allocation which should be created.
  requestedAt	Time	The time at which the allocation was requested.
  inputHoldingCids	[ContractId Holding]	The holdings that SHOULD be used to fund the allocation. MAY be empty for registries that do not represent their holdings on-ledger; or for registries that support automatic selection of holdings for allocations. If specified, then the successful allocation MUST archive all of these holdings, so that the execution of the allocation conflicts with any other allocations using these holdings. Thereby allowing that the sender can use deliberate contention on holdings to prevent duplicate allocations.
  extraArgs	ExtraArgs	Additional choice arguments.

• Choice AllocationFactory_PublicFetch

  Controller: actor

  Returns: AllocationFactoryView

  Field	Type	Description
  expectedAdmin	Party	The expected admin party issuing the factory. Implementations MUST validate that this matches the admin of the factory. Callers should ensure they get expectedAdmin from a trusted source, e.g., a read against their own participant. That way they can ensure that it is safe to exercise a choice on a factory contract acquired from an untrusted source provided all vetted Daml packages only contain interface implementations that check the expected admin party.
  actor	Party

• Choice Archive

  Controller: Signatories of implementing template

  Returns: ()

  (no fields)

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

• Method allocationFactory_publicFetchImpl : 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.

viewtype AllocationInstructionView

• Choice AllocationInstruction_Update

  Update the state of the allocation instruction. Used by the registry to execute registry internal workflow steps that advance the state of the allocation instruction. A reason may be communicated via the metadata.

  Controller: (DA.Internal.Record.getField @“admin” (DA.Internal.Record.getField @“instrumentId” (DA.Internal.Record.getField @“transferLeg” (DA.Internal.Record.getField @“allocation” (view this))))), extraActors

  Returns: AllocationInstructionResult

  Field	Type	Description
  extraActors	[Party]	Extra actors authorizing the update. Implementations MUST check that this field contains the expected actors for the specific update.
  extraArgs	ExtraArgs	Additional context required in order to exercise the choice.

• Choice AllocationInstruction_Withdraw

  Withdraw the allocation instruction as the sender.

  Controller: (DA.Internal.Record.getField @“sender” (DA.Internal.Record.getField @“transferLeg” (DA.Internal.Record.getField @“allocation” (view this))))

  Returns: AllocationInstructionResult

  Field	Type	Description
  extraArgs	ExtraArgs	Additional context required in order to exercise the choice.

• Choice Archive

  Controller: Signatories of implementing template

  Returns: ()

  (no fields)

• Method allocationInstruction_updateImpl : ContractId AllocationInstruction -> AllocationInstruction_Update -> Update AllocationInstructionResult

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

Data Types

data AllocationFactoryView

View for AllocationFactory.

AllocationFactoryView

Field	Type	Description
admin	Party	The party representing the registry app that administers the instruments for which this allocation factory can be used.
meta	Metadata	Additional metadata specific to the allocation factory, used for extensibility.

instance Eq AllocationFactoryView

instance Show AllocationFactoryView

instance HasMethod AllocationFactory “allocationFactory_publicFetchImpl” (ContractId AllocationFactory -> AllocationFactory_PublicFetch -> Update AllocationFactoryView)

instance HasFromAnyView AllocationFactory AllocationFactoryView

instance HasInterfaceView AllocationFactory AllocationFactoryView

instance GetField “admin” AllocationFactoryView Party

instance GetField “meta” AllocationFactoryView Metadata

instance SetField “admin” AllocationFactoryView Party

instance SetField “meta” AllocationFactoryView Metadata

instance HasExercise AllocationFactory AllocationFactory_PublicFetch AllocationFactoryView

instance HasExerciseGuarded AllocationFactory AllocationFactory_PublicFetch AllocationFactoryView

instance HasFromAnyChoice AllocationFactory AllocationFactory_PublicFetch AllocationFactoryView

instance HasToAnyChoice AllocationFactory AllocationFactory_PublicFetch AllocationFactoryView

data AllocationInstructionResult

The result of instructing an allocation or advancing the state of an allocation instruction.

AllocationInstructionResult

Field	Type	Description
output	AllocationInstructionResult_Output	The output of the step.
senderChangeCids	[ContractId Holding]	New holdings owned by the sender created to return “change”. Can be used by callers to batch creating or updating multiple allocation instructions in a single Daml transaction.
meta	Metadata	Additional metadata specific to the allocation instruction, used for extensibility; e.g., fees charged.

instance Eq AllocationInstructionResult

instance Show AllocationInstructionResult

instance HasMethod AllocationFactory “allocationFactory_allocateImpl” (ContractId AllocationFactory -> AllocationFactory_Allocate -> Update AllocationInstructionResult)

instance HasMethod AllocationInstruction “allocationInstruction_updateImpl” (ContractId AllocationInstruction -> AllocationInstruction_Update -> Update AllocationInstructionResult)

instance HasMethod AllocationInstruction “allocationInstruction_withdrawImpl” (ContractId AllocationInstruction -> AllocationInstruction_Withdraw -> Update AllocationInstructionResult)

instance GetField “meta” AllocationInstructionResult Metadata

instance GetField “output” AllocationInstructionResult AllocationInstructionResult_Output

instance GetField “senderChangeCids” AllocationInstructionResult [ContractId Holding]

instance SetField “meta” AllocationInstructionResult Metadata

instance SetField “output” AllocationInstructionResult AllocationInstructionResult_Output

instance SetField “senderChangeCids” AllocationInstructionResult [ContractId Holding]

instance HasExercise AllocationFactory AllocationFactory_Allocate AllocationInstructionResult

instance HasExercise AllocationInstruction AllocationInstruction_Update AllocationInstructionResult

instance HasExercise AllocationInstruction AllocationInstruction_Withdraw AllocationInstructionResult

instance HasExerciseGuarded AllocationFactory AllocationFactory_Allocate AllocationInstructionResult

instance HasExerciseGuarded AllocationInstruction AllocationInstruction_Update AllocationInstructionResult

instance HasExerciseGuarded AllocationInstruction AllocationInstruction_Withdraw AllocationInstructionResult

instance HasFromAnyChoice AllocationFactory AllocationFactory_Allocate AllocationInstructionResult

instance HasFromAnyChoice AllocationInstruction AllocationInstruction_Update AllocationInstructionResult

instance HasFromAnyChoice AllocationInstruction AllocationInstruction_Withdraw AllocationInstructionResult

instance HasToAnyChoice AllocationFactory AllocationFactory_Allocate AllocationInstructionResult

instance HasToAnyChoice AllocationInstruction AllocationInstruction_Update AllocationInstructionResult

instance HasToAnyChoice AllocationInstruction AllocationInstruction_Withdraw AllocationInstructionResult

data AllocationInstructionResult_Output

The output of instructing an allocation or advancing the state of an allocation instruction.

AllocationInstructionResult_Pending

Use this result to communicate that the creation of the allocation is pending further steps.

Field	Type	Description
allocationInstructionCid	ContractId AllocationInstruction	Contract id of the allocation instruction representing the pending state.

AllocationInstructionResult_Completed

Use this result to communicate that the allocation was created.

Field	Type	Description
allocationCid	ContractId Allocation	The newly created allocation.

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.

instance Eq AllocationInstructionResult_Output

instance Show AllocationInstructionResult_Output

instance GetField “allocationCid” AllocationInstructionResult_Output (ContractId Allocation)

instance GetField “allocationInstructionCid” AllocationInstructionResult_Output (ContractId AllocationInstruction)

instance GetField “output” AllocationInstructionResult AllocationInstructionResult_Output

instance SetField “allocationCid” AllocationInstructionResult_Output (ContractId Allocation)

instance SetField “allocationInstructionCid” AllocationInstructionResult_Output (ContractId AllocationInstruction)

instance SetField “output” AllocationInstructionResult AllocationInstructionResult_Output

data AllocationInstructionView

View for AllocationInstruction.

AllocationInstructionView

Field	Type	Description
originalInstructionCid	Optional (ContractId AllocationInstruction)	The contract id of the original allocation instruction contract. Used by the wallet to track the lineage of allocation instructions through multiple steps. Only set if the registry evolves the allocation instruction in multiple steps.
allocation	AllocationSpecification	The allocation that this instruction should create.
pendingActions	Map Party Text	The pending actions to be taken by different actors to create the allocation. ^ This field can by used to report on the progress of registry specific workflows that are required to prepare the allocation.
requestedAt	Time	The time at which the allocation was requested.
inputHoldingCids	[ContractId Holding]	The holdings to be used to fund the allocation. MAY be empty for registries that do not represent their holdings on-ledger.
meta	Metadata	Additional metadata specific to the allocation instruction, used for extensibility; e.g., more detailed status information.

instance Eq AllocationInstructionView

instance Show AllocationInstructionView

instance HasFromAnyView AllocationInstruction AllocationInstructionView

instance HasInterfaceView AllocationInstruction AllocationInstructionView

instance GetField “allocation” AllocationInstructionView AllocationSpecification

instance GetField “inputHoldingCids” AllocationInstructionView [ContractId Holding]

instance GetField “meta” AllocationInstructionView Metadata

instance GetField “originalInstructionCid” AllocationInstructionView (Optional (ContractId AllocationInstruction))

instance GetField “pendingActions” AllocationInstructionView (Map Party Text)

instance GetField “requestedAt” AllocationInstructionView Time

instance SetField “allocation” AllocationInstructionView AllocationSpecification

instance SetField “inputHoldingCids” AllocationInstructionView [ContractId Holding]

instance SetField “meta” AllocationInstructionView Metadata

instance SetField “originalInstructionCid” AllocationInstructionView (Optional (ContractId AllocationInstruction))

instance SetField “pendingActions” AllocationInstructionView (Map Party Text)

instance SetField “requestedAt” AllocationInstructionView Time

Functions

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

allocationInstruction_updateImpl : AllocationInstruction -> ContractId AllocationInstruction -> AllocationInstruction_Update -> Update AllocationInstructionResult

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

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