Deprecated

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

Open current docs

Splice.TokenStandard.Utils.Internal.Allocations

Internal module of utilities to implement V2 allocations and settlement factories.

Import ‘Splice.TokenStandard.Utils’ to get access to the public ones.

Orphan Typeclass Instances

instance ForwardCompatible Reference SettlementInfo

instance BackwardCompatible SettlementInfo SettlementInfo

instance BackwardCompatible AllocationSpecification AllocationSpecification

instance BackwardCompatible (ContractId Allocation) (ContractId Allocation)

instance BackwardCompatible (ContractId AllocationInstruction) (ContractId AllocationInstruction)

instance BackwardCompatible AllocationInstructionResult_Output AllocationInstructionResult_Output

instance ForwardCompatible AllocationInstructionResult_Output AllocationInstructionResult_Output

instance ForwardCompatible AllocationInstructionResult AllocationInstructionResult

instance ForwardCompatible AllocationRequestView AllocationRequestView

Functions

senderSide

: TransferLeg -> TransferLegSide

The sender side of a transfer leg.

receiverSide

: TransferLeg -> TransferLegSide

The receiver side of a transfer leg.

transferLegFromSide

: Account -> TransferLegSide -> TransferLeg

Create a transfer-leg from a side and its authorizer.

transferLegSidesWithAuthorizer

: TransferLeg -> [(Account, TransferLegSide)]

Compute a transfer leg’s sides and their authorizers.

nonIteratedAllocation

: ContractId Allocation -> FinalizedAllocation

Smart-constructor to finalize a non-iterated allocation for settlement.

netAllocationCreditAmounts

: Account -> [TransferLegSide] -> TextMap Decimal

Net amounts of credit from an allocation’s transfer leg sides.

Allocations for the sender of a mint do not result in a negative credit amount and allocations for the receiver of a burn do not result in a positive credit amount. Thereby allowing the instrument admin to use allocations to authorize mints and burns as part of settlement.

isValidSettlementInfoV1

: SettlementInfo -> Bool

Check basic invariants of a V1.SettlementInfo.

isValidAllocationSpecificationV1

: AllocationSpecification -> Bool

Check basic invariants of a V1.AllocationSpecification.

isValidSettlementInfoV2

: SettlementInfo -> Bool

Check basic invariants of a V2.SettlementInfo.

isValidAllocationSpecificationV2

: (Text -> Bool) -> AllocationSpecification -> Bool

Check basic invariants of a V2.AllocationSpecification.

ensureIsReceiptAllocation

: [Party] -> Party -> Account -> AllocationFactory_Allocate -> Update ()

Check that the allocation factory call creates a receipt allocation for the given account.

cannotWithdrawCommittedAllocationFailure

: Optional Time -> FailureStatus

Report a failure when trying to withdraw a committed allocation.

ensureWithdrawIsAllowed

: AllocationSpecification -> Update ()

Ensure that withdraw is allowed given the allocation’s committment status and settlement deadline.

allocationV2_withdrawDefaultImplUsingV1

: Allocation -> ContractId Allocation -> Allocation_Withdraw -> Update AllocationResult

Default implementation for the V2.Allocation_Withdraw for a template that implements the V1.Allocation interface.

It uses the V1.Allocation_Withdraw choice to ensure the sender’s tx parsing sees the expected choice.

allocationV2_cancelDefaultImpl

: Allocation -> ContractId Allocation -> Allocation_Cancel -> Update (TextMap [ContractId Holding], Metadata) -> Update AllocationResult

Default implementation for the V2.Allocation_Cancel that allows the executors to cancel the allocation, and also allows the admin to cancel the allocation if it is expired.

settlementFactoryV2_publicAsset_settleBatchExtraObserversDefaultImpl

: Party -> SettlementFactory_SettleBatch -> [Party]

The default observers for a public asset are all acount parties of the transfer legs being settled.

settlementFactoryV2_privateAsset_settleBatchExtraObserversDefaultImpl

: SettlementFactory_SettleBatch -> [Party]

For a private asset there are no extra observers by default.

settlementFactoryV2_settleBatchDefaultImpl

: (AllocationView -> Allocation_Settle -> Update ExtraArgs) -> Party -> ContractId SettlementFactory -> SettlementFactory_SettleBatch -> Update SettlementFactory_SettleBatchResult

Default implementation for settling a batch of allocations.

It validates that the transfer legs and allocations are unique, creates missing receipt allocations and then settles all allocations using their V2.Allocation_Settle choice.

The implementation uses the default controllers for calling the V2.Allocation_Settle choices. Registries that need to use custom controllers can reuse the validation and preparation logic in validateAndPrepareAllocations, but will have to reimplement the execution of the settlement choices.

validateNextIterationArgs

: Text -> Bool -> [TransferLegSide] -> Optional (TextMap Decimal) -> Update ()

Validate the arguments for a next iteration of allocation settlement.

fetchAndValidateAllocations

: Party -> SettlementFactory_SettleBatch -> Update [(FinalizedAllocation, AllocationView)]

Core logic to validate the allocations for a batch settlement. Used in settlementFactoryV2_settleBatchDefaultImpl and exposed as a standalone function to be reused by factories that need custom settlement execution logic.

extraExecutorsMetaKey

: Text

executorsFromSettlementInfoV1

: SettlementInfo -> [Party]

downcast_v2_v1_TransferLeg

: Party -> TransferLeg -> TransferLeg

upcast_v1_v2_TransferLeg

: Text -> TransferLeg -> TransferLeg

downcast_v2_v1_SettlementInfo

: Time -> Optional Time -> Optional Time -> SettlementInfo -> SettlementInfo

upcast_v1_v2_AllocationView

: Optional (ContractId Allocation) -> Optional Time -> Map AllocationAction [[Party]] -> AllocationView -> AllocationView

Generic method that allows to upcast a V1 allocation specification to a V2 one with custom available actions, and a custom originalAllocationCid.

allocationV1_availableActionsDefault

: AllocationView -> Map AllocationAction [[Party]]

Available actions for a V1 allocation that uses the default controllers for its actions.

The admin’s right to cancel an expired allocation is not included here, as it is time-limited and it is not expected to be executed via a token standard wallet.

allocationV2_availableActionsDefault

: [Party] -> AllocationSpecification -> Map AllocationAction [[Party]]

Available actions for a V2 allocations, ignoring timebounds like the settlement deadline.

The admin’s right to cancel an expired allocation is not included here, as it is time-limited and it is not expected to be executed via a token standard wallet.

upcast_v1_v2_AllocationInstructionView

: Optional Time -> Map AllocationInstructionAction [[Party]] -> AllocationInstructionView -> AllocationInstructionView

viewAsAllocationInstructionV1

: HasToInterface t AllocationInstruction => (Optional Time, t) -> AllocationInstructionView

Attempt to view a V2 allocation instruction as a V1 allocation instruction.

canViewAsAllocationInstructionV1

: HasToInterface t AllocationInstruction => (Optional Time, t) -> Bool

True if one can view the given V2 allocation instruction as a V1 allocation instruction.

tryDowncast_v2_v1_AllocationInstructionView

: Optional Time -> AllocationInstructionView -> Optional AllocationInstructionView

Attempt to downcast a V2 allocation instruction view to a V1 allocation instruction view.

Report failed downcast using None.

allocationInstructionV1_withdrawDefaultImplUsingV2

: AllocationInstruction -> (ContractId AllocationInstruction -> AllocationInstruction_Withdraw -> Update AllocationInstructionResult) -> ContractId AllocationInstruction -> AllocationInstruction_Withdraw -> Update AllocationInstructionResult

Adapter to implement V1.AllocationInstruction_Withdraw using the body of the V2 choice.

Built as an adapter, as calling the V2 interface method directly is not possible, as that will archive the allocation instruction again.

allocationInstructionV1_updateDefaultImplUsingV2

: ContractId AllocationInstruction -> AllocationInstruction_Update -> Update AllocationInstructionResult

Default implementation for V1.AllocationInstruction_Update for a V1 allocation instruction based on its V2 counterpart.

Always aborts, as the update choice is not required to be called in this case.

allocationSettlementTxHistoryV1ToMeta

: AllocationSpecification -> Metadata -> Metadata

Add tx history metadata that makes settlement of allocations recognizable by V1 tx history parsers using the new ‘settle-V2-allocation’ tx kind, and a reason.

viewAsAllocationV1

: HasToInterface t Allocation => (Optional Time, t) -> AllocationView

Attempt to view a V2 allocation as a V1 allocation.

canViewAsAllocationV1

: HasToInterface t Allocation => (Optional Time, t) -> Bool

True if one can view the given V2 allocation as a V1 allocation.

tryDowncast_v2_v1_AllocationView

: Optional Time -> AllocationView -> Optional AllocationView

Attempt to downcast a V2 allocation view to a V1 allocation view.

Report failed downcast using None.

allocationV1_cancelDefaultImplUsingV2

: Allocation -> (ContractId Allocation -> Allocation_Cancel -> Update AllocationResult) -> ContractId Allocation -> Allocation_Cancel -> Update Allocation_CancelResult

Adapter to implement V1.Allocation_Cancel using the body of the V2 choice.

Built as an adapter, as calling the V2 interface method directly is not possible, as that would archive the allocation again.

allocationV1_withdrawDefaultImplUsingV2

: Allocation -> (ContractId Allocation -> Allocation_Withdraw -> Update AllocationResult) -> ContractId Allocation -> Allocation_Withdraw -> Update Allocation_WithdrawResult

Adapter to implement V1.Allocation_Withdraw using the body of the V2 choice.

Built as an adapter, as calling the V2 interface method directly is not possible, as that would archive the allocation again.

allocationV1_executeTransferDefaultImplUsingV2

: ContractId AllocationFactory -> ContractId SettlementFactory -> Allocation -> ContractId Allocation -> Allocation_ExecuteTransfer -> Update Allocation_ExecuteTransferResult

Default implementation for V1.Allocation_ExecuteTransfer based on the V2 batch settlement.

It creates the receiver allocation on-demand, which works if that allocation can be created in a single step. For other cases, the receiver must use a V2 wallet.

Note that the calling method must recreate the sender allocation that was archived by the V1 choice, so the consuming V2.AllocationSettle choice can be called on it.

allocationRequestV2_rejectDefaultImplUsingV1

: [[Party]] -> ContractId AllocationRequest -> AllocationRequest_Reject -> Update AllocationRequest_RejectResult

Default implementation for the V2.AllocationRequest_Reject choice of a template that implements the V1.AllocationRequest interface.

Calls the V1 choice for backward compatibility with V1 tx history parsers if there is only one actor.

allocationRequestV2_withdrawDefaultImplUsingV1

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

Default implementation for the V2.AllocationRequest_Withdraw choice of a template that implements the V1.AllocationRequest interface.

Calls the V1 choice for backward compatibility with V1 tx history parsers if there is only one executor.

allocationRequestV1_rejectDefaultImpl

: [Party] -> ContractId AllocationRequest -> AllocationRequest_Reject -> Update ChoiceExecutionMetadata

Default implementation for the V1.AllocationRequest_Reject choice, which just checks the actors to one of the allowedActors.

allocationRequestV1_withdrawDefaultImpl

: AllocationRequest -> ContractId AllocationRequest -> AllocationRequest_Withdraw -> Update ChoiceExecutionMetadata

allocationRequestV2_acceptDefaultImpl

: [[Party]] -> ContractId AllocationRequest -> AllocationRequest_Accept -> Update AllocationRequest_AcceptResult

Default implementation for the V2.AllocationRequest_Accept choice that checks the actors are in the allowedActors and archives the request.

downcast_v2_v1_AllocationRequestView

: Optional Time -> AllocationRequestView -> AllocationRequestView

Note we are not offering the upcast from V1 to V2 for the allocation request views, as the authorizer on V2 is lost this way. The downcast is still useful, as it simplifies implementing dual version V1/V2 allocation requests.

V1 wallets will create one V1 allocation per transfer leg with their wallet party as the sender. Their authorizer will thus be set to the sender.owner of each individual transfer leg.

Note: that transfer legs must be unique across allocations for this downcast to work.

allocationFactoryV2_publicAsset_allocateExtraObserversDefaultImpl

: AllocationFactory_Allocate -> [Party]

For public assets the settlement executors should be observers of the allocation choice itself so there’s no extra view for communicating the created allocation.

allocationFactoryV2_privateAsset_allocateExtraObserversDefaultImpl

: AllocationFactory_Allocate -> [Party]

Default for private assets, where the settlement executors are only be observers of the allocation choice itself if no funding is required.

allocationFactoryV1_allocateDefaultImplUsingV2

: Party -> (Optional Time -> ContractId AllocationFactory -> AllocationFactory_Allocate -> Update AllocationInstructionResult) -> ContractId AllocationFactory -> AllocationFactory_Allocate -> Update AllocationInstructionResult

Adapter to implement V1.AllocationFactory_Allocate using the body of the V2 choice.

Built as an adapter, as the body MUST be configured so that it creates a template that implements both the V1.Allocation and V2.Allocation interfaces.

Comments