canton: make core-bridge contracts publicly readable via a public observer party

Add a read-only 'public' party as an observer to CoreState, EmitterRequest, and
Emitter so the full records (config, emitter registrations, sequences, and
published messages) are readable by anyone the participant grants read-as rights
to that party. The public party carries no authority; operator remains the sole
signatory. It is chosen at setup, stored on CoreState, supplied on each
EmitterRequest, and copied into the Emitter on approval.

- Thread public through mkInitialCoreState and the test setup/registerEmitter.
- Add testPublicVisibility (public reads CoreState and the sequence-advanced
  Emitter; a non-stakeholder sees nothing).
- Surface the public party id in the devnet bootstrap.
- Document the visibility model and the required topology read-grant (README 4.6).

Author: bengtlofgren

canton/README.md

@@ -152,6 +152,7 @@ Daml package name: `wormhole-core` (the `core` package). Module layout under
 template CoreState
   with
     operator           : Party          -- holds/advances the singleton; the "deployer"
+    public             : Party          -- read-only visibility party (§4.6)
     chainId            : Int            -- 72
     governanceChainId  : Int            -- 1 (Solana)
     governanceContract : Bytes32        -- 0x..0004 (the governance emitter)
@@ -368,6 +369,33 @@ Matches EVM (`Setters.sol`): when a new set is installed, the previous set's
 non-current set only while `effectiveTime < expirationTime`. The current set
 never expires.
 
+### 4.6 Public readability
+
+Canton contracts are private to their stakeholders (signatories + observers), so
+by default only the `operator` and an emitter's `owner` could read the bridge
+state. To make the full record world-readable — config, emitter registrations,
+per-emitter sequences, and every published message — each template carries a
+`public` party and lists it as an `observer`. `CoreState`, `EmitterRequest`, and
+`Emitter` are therefore all readable by `public`.
+
+`public` is an **ordinary party with no choices and no authority**; observing it
+only widens visibility. It is chosen at `setup`, stored on `CoreState`, supplied
+on each `EmitterRequest`, and copied into the `Emitter` on approval (and carried
+forward unchanged on every recreate). The `operator`, as the trusted bookkeeper
+that already enforces emitter-address uniqueness, approves only requests carrying
+the canonical `public` party.
+
+**The Daml change is necessary but not sufficient.** Listing `public` as an
+observer makes the contracts *visible to that party*; letting arbitrary readers
+actually **read as** `public` is a Canton topology/participant concern — grant
+read-as rights for the `public` party on each participant that should serve
+reads, or stand up a read-only front-end (the JSON Ledger API or a Participant
+Query Store instance) configured to read as `public`, so consumers query an
+endpoint and never need the party id. A party id is `hint::fingerprint`, where
+the fingerprint is a hash of the allocating namespace's key — deployment-specific
+and not guessable — so the `public` party id must be published or fronted by an
+API; it cannot be inferred.
+
 ---
 
 ## 5. On-chain signature verification (the crux)
@@ -766,6 +794,32 @@ Canton equivalent of EVM's `parseAndVerifyVM(bytes)`.
 
 These are tracked in [Open Questions](#11-open-questions--validation-items).
 
+### Worked example: token-bridge send path
+
+`examples/token-bridge` is a runnable example of the lock-and-attest send path on
+the Canton Network Token Standard (CIP-0056). A `TokenBridge.LockAndPublish` choice
+atomically (1) transfers a user's holding into the bridge's custody via the token
+standard's `TransferFactory_Transfer` (`receiver = bridge`) and (2) publishes a
+Wormhole Transfer message from the bridge's `Emitter` — in a single transaction the
+user submits.
+
+Key points it demonstrates:
+
+- **Custody = transfer to the bridge party**, not the allocation API (allocation is
+  DvP and needs a counter-leg, which a one-sided lock does not have).
+- **Atomicity via authority composition**: the bridge-signed orchestrator supplies
+  the publish authority while the registry factory supplies the authority to move
+  the asset, so no core operator is involved — matching EVM's permissionless
+  lock+publish.
+- **Explicit disclosure**: the user receives the bridge, factory, and emitter
+  contracts as disclosed contracts (it is not a stakeholder of them), the standard
+  pattern for an app handing its factory to a user.
+
+The example vendors the standard's interface DARs (pinned; see
+`examples/token-bridge/.lib/THIRD_PARTY.md`) and ships a minimal admin-custodied
+registry so it is self-issuing and runnable without Amulet. Build and test with
+`dpm build --all` then `cd examples/token-bridge && dpm test --all`.
+
 ---
 
 ## 11. Open Questions & Validation Items

canton/core/daml/Wormhole/Core/Setup.daml

@@ -25,13 +25,15 @@ defaultGovernanceContract = "000000000000000000000000000000000000000000000000000
 -- the supplied governance configuration. The caller @create@s it as @operator@.
 mkInitialCoreState :
   Party        -- ^ operator
+  -> Party     -- ^ public (read-only visibility party)
   -> Int       -- ^ governance chain id
   -> Bytes32   -- ^ governance contract
   -> [Bytes20] -- ^ initial guardian addresses (set 0)
   -> CoreState
-mkInitialCoreState operator govChain govContract initialGuardians =
+mkInitialCoreState operator public govChain govContract initialGuardians =
   CoreState with
     operator
+    public
     chainId = cantonChainId
     governanceChainId = govChain
     governanceContract = normalizeHex govContract

canton/core/daml/Wormhole/Core/State.daml

@@ -22,6 +22,16 @@
 -- sequence without the operator's authority, matching EVM where anyone may call
 -- @publishMessage@. 'CoreState' holds only the shared config and governance
 -- state.
+--
+-- PUBLIC READABILITY: every template carries a @public@ party and lists it as an
+-- 'observer', so the full record (config, emitter registrations, sequences, and
+-- published messages) is readable by anyone the participant grants read-as
+-- rights to that party. @public@ is an ordinary party with no choices and no
+-- authority — it only widens visibility. Granting arbitrary readers the right to
+-- read as @public@ is a Canton topology/participant concern, not enforced here;
+-- see canton/README.md. The @public@ party is chosen at setup, stored on
+-- 'CoreState', supplied on each 'EmitterRequest', and copied into the 'Emitter'
+-- on approval (and carried forward on every recreate).
 module Wormhole.Core.State where
 
 import DA.Map (Map)
@@ -70,6 +80,7 @@ maxPayloadBytes = 750
 template CoreState
   with
     operator           : Party              -- owns/advances the singleton; no power over outcomes
+    public             : Party              -- read-only visibility party; see module header
     chainId            : Int                -- 72 (Canton)
     governanceChainId  : Int                -- 1 (Solana)
     governanceContract : Bytes32            -- governance emitter address
@@ -79,6 +90,9 @@ template CoreState
     consumedGovernance : Set Bytes32        -- replay protection, keyed by digest
   where
     signatory operator
+    -- @public@ is an ordinary party that the participant grants broad read-as
+    -- rights to; observing it makes the full record publicly readable.
+    observer public
     -- No contract key: Canton 3.x has no unique keys (see module header).
     -- Uniqueness is operator-enforced; the current cid is tracked off-ledger.
 
@@ -186,19 +200,24 @@ template EmitterRequest
   with
     requester : Party
     operator  : Party
+    public    : Party   -- read-only visibility party, carried into the Emitter
   where
     signatory requester
-    observer operator
+    observer operator, public
 
     choice ApproveEmitter : ContractId Emitter
       controller operator
       do
         -- The identity cid is known within this transaction; the 'Emitter' stores
         -- it (not a derived address) and the watcher hashes it off-ledger.
-        identityCid <- create EmitterIdentity with operator, owner = requester
+        identityCid <- create EmitterIdentity with operator, owner = requester, public
         create Emitter with
           operator
           owner = requester
+          -- Visibility party is copied from the request; the operator (the
+          -- trusted bookkeeper, see module header) approves only requests that
+          -- carry the canonical @public@ party.
+          public
           identity = identityCid
           sequence = 0
 
@@ -214,9 +233,10 @@ template EmitterIdentity
   with
     operator : Party
     owner    : Party
+    public   : Party   -- read-only visibility party; see module header
   where
     signatory operator
-    observer owner
+    observer owner, public
     -- No choices: immutability is the point. Re-minting an 'Emitter' from a fresh
     -- identity would reset the sequence to 0, so identities are strictly one-shot.
 
@@ -228,11 +248,15 @@ template Emitter
   with
     operator  : Party
     owner     : Party
-    identity  : ContractId EmitterIdentity  -- permanent identity; address = keccak256(this cid)
-    sequence  : Int      -- next sequence to assign
+    public    : Party                        -- read-only visibility party; see module header
+    identity  : ContractId EmitterIdentity   -- permanent identity; address = keccak256(this cid)
+    sequence  : Int                          -- next sequence to assign
   where
     signatory operator
-    observer owner
+    -- @owner@ controls publishing; @public@ makes the record (and every
+    -- published message) world-readable. @create this@ on each publish carries
+    -- @public@ forward unchanged.
+    observer owner, public
     -- No contract key (Canton 3.x); the owner tracks the current cid off-ledger.
 
     -- | Publish a Wormhole message. The choice result is the 'WormholeMessage'

canton/devnet/bootstrap.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 #
 # Bootstrap the Wormhole core bridge on the Canton sandbox: allocate the Operator
-# party and create the CoreState (with the devnet guardian) by running the
-# Test.TestCore:setup Daml Script.
+# and Public parties and create the CoreState (with the devnet guardian) by
+# running the Test.TestCore:setup Daml Script.
 #
 # The guardian does NOT need the Operator party id — the watcher uses a wildcard
 # "any party" filter (see canton/README.md §7.1). The party is surfaced below for
@@ -35,11 +35,18 @@ dpm script \
   --ledger-port "${PORT}" \
   --output-file "${RESULT}"
 
-# The setup script returns a tuple {"_1": <Party>, "_2": <ContractId>} as JSON.
-# The party id is the quoted value containing "::" (the namespace separator); the
-# contract id has none. Informational only (the watcher needs no party id).
-OPERATOR_PARTY="$(grep -oE '"[^"]*::[^"]*"' "${RESULT}" | head -1 | tr -d '"')"
+# The setup script returns a tuple {"_1": <Operator>, "_2": <Public>, "_3":
+# <ContractId>} as JSON. Party ids are the quoted values containing "::" (the
+# namespace separator) in tuple order — operator first, then public; the contract
+# id has none. The Operator party is informational (the watcher uses a wildcard
+# filter). The Public party is the read-only visibility party every contract
+# observes (canton/README.md §4.6); surface it so operators can grant read-as
+# rights or point a JSON Ledger API / PQS reader at it.
+PARTIES="$(grep -oE '"[^"]*::[^"]*"' "${RESULT}" | tr -d '"')"
+OPERATOR_PARTY="$(echo "${PARTIES}" | sed -n '1p')"
+PUBLIC_PARTY="$(echo "${PARTIES}" | sed -n '2p')"
 echo "[canton] setup complete; Operator party: ${OPERATOR_PARTY}"
+echo "[canton] public (read-only) party: ${PUBLIC_PARTY}"
 
 touch /canton/success
 echo "[canton] bootstrap done; sleeping"

canton/test/daml/Test/TestCore.daml

@@ -29,19 +29,22 @@ devnetGuardianPubKey = "04d4a4629979f0c9fa0f0bb54edf33f87c8c5a1f42c0350a30d68f7e
 govSetFeeVAA : Bytes
 govSetFeeVAA = "01000000000100710ab5dcf6885f62016990540e090400f26f41286382dab479a78ed5f85017ff4a562a46379753e94abba1e69b9fec5d1994ac7d9fb145820727df0759bf4f80016553f100000000000001000000000000000000000000000000000000000000000000000000000000000400000000000000010000000000000000000000000000000000000000000000000000000000436f726503004800000000000000000000000000000000000000000000000000000000000003e8"
 
--- | Bootstrap a devnet 'CoreState' as a fresh operator party.
-setup : Script (Party, ContractId CoreState)
+-- | Bootstrap a devnet 'CoreState' as a fresh operator party, allocating the
+-- read-only @public@ visibility party that every template observes.
+setup : Script (Party, Party, ContractId CoreState)
 setup = do
   operator <- allocateParty "Operator"
+  public <- allocateParty "Public"
   csId <- submit operator do
-    createCmd (mkInitialCoreState operator solanaGovernanceChainId defaultGovernanceContract [devnetGuardian])
-  pure (operator, csId)
+    createCmd (mkInitialCoreState operator public solanaGovernanceChainId defaultGovernanceContract [devnetGuardian])
+  pure (operator, public, csId)
 
 -- | Register an emitter for @owner@: mints its immutable 'EmitterIdentity' and
--- the 'Emitter' bound to it, and returns the 'Emitter' cid.
-registerEmitter : Party -> Party -> Script (ContractId Emitter)
-registerEmitter operator owner = do
-  reqId <- submit owner do createCmd EmitterRequest with requester = owner, operator
+-- the 'Emitter' bound to it, carrying the @public@ visibility party. Returns the
+-- 'Emitter' cid.
+registerEmitter : Party -> Party -> Party -> Script (ContractId Emitter)
+registerEmitter operator public owner = do
+  reqId <- submit owner do createCmd EmitterRequest with requester = owner, operator, public
   submit operator do exerciseCmd reqId ApproveEmitter
 
 -- | Publishing increments the per-emitter sequence and yields the expected
@@ -50,9 +53,9 @@ registerEmitter operator owner = do
 -- address itself is not stored on-ledger, so there is nothing to assert here.
 testPublishMessage : Script ()
 testPublishMessage = do
-  (operator, _) <- setup
+  (operator, public, _) <- setup
   alice <- allocateParty "Alice"
-  emitterId <- registerEmitter operator alice
+  emitterId <- registerEmitter operator public alice
   Some em <- queryContractId alice emitterId
 
   msg0 <- submit alice do
@@ -73,12 +76,41 @@ testPublishMessage = do
   msg1.identity === em.identity
   pure ()
 
+-- | The @public@ party observes every template, so it can read the full record
+-- of the 'CoreState' and each 'Emitter' (including the advanced sequence). A
+-- party that is neither a stakeholder nor @public@ sees nothing.
+testPublicVisibility : Script ()
+testPublicVisibility = do
+  (operator, public, csId) <- setup
+  carol <- allocateParty "Carol"
+  emitterId <- registerEmitter operator public carol
+  _ <- submit carol do
+    exerciseCmd emitterId PublishMessage with nonce = 1, payload = "abcd", consistencyLevel = 0
+
+  -- public reads the shared config singleton...
+  [(csId', _)] <- query @CoreState public
+  csId' === csId
+  -- ...the recreated emitter with its advanced sequence...
+  [(_, em)] <- query @Emitter public
+  em.sequence === 1
+  -- ...and the emitter's immutable identity.
+  [(identId, _)] <- query @EmitterIdentity public
+  em.identity === identId
+
+  -- privacy still holds for a party that is neither stakeholder nor public.
+  outsider <- allocateParty "Outsider"
+  emsForOutsider <- query @Emitter outsider
+  length emsForOutsider === 0
+  csForOutsider <- query @CoreState outsider
+  length csForOutsider === 0
+  pure ()
+
 -- | Payloads larger than 750 bytes are rejected.
 testPayloadTooLarge : Script ()
 testPayloadTooLarge = do
-  (operator, _) <- setup
+  (operator, public, _) <- setup
   bob <- allocateParty "Bob"
-  emitterId <- registerEmitter operator bob
+  emitterId <- registerEmitter operator public bob
   -- 751 bytes = 1502 hex chars.
   let bigPayload = mconcat (replicate 1502 "f")
   submitMustFail bob do
@@ -97,7 +129,7 @@ testQuorum = do
 -- | The current guardian set is installed at index 0 and never expires.
 testInitialGuardianSet : Script ()
 testInitialGuardianSet = do
-  (operator, csId) <- setup
+  (operator, _, csId) <- setup
   Some cs <- queryContractId operator csId
   cs.guardianSetIndex === 0
   let gs = fromSome (Map.lookup 0 cs.guardianSets)
@@ -109,7 +141,7 @@ testInitialGuardianSet = do
 -- exercises the full keccak256 + DER + secp256k1WithEcdsaOnly path.
 testParseAndVerifyVAA : Script ()
 testParseAndVerifyVAA = do
-  (operator, csId) <- setup
+  (operator, _, csId) <- setup
   vaa <- submit operator do
     exerciseCmd csId ParseAndVerifyVAA with
       encodedVAA = govSetFeeVAA
@@ -121,7 +153,7 @@ testParseAndVerifyVAA = do
 -- | A SetMessageFee governance VAA verifies and updates the message fee.
 testGovernanceSetMessageFee : Script ()
 testGovernanceSetMessageFee = do
-  (operator, csId) <- setup
+  (operator, _, csId) <- setup
   newCsId <- submit operator do
     exerciseCmd csId SubmitGovernanceVAA with
       encodedVAA = govSetFeeVAA
@@ -137,23 +169,23 @@ testGovernanceSetMessageFee = do
 -- contract-id, which the Go test recomputes to check the mapping.
 integrationPublish : Script Party
 integrationPublish = do
-  (operator, _) <- setup
+  (operator, public, _) <- setup
   owner <- allocateParty "IntegrationEmitter"
-  emitterId <- registerEmitter operator owner
+  emitterId <- registerEmitter operator public owner
   _ <- submit owner do
     exerciseCmd emitterId PublishMessage with nonce = 42, payload = "11223344", consistencyLevel = 0
   pure operator
 
 -- | Exercise the auto-generated Archive choice on each template (for coverage).
 testArchives : Script ()
 testArchives = do
-  (operator, csId) <- setup
+  (operator, public, csId) <- setup
   submit operator do archiveCmd csId            -- Archive CoreState
   alice <- allocateParty "ArchAlice"
-  reqId <- submit alice do createCmd EmitterRequest with requester = alice, operator
+  reqId <- submit alice do createCmd EmitterRequest with requester = alice, operator, public
   submit alice do archiveCmd reqId              -- Archive EmitterRequest
   bob <- allocateParty "ArchBob"
-  emId <- registerEmitter operator bob
+  emId <- registerEmitter operator public bob
   submit operator do archiveCmd emId            -- Archive Emitter
   -- The immutable identity is normally never archived; exercise it here for
   -- coverage (operator is its signatory).