canton: document the NTT layer

Author: bengtlofgren

canton/README.md

@@ -66,7 +66,7 @@ The most consequential differences:
   contract (§4.2), analogous to Sui's `EmitterCap`. The emitting party (`owner`)
   co-signs the `Emitter` and is part of the address derivation, so it is the
   faithful Canton analog of `msg.sender`: only that party's key can emit under
-  its address (§4.2, §10).
+  its address (§4.2, §10.1).
 - **No `ecrecover`.** Daml's `secp256k1` builtin _verifies_ a signature against
   a _public key_; it does not _recover_ the signer from the signature like
   Ethereum does. Guardian-set state on Canton therefore stores guardian
@@ -289,7 +289,7 @@ emit under an existing emitter's address: an operator-alone forge is rejected in
 guardian replay (missing the owner's signature), and a colluding duplicate under
 a different owner derives a **different**, untrusted address. This is the
 invariant guardians verify — "the transaction is Daml-valid under the vetted
-package" — with no bespoke watcher logic (see [§10](#10-trust-model--deployment-topology)).
+package" — with no bespoke watcher logic (see [§10.1](#101-trust-model--deployment-topology)).
 Registry-allocated ids give per-owner uniqueness and let one party hold **many**
 emitters, matching Sui's multiple `EmitterCap`s; id-sequence discipline is
 operator-behavioral, but address integrity is not.
@@ -454,16 +454,17 @@ We use **`secp256k1WithEcdsaOnly`** because Ethereum signs the 32-byte
 ### Making verification hint-free for integrators (recommended)
 
 Supplying `pubKeys` on every call is acceptable for governance (rare,
-operator-submitted) but is real friction for integrators (e.g. a token bridge),
-whose relayers would otherwise have to look up the signing guardians' keys on
-every inbound message. The recommended evolution: **persist the guardian public
-keys in the guardian set** — i.e. `GuardianSet` stores `pubKeys` alongside `keys`,
+operator-submitted) but is real friction for integrators like NTT, whose
+relayers would otherwise have to look up the signing guardians' keys on every
+inbound message. The recommended evolution: **persist the guardian public keys
+in the guardian set** — i.e. `GuardianSet` stores `pubKeys` alongside `keys`,
 bound to the canonical addresses _once_ at install time (the
 GuardianSetUpgrade / setup choices already receive pubkey hints and verify
 `keccak256(pubKey)[12..32] == addr`, so the binding is free). After that,
 `verifyVAA` reads the keys from the set and callers pass **only the VAA bytes**,
-making the integrator API equivalent to EVM's `parseAndVerifyVM(bytes)`. This is
-a planned change to the current code, which still takes per-call hints.
+making the integrator API equivalent to EVM's `parseAndVerifyVM(bytes)`. See
+[§10](#10-native-token-transfers-ntt). This is a
+planned change to the current code, which still takes per-call hints.
 
 ### Validation status
 
@@ -626,9 +627,12 @@ canton/
     daml/Wormhole/Core/State.daml
     daml/Wormhole/Core/Governance.daml
     daml/Wormhole/Core/Setup.daml
+  ntt-token/ ntt/ ntt-cip56/     ← NTT packages (see §10)
+  vendor/token-standard/         ← vendored CIP-56 interface DARs
   test/                          ← `wormhole-core-test` package (Daml Scripts)
-    daml.yaml                    ← data-dependency on core's DAR
+    daml.yaml                    ← data-dependencies on the built DARs
     daml/Test/TestCore.daml      ← unit tests + devnet `setup` / `integrationPublish`
+    daml/Test/TestNtt.daml       ← NTT codec / deployment / send / receive tests
   devnet/
     start_sandbox.sh             ← starts the Ledger API v2 sandbox
     bootstrap.sh                 ← allocates Operator + creates CoreState
@@ -663,17 +667,19 @@ curl https://get.digitalasset.com/install/install.sh | sh
 
 cd canton
 dpm install 3.5.1                # fetch the pinned SDK (Daml-LF 2.3)
-dpm build --all                  # builds core, then test → *.daml/dist/*.dar
+dpm build --all                  # builds all packages (core, ntt-token, ntt,
+                                 #   ntt-cip56, test) → *.daml/dist/*.dar
 cd test && dpm test --all --show-coverage   # run the Scripts + coverage
 ```
 
 `dpm test` runs every `Script` in
-[`TestCore.daml`](test/daml/Test/TestCore.daml) on an in-memory ledger — no
-running sandbox required. The suite passes, including governance and VAA
-verification with a **real guardian-signed VAA** test vector (§5) and the
-owner-bound emitter address derivation pinned against the shared cross-language
-vector (`testAddressVector`). Note Daml coverage is **template/choice coverage
-only**; the pure parser / DER / governance
+[`TestCore.daml`](test/daml/Test/TestCore.daml) and
+[`TestNtt.daml`](test/daml/Test/TestNtt.daml) on an in-memory ledger — no running
+sandbox required. The suite passes, including governance and VAA verification
+with a **real guardian-signed VAA** test vector (§5) and the owner-bound emitter
+address derivation pinned against the shared cross-language vector
+(`testAddressVector`, and the manager vector in `testNttDeployment`). Note Daml
+coverage is **template/choice coverage only**; the pure parser / DER / governance
 helpers and the address encoding are additionally validated by Script
 _assertions_ and the signed-VAA / address vectors, not by the coverage metric.
 
@@ -739,7 +745,111 @@ covered by the integration test in §9.
 
 ---
 
-## 10. Trust model & deployment topology
+## 10. Native Token Transfers (NTT)
+
+[NTT](https://github.com/wormhole-foundation/native-token-transfers) is
+implemented as a separate, uploadable package set on top of the core bridge —
+the core bridge is untouched and used as two primitives, **publish** and
+**verify**. NTT's on-chain shape is a **Manager** plus a **Wormhole
+transceiver**; on Canton the transceiver *is* a core `Emitter`.
+
+Packages (all data-depend on the built `wormhole-core` DAR, as `test` does):
+
+| Package | Contents |
+| --- | --- |
+| `ntt-token` (`wormhole-ntt-token`) | The `NttToken` interface (token effect seam) + `TokenMode`, `TrimmedAmount`. Interface-only, per Daml's upgradeability rule. Depends on the CIP-56 `holding`/`metadata` interfaces (the seam carries `[ContractId Holding]` + `ExtraArgs`). |
+| `ntt` (`wormhole-ntt`) | `Payload` (wire codec), `Manager` (`NttManagerRegistry`, `NttManager`, deployment/send/receive/peers). |
+| `ntt-cip56` (`wormhole-ntt-cip56`) | Real CIP-56 implementations of `NttToken` — `Cip56CustodyToken` (lock/unlock via `TransferFactory`) and `Cip56BurnMintToken` (burn/mint via `BurnMintFactory`). Works for Canton Coin (Amulet) or any conforming token. See [`ntt-cip56/README.md`](ntt-cip56/README.md). |
+| `vendor/token-standard/` | Vendored CIP-56 interface DARs (`splice-api-token-*-1.0.0`), from cn-quickstart — see [`vendor/token-standard/README.md`](vendor/token-standard/README.md). |
+
+### Deployment — permissionless, guardian-hosted
+
+Anyone can stand up a deployment (bring your own token, pick a mode). The
+`operator` and the deployer (`admin`) **co-sign** the `NttManager` (mirroring
+`Emitter`); neither has power over transfer contents. Flow: the deployer registers
+a core `Emitter` (the transceiver) via the existing `EmitterRequest`→`ApproveEmitter`
+flow, then submits an `NttDeploymentRequest` (the transceiver's key components
+`transceiverRegistrar` + `transceiverEmitterId`, token hook, mode, decimals); the
+operator's `ApproveDeployment` allocates a `managerId` from the `NttManagerRegistry`
+and creates the keyed `NttManager`.
+
+**Two key-derived identities**, both owner-bound per
+[§4.2](#42-message-publishing):
+- **transceiver address** = `keccak256("wormhole:emitter:v1" ‖ operator ‖ admin ‖ emitterId)`
+  — the VAA emitter other chains register; derived by the watcher, not stored.
+- **manager address** = `keccak256("wormhole:ntt-manager:v1" ‖ operator ‖ admin ‖ managerId)`.
+  The manager needs its own address *on-ledger* to build/validate NTT payloads,
+  so it is computed **on-ledger at approval** (via `DA.Crypto.Text`) and stored in
+  `NttManager.managerAddress` — **no longer operator-supplied**. The distinct
+  domain tag keeps an emitter and a manager with the same `(operator, admin, id)`
+  ordinals from colliding; `admin` co-signs so a compromised operator cannot forge
+  an existing manager's address (which would let it consume that peer's inbound
+  VAAs). The former strict-binding follow-up is thus resolved by construction.
+
+### Wire codec (`Wormhole.Ntt.Payload`)
+
+Implements the three nested structures with big-endian encoders built on
+`Bytes.daml` (`NativeTokenTransfer` prefix `0x994E5454`; `NttManagerMessage`;
+`WormholeTransceiverMessage` prefix `0x9945FF10`). Amounts use the NTT
+**TrimmedAmount** (≤ 8 decimals + a scale byte). Round-trips are tested in
+`test/daml/Test/TestNtt.daml:testNttCodec`.
+
+### Send (`NttManager.Transfer`, controller `admin`)
+
+Trims the amount, drives the token seam's `LockOrBurn`, assembles the nested
+message, and publishes it via `Emitter.PublishMessage` — so the guardian watcher
+observes an **ordinary core message** (no NTT-specific watcher code). Both the
+manager and its transceiver are resolved by their stable keys (`Transfer` is
+exercised via `ExerciseByKeyCommand`; the transceiver is `fetchByKey`-ed inside
+the choice), so there is no caller-supplied cid to track — and because the
+transceiver key's owner slot is the `admin`, ownership is enforced by the key
+itself rather than a separate assertion.
+
+### Receive (`NttManager.Receive`, controller `operator` — guardian-relayed)
+
+Reuses `Wormhole.Core.VAA.parseVAA`/`verifyVAA` against the guardian set read
+from a disclosed `CoreState`, enforces the configured peer
+(`(chainId → managerAddress, transceiverAddress)` from `SetPeer`), **replay-
+protects on the VAA hash** (integrator-owned — `CoreState.consumedGovernance`
+stays reserved for `"Core"`), decodes, and drives `MintOrUnlock`. `pubKeys` are
+untrusted hints today (hint-free is a follow-up). Tested end-to-end against a
+real devnet-guardian-signed NTT VAA in `testNttReceive` (incl. replay rejection).
+
+### Token seam (`NttToken`) and modes
+
+`NttManager` never references a concrete token; it holds a `ContractId NttToken`
+and calls `LockOrBurn` / `MintOrUnlock`. This isolates the token detail the way
+`VAA.daml` isolates crypto. `TokenMode` selects **lock/unlock** or **burn/mint**.
+The seam choices carry the CIP-56 runtime handles a real registry needs —
+`inputHoldingCids : [ContractId Holding]` (the holdings to lock/burn; empty for a
+mint) and `extraArgs : ExtraArgs` (the registry's choice context) — which the
+manager threads from `Transfer`/`Receive`.
+
+Real implementations live in `ntt-cip56`: `Cip56CustodyToken` drives
+`TransferFactory_Transfer` (lock = sender→custody, unlock = custody→recipient)
+and `Cip56BurnMintToken` drives `BurnMintFactory_BurnMint` (burn = inputs, mint =
+outputs). Both work for Canton Coin (Amulet) or any conforming token. A stdlib
+`MockToken` in the test package (which ignores the CIP-56 handles) exercises the
+whole protocol end-to-end in `dpm test`.
+
+**Submission caveat:** the factory calls are real token-standard choices, so a
+production send/receive is app-orchestrated — the caller submits with the token
+holder's authority and the registry's **disclosed contracts** (`extraArgs`),
+via `submitWithDisclosures`, exactly as cn-quickstart's
+`RegistryApi.getTransferFactory` + `submitWithDisclosures` do. The on-ledger Daml
+is complete; that submission wiring is off-ledger (relayer/app).
+
+### Follow-ups (tracked in [Open Questions](#11-open-questions--validation-items))
+
+- **`recipientAddress` → `Party`**: inbound mints to a relayer-supplied `Party`,
+  not yet bound to the 32-byte NTT address — needs a Canton address registry.
+- **Hint-free verification** (persist guardian pubkeys) + a **readable
+  guardian-set contract** for permissionless (non-operator) receive via
+  disclosure, so `Receive` need not be operator-controlled.
+- Deferred NTT features: rate limiting, queuing, multi-transceiver threshold
+  (currently fixed at 1).
+
+### 10.1 Trust model & deployment topology
 
 How does a set of `n` guardians (`k`-of-`n` threshold) run Wormhole on Canton
 faithfully — see and attest only what actually happened under rules they accept —
@@ -817,14 +927,15 @@ implemented here.
    (Emitter/manager **address** integrity is separately owner-bound and
    owner-co-signed, §4.2.)
 3. **Guardian observer topology.** Confirm the observer-party mechanics from
-   §10 (dedicated observer party as template `observer` vs. replica-hosted
+   §10.1 (dedicated observer party as template `observer` vs. replica-hosted
    `operator`; external-party namespace-key custody; how `--cantonReadAsParty`
    maps to the chosen party). Reconcile with `feat/canton-public-observer`. Note
    this observer party is distinct from the `guardianGovernance` signatory party
    (item 2): the observer is read-only, the governance party has signatory power.
 4. **Integrator VAA verification.** Implement the hint-free guardian set (persist
    pubkeys, §5) and confirm the guardian-set distribution mechanism for
-   integrators (explicit disclosure vs public-observer snapshot).
+   integrators (explicit disclosure vs public-observer snapshot). See
+   [§10](#10-native-token-transfers-ntt).
 5. **Native fees.** Whether/when to wire real Canton Coin (Splice `amulet`)
    payments into `PublishMessage`/`TransferFees`, or whether Canton runs fee-less
    initially (`messageFee = 0`).

cspell-custom-words.txt

@@ -302,3 +302,7 @@ pekko
 googleapis
 preimage
 builtins
+quickstart
+quickstart's
+cids
+dars