Skip to main content

​
Splice.Api.Token.TransferInstructionV2

V2 API to instruct transfers of holdings between accounts.

​
Interfaces

​
Interface TransferFactory

A factory contract to instruct transfers of holdings between parties. View Type: TransferFactoryView Choices:

​
Choice Archive

Controllers: Signatories of implementing template Returns: ()

​
Choice TransferFactory_PublicFetch

Fetch the view of the factory contract. Controllers: actors Returns: TransferFactoryView Arguments:
​
[Party]
Set of parties executing the fetch.

​
Choice TransferFactory_Transfer

Instruct the registry to execute a transfer. Implementations MUST ensure that this choice fails if transfer.executeBefore is in the past. Controllers: actors Returns: TransferInstructionResult Arguments:
​
Transfer
The transfer to execute.Implementations MUST validate that the admin of the transferred instrumentmatches the admin of the factory.
​
[Party]
Set of parties executing the transfer.Implementations MUST check these parties to avoid unauthorized transfer instructions.Implementations SHOULD
  • complete the transfer in a single-step if the actors include all
parties required to authorize the transfer
  • allow all the sender’s account parties to call this choice, so they
can all initiate a transfer on their own
​
ExtraArgs
The extra arguments to pass to the transfer implementation.
Methods:

​
Method transferFactory_publicFetchImpl

Type: ContractId TransferFactory -> TransferFactory_PublicFetch -> Update TransferFactoryView

​
Method transferFactory_transferExtraObservers

Type: TransferFactory_Transfer -> [Party]

​
Method transferFactory_transferImpl

Type: ContractId TransferFactory -> TransferFactory_Transfer -> Update TransferInstructionResult

​
Interface TransferInstruction

An interface for tracking the status of a transfer instruction, i.e., a request to a registry app to execute a transfer. View Type: TransferInstructionView Choices:

​
Choice Archive

Controllers: Signatories of implementing template Returns: ()

​
Choice TransferInstruction_Accept

Accept the transfer instruction as someone that needs to authorize it, either on the sending or receiving side. Implementations MUST ensure that the transfer instruction is archived upon acceptance. They SHOULD do so by calling TransferInstructionV1.TransferInstruction_Accept where possible to maximize compatibility with v1 transaction parsers. Note that while implementations will typically return TransferInstructionResult_Completed, this is not guaranteed. The result of the choice is implementation-specific and MAY be any of the three possible results. Controllers: actors Returns: TransferInstructionResult Arguments:
​
[Party]
Set of parties executing the acceptance.Implementations MUST check these parties to avoid unauthorized acceptance.Implementations SHOULD allow the owner and the provider of the recipientaccount to call this choice.
​
ExtraArgs
Additional context required in order to exercise the choice.

​
Choice TransferInstruction_Reject

Reject the transfer offer represented by the transfer instruction. Implementations MUST ensure that the transfer instruction is archived upon rejection. They SHOULD do so by calling TransferInstructionV1.TransferInstruction_Reject where possible to maximize compatibility with v1 transaction parsers. Controllers: actors Returns: TransferInstructionResult Arguments:
​
[Party]
Set of parties executing the rejection.Implementations MUST check these parties to avoid unauthorized rejection.Implementations SHOULD allow the owner and the provider of the recipientaccount to call this choice.
​
ExtraArgs
Additional context required in order to exercise the choice.

​
Choice TransferInstruction_Withdraw

Withdraw the transfer offer represented by the transfer instruction. Implementations MUST ensure that the transfer instruction is archived upon withdrawal. They SHOULD do so by calling TransferInstructionV1.TransferInstruction_Withdraw where possible to maximize compatibility with v1 transaction parsers. Controllers: actors Returns: TransferInstructionResult Arguments:
​
[Party]
Set of parties executing the withdrawal.Implementations MUST check these parties to avoid unauthorized withdrawal.Implementations SHOULD allow the owner and the provider of the senderaccount to call this choice.
​
ExtraArgs
Additional context required in order to exercise the choice.
Methods:

​
Method transferInstruction_acceptExtraObservers

Type: TransferInstruction_Accept -> [Party]

​
Method transferInstruction_acceptImpl

Type: ContractId TransferInstruction -> TransferInstruction_Accept -> Update TransferInstructionResult

​
Method transferInstruction_rejectExtraObservers

Type: TransferInstruction_Reject -> [Party]

​
Method transferInstruction_rejectImpl

Type: ContractId TransferInstruction -> TransferInstruction_Reject -> Update TransferInstructionResult

​
Method transferInstruction_withdrawExtraObservers

Type: TransferInstruction_Withdraw -> [Party]

​
Method transferInstruction_withdrawImpl

Type: ContractId TransferInstruction -> TransferInstruction_Withdraw -> Update TransferInstructionResult

​
Data Types

​
data Transfer

A specification of a transfer of holdings between two accounts. Constructors:
  • Transfer
​
Account
The sender of the transfer.
​
Account
The receiver of the transfer.
​
Decimal
The amount to transfer.
​
InstrumentId
The instrument identifier.
​
Time
Wallet provided timestamp when the transfer was requested.MUST be in the past when instructing the transfer.
​
Time
Until when (exclusive) the transfer may be executed. MUST be in thefuture when instructing the transfer.Registries SHOULD NOT execute the transfer instruction after this time,so that senders can retry creating a new transfer instruction after this time.Registries MAY limit the duration between requestedAt andexecuteBefore to limit the resources spent on tracking activetransfer instructions.
​
[ContractId Holding]
The holding contracts that should be used to fund the transfer.The holdings MUST be owned by the sender account, and match theinstrument specified by the transfer.MAY be empty if the registry supports automatic selection of holdings for transfersor does not represent holdings on-ledger.If specified, then the transfer MUST archive all of these holdings, sothat the execution of the transfer conflicts with any other transfersusing these holdings. Thereby allowing that the sender can usedeliberate contention on holdings to prevent duplicate transfers.
​
Metadata
Metadata.
Instances:

​
data TransferFactoryView

View for TransferFactory. Constructors:
  • TransferFactoryView
​
Party
The party representing the registry app that administers the instruments forwhich this transfer factory can be used.
​
Metadata
Additional metadata specific to the transfer factory, used for extensibility.
Instances:

​
data TransferInstructionAction

Actions to advance the state of a transfer instruction. Constructors:
  • TIA_Accept
  • TIA_Reject
  • TIA_Withdraw
  • TIA_Custom
​
Text
Identifier of the action. Namespaced analogously to metadata keys.
Used to represent registry-specific actions that need to happen for the transfer instruction to advance. Instances:

​
data TransferInstructionResult

The result of instructing a transfer or advancing the state of a transfer instruction. Constructors:
  • TransferInstructionResult
​
TransferInstructionResult_Output
The output of the step.
​
[ContractId Holding]
New holdings owned by the sender created to return “change”. Can be usedby actors to batch creating or updating multiple transfer instructionsin a single Daml transaction.
​
Metadata
Additional metadata specific to the transfer instruction, used for extensibility; e.g., fees charged.
Instances:

​
data TransferInstructionResult_Output

The output of instructing a transfer or advancing the state of a transfer instruction. Constructors:
  • TransferInstructionResult_Pending
​
ContractId TransferInstruction
Contract id of the transfer instruction representing the pending state.
Use this result to communicate that the transfer is pending further steps.
  • TransferInstructionResult_Completed
​
[ContractId Holding]
The newly created holdings owned by the receiver as part of successfullycompleting the transfer.MAY be empty if the registry does not represent holdings on-ledger.
Use this result to communicate that the transfer succeeded and the receiver has received their holdings.
  • TransferInstructionResult_Failed
Use this result to communicate that the transfer did not succeed and all holdings (minus fees) have been returned to the sender. Instances:

​
data TransferInstructionView

View for TransferInstruction. Constructors:
  • TransferInstructionView
​
Optional (ContractId TransferInstruction)
The contract id of the original transfer instruction contract, which is Nonefor the original transfer instruction itself.This SHOULD be used by wallets to correlate the same transfer instruction acrossupdates to its state.
​
Transfer
The transfer specified by the transfer instruction.
​
Optional Time
The time at which the transfer instruction expires if inactive.Registries MAY expire the transfer instruction after this time. Therebyrecovering storage resources and protecting themselves fromdenial-of-service attacks.Registries SHOULD avoid unnecessary expiries by
  • making the expiry time as close to the transfer’s executeBefore as possible
  • bumping expiry on every action on the transfer instruction
​
Map TransferInstructionAction [[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.
​
Metadata
Additional metadata specific to the transfer instruction, used for extensibility; e.g., more detailed status information.
Instances:

​
Functions

​
transferInstruction_acceptImpl

transferInstruction_acceptImpl : TransferInstruction -> ContractId TransferInstruction -> TransferInstruction_Accept -> Update TransferInstructionResult

​
transferInstruction_rejectImpl

transferInstruction_rejectImpl : TransferInstruction -> ContractId TransferInstruction -> TransferInstruction_Reject -> Update TransferInstructionResult

​
transferInstruction_withdrawImpl

transferInstruction_withdrawImpl : TransferInstruction -> ContractId TransferInstruction -> TransferInstruction_Withdraw -> Update TransferInstructionResult

​
transferInstruction_acceptExtraObservers

transferInstruction_acceptExtraObservers : TransferInstruction -> TransferInstruction_Accept -> [Party]

​
transferInstruction_rejectExtraObservers

transferInstruction_rejectExtraObservers : TransferInstruction -> TransferInstruction_Reject -> [Party]

​
transferInstruction_withdrawExtraObservers

transferInstruction_withdrawExtraObservers : TransferInstruction -> TransferInstruction_Withdraw -> [Party]

​
transferFactory_transferExtraObservers

transferFactory_transferExtraObservers : TransferFactory -> TransferFactory_Transfer -> [Party]

​
transferFactory_transferImpl

transferFactory_transferImpl : TransferFactory -> ContractId TransferFactory -> TransferFactory_Transfer -> Update TransferInstructionResult

​
transferFactory_publicFetchImpl

transferFactory_publicFetchImpl : TransferFactory -> ContractId TransferFactory -> TransferFactory_PublicFetch -> Update TransferFactoryView