- 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.
- 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
DvpLegAllocationtemplate 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
AllocationV2template 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.
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.Feature compatibility across Registry App versions
New features are added to existing contracts asOptional 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 on0.14.
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 version0.13or later.isSomeis true if the optional field has any value, and false if it isNone.- In JSON API responses,
Noneis represented asnullor a missing field.
- 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-v2insupportedApis) and whether it is paused. - Instrument configuration:
POST /api/utilities/v0/contract/instrument-configuration, called with the instrument’s default identifier as described here. Thepayload.checkBlockListandpayload.forceTransferEnabledfields 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).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 vetted0.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.
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 V2AllocationRequest 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 aTradeSettlementAgreement 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.