Deprecated

This Splice documentation site is deprecated. Use the current Canton Network docs.

Open current docs

Splice.Api.Token.AllocationRequestV2

V2 of the AllocationRequest interface, which is used by applications to inform their users that they should create allocations for a specific settlement.

Users may view and react to these requests using for example a token standard wallet or custom automation that uses the Ledger API directly.

Interfaces

interface AllocationRequest

A request by an app for allocations to be created to enable the execution of a settlement.

Apps MAY use one or more requests per settlement, depending on their needs and confidentiality requirements.

Apps SHOULD have as contract observers both the owners and providers of all authorizer accounts that need to create requested allocations.

viewtype AllocationRequestView

• Choice AllocationRequest_Accept

  Signal to settlement.executors that the requested allocations were or will be created.

  Wallets MAY call this choice in the same transaction as the creation of the requested allocations to protect from creating the same allocations multiple times.

  Apps MUST cleanup allocation requests independently of whether this choice is called, as there is no guarantee that the choice will be called.

  IMPORTANT: implementations MUST ensure that the allocation request is consumed by the body of this choice.

  Controller: actors

  Returns: AllocationRequest_AcceptResult

  Field	Type	Description
  actors	[Party]	Set of parties executing the acceptance. Implementations MUST check these parties to avoid unauthorized acceptance. Implementations SHOULD allow calling this choice for all parties that can create an allocation matching this request.
  extraArgs	ExtraArgs	Additional context required in order to exercise the choice.

• Choice AllocationRequest_Reject

  Reject an allocation request to signal that no allocation will be created for it.

  The choice is nonconsuming to support alternative consumption patterns, e.g., by calling the consuming V1.AllocationRequest_Reject choice for transaction parsing compatibility.

  IMPORTANT: implementations MUST ensure that the allocation request is consumed by the body of this choice.

  Controller: actors

  Returns: AllocationRequest_RejectResult

  Field	Type	Description
  actors	[Party]	Set of parties executing the rejection. Implementations MUST check these parties to avoid unauthorized rejection. Implementations SHOULD allow calling this choice for all parties that can create an allocation matching this request.
  extraArgs	ExtraArgs	Additional context required in order to exercise the choice.

• Choice AllocationRequest_Withdraw

  Withdraw an allocation request as the executors.

  The choice is nonconsuming to support alternative consumption patterns, e.g., by calling the consuming V1.AllocationRequest_Withdraw choice for transaction parsing compatibility.

  IMPORTANT: implementations MUST ensure that the allocation request is consumed by the body of this choice.

  Controller: actors

  Returns: AllocationRequest_WithdrawResult

  Field	Type	Description
  actors	[Party]	Set of parties executing the withdrawal. Implementations MUST check these parties to avoid unauthorized withdrawal. Implementations SHOULD allow the settlement.executors to jointly call this choice.
  extraArgs	ExtraArgs	Additional context required in order to exercise the choice.

• Choice Archive

  Controller: Signatories of implementing template

  Returns: ()

  (no fields)

• Method allocationRequest_acceptExtraObservers : AllocationRequest_Accept -> [Party]

• Method allocationRequest_acceptImpl : ContractId AllocationRequest -> AllocationRequest_Accept -> Update AllocationRequest_AcceptResult

• Method allocationRequest_rejectExtraObservers : AllocationRequest_Reject -> [Party]

• Method allocationRequest_rejectImpl : ContractId AllocationRequest -> AllocationRequest_Reject -> Update AllocationRequest_RejectResult

• Method allocationRequest_withdrawExtraObservers : AllocationRequest_Withdraw -> [Party]

• Method allocationRequest_withdrawImpl : ContractId AllocationRequest -> AllocationRequest_Withdraw -> Update AllocationRequest_WithdrawResult

Data Types

data AllocationRequestAction

Actions available on an allocation request.

ARA_Accept

ARA_Reject

ARA_Custom

Used to represent app-specific actions on allocation requests.

Field	Type	Description
id	Text	Identifier of the action. Namespaced analogously to metadata keys.

instance Eq AllocationRequestAction

instance Ord AllocationRequestAction

instance Show AllocationRequestAction

instance GetField "availableActions" AllocationRequestView (Map AllocationRequestAction [[Party]])

instance GetField "id" AllocationRequestAction Text

instance SetField "availableActions" AllocationRequestView (Map AllocationRequestAction [[Party]])

instance SetField "id" AllocationRequestAction Text

data AllocationRequestView

View of an AllocationRequest.

AllocationRequestView

Field	Type	Description
originalRequestCid	Optional (ContractId AllocationRequest)	The contract id of the original allocation request contract, which is None for the original allocation request itself. This SHOULD be used by wallets to correlate the same allocation request across updates to its state. It should not be used to correlate different allocation requests for the same settlement. That can be done using the settlement field.
settlement	SettlementInfo	Settlement for which allocations are requested to be created.
allocations	[AllocationSpecification]	The allocations that are requested to be authorized for execution as part of the settlement. Wallets SHOULD check their authorizer to see whether this request requires action from their users or merely serves informational purposes.
requestedAt	Time	Timestamp at which the request was created.
settleAt	Optional Time	Timestamp at which the settlement is expected to be executed. The authorizer SHOULD create their allocations before this time. For iterated settlements, this is the expected time of the first iteration.
availableActions	Map AllocationRequestAction [[Party]]	What actions are available to which groups of parties. The list of lists is interpreted as a set of sets and represents a disjunction of conjunctions of parties, i.e., each inner list represents a group of parties 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. All possible combinations of action actors that could call a choice SHOULD be included.
meta	Metadata	Additional metadata specific to the allocation request, used for extensibility.

instance Eq AllocationRequestView

instance Show AllocationRequestView

instance HasFromAnyView AllocationRequest AllocationRequestView

instance HasInterfaceView AllocationRequest AllocationRequestView

instance GetField "allocations" AllocationRequestView [AllocationSpecification]

instance GetField "availableActions" AllocationRequestView (Map AllocationRequestAction [[Party]])

instance GetField "meta" AllocationRequestView Metadata

instance GetField "originalRequestCid" AllocationRequestView (Optional (ContractId AllocationRequest))

instance GetField "requestedAt" AllocationRequestView Time

instance GetField "settleAt" AllocationRequestView (Optional Time)

instance GetField "settlement" AllocationRequestView SettlementInfo

instance SetField "allocations" AllocationRequestView [AllocationSpecification]

instance SetField "availableActions" AllocationRequestView (Map AllocationRequestAction [[Party]])

instance SetField "meta" AllocationRequestView Metadata

instance SetField "originalRequestCid" AllocationRequestView (Optional (ContractId AllocationRequest))

instance SetField "requestedAt" AllocationRequestView Time

instance SetField "settleAt" AllocationRequestView (Optional Time)

instance SetField "settlement" AllocationRequestView SettlementInfo

data AllocationRequest_AcceptResult

The result of the AllocationRequest_Accept choice.

AllocationRequest_AcceptResult

Field	Type	Description
meta	Metadata	Additional metadata specific to the result of accepting the allocation request, used for extensibility.

instance Eq AllocationRequest_AcceptResult

instance Show AllocationRequest_AcceptResult

instance HasMethod AllocationRequest "allocationRequest_acceptImpl" (ContractId AllocationRequest -> AllocationRequest_Accept -> Update AllocationRequest_AcceptResult)

instance GetField "meta" AllocationRequest_AcceptResult Metadata

instance SetField "meta" AllocationRequest_AcceptResult Metadata

instance HasExercise AllocationRequest AllocationRequest_Accept AllocationRequest_AcceptResult

instance HasExerciseGuarded AllocationRequest AllocationRequest_Accept AllocationRequest_AcceptResult

instance HasFromAnyChoice AllocationRequest AllocationRequest_Accept AllocationRequest_AcceptResult

instance HasToAnyChoice AllocationRequest AllocationRequest_Accept AllocationRequest_AcceptResult

data AllocationRequest_RejectResult

The result of the AllocationRequest_Reject choice.

AllocationRequest_RejectResult

Field	Type	Description
meta	Metadata	Additional metadata specific to the result of rejecting the allocation request, used for extensibility.

instance Eq AllocationRequest_RejectResult

instance Show AllocationRequest_RejectResult

instance HasMethod AllocationRequest "allocationRequest_rejectImpl" (ContractId AllocationRequest -> AllocationRequest_Reject -> Update AllocationRequest_RejectResult)

instance GetField "meta" AllocationRequest_RejectResult Metadata

instance SetField "meta" AllocationRequest_RejectResult Metadata

instance HasExercise AllocationRequest AllocationRequest_Reject AllocationRequest_RejectResult

instance HasExerciseGuarded AllocationRequest AllocationRequest_Reject AllocationRequest_RejectResult

instance HasFromAnyChoice AllocationRequest AllocationRequest_Reject AllocationRequest_RejectResult

instance HasToAnyChoice AllocationRequest AllocationRequest_Reject AllocationRequest_RejectResult

data AllocationRequest_WithdrawResult

The result of the AllocationRequest_Withdraw choice.

AllocationRequest_WithdrawResult

Field	Type	Description
meta	Metadata	Additional metadata specific to the result of withdrawing the allocation request, used for extensibility.

instance Eq AllocationRequest_WithdrawResult

instance Show AllocationRequest_WithdrawResult

instance HasMethod AllocationRequest "allocationRequest_withdrawImpl" (ContractId AllocationRequest -> AllocationRequest_Withdraw -> Update AllocationRequest_WithdrawResult)

instance GetField "meta" AllocationRequest_WithdrawResult Metadata

instance SetField "meta" AllocationRequest_WithdrawResult Metadata

instance HasExercise AllocationRequest AllocationRequest_Withdraw AllocationRequest_WithdrawResult

instance HasExerciseGuarded AllocationRequest AllocationRequest_Withdraw AllocationRequest_WithdrawResult

instance HasFromAnyChoice AllocationRequest AllocationRequest_Withdraw AllocationRequest_WithdrawResult

instance HasToAnyChoice AllocationRequest AllocationRequest_Withdraw AllocationRequest_WithdrawResult

Functions

allocationRequest_acceptImpl

: AllocationRequest -> ContractId AllocationRequest -> AllocationRequest_Accept -> Update AllocationRequest_AcceptResult

allocationRequest_rejectImpl

: AllocationRequest -> ContractId AllocationRequest -> AllocationRequest_Reject -> Update AllocationRequest_RejectResult

allocationRequest_withdrawImpl

: AllocationRequest -> ContractId AllocationRequest -> AllocationRequest_Withdraw -> Update AllocationRequest_WithdrawResult

allocationRequest_acceptExtraObservers

: AllocationRequest -> AllocationRequest_Accept -> [Party]

allocationRequest_rejectExtraObservers

: AllocationRequest -> AllocationRequest_Reject -> [Party]

allocationRequest_withdrawExtraObservers

: AllocationRequest -> AllocationRequest_Withdraw -> [Party]

Comments