.. _module-splice-api-token-allocationinstructionv1-81747: Splice.Api.Token.AllocationInstructionV1 ======================================== Interfaces to enable wallets to instruct the registry to create allocations\. Interfaces ---------- .. _type-splice-api-token-allocationinstructionv1-allocationfactory-42588: **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 `_ + .. _type-splice-api-token-allocationinstructionv1-allocationfactoryallocate-8885: **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 `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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\. + .. _type-splice-api-token-allocationinstructionv1-allocationfactorypublicfetch-20324: **Choice** `AllocationFactory_PublicFetch `_ Controller\: actor Returns\: `AllocationFactoryView `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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 `_ .. _type-splice-api-token-allocationinstructionv1-allocationinstruction-29622: **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 `_ + .. _type-splice-api-token-allocationinstructionv1-allocationinstructionupdate-50223: **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 `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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\. + .. _type-splice-api-token-allocationinstructionv1-allocationinstructionwithdraw-35988: **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 `_ .. 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 allocationInstruction\_updateImpl \:** `ContractId `_ `AllocationInstruction `_ \-\> `AllocationInstruction_Update `_ \-\> `Update `_ `AllocationInstructionResult `_ + **Method allocationInstruction\_withdrawImpl \:** `ContractId `_ `AllocationInstruction `_ \-\> `AllocationInstruction_Withdraw `_ \-\> `Update `_ `AllocationInstructionResult `_ Data Types ---------- .. _type-splice-api-token-allocationinstructionv1-allocationfactoryview-21751: **data** `AllocationFactoryView `_ View for ``AllocationFactory``\. .. _constr-splice-api-token-allocationinstructionv1-allocationfactoryview-66354: `AllocationFactoryView `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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 `_ .. _type-splice-api-token-allocationinstructionv1-allocationinstructionresult-30943: **data** `AllocationInstructionResult `_ The result of instructing an allocation or advancing the state of an allocation instruction\. .. _constr-splice-api-token-allocationinstructionv1-allocationinstructionresult-54130: `AllocationInstructionResult `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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 `_ .. _type-splice-api-token-allocationinstructionv1-allocationinstructionresultoutput-46212: **data** `AllocationInstructionResult_Output `_ The output of instructing an allocation or advancing the state of an allocation instruction\. .. _constr-splice-api-token-allocationinstructionv1-allocationinstructionresultpending-58494: `AllocationInstructionResult_Pending `_ Use this result to communicate that the creation of the allocation is pending further steps\. .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - allocationInstructionCid - `ContractId `_ `AllocationInstruction `_ - Contract id of the allocation instruction representing the pending state\. .. _constr-splice-api-token-allocationinstructionv1-allocationinstructionresultcompleted-89210: `AllocationInstructionResult_Completed `_ Use this result to communicate that the allocation was created\. .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Field - Type - Description * - allocationCid - `ContractId `_ Allocation - The newly created allocation\. .. _constr-splice-api-token-allocationinstructionv1-allocationinstructionresultfailed-56799: `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 `_ .. _type-splice-api-token-allocationinstructionv1-allocationinstructionview-72001: **data** `AllocationInstructionView `_ View for ``AllocationInstruction``\. .. _constr-splice-api-token-allocationinstructionv1-allocationinstructionview-32140: `AllocationInstructionView `_ .. list-table:: :widths: 15 10 30 :header-rows: 1 * - 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 --------- .. _function-splice-api-token-allocationinstructionv1-allocationinstructionwithdrawimpl-26170: `allocationInstruction_withdrawImpl `_ \: `AllocationInstruction `_ \-\> `ContractId `_ `AllocationInstruction `_ \-\> `AllocationInstruction_Withdraw `_ \-\> `Update `_ `AllocationInstructionResult `_ .. _function-splice-api-token-allocationinstructionv1-allocationinstructionupdateimpl-49061: `allocationInstruction_updateImpl `_ \: `AllocationInstruction `_ \-\> `ContractId `_ `AllocationInstruction `_ \-\> `AllocationInstruction_Update `_ \-\> `Update `_ `AllocationInstructionResult `_ .. _function-splice-api-token-allocationinstructionv1-allocationfactoryallocateimpl-1231: `allocationFactory_allocateImpl `_ \: `AllocationFactory `_ \-\> `ContractId `_ `AllocationFactory `_ \-\> `AllocationFactory_Allocate `_ \-\> `Update `_ `AllocationInstructionResult `_ .. _function-splice-api-token-allocationinstructionv1-allocationfactorypublicfetchimpl-77778: `allocationFactory_publicFetchImpl `_ \: `AllocationFactory `_ \-\> `ContractId `_ `AllocationFactory `_ \-\> `AllocationFactory_PublicFetch `_ \-\> `Update `_ `AllocationFactoryView `_