canton: bind NTT Receive's recipient to the VAA's recipientAddress via a hash

Receive previously took `recipient : Party` as a plain, relayer-supplied choice
argument with no binding to the VAA's `recipientAddress` at all -- the operator
(the choice's controller) could steer an inbound mint to any Canton party.

recipientAddress is a Bytes32, sized for chains whose native address IS a
fixed-size identifier (EVM, Solana). A Canton Party id has no such fixed-size
form, so there's nothing to compare it against directly.

recipientAddressFor recipient = keccak256("wormhole:ntt-recipient:v1" ‖
lp(partyToText recipient)), mirroring nttManagerAddressFor's style. Receive
keeps `recipient` as a choice argument, but asserts recipientAddressFor
recipient == ntt.recipientAddress before minting: recipientAddress is fixed by
the sender and covered by the guardian signature, so the operator still cannot
steer an inbound mint anywhere the sender didn't address, without needing a
registry template pair or an extra on-ledger lookup on every receive.

Tradeoff, accepted deliberately: a Canton Party id never changes once
allocated (it's the hash of a namespace root, or of a
DecentralizedNamespaceDefinition's founding owners), so this permanently binds
a signed VAA to the recipient party as it existed when the sender computed the
hash. If that party ever needs to change (a lost key, a planned custodial
migration -- not a rename of the same party, which has no meaning in Canton), a
VAA already signed against the old hash cannot be redirected; the sender must
re-send against the new party's hash. A self-service handle registry (resolving
a stable, sender-chosen handle to a party that can be repointed later) avoids
that, at the cost of an extra template pair and a fetchByKey on every receive;
this is the simpler mechanism, accepting a manual re-send as the cost of a
Party ever having to change.

Tests: testRecipientAddressForVector pins the encoding against fixed text (a
live Party's fingerprint is nondeterministic and can't be baked into a
constant -- same reasoning as nttManagerAddressFor's own vector), cross-checked
in node/pkg/cantonclient/vectorgen_test.go:TestGenerateAddressVectors (extended
with the matching preimage shape). testNttReceiveRecipientMismatchFails proves
the check actually gates Receive against the real signed fixture.

Known test gap (documented in README.md and Manager.daml): no automated test
exercises the MATCHING-recipient path through a real Receive call end-to-end.
The fixture is a single, statically pre-signed VAA with a fixed
recipientAddress, and a live Party's fingerprint is freshly and unpredictably
allocated every run, so no allocated Party can ever be made to match it ahead
of time. Closing this needs a live two-step sign-then-relay harness (allocate
the recipient, compute its hash, sign a fresh VAA against that hash via the
guardian test key, then relay it) -- not built here, since it would add back
most of the complexity this change was meant to avoid.

Verified: dpm build --all clean (5 packages); dpm test 20/20; gofmt/go vet/go
test clean on node/pkg/cantonclient and pkg/watchers/canton.

Author: bengtlofgren

canton/README.md

@@ -673,7 +673,7 @@ canton/
     daml.yaml                    ← data-dependencies on the built DARs
     daml/Test/TestCore.daml      ← unit tests + devnet `setup` / `integrationPublish`
     daml/Test/TestGuardianObserver.daml ← read-only guardianObserver visibility/authority tests
-    daml/Test/TestNtt.daml       ← NTT codec / deployment / send / receive tests
+    daml/Test/TestNtt.daml       ← NTT codec / deployment / send / receive / recipient-binding tests
   devnet/
     start_sandbox.sh             ← starts the Ledger API v2 sandbox
     bootstrap.sh                 ← allocates Operator + creates CoreState
@@ -852,9 +852,61 @@ 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).
+stays reserved for `"Core"`), decodes, binds the caller-supplied `recipient` to
+the VAA's own `recipientAddress` (below), and drives `MintOrUnlock`. `pubKeys`
+are untrusted hints today (hint-free is a follow-up).
+
+### Recipient binding (`recipientAddressFor`)
+
+The NTT wire payload's `recipientAddress` is a `Bytes32`, sized for chains whose
+native address *is* a fixed-size on-chain identifier (EVM, Solana). A Canton
+`Party` id is an unbounded-length, namespace-qualified string, so there is no
+such fixed-size value to bind it to directly. `Receive` used to take `recipient`
+as a plain, relayer-supplied choice argument with no binding to the VAA at all —
+the operator could steer an inbound mint to any party.
+
+`Receive` now checks `recipientAddressFor recipient == ntt.recipientAddress` —
+`recipientAddressFor` is `keccak256("wormhole:ntt-recipient:v1" ‖
+lp(partyToText recipient))` (`lp` the same 4-byte length-prefix
+`derivedAddressFromText` uses), mirroring `nttManagerAddressFor`'s style. A
+sender addresses Canton by computing this same hash off-chain, over the
+recipient's exact Party-id string, and putting the result in the outbound
+transfer's `recipientAddress` field. Since that field is inside the VAA
+payload, it's covered by the guardian signature — the operator (`Receive`'s
+controller) still supplies `recipient` as a choice argument, but the
+transaction only succeeds if it hashes to whatever the sender committed to, so
+the operator cannot steer the mint anywhere the sender didn't address.
+
+**Tradeoff, chosen deliberately over a self-service handle-registry
+indirection:** a Canton Party id never changes once allocated (it's the hash of
+a namespace root, or of a `DecentralizedNamespaceDefinition`'s founding
+owners), so this binds a signed VAA to the recipient party *as it exists when
+the sender computes the hash* — permanently. If the recipient ever needs a
+*different* party (a lost key, or a planned custodial migration — not a rename
+of the same party, since that has no meaning in Canton), a VAA already signed
+against the old party's hash cannot be redirected to the new one; the sender
+would need to re-send using the new party's hash. A registry indirection (a
+recipient-chosen handle resolving to a party that can be updated later) avoids
+that at the cost of an extra template pair and an on-ledger lookup on every
+receive; this is the simpler mechanism, accepting a manual re-send as the cost
+of a Party ever having to change.
+
+Tested in `test/daml/Test/TestNtt.daml`: `testRecipientAddressForVector` pins
+the encoding against fixed text (a live Party's fingerprint is nondeterministic
+and can't be baked into a constant — same reasoning as `nttManagerAddressFor`'s
+vector, and cross-checked in
+[`node/pkg/cantonclient/vectorgen_test.go`](../node/pkg/cantonclient/vectorgen_test.go):`TestGenerateAddressVectors`);
+`testNttReceiveRecipientMismatchFails` proves the check actually gates
+`Receive` against the real signed fixture. **Known test gap:** the fixture is a
+single, statically pre-signed VAA with a fixed `recipientAddress`, and a live
+Party's fingerprint is freshly (and unpredictably) allocated every test run, so
+no allocated Party can ever be made to match it — there is currently no
+automated test exercising the *matching*-recipient path through a real
+`Receive` call end-to-end (only the pure-function vector above and the
+negative/mismatch case are covered). Closing that gap needs either a
+live two-step flow (allocate the recipient, compute its hash, sign a fresh VAA
+against that hash via the guardian test key, *then* relay it) or accepting
+manual/code-review coverage for that one branch.
 
 ### Token seam (`NttToken`) and modes
 
@@ -882,8 +934,13 @@ 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.
+- **Recipient-address change**: `recipientAddressFor` permanently binds a signed
+  VAA to the recipient party as it existed when the sender computed the hash —
+  a party that needs to change (lost key, custodial migration) has no recovery
+  for VAAs already signed against the old one; the sender must re-send.
+- **Matching-recipient test coverage**: no automated test exercises `Receive`'s
+  success path end-to-end (see §10's "Known test gap"); a live two-step
+  sign-then-relay harness would close it.
 - **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.

canton/ntt/daml/Wormhole/Ntt/Manager.daml

@@ -23,9 +23,11 @@
 -- watcher code). Receive is guardian-relayed: 'Receive' reuses
 -- 'Wormhole.Core.VAA.parseVAA'/'verifyVAA' against the guardian set read from a
 -- disclosed 'CoreState', enforces the configured peer, replay-protects on the VAA
--- hash, decodes, and drives the token mint/unlock.
+-- hash, decodes, binds the caller-supplied @recipient@ to the VAA's own
+-- @recipientAddress@ via 'recipientAddressFor', and drives the token mint/unlock.
 module Wormhole.Ntt.Manager where
 
+import DA.Crypto.Text (keccak256, toHex)
 import DA.Map (Map)
 import DA.Map qualified as Map
 import DA.Optional (fromSomeNote)
@@ -65,6 +67,30 @@ nttManagerAddressFor : Party -> Party -> Int -> Bytes32
 nttManagerAddressFor registrar admin managerId =
   derivedAddress (DomainTag nttManagerAddressTag) registrar admin (RegistryId managerId)
 
+-- | Domain-separation tag for NTT recipient-address bindings. Distinct from
+-- every other domain tag in this codebase so a recipient binding can never
+-- collide with an emitter, manager, or governance address.
+recipientAddressTag : Text
+recipientAddressTag = "wormhole:ntt-recipient:v1"
+
+-- | @keccak256(tag ‖ lp(utf8(recipientText)))@, where @lp@ is the 4-byte
+-- big-endian length prefix ('lenPrefixed'). Text form split out from
+-- 'recipientAddressFor' so tests can pin the encoding against a fixed string —
+-- a live Party's fingerprint is nondeterministic, so it cannot be baked into a
+-- static, pre-signed VAA fixture. Mirrors 'derivedAddressFromText'.
+recipientAddressFromText : Text -> Bytes32
+recipientAddressFromText recipientText =
+  normalizeHex (keccak256 (toHex recipientAddressTag
+    <> unLenPrefixed (lenPrefixed (toHex recipientText))))
+
+-- | The 32-byte binding a sender must compute off-chain and put in an outbound
+-- NTT transfer's @recipientAddress@ field to address @recipient@ on Canton.
+-- 'Receive' recomputes this from the caller-supplied @recipient@ and checks it
+-- against the VAA's own @recipientAddress@ -- see 'Receive' for the tradeoff
+-- this makes against a registry indirection.
+recipientAddressFor : Party -> Bytes32
+recipientAddressFor recipient = recipientAddressFromText (partyToText recipient)
+
 -- | Allocates monotonically increasing manager ids, one registry per operator
 -- (keyed by the operator party). Same non-uniqueness caveat as
 -- 'Wormhole.Core.State.EmitterRegistry': the counter discipline is behavioral,
@@ -209,15 +235,32 @@ template NttManager
         create this with outboundSequence = outboundSequence + 1
 
     -- | Inbound transfer, guardian-relayed. Verifies the VAA against the guardian
-    -- set in a disclosed 'CoreState', enforces the configured peer, replay-protects
-    -- on the VAA hash, decodes, and mints/unlocks to @recipient@. @pubKeys@ are
-    -- untrusted hints bound to guardian addresses inside 'verifyVAA'.
+    -- set in a disclosed 'CoreState', enforces the configured peer,
+    -- replay-protects on the VAA hash, decodes, binds the caller-supplied
+    -- @recipient@ to the VAA's own @recipientAddress@ via
+    -- 'recipientAddressFor', and mints/unlocks to it. @pubKeys@ are untrusted
+    -- hints bound to guardian addresses inside 'verifyVAA'.
+    --
+    -- @recipient@ is a choice argument, but the relayer (@operator@, the
+    -- controller) cannot supply an arbitrary one: 'recipientAddressFor recipient'
+    -- must equal the VAA's own @recipientAddress@, a value fixed by the sender
+    -- and therefore covered by the guardian signature. A sender addresses
+    -- Canton by computing this same keccak256 off-chain (mirroring
+    -- 'nttManagerAddressFor') over the recipient's exact Party-id string and
+    -- putting the result in the outbound transfer's @recipientAddress@ field.
+    --
+    -- Tradeoff (chosen over a registry indirection): this permanently binds a
+    -- signed VAA to the recipient Party string as it existed when the sender
+    -- computed the hash. A Canton Party id is fixed forever once allocated, but
+    -- if the recipient ever needs a DIFFERENT party (lost key, planned
+    -- custodial migration -- not a rename of the same party, which cannot
+    -- happen), a VAA already signed against the old party's hash cannot be
+    -- redirected to the new one. A self-service handle registry avoids that at
+    -- the cost of an extra template pair and an on-ledger lookup; this is the
+    -- simpler mechanism, accepting that cost.
     --
-    -- NOTE (milestone gaps, see README §10): (a) the NTT @recipientAddress@ is a
-    -- 32-byte address; mapping it to a Canton @Party@ needs an address registry,
-    -- so @recipient@ is supplied by the relayer here and NOT yet bound to
-    -- @recipientAddress@; (b) hint-free verification via persisted guardian
-    -- pubkeys is a tracked follow-up.
+    -- NOTE (milestone gap, see README §10): hint-free verification via persisted
+    -- guardian pubkeys is a tracked follow-up.
     choice Receive : NativeTokenTransfer
       with
         coreStateCid     : ContractId CoreState
@@ -245,6 +288,8 @@ template NttManager
           (wm.sourceManager == peer.managerAddress)
         let mm = decodeNttManagerMessage wm.managerPayload
             ntt = decodeNativeTokenTransfer mm.payload
+        assertMsg "ntt: recipient does not match VAA recipientAddress"
+          (recipientAddressFor recipient == normalizeHex ntt.recipientAddress)
         exercise tokenCid MintOrUnlock with
           recipient
           amount = TrimmedAmount with decimals = ntt.decimals, amount = ntt.amount

canton/test/daml/Test/TestNtt.daml

@@ -1,7 +1,8 @@
 -- | Daml Script tests for the NTT package: the wire codec, permissionless
 -- deployment, the outbound send path (publishes via the core Emitter), and the
 -- inbound receive path (verifies a real guardian-signed VAA, enforces the peer,
--- mints via the token seam, and rejects replays).
+-- binds the recipient to the VAA's own recipientAddress, mints via the token
+-- seam, and rejects replays).
 --
 -- 'MockToken' is a minimal CIP-56-shaped implementation of the 'NttToken' seam
 -- (stdlib only) so the whole protocol is exercised without the real
@@ -218,11 +219,34 @@ testNttSend = do
 nttTransferVAA : Bytes
 nttTransferVAA = "010000000001009e180f3b0c9a9b4d77e9be4c25e67db813e222af53f3fff09219c2b1c43570ea003de6b1c3f91ad6a80a7c8c5b32ee349dd2e8778a77f1d2638414a18821de72016553f10000000000000200000000000000000000000000000000000000000000000000000000000000cc0000000000000001009945ff1000000000000000000000000000000000000000000000000000000000000000bb00000000000000000000000000000000000000000000000000000000000000aa0091000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000bb004f994e54540800000000000f424000000000000000000000000000000000000000000000000000000000000000dd00000000000000000000000000000000000000000000000000000000000000ee00480000"
 
-testNttReceive : Script ()
-testNttReceive = do
+-- | Pins the recipient-binding formula against fixed, non-Party text -- a live
+-- Party's fingerprint is nondeterministic (freshly allocated each run) and
+-- cannot be pinned into a constant, unlike the string literals here. Same
+-- style as testNttDeployment's nttManagerAddressFor vector; Go side in
+-- node/pkg/cantonclient/vectorgen_test.go:TestGenerateAddressVectors.
+testRecipientAddressForVector : Script ()
+testRecipientAddressForVector = do
+  recipientAddressFromText "vector-recipient::1220deadbeef"
+    === "dbd2d1b09ea5715be3e45d0e38e5c5c0f6fcd0f181d45a9620dfb20f8ae3a4d9"
+  assert (recipientAddressFromText "vector-recipient::1220deadbeef"
+            /= recipientAddressFromText "vector-recipient::1220cafebabe")
+
+-- | 'Receive' verifies the VAA, checks the peer, and decodes the payload
+-- against the real signed fixture -- then rejects a recipient whose
+-- 'recipientAddressFor' doesn't match the fixture's baked-in recipientAddress
+-- (0x..ee). This is the only receive-level case a static fixture can exercise
+-- for the SUCCESS side of the check: a live Party's fingerprint is
+-- nondeterministic, so no Party allocated in this (or any) test run can ever
+-- hash to a value that was baked into an already-signed fixture ahead of time.
+-- The match case itself is pinned in testRecipientAddressForVector above; a
+-- real production Receive matches because the sender computed
+-- recipientAddressFor over the ACTUAL recipient's Party-id text before the VAA
+-- was ever signed, which this fixture-based test cannot reproduce.
+testNttReceiveRecipientMismatchFails : Script ()
+testNttReceiveRecipientMismatchFails = do
   (operator, csId) <- nttSetup
   admin <- allocateParty "RecvAdmin"
-  recipient <- allocateParty "Recipient"
+  wrongRecipient <- allocateParty "WrongRecipient"
   -- Our manager address must match the VAA's recipientManager (0x..aa), which a
   -- registry-derived address cannot reproduce (party fingerprints are
   -- nondeterministic). Create the manager directly — deliberately using the
@@ -231,7 +255,7 @@ testNttReceive = do
   -- against the static signed fixture. The transceiver key is unused by Receive.
   mockCid <- submit admin do createCmd MockToken with admin, manager = operator, mode = BurnMint
   let tokenCid = toInterfaceContractId @NttToken mockCid
-  mgrId <- submitMulti [operator, admin] [] do
+  mgrId <- submit (actAs operator <> actAs admin) do
     createCmd NttManager with
       operator
       admin
@@ -250,35 +274,12 @@ testNttReceive = do
       chainId = 2
       peer = Peer with managerAddress = b32 "bb", transceiverAddress = b32 "cc"
 
-  ntt <- submit operator do
-    exerciseCmd mgrId Receive with
-      coreStateCid = csId
-      vaaBytes = nttTransferVAA
-      pubKeys = [(0, devnetGuardianPubKey)]
-      recipient
-      inputHoldingCids = []
-      extraArgs = emptyExtraArgs
-
-  -- The decoded transfer matches the fixture.
-  ntt.decimals === 8
-  ntt.amount === 1000000
-  ntt.recipientChain === 72
-  ntt.sourceToken === b32 "dd"
-  ntt.recipientAddress === b32 "ee"
-
-  -- The token was minted to the recipient.
-  [(_, h)] <- query @MockHolding admin
-  h.owner === recipient
-  h.amount === 1000000
-
-  -- Replaying the same VAA is rejected.
-  [(mgr2, _)] <- query @NttManager admin
   submitMustFail operator do
-    exerciseCmd mgr2 Receive with
+    exerciseCmd mgrId Receive with
       coreStateCid = csId
       vaaBytes = nttTransferVAA
       pubKeys = [(0, devnetGuardianPubKey)]
-      recipient
+      recipient = wrongRecipient
       inputHoldingCids = []
       extraArgs = emptyExtraArgs
   pure ()

node/pkg/cantonclient/vectorgen_test.go

@@ -182,4 +182,10 @@ func TestGenerateAddressVectors(t *testing.T) {
 		buf = append(buf, idb[:]...)
 		t.Logf("%s(%s, %s, %d) = %x", tag, registrar, owner, id, crypto.Keccak256(buf))
 	}
+
+	// Recipient-address preimage shape differs (single string, no id):
+	//   utf8(tag) ‖ uint32be(len(recipientText)) ‖ utf8(recipientText)
+	const recipientText = "vector-recipient::1220deadbeef"
+	recipientBuf := append([]byte("wormhole:ntt-recipient:v1"), lp(recipientText)...)
+	t.Logf("wormhole:ntt-recipient:v1(%s) = %x", recipientText, crypto.Keccak256(recipientBuf))
 }