CCPEDIAby Unity Nodes
Digital Asset docs

Token Standard V1 / V2 cross-version compatibility

Updated 30-10-2026

View on Digital Asset docs (opens in a new tab)
Support for the Token Standard V2 interfaces (CIP-112) was added in version 0.14 of the Registry App Daml models. Starting with this version, the Registry App provides cross-version compatibility between the V1 (CIP-56) and V2 interfaces. This page only clarifies the Registry App specific aspects of cross-version compatibility, in particular for DvP settlements. For the token standard V2 itself, refer to the CIP-0112 specification:
  • Functional extensions such as accounts, batch settlement via the SettlementFactory, and committed allocations and iterated settlement.
  • Backwards compatibility, including the compatibility rules for apps, assets and wallets, and the allocation compatibility matrix.

​
How V1 and V2 relate in the Registry App

​
Holdings

There is a one-to-one correspondence between the Holding V1 and Holding V2 views, achieved by encoding the V2 data (such as account information) into the metadata of the V1 view. Every Registry holding can be read through either interface.

​
Transfers

The Token Standard V2 transfer implementation is built on top of the Token Standard V1 transfer implementation.

​
Allocations

In line with the CIP-0112 compatibility rules, the Registry App maintains two allocation templates:
  • The DvpLegAllocation template implements both the V1 and the V2 allocation interfaces. It can therefore be executed as part of a V2 settlement batch, using only the executors’ authority. Multiple executors and accounts are supported by encoding them in the V1 metadata.
  • The AllocationV2 template only implements the V2 allocation interface. It was added because a V1 allocation can in general be upcast to a V2 allocation, but not the other way around: a V2 allocation cannot in general be represented as a V1 allocation.
TemplateAllocation V1 interfaceAllocation V2 interfaceMultiple executorsCommitted settlementIterated settlement
DvpLegAllocationYesYesYes (via V1 metadata)NoNo
AllocationV2NoYesYesYesYes
Committed allocations and iterated settlement are described in CIP-112, 4.1.6 and 4.3.6. As a result, from version 0.14 onwards, an allocation request from a trading venue that implements both the V1 and V2 AllocationRequest interfaces can be fulfilled using either a V1 or a V2 wallet. Since a DvpLegAllocation is also a V2 allocation, allocations created by V1 wallets can be executed as part of a V2 settlement.
Cross-version compatibility is one-directional. The AllocationV2 template is intended for V2 allocations only: it is more generic and supports multiple transfer legs, whereas a V1 allocation only addresses a single transfer leg. A V2 wallet calling the V2 allocation factory creates AllocationV2 contracts, which only implement CIP-0112 and are therefore not compatible with CIP-0056.
  • A DvpLegAllocation created through a V1 wallet can be executed as part of a V2 settlement flow.
  • An AllocationV2 instance cannot be settled as part of a V1 settlement flow.
Trading venues that send out V2 AllocationRequests are therefore expected to settle exclusively through V2.

​
Registry App version requirements

Besides the Token Standard version, the Registry App DAR version vetted by each participant matters. Each minor release is a smart contract upgrade (SCU) of the previous one, and we support the two minor versions before the current release. With 0.14, participants may therefore still legitimately run 0.12 or 0.13, which contain no V2 functionality: there, DvpLegAllocation does not implement the V2 allocation interface. V1 / V2 cross-version settlement therefore requires all participants involved in the settlement transaction to have vetted 0.14 or later. A V1 allocation of an admin that has only vetted 0.12 or 0.13 cannot be exercised as a V2 allocation.
Registry version vettedV1 settlementV2 settlement (cross-version)
0.12 / 0.13 by any involved participantSupportedNot supported
0.14 or later by all involved participantsSupportedSupported
This is a transitional limitation: once support for 0.12 and 0.13 has been dropped and these versions have been unvetted, V1 / V2 cross-version settlement can be orchestrated for all participants.

​
Single package version per transaction

Canton’s package selection algorithm (topology-aware package selection, TAPS) resolves a single version per package name for the entire transaction: the highest version vetted by all participants involved. It does not select different versions for different subtransactions, even where this would be possible in principle. This is a current implementation of Canton. This matters in particular for DvPs where both assets are issued on the Registry App, e.g. an instrument of issuer A traded against an instrument of issuer B. Although the two legs are settled by different instrument admins on different participants, both are implemented by the same Registry App packages (same package names). TAPS therefore has to pick a single Registry App version for both legs, which must be vetted by the participants of both issuers and all traders. A DvP against an asset implemented by a different package (e.g. Canton Coin) is not affected in the same way, as different package names are resolved independently.
Any involved participant (instrument admin, trader, venue, or any other informee) that has only vetted an older Registry App version forces the whole settlement transaction onto that version. For example, if issuer A has only vetted 0.13 and issuer B has vetted 0.13 and 0.14, a trade involving both settles all legs on 0.13, so a V1 / V2 cross-version settlement is not possible, also not for issuer B’s instruments. If no common version exists, the submission fails.
Until all participants have vetted 0.14 or later, a trading venue should determine per settlement whether a V2 flow can be used. If any involved participant is on an older Registry App version, orchestrate a V1 settlement for all Registry App instruments, as TAPS selects that older version for the whole settlement transaction. Batches settled in separate transactions are resolved independently by TAPS, at the cost of atomicity across batches. Always settle through the token standard interfaces (SettlementFactory, Allocation, …) rather than referencing Registry App templates directly, so that the Registry App version is resolved at submission time through TAPS.
1

Check V2 support of the instrument admins

For every instrument involved in the settlement, call the token metadata endpoint of the Registry App:
GET /registry/metadata/v1/instruments/{instrumentId}
Inspect the supportedApis field of the response. If any instrument admin does not signal support for splice-api-token-allocation-v2 (the entry is missing or set to 0), send out V1 AllocationRequests only and orchestrate the legacy V1 settlement flow.
2

Check the Registry DAR version of all settlement participants

If all instrument admins signal V2 support, additionally verify that every participant taking part in the settlement (instrument admins, traders, the venue itself, and any other informee) has vetted the Registry App DARs at version 0.14 or later. If not, orchestrate a V1 settlement for all Registry App instruments.
3

Orchestrate a V2 settlement

Only when both conditions above are met should the venue orchestrate a V2 settlement. In this case, send out an allocation request that has both V1 and V2 implementations, so that users can respond with either a V1 or a V2 wallet.Note that once support for versions before 0.14 has been dropped, both conditions are trivially met, and a V2 settlement can always be orchestrated.

​
V2 settlement with V1 and V2 wallets

In a V2 settlement, the trading app creates one allocation request per trader that implements both the V1 and the V2 AllocationRequest interfaces, and settles through the Registry App’s V2 settlement factory. How each trader’s wallet responds depends on its token standard version and on its role in the trade:
WalletResponse to the allocation request
V2 walletAccepts the request through the V2 interface and, in the same transaction, creates an AllocationV2 for its side(s) via the V2 allocation factory.
V1 wallet as senderReads the request through the V1 interface and creates a DvpLegAllocation via the V1 allocation factory. It cannot accept the request, as V1 has no accept choice, so the request stays open. The DvpLegAllocation also implements the V2 allocation interface and can be settled through V2.
V1 wallet as receiverCreates nothing, as in V1 only senders create allocations.
All four sender / receiver combinations of V1 and V2 wallets can be settled through V2:
Sender walletReceiver walletSender allocationReceiver allocation
V2V2V2 allocation, created by the sender’s walletV2 allocation, created by the receiver’s wallet
V1V2DvpLegAllocation, created by the sender’s walletV2 allocation, created by the receiver’s wallet
V2V1V2 allocation, created by the sender’s walletV2 receipt allocation, created by the trading app
V1V1DvpLegAllocation, created by the sender’s walletV2 receipt allocation, created by the trading app

​
Receipt allocations for V1 wallet users

Trading apps are expected to create the V2 receipt allocation on behalf of receivers using a V1 wallet, based on an agreement in which the receiver delegates this right to the trading app. For example, the Splice V2 reference trading app uses a TradeSettlementAgreement for this purpose. The trading app is also responsible for archiving allocation requests that remain open, for example those of V1 wallet senders, as part of settlement.
Creating and settling receipt allocations atomically (in the same transaction) is not supported by the Registry App. It needs to be done in two steps:
  1. Create the receipt allocation.
  2. Settle the batch using SettlementFactory_SettleBatch.
The Registry App off-ledger endpoint for SettlementFactory_SettleBatch only provides the choice context and disclosures for allocations that already exist on-ledger.Do not manually compose choice contexts obtained from different endpoints. Their internal structure may change without notice.
To reduce the need for trading apps to manage V2 receipt allocations, trading parties are strongly recommended to migrate to V2 wallets as early as possible.

​
See also

Back to Documentation