> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digitalasset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Standard and Registry App version compatibility

Support for the Token Standard V2 interfaces ([CIP-112](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md))
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](https://github.com/canton-foundation/cips/blob/main/cip-0056/cip-0056.md))
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](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#4-functional-extensions)
  such as accounts, batch settlement via the `SettlementFactory`, and committed allocations and iterated settlement.
* [Backwards compatibility](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#5-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](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#51-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.

| Template | Allocation V1 interface | Allocation V2 interface | Multiple executors | Committed settlement | Iterated settlement |
| :- | :-: | :-: | :-: | :-: | :-: |
| `DvpLegAllocation` | Yes | Yes | Yes (via V1 metadata) | No | No |
| `AllocationV2` | No | Yes | Yes | Yes | Yes |

Committed allocations and iterated settlement were introduced in sections
[4.1.6](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#416-committed-allocations-for-prefunded-trading-and-iterated-settlement)
and [4.3.6](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#436-committed-allocations-and-iterated-settlement)
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.

> [!WARNING]
>
> 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 `AllocationRequest`s 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](https://docs.digitalasset.com/registry/releases/daml-models.md). 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](https://docs.canton.network/appdev/deep-dives/smart-contract-upgrade) (SCU) of
the previous one, and [older minor versions remain supported](https://docs.digitalasset.com/registry/releases/daml-models.md#supported-versions) 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.

| Registry version vetted | V1 settlement | V2 settlement (cross-version) |
| :- | :-: | :-: |
| Before 0.14 by any involved participant | Supported | Not supported |
| 0.14 or later by all involved participants | Supported | Supported |

> [!NOTE]
>
> 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](https://docs.canton.network/appdev/deep-dives/smart-contract-upgrade#package-selection-in-the-ledger-api)
(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.

> [!WARNING]
>
> **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](https://docs.canton.network/appdev/modules/m6-upgrade-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.

| Feature | Version required | If and only if | Detectable via |
| :- | :-: | :- | :- |
| [Blocklist](https://docs.digitalasset.com/registry/guides/blocklist.md) | `0.13+` | `isSome checkBlockList` on `InstrumentConfiguration` | Instrument configuration |
| [Force transfer](https://docs.digitalasset.com/registry/guides/force-transfer.md) | `0.15+` | `isSome forceTransferEnabled` on `InstrumentConfiguration` or holdings | Instrument configuration |
| [Pause](https://docs.digitalasset.com/registry/guides/pause-unpause.md) | `0.15+` | `isSome isPaused` on `InstrumentConfiguration` | Instrument metadata |
| [Committed settlement (patch)](https://docs.digitalasset.com/registry/releases/release-notes/0.14.md#patch-0-14-13) | `0.14.13+` | `committed = True` on the allocation's `AllocationSpecification` | Allocation request |

> [!NOTE]
>
> * `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.

> [!WARNING]
>
> [Patch 0.14.13](https://docs.digitalasset.com/registry/releases/release-notes/0.14.md#patch-0-14-13) hardens
> [committed allocations](https://github.com/canton-foundation/cips/blob/main/cip-0112/cip-0112.md#416-committed-allocations-for-prefunded-trading-and-iterated-settlement):
> 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](https://docs.digitalasset.com/registry/guides/force-transfer.md#check-whether-an-instrument-has-force-transfer-enabled).
  The `payload.checkBlockList` and `payload.forceTransferEnabled` fields of the response show whether the blocklist
  check and force transfer are enabled.

> [!NOTE]
>
> The instrument configuration endpoint returns the `checkBlockList` and `forceTransferEnabled`
> fields from release `0.15` onwards ([Operator Backend API](https://docs.digitalasset.com/registry/apis/operator-backend-api.md) `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](https://docs.digitalasset.com/registry/releases/daml-models.md#supported-versions), a V2 settlement requires `0.14` or
higher, and a committed V2 settlement (including the patch) requires `0.14.13` or higher.

> [!NOTE]
>
> 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).

## 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](#minimum-registry-app-version-per-feature)
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:

```
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 `AllocationRequest`s 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.

```mermaid theme={null}
flowchart TD
    A[Plan atomic settlement of<br/>Registry App instruments] --> F{"Have all participants vetted a common<br/>Registry App version that supports<br/>the enabled features?"}
    F -- No --> X[Settlement not possible]
    F -- Yes --> V{"All admins signal V2 support<br/>and<br/>common version >= 0.14?"}
    V -- No --> V1[V1 AllocationRequests]
    V -- Yes --> V2[V1 and V2 AllocationRequest]
```

The enabled features and their minimum versions are listed in
[Minimum Registry App version per feature](#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:

| Wallet | Response to the allocation request |
| :- | :- |
| V2 wallet | Reads the request through the V2 interface and creates an `AllocationV2` for its side(s) via the V2 allocation factory. |
| V1 wallet as **sender** | Reads the request through the V1 interface and creates a `DvpLegAllocation` via the V1 allocation factory. The `DvpLegAllocation` also implements the V2 allocation interface and can be settled through V2. |
| V1 wallet as **receiver** | Creates nothing, as in V1 only senders create allocations. |

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:

| Sender wallet | Receiver wallet | Sender allocation | Receiver allocation |
| :- | :- | :- | :- |
| V2 | V2 | `AllocationV2`, created by the sender's wallet | `AllocationV2`, created by the receiver's wallet |
| V1 | V2 | `DvpLegAllocation`, created by the sender's wallet | `AllocationV2`, created by the receiver's wallet |
| V2 | V1 | `AllocationV2`, created by the sender's wallet | `AllocationV2` receipt, **created by the trading venue** |
| V1 | V1 | `DvpLegAllocation`, created by the sender's wallet | `AllocationV2` receipt, **created by the trading venue** |

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

> [!NOTE]
>
> This applies to receivers who do not use the [DA Registry UI](https://registry.app.digitalasset.com/) and
> interact only through their V1 wallet.

> [!WARNING]
>
> 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

* [Token Standard APIs (CIP 56 / CIP 112)](https://docs.digitalasset.com/registry/apis/token-standard)
* [V1 wallet compatibility](https://docs.digitalasset.com/registry/apis/token-standard/compatibility-v1-wallets.md)
* [Off-ledger API](https://docs.digitalasset.com/registry/apis/token-standard/off-ledger-api)
* [Smart Contract Upgrades overview](https://docs.canton.network/appdev/modules/m6-overview)
