Skip to main content
Support for the Token Standard V2 interfaces (CIP-112) was added in version 0.14 of the Registry App. Starting with this version, the Registry App provides cross-version compatibility between the V1 (CIP-56) and V2 interfaces. This page clarifies the Registry App specific aspects of two kinds of compatibility, in particular for DvP settlements:
  • Token Standard V1 / V2 cross-version compatibility: how V1 and V2 allocations, wallets, and settlement flows interoperate.
  • Registry App version compatibility: which Registry App version a settlement runs on, depending on the versions vetted by the involved participants and the features enabled on the traded instruments.
For the token standard V2 itself, refer to the CIP-112 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 compatibility rules of the V2 specification, 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.
Committed allocations and iterated settlement were introduced in sections 4.1.6 and 4.3.6 of the V2 specification. 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 leg sides, whereas a V1 allocation only addresses the sender side of a single transfer leg. A V2 wallet calling the V2 allocation factory creates AllocationV2 contracts, which only implement the V2 interfaces and are therefore not compatible with V1.
  • 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

The Registry App is shipped as a bundle of packages (utility-registry-app-v0, utility-registry-v0, utility-registry-holding-v0, …), see Daml models. TAPS selects a version per package name, but as the packages of a release depend on each other, this in practice results in the packages of a single Registry App release. On this page, “Registry App version” refers to that release. 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 older minor versions remain supported for some time. Participants may therefore still legitimately run a version before 0.14, which contains 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 an earlier version cannot be exercised as a V2 allocation.
This is a transitional limitation: once support for versions before 0.14 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 reflects the current Canton implementation. 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.

Feature compatibility across Registry App versions

New features are added to existing contracts as Optional fields, as described by Smart Contract Upgrade (SCU) Compatibility. As long as such a field is unset (for example, checkBlockList = None), the contract can be downgraded to an earlier version that does not have this field. Once a feature is enabled by setting the field (for example, checkBlockList = Some True), the contract can no longer be downgraded. This applies to V1 and V2 settlements alike, and to all parties of the settlement. For example:
  • An instrument with the blocklist check enabled (introduced in 0.13) cannot be settled on an earlier version, even if no involved party is blocklisted.
  • An instrument with force transfer enabled (introduced in 0.15) cannot be settled on 0.14.
Allocation and settlement are separate transactions with different informees, so they can run on different versions. For example, in a DvP, the allocation for an instrument with force transfer enabled can be created on 0.15, while the allocation for the other instrument is created on 0.14, as one of its participants has only vetted 0.14. The settlement involves all participants, so TAPS selects 0.14. The instrument configuration and holdings of the force-transfer instrument cannot be downgraded to 0.14, and the settlement fails. Trading venues therefore need to determine a compatible version per settlement. It depends not only on V1 / V2 support and the versions vetted by the participants, but also on the features enabled on each traded instrument. A settlement can involve several Registry App instruments, possibly of different instrument admins, e.g. a DvP of two Registry App instruments, and TAPS selects one Registry App version for all of them.

Minimum Registry App version per feature

A settlement requires the version listed for a feature if and only if the condition holds for at least one allocation in the settlement. Otherwise, the contracts can still be SCU-downgraded to an earlier version.
  • 0.13+ means version 0.13 or later.
  • isSome is true if the optional field has any value, and false if it is None.
  • In JSON API responses, None is represented as null or a missing field.
Patch 0.14.13 hardens committed allocations: a committed AllocationV2 now sets a purpose on the lock of its holding. For the patch to take effect, all involved participants need to have vetted 0.14.13 or later.
For the instrument features, both endpoints of the Registry App need to be called for each Registry App instrument of the settlement:
  • Instrument metadata: GET /registry/metadata/v1/instruments/{instrumentId}, the token standard metadata endpoint. It shows whether the instrument supports Token Standard V2 (splice-api-token-allocation-v2 in supportedApis) and whether it is paused.
  • Instrument configuration: POST /api/utilities/v0/contract/instrument-configuration, called with the instrument’s default identifier as described here. The payload.checkBlockList and payload.forceTransferEnabled fields of the response show whether the blocklist check and force transfer are enabled.
The instrument configuration endpoint returns the checkBlockList and forceTransferEnabled fields from release 0.15 onwards (Operator Backend API 2.2.0).
A settlement requires the highest minimum version of all features set on any of its instruments, and is only possible if all involved participants have vetted a common version at or above it. For example, a DvP of an instrument with the blocklist check enabled (0.13) against an instrument with force transfer enabled (0.15) requires 0.15 or higher. If none of these fields are set, there is no feature-specific minimum version: a V1 settlement can run on any supported version, a V2 settlement requires 0.14 or higher, and a committed V2 settlement (including the patch) requires 0.14.13 or higher.
The Registry App does not yet advertise a minimum compatible version per instrument. Trading venues need to derive it from the endpoints above, as described in the trading venue guidelines.

Trading venue guidelines

These guidelines cover the Registry App instruments of a settlement. Assets of other registries in the same settlement, e.g. Canton Coin, are implemented by packages with other package names, which TAPS resolves independently. They therefore do not constrain the Registry App version, and vice versa. 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 the feature requirements of the traded instruments

Before sending out any allocation request, check which features are enabled on each Registry App instrument of the settlement, using the instrument metadata and instrument configuration endpoints, and take the highest minimum version. Then determine the highest Registry App version vetted by every participant taking part in the settlement (instrument admins, traders, the venue itself, and any other informee).If that version is lower than the minimum version, the settlement is not possible, neither in V1 nor in V2. Do not send out allocation requests for it, as the allocations could possibly be created, but the settlement would fail.
2

Check V2 support of the instrument admins

For every instrument involved in the settlement, call the token metadata endpoint of the Registry App:
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.
3

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.
4

Orchestrate a V2 settlement

Only when all 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, the V2 checks are trivially met, and a V2 settlement can always be orchestrated, provided the feature requirements of the traded instruments are met.
The enabled features and their minimum versions are listed in Minimum Registry App version per feature.

V2 settlement with V1 and V2 wallets

In a V2 settlement, the trading venue 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: A V1 wallet cannot answer a request that only implements V2.AllocationRequest. Conversely, a V2 wallet answering a V1-only request uses the V1 allocation factory, for sender legs only. All four sender / receiver combinations of V1 and V2 wallets can be settled through V2:

Receipt allocations for V1 wallet users

Trading venues 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 venue. For example, the Splice V2 reference trading app uses a TradeSettlementAgreement for this purpose. The trading venue is also responsible for archiving allocation requests that remain open, for example those of V1 wallet senders, as part of settlement.
This applies to receivers who do not use the DA Registry UI and interact only through their V1 wallet.
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 venues to manage V2 receipt allocations, trading parties are strongly recommended to migrate to V2 wallets as early as possible.

See also