.. _module-splice-api-token-allocationv1-39050: Splice.Api.Token.AllocationV1 ============================= This module defines the ``Allocation`` interface and supporting types\. Contracts implementing the ``Allocation`` interface represent a reservation of assets to transfer them as part of an atomic on\-ledger settlement requested by an app\. Interfaces ---------- .. _type-splice-api-token-allocationv1-allocation-9928: **interface** `Allocation `_ A contract representing an allocation of some amount of aasset holdings to a specific leg of a settlement\. **viewtype** `AllocationView `_ + .. _type-splice-api-token-allocationv1-allocationcancel-25504: **Choice** `Allocation_Cancel `_ Cancel the allocation\. Requires authorization from sender, receiver, and executor\. Typically this authorization is granted by sender and receiver to the executor as part of the contract coordinating the settlement, so that that the executor can release the allocated assets early in case the settlement is aborted or it has definitely failed\. Controller\: allocationControllers (view this) Returns\: `Allocation_CancelResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - extraArgs - ExtraArgs - Additional context required in order to exercise the choice\. + .. _type-splice-api-token-allocationv1-allocationexecutetransfer-74529: **Choice** `Allocation_ExecuteTransfer `_ Execute the transfer of the allocated assets\. Intended to be used to execute the settlement\. This choice SHOULD succeed provided the ``settlement.settleBefore`` deadline has not yet passed\. Controller\: allocationControllers (view this) Returns\: `Allocation_ExecuteTransferResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - extraArgs - ExtraArgs - Additional context required in order to exercise the choice\. + .. _type-splice-api-token-allocationv1-allocationwithdraw-60458: **Choice** `Allocation_Withdraw `_ Withdraw the allocated assets\. Used by the sender to withdraw the assets before settlement was completed\. This SHOULD not fail settlement if the sender has still time to allocate the assets again; i\.e\., the ``settlement.allocateBefore`` deadline has not yet passed\. Controller\: (DA\.Internal\.Record\.getField @\"sender\" (DA\.Internal\.Record\.getField @\"transferLeg\" (DA\.Internal\.Record\.getField @\"allocation\" (view this)))) Returns\: `Allocation_WithdrawResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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 allocation\_cancelImpl \:** `ContractId `_ `Allocation `_ \-\> `Allocation_Cancel `_ \-\> `Update `_ `Allocation_CancelResult `_ + **Method allocation\_executeTransferImpl \:** `ContractId `_ `Allocation `_ \-\> `Allocation_ExecuteTransfer `_ \-\> `Update `_ `Allocation_ExecuteTransferResult `_ + **Method allocation\_withdrawImpl \:** `ContractId `_ `Allocation `_ \-\> `Allocation_Withdraw `_ \-\> `Update `_ `Allocation_WithdrawResult `_ Data Types ---------- .. _type-splice-api-token-allocationv1-allocationspecification-94148: **data** `AllocationSpecification `_ The specification of an allocation of assets to a specific leg of a settlement\. In contrast to an ``AllocationView`` this just specifies what should be allocated, but not the holdings that are backing the allocation\. .. _constr-splice-api-token-allocationv1-allocationspecification-66543: `AllocationSpecification `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - settlement - `SettlementInfo `_ - The settlement for whose execution the assets are being allocated\. * - transferLegId - `Text `_ - A unique identifer for the transfer leg within the settlement\. * - transferLeg - `TransferLeg `_ - The transfer for which the assets are being allocated\. **instance** `Eq `_ `AllocationSpecification `_ **instance** `Show `_ `AllocationSpecification `_ **instance** `GetField `_ \"allocation\" `AllocationView `_ `AllocationSpecification `_ **instance** `GetField `_ \"settlement\" `AllocationSpecification `_ `SettlementInfo `_ **instance** `GetField `_ \"transferLeg\" `AllocationSpecification `_ `TransferLeg `_ **instance** `GetField `_ \"transferLegId\" `AllocationSpecification `_ `Text `_ **instance** `SetField `_ \"allocation\" `AllocationView `_ `AllocationSpecification `_ **instance** `SetField `_ \"settlement\" `AllocationSpecification `_ `SettlementInfo `_ **instance** `SetField `_ \"transferLeg\" `AllocationSpecification `_ `TransferLeg `_ **instance** `SetField `_ \"transferLegId\" `AllocationSpecification `_ `Text `_ .. _type-splice-api-token-allocationv1-allocationview-9103: **data** `AllocationView `_ View of a funded allocation of assets to a specific leg of a settlement\. .. _constr-splice-api-token-allocationv1-allocationview-89090: `AllocationView `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - allocation - `AllocationSpecification `_ - The settlement for whose execution the assets are being allocated\. * - holdingCids - \[`ContractId `_ Holding\] - The holdings that are backing this allocation\. Provided so that that wallets can correlate the allocation with the holdings\. MAY be empty for registries that do not represent their holdings on\-ledger\. * - meta - Metadata - Additional metadata specific to the allocation, used for extensibility\. **instance** `Eq `_ `AllocationView `_ **instance** `Show `_ `AllocationView `_ **instance** `HasFromAnyView `_ `Allocation `_ `AllocationView `_ **instance** `HasInterfaceView `_ `Allocation `_ `AllocationView `_ **instance** `GetField `_ \"allocation\" `AllocationView `_ `AllocationSpecification `_ **instance** `GetField `_ \"holdingCids\" `AllocationView `_ \[`ContractId `_ Holding\] **instance** `GetField `_ \"meta\" `AllocationView `_ Metadata **instance** `SetField `_ \"allocation\" `AllocationView `_ `AllocationSpecification `_ **instance** `SetField `_ \"holdingCids\" `AllocationView `_ \[`ContractId `_ Holding\] **instance** `SetField `_ \"meta\" `AllocationView `_ Metadata .. _type-splice-api-token-allocationv1-allocationcancelresult-26037: **data** `Allocation_CancelResult `_ The result of the ``Allocation_Cancel`` choice\. .. _constr-splice-api-token-allocationv1-allocationcancelresult-74846: `Allocation_CancelResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - senderHoldingCids - \[`ContractId `_ Holding\] - The holdings that were released back to the sender\. * - meta - Metadata - Additional metadata specific to the allocation, used for extensibility\. **instance** `Eq `_ `Allocation_CancelResult `_ **instance** `Show `_ `Allocation_CancelResult `_ **instance** HasMethod `Allocation `_ \"allocation\_cancelImpl\" (`ContractId `_ `Allocation `_ \-\> `Allocation_Cancel `_ \-\> `Update `_ `Allocation_CancelResult `_) **instance** `GetField `_ \"meta\" `Allocation_CancelResult `_ Metadata **instance** `GetField `_ \"senderHoldingCids\" `Allocation_CancelResult `_ \[`ContractId `_ Holding\] **instance** `SetField `_ \"meta\" `Allocation_CancelResult `_ Metadata **instance** `SetField `_ \"senderHoldingCids\" `Allocation_CancelResult `_ \[`ContractId `_ Holding\] **instance** `HasExercise `_ `Allocation `_ `Allocation_Cancel `_ `Allocation_CancelResult `_ **instance** `HasExerciseGuarded `_ `Allocation `_ `Allocation_Cancel `_ `Allocation_CancelResult `_ **instance** `HasFromAnyChoice `_ `Allocation `_ `Allocation_Cancel `_ `Allocation_CancelResult `_ **instance** `HasToAnyChoice `_ `Allocation `_ `Allocation_Cancel `_ `Allocation_CancelResult `_ .. _type-splice-api-token-allocationv1-allocationexecutetransferresult-74160: **data** `Allocation_ExecuteTransferResult `_ The result of the ``Allocation_ExecuteTransfer`` choice\. .. _constr-splice-api-token-allocationv1-allocationexecutetransferresult-50341: `Allocation_ExecuteTransferResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - senderHoldingCids - \[`ContractId `_ Holding\] - The holdings that were created for the sender\. Can be used to return \"change\" to the sender if required\. * - receiverHoldingCids - \[`ContractId `_ Holding\] - The holdings that were created for the receiver\. * - meta - Metadata - Additional metadata specific to the transfer instruction, used for extensibility\. **instance** `Eq `_ `Allocation_ExecuteTransferResult `_ **instance** `Show `_ `Allocation_ExecuteTransferResult `_ **instance** HasMethod `Allocation `_ \"allocation\_executeTransferImpl\" (`ContractId `_ `Allocation `_ \-\> `Allocation_ExecuteTransfer `_ \-\> `Update `_ `Allocation_ExecuteTransferResult `_) **instance** `GetField `_ \"meta\" `Allocation_ExecuteTransferResult `_ Metadata **instance** `GetField `_ \"receiverHoldingCids\" `Allocation_ExecuteTransferResult `_ \[`ContractId `_ Holding\] **instance** `GetField `_ \"senderHoldingCids\" `Allocation_ExecuteTransferResult `_ \[`ContractId `_ Holding\] **instance** `SetField `_ \"meta\" `Allocation_ExecuteTransferResult `_ Metadata **instance** `SetField `_ \"receiverHoldingCids\" `Allocation_ExecuteTransferResult `_ \[`ContractId `_ Holding\] **instance** `SetField `_ \"senderHoldingCids\" `Allocation_ExecuteTransferResult `_ \[`ContractId `_ Holding\] **instance** `HasExercise `_ `Allocation `_ `Allocation_ExecuteTransfer `_ `Allocation_ExecuteTransferResult `_ **instance** `HasExerciseGuarded `_ `Allocation `_ `Allocation_ExecuteTransfer `_ `Allocation_ExecuteTransferResult `_ **instance** `HasFromAnyChoice `_ `Allocation `_ `Allocation_ExecuteTransfer `_ `Allocation_ExecuteTransferResult `_ **instance** `HasToAnyChoice `_ `Allocation `_ `Allocation_ExecuteTransfer `_ `Allocation_ExecuteTransferResult `_ .. _type-splice-api-token-allocationv1-allocationwithdrawresult-40879: **data** `Allocation_WithdrawResult `_ The result of the ``Allocation_Withdraw`` choice\. .. _constr-splice-api-token-allocationv1-allocationwithdrawresult-86620: `Allocation_WithdrawResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - senderHoldingCids - \[`ContractId `_ Holding\] - The holdings that were released back to the sender\. * - meta - Metadata - Additional metadata specific to the allocation, used for extensibility\. **instance** `Eq `_ `Allocation_WithdrawResult `_ **instance** `Show `_ `Allocation_WithdrawResult `_ **instance** HasMethod `Allocation `_ \"allocation\_withdrawImpl\" (`ContractId `_ `Allocation `_ \-\> `Allocation_Withdraw `_ \-\> `Update `_ `Allocation_WithdrawResult `_) **instance** `GetField `_ \"meta\" `Allocation_WithdrawResult `_ Metadata **instance** `GetField `_ \"senderHoldingCids\" `Allocation_WithdrawResult `_ \[`ContractId `_ Holding\] **instance** `SetField `_ \"meta\" `Allocation_WithdrawResult `_ Metadata **instance** `SetField `_ \"senderHoldingCids\" `Allocation_WithdrawResult `_ \[`ContractId `_ Holding\] **instance** `HasExercise `_ `Allocation `_ `Allocation_Withdraw `_ `Allocation_WithdrawResult `_ **instance** `HasExerciseGuarded `_ `Allocation `_ `Allocation_Withdraw `_ `Allocation_WithdrawResult `_ **instance** `HasFromAnyChoice `_ `Allocation `_ `Allocation_Withdraw `_ `Allocation_WithdrawResult `_ **instance** `HasToAnyChoice `_ `Allocation `_ `Allocation_Withdraw `_ `Allocation_WithdrawResult `_ .. _type-splice-api-token-allocationv1-reference-53456: **data** `Reference `_ A generic type to refer to data defined within an app\. .. _constr-splice-api-token-allocationv1-reference-11427: `Reference `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - id - `Text `_ - The key that identifies the data\. Can be set to the empty string if the contract\-id is provided and is sufficient\. * - cid - `Optional `_ AnyContractId - Optional contract\-id to use for referring to contracts\. This field is there for technical reasons, as contract\-ids cannot be converted to text from within Daml, which is due to their full textual representation being only known after transactions have been prepared\. **instance** `Eq `_ `Reference `_ **instance** `Show `_ `Reference `_ **instance** `GetField `_ \"cid\" `Reference `_ (`Optional `_ AnyContractId) **instance** `GetField `_ \"id\" `Reference `_ `Text `_ **instance** `GetField `_ \"settlementRef\" `SettlementInfo `_ `Reference `_ **instance** `SetField `_ \"cid\" `Reference `_ (`Optional `_ AnyContractId) **instance** `SetField `_ \"id\" `Reference `_ `Text `_ **instance** `SetField `_ \"settlementRef\" `SettlementInfo `_ `Reference `_ .. _type-splice-api-token-allocationv1-settlementinfo-4367: **data** `SettlementInfo `_ The minimal set of information about a settlement that an app would like to execute\. .. _constr-splice-api-token-allocationv1-settlementinfo-25294: `SettlementInfo `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - executor - `Party `_ - The party that is responsible for executing the settlement\. * - settlementRef - `Reference `_ - Reference to the settlement that app would like to execute\. * - requestedAt - `Time `_ - When the settlement was requested\. Provided for display and debugging purposes, but SHOULD be in the past\. * - allocateBefore - `Time `_ - Until when (exclusive) the senders are given time to allocate their assets\. This field has a particular relevance with respect to instrument versioning / corporate actions, in that the settlement pertains to the instrument version resulting from the processing of all corporate actions falling strictly before the ``allocateBefore`` time\. * - settleBefore - `Time `_ - Until when (exclusive) the executor is given time to execute the settlement\. SHOULD be strictly after ``allocateBefore``\. * - meta - Metadata - Additional metadata about the settlement, used for extensibility\. **instance** `Eq `_ `SettlementInfo `_ **instance** `Show `_ `SettlementInfo `_ **instance** `GetField `_ \"allocateBefore\" `SettlementInfo `_ `Time `_ **instance** `GetField `_ \"executor\" `SettlementInfo `_ `Party `_ **instance** `GetField `_ \"meta\" `SettlementInfo `_ Metadata **instance** `GetField `_ \"requestedAt\" `SettlementInfo `_ `Time `_ **instance** `GetField `_ \"settleBefore\" `SettlementInfo `_ `Time `_ **instance** `GetField `_ \"settlement\" `AllocationSpecification `_ `SettlementInfo `_ **instance** `GetField `_ \"settlementRef\" `SettlementInfo `_ `Reference `_ **instance** `SetField `_ \"allocateBefore\" `SettlementInfo `_ `Time `_ **instance** `SetField `_ \"executor\" `SettlementInfo `_ `Party `_ **instance** `SetField `_ \"meta\" `SettlementInfo `_ Metadata **instance** `SetField `_ \"requestedAt\" `SettlementInfo `_ `Time `_ **instance** `SetField `_ \"settleBefore\" `SettlementInfo `_ `Time `_ **instance** `SetField `_ \"settlement\" `AllocationSpecification `_ `SettlementInfo `_ **instance** `SetField `_ \"settlementRef\" `SettlementInfo `_ `Reference `_ .. _type-splice-api-token-allocationv1-transferleg-71662: **data** `TransferLeg `_ A specification of a transfer of holdings between two parties for the purpose of a settlement, which often requires the atomic execution of multiple legs\. .. _constr-splice-api-token-allocationv1-transferleg-72717: `TransferLeg `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - sender - `Party `_ - The sender of the transfer\. * - receiver - `Party `_ - The receiver of the transfer\. * - amount - `Decimal `_ - The amount to transfer\. * - instrumentId - InstrumentId - The instrument identifier\. * - meta - Metadata - Additional metadata about the transfer leg, used for extensibility\. **instance** `Eq `_ `TransferLeg `_ **instance** `Ord `_ `TransferLeg `_ **instance** `Show `_ `TransferLeg `_ **instance** `GetField `_ \"amount\" `TransferLeg `_ `Decimal `_ **instance** `GetField `_ \"instrumentId\" `TransferLeg `_ InstrumentId **instance** `GetField `_ \"meta\" `TransferLeg `_ Metadata **instance** `GetField `_ \"receiver\" `TransferLeg `_ `Party `_ **instance** `GetField `_ \"sender\" `TransferLeg `_ `Party `_ **instance** `GetField `_ \"transferLeg\" `AllocationSpecification `_ `TransferLeg `_ **instance** `SetField `_ \"amount\" `TransferLeg `_ `Decimal `_ **instance** `SetField `_ \"instrumentId\" `TransferLeg `_ InstrumentId **instance** `SetField `_ \"meta\" `TransferLeg `_ Metadata **instance** `SetField `_ \"receiver\" `TransferLeg `_ `Party `_ **instance** `SetField `_ \"sender\" `TransferLeg `_ `Party `_ **instance** `SetField `_ \"transferLeg\" `AllocationSpecification `_ `TransferLeg `_ Functions --------- .. _function-splice-api-token-allocationv1-allocationcontrollers-10222: `allocationControllers `_ \: `AllocationView `_ \-\> \[`Party `_\] Convenience function to refer to the union of sender, receiver, and executor of the settlement, which jointly control the execution of the allocation\. .. _function-splice-api-token-allocationv1-allocationexecutetransferimpl-90251: `allocation_executeTransferImpl `_ \: `Allocation `_ \-\> `ContractId `_ `Allocation `_ \-\> `Allocation_ExecuteTransfer `_ \-\> `Update `_ `Allocation_ExecuteTransferResult `_ .. _function-splice-api-token-allocationv1-allocationcancelimpl-12334: `allocation_cancelImpl `_ \: `Allocation `_ \-\> `ContractId `_ `Allocation `_ \-\> `Allocation_Cancel `_ \-\> `Update `_ `Allocation_CancelResult `_ .. _function-splice-api-token-allocationv1-allocationwithdrawimpl-40108: `allocation_withdrawImpl `_ \: `Allocation `_ \-\> `ContractId `_ `Allocation `_ \-\> `Allocation_Withdraw `_ \-\> `Update `_ `Allocation_WithdrawResult `_