canton: add token-bridge lock-and-attest example (CN Token Standard)

[bengtlofgren]

Summary

Adds a self-contained worked example of the Wormhole lock-and-attest send path on the Canton Network Token Standard (CIP-0056). A TokenBridge.LockAndPublish choice atomically transfers a user's holding into bridge custody and publishes a Wormhole Transfer message in a single user-submitted transaction. Stacks on canton-guardian-observer (#32) — rebased off feat/canton-public-observer, which is closed in favor of #32.

Changes

• canton/examples/token-bridge/daml/Wormhole/Example/TokenBridge.daml — TokenBridge orchestrator with LockAndPublish choice; composes transfer authority (from the token registry factory) with publish authority (from the bridge's Emitter) in one atomic transaction. Its visibility field is guardianObserver (was public), matching canton: read-only guardianObserver party for guardian read visibility #32.
• canton/examples/token-bridge/daml/Wormhole/Example/TokenRegistry.daml — minimal admin-custodied token registry implementing the CN Token Standard Holding and TransferInstruction interfaces; self-issuing so the example runs without Amulet.
• canton/examples/token-bridge/daml/Wormhole/Example/Test/TestTokenBridge.daml — Daml Script test covering the full flow: allocate parties, register emitter via the registry-keyed EmitterRegistry/ApproveEmitter, mint holding, lock and attest. Assertions moved from the old EmitterIdentity contract-id scheme to the current WormholeMessage.{registrar,owner,emitterId} fields.
• canton/examples/token-bridge/.lib/ — vendored CN Token Standard interface DARs (splice-api-token-{metadata,holding,transfer-instruction}-v1-1.0.0.dar), pinned to Splice v0.5.18 with sha256 verification. See .lib/THIRD_PARTY.md.
• node/pkg/watchers/canton/token_bridge_integration_test.go — integration test (//go:build integration) that runs the full flow against a live Canton sandbox and verifies the published transfer message through the real watcher, deriving the expected address via deriveEmitterAddress (matching watcher_integration_test.go) instead of hashing an identity contract-id.
• canton/README.md — worked-example section added documenting the lock-and-attest pattern, atomicity via authority composition, and explicit disclosure.
• canton/multi-package.yaml — token-bridge example added to the multi-package build.
• canton/examples/token-bridge/daml.yaml — bumped to sdk-version: 3.5.1 / --target=2.3 to match wormhole-core.

Rebase notes (off feat/canton-public-observer onto canton-guardian-observer)

The example predated both #29 (registry-keyed Emitter/EmitterRegistry, no separate EmitterIdentity template) and #32 (guardianObserver replacing the generic public party), so this was an adaptation, not a mechanical replay:

• mkInitialCoreState now takes guardianGovernance + guardianObserver; setup also creates an EmitterRegistry via mkInitialEmitterRegistry.
• ApproveEmitter returns ContractId Emitter directly (no coreStateCid arg, no separate EmitterIdentity contract).
• WormholeMessage carries registrar/owner/emitterId directly instead of an identity contract-id.

Verified: dpm build --all and dpm test --all pass (all 3 scripts); go vet -tags integration ./pkg/watchers/canton/... is clean.

Notes

• Custody is implemented as a transfer to the bridge party via TransferFactory_Transfer, not the allocation API (allocation requires a counter-leg).
• The bridge, factory, and emitter contracts are shared to the user via explicit disclosure — the standard pattern for handing a factory to a non-stakeholder.
• Third-party DARs are committed (not fetched at build time) with pinned sha256s; re-fetch instructions are in .lib/THIRD_PARTY.md.
• Build and test: dpm build --all then cd canton/examples/token-bridge && dpm test --all.

---

Hardening pass + CompleteTransfer receive leg. This example predated the NTT layer (#30); this commit applies lessons learned building and hardening NTT to the classic Token Bridge, and adds the receive leg that was previously missing entirely (the example only ever demonstrated the send path).

Send-leg fixes:

• LockAndPublish now resolves the bridge's Emitter by its stable key instead of a caller-supplied emitterCid argument — the old cid arg was stale after one use (PublishMessage is consuming) and unchecked (a caller could pass any emitter satisfying controller owner with their own authority).
• tokenAddress is now derived on-ledger from the instrument actually locked (tokenAddressFor instrumentId, a domain-tagged keccak256, mirroring Wormhole.Core.Bytes.derivedAddressFromText's style) instead of being a free-standing caller-supplied argument with no connection to what was locked.
• Amounts are normalized to 8 decimals and truncated before locking, not just at encoding time — the original encodeTransfer (truncate amount) truncated only the encoded integer while locking the full untruncated amount, silently stranding the difference in an unaccounted-for custody holding. Locked and attested amounts can no longer diverge; any sub-8dp dust now comes back to the sender as ordinary registry change.
• TokenRegistry's ExampleRegistry now accepts multiple input holdings and returns change, instead of requiring a single holding whose amount exactly matches the transfer.

New: TokenBridge.CompleteTransfer (receive leg) — verifies an inbound VAA against the guardian set, enforces a registered peer (RegisterPeer), replay-protects on the VAA hash (TokenBridge is now keyed, added now since Daml keys can't be added later by upgrade), decodes the payload, and unlocks the corresponding custody holding to the attested recipient. Recipient binding mirrors NTT's recipientAddressFor pattern (tokenBridgeRecipientAddressFor, a distinct domain tag) with the same tradeoff: the binding is permanent once the sender computes it, since a Canton Party id never changes.

Worth flagging explicitly: CompleteTransfer was first written controller relayer (an arbitrary, permissionless relay, matching EVM's completeTransfer) and that design was empirically disproven, not just reconsidered — fetching the disclosed CoreState is a plain Daml Fetch action, and a Fetch action's required authorizers must include one of the fetched contract's own stakeholders (operator/guardianGovernance/guardianObserver), which no relayer/bridge combination can ever satisfy. This is a hard Daml/Canton ledger-model constraint, not a design preference — it's exactly why NTT's own Receive is controller operator too. Fell back to controller operator, confirmed against a real AuthorizationError before the fix.

Verified:

• dpm build --all clean; dpm test --all 17/17 (was 1) — new coverage includes derivation/codec vectors, authority-vs-visibility negative pairs, the fractional-amount fix, and the full CompleteTransfer check sequence against static VAA fixtures.
• go build/gofmt/go vet (including -tags integration) clean.
• Both integration tests pass live against a real Canton sandbox: TestCantonTokenBridgeIntegration (send, pre-existing) and the new TestCantonTokenBridgeCompleteIntegration — a live two-step sign-then-relay harness (mirroring NTT's own ntt_recipient_match_integration_test.go) that allocates real parties, reads their actual on-ledger derived hashes, signs a fresh VAA against them in Go, and relays it, asserting the unlock lands on the matching recipient and that replay is rejected.

canton/README.md rewritten for this example to match the design-rationale depth of the NTT section (§10), including an explicit "what this example deliberately does not show" note (wrapped-asset mint, fee handling, governance-gated peer registration).

[cursor]

Stale comment

[bengtlofgren]

I'm going to close this because token bridge isnt even a requirement. Reduce the surface area for review