Multiasset: FA2 token bridging support (REQUIRES THOROUGH AUDIT BEFORE MERGE)

[murbard]

⚠️ This branch requires several deep adversarial audit passes by independent reviewers before merge. Nothing here has been externally validated.

Why

The rollup has been tez-only. Adding FA2 tokens (Tezos's fungible-asset standard) lets users shield/transfer/unshield arbitrary assets while reusing the same proof system. The hard constraint is doing this without sacrificing privacy: if every asset had its own commitment encoding, on-chain observers could trivially separate rare-asset transactions from common-asset ones. The design here keeps a single commitment scheme that hides which asset a note carries, so rare-asset transactions blend with the common-asset crowd.

How — the key design choices

Asset hides in the commitment preimage, not on the wire. The commitment goes from 4-ary H_commit(d_j, v, rcm, owner_tag) to 5-ary H_commit(d_j, v, asset_id, rcm, owner_tag). The on-chain cm is still a single felt; nothing about it reveals the asset. Two notes with identical (d_j, v, rcm, owner_tag) but different assets produce different commitments, but an observer can't reverse this.

Asset_id is structurally derived from the L1 ticketer. asset_id = H("tzel:asset:" || ticketer_kt1). ASSET_TEZ = 0 preserves backward compat. One KT1 = one asset_id; no on-chain registration step. The kernel's registered-asset list is the compile-time constant COMPILE_TIME_FA2_BRIDGES. Trade-off: asset removal is asymmetric — un-registering a ticketer refuses new deposits but leaves existing pools and notes intact (re-add the ticketer to restore spendability).

Two-accumulator per-asset balance, not N-asset. Cairo can't iterate over felts inside a constraint system, so the abstract "for every α, sum_in(α) = sum_out(α) + (fee if α==tez)" doesn't transpile directly. Instead the witness declares one primary non-tez asset A per transaction, and the circuit gates every input/output asset to {ASSET_TEZ, A}. Two accumulators (tez_in/tez_out, primary_in/primary_out) close the per-asset balance separately. This is strictly stronger than the abstract conservation: a 3-asset transaction (tez + FA2_X + FA2_Y) is rejected, and clients serialize it as a sequence of 2-asset transactions. The simplification dramatically cuts circuit cost.

Producer fee is permanently tez. DAL slot publisher liquidity argument: if producer-fee notes could be in any asset, a hostile publisher submitting blocks of fee-paid-in-illiquid-NFT transactions would starve the inclusion market. The circuit pins asset_producer == ASSET_TEZ directly. This drives the most consequential downstream constraint: any FA2 transaction must also spend some tez (to pay the producer fee), and any FA2 shield must debit producer_fee from a tez pool somewhere. The kernel's FA2 shield path therefore debits two pools — the FA2 pool for v + fee AND the user's tez pool at the same pubkey_hash for producer_fee. Without this dual-pool debit, an FA2 shield would mint producer_fee tez in the commitment tree out of nothing.

Phase C adds slots, not transactions. Mixed-asset transfers can legitimately need two change notes (one per asset). Transfer goes from 3 output slots (recipient + change + producer fee) to 4 (recipient + change_1 + change_2 + producer fee). Unshield gains a parallel cm_change_2. Single-asset transactions use the extra slot as a zero-value placeholder — uniformity is cheaper at proof time than branching.

L2 ticket content is canonical (0, None). The FA2 bridge ticketer's L2 ticket carries no FA2-specific info inside its content. The (FA2, token_id) binding lives in the ticketer's immutable storage; the L2 asset_id derivation from the ticketer's KT1 captures the rest. The kernel uniformly enforces content.token_id == 0 on every deposit and emits the same on every burn — so any non-canonical content design would only work for token_id == 0 FA2s.

Where to direct review attention

In rough order of "what breaks worst if wrong":

1. Per-asset balance in the Cairo circuits. The 2-accumulator scheme is stricter than the abstract conservation property — convince yourself the stricter constraint actually closes for transfer and unshield, including the producer-fee tez routing and (for unshield) the v_pub routing to tez_out or primary_out based on asset_pub.
2. Dual-pool debit for FA2 shields, kernel side. The apply step must remain infallible; convince yourself the second debit doesn't introduce a fallible operation, and that interleaved sequences of (FA2 deposit, FA2 shield, tez deposit, tez shield) can't get the kernel into an inconsistent state.
3. Asset_id consistency across layers. Cairo, Rust kernel, and Michelson must agree on the bit-string asset_id for any given ticketer. Three layers, three opportunities for drift (string canonicalisation, b58check round-trip, hash personalisation, padding).
4. L2 ticket canonical content. Convince yourself the Michelson ticketer's mint/burn paths emit/accept (0, None) regardless of storage.token_id, AND that the kernel's outbox encoder for unshield burns produces a ticket the ticketer's burn entrypoint will accept.
5. Watcher recovery iteration. View and outgoing watch modes can't read the asset from the on-chain cm alone — they iterate the candidate-asset list and pick the one whose recomputed commitment matches. Convince yourself this iteration can't produce a wrong-asset label or admit a collision yielding a false positive.
6. Wire v3→v4 boundary. Cross-implementation consumers pinned to v3 will silently compute different commitments. The branch ships no upgrade migration; multiasset assumes a fresh deployment.

Known limitations

• Coq Spec/* is aspirational. See coq/STATUS.md. The Spec→Impl refinement theorems for shield, transfer, and unshield are stubs. If anything downstream is marketed as "formally verified", the marketing is overclaiming. Treat the Coq layer as documentation of intended invariants, not proof of them.
• The .xmss-floor sidecar protection against stale-wallet-backup restore is best-effort, not addressable without external attestation infrastructure (out of scope for this branch).

Scale

76 commits ahead of main. 93 files changed; ~16,600 lines added.

Updated 2026-06-10: merged main back into the branch (resolving wallet conflicts between the multiasset (asset_id, pubkey_hash) pool keying and main's pinned-block consistency refactor), synced the OCaml port to the 5-ary commitment (fixing the long-red ocaml CI job), and restored the outgoing_ct field the vector regeneration had dropped.

[denver-s]

Continued audit, now at e2fbf1f (previous pass was at 744fedf). TL;DR: ce399d1 correctly fixes the OCaml 4-ary-commitment HIGH, and the merge resolution in e2fbf1f checks out — but one HIGH remains open (silent note drop + cursor advance, inline comment below), and the merge actually widened its blast radius.

Verified this round

• ce399d1 is correct. The new OCaml hash_commit 160-byte layout matches Rust core::commit() byte-for-byte (v as u64 LE at [32..40), zero pad to 64, asset at [64..96), cmmtSP__). Every regenerated cm/nf in protocol_v1_ocaml.json appears verbatim in the Rust-generated protocol_v1.json, and the restored outgoing_ct line matches the generator's vec![0xEE; …] fixture. cargo test -p tzel-services --release: green.
• The e2fbf1f conflict resolutions are sound. load_pool_balances_at_block threads block_ref (not a re-resolved head) into the 3-arg try_read_deposit_balance, preserving PR #24's pinned-block invariant under the multiasset (asset_id, pubkey_hash) keying; apply_scan_feed_finalize's prune predicate keys on (p.asset_id, p.pubkey_hash). No evil-merge content found in the combined diff.

Still open, not inline-anchorable (code outside this PR's diff or no single line):

1. test_vectors.exe is still not wired into CI — scripts/ocaml_unit_tests.sh only runs test_main.exe. This is exactly how 744fedf's outgoing_ct drop shipped silently: it broke test_vectors.exe, which nothing executes. ce399d1 repaired the data but not the missing gate; it's a one-line addition to the script.
2. No version field on WalletFile (apps/wallet/src/lib.rs:465). Loading is bare serde-with-defaults. v3→v4 is fine (old notes default to tez), but a v4 wallet opened by a pre-multiasset binary silently drops asset_id and treats FA2 notes as tez. WatchWalletFile.version exists but is never checked outside tests.
3. Withdrawals to KT1 can strand funds permanently — validate_l1_withdrawal_recipient (core/src/lib.rs:661) accepts any contract, but the outbox message types the receiver as contract unit; a KT1 without a unit/default entrypoint fails outbox typing forever (ticket stuck in the rollup, FA2 stuck in the ticketer). Restrict to implicit accounts or document loudly.
4. configure_bridge uses a weaker ticketer validator than validate_l1_ticketer_canonical (tezos/rollup-kernel/src/lib.rs:2099): no trim, no round-trip re-emit, and it stores the original string later used in exact-match deposit comparison. Config is one-shot, so any looseness is a permanent brick — route it through the canonical validator (744fedf did this for the CLI but not the kernel).
5. encode_withdrawal_record's .expect() (tezos/rollup-kernel/src/lib.rs:640) sits inside the infallible apply path after write_output. Currently unreachable (recipient capped at 128 wire bytes), but it re-opens the H1 atomicity shape if bounds ever change — hoist into the fallible prepare step.
6. FA2 paths still have no cross-impl or real-proof coverage: protocol_v1.json has no derive_asset_id vectors and no asset_id on note vectors; cross_impl_interop and proof_bench are tez-only; all FA2 routing tests use synthetic hand-built public outputs, never an actual STARK proof.

Recommendation: fix the silent-drop HIGH (inline at apps/wallet/src/lib.rs:803) before merge — the merge made it strictly worse, see comment. Items 1 and the spec/wire-doc inline nits are trivial; the rest are solid fast-follows, with FA2 real-proof coverage the most valuable for an audit-gated branch.

[denver-s]

HIGH — still open at e2fbf1f, and the merge widened it. A note that detects and decrypts (a strong signal it's ours) but matches no compile-time asset candidate returns None via this .find(…)? — indistinguishable from "not my note", no warning. The scan cursor then advances unconditionally, and there's no rescan command, so the note is permanently lost behind the cursor.

Concrete scenario: a user on binary vN receives an FA2 note for a bridge added in vN+1 (the registry is compile-time). The note decrypts, is silently dropped, and after upgrading is never revisited — funds invisible short of hand-editing scanned in wallet.json.

The merge made this worse: the cursor now advances in three places — apply_scan_feed (~line 5968), main's new batched hot path apply_scan_feed_recover_batch (~line 6036), and the watcher paths (~lines 1271/1291/1310) — and PR #24's incremental persist fsyncs the cursor at every checkpoint, so the loss is durable even on an interrupted sync.

Minimal fix: distinguish "decrypts but no candidate matches" from "not my note" — log loudly and either don't advance the cursor past it or record the index for re-evaluation; and/or add a rescan command. This is the same class as the W1/W2 fixes, but for registry-version skew: a214260 added candidate iteration without adding detection of the no-candidate-matches state.

[denver-s]

False backward-compat claim — likely the root cause of the OCaml drift that ce399d1 just fixed. The 128→160-byte arity change alters every commitment even with asset = 0x00..00: H(d‖v‖rcm‖otag) ≠ H(d‖v‖0³²‖rcm‖otag). "A tez-only deployment computes the same cm as it did pre-multiasset" is exactly why the fixtures had to be regenerated — the sentence contradicts the regeneration it forced. Suggest: "ASSET_TEZ = 0x00..00 reserves the zero tag for tez; note that the v4 arity change alters all commitments relative to pre-multiasset, including tez-only ones."

[denver-s]

This docstring is false: pre-multiasset messages don't "decode to ASSET_TEZ" — they misparse entirely. Shield gained a leading asset_id, transfer gained cm_4/enc_4, unshield gained cm_change_2, yet KERNEL_WIRE_VERSION is still 17 (line 14). A v17-pinned consumer passes the version gate and misparses — the same rationale the team used for the canonical-wire v3→v4 bump applies here. Mitigated by the fresh-deployment assumption, but the bump is a one-line fix and the docstring should be corrected either way.

[denver-s]

Registry is untested. Nothing asserts the docstring's derived asset_id (b7d8096d…) or that these entries pass validate_l1_ticketer_canonical. A typo'd KT1 here compiles fine and yields a dead registry entry whose deposits are rejected at runtime — on the wallet side that feeds directly into the silent-drop path flagged at apps/wallet/src/lib.rs:803. A #[test] asserting each entry round-trips through the canonical validator + a pinned-value test for the derived asset_id would make this compile-time data self-checking.

[denver-s]

Nit (pre-existing, but adjacent to this fix): Felt.of_u64 (Int64.to_int v) truncates — OCaml's native int is 63-bit, so any v ≥ 2^62 loses the top bit(s) and produces a commitment that diverges from Rust. The u64-max cross-impl fixture test only passes because it builds the value felt from raw fixture bytes, bypassing this path. Since ce399d1 is specifically about killing u64-range cross-impl drift, consider a Felt.of_int64 using Int64.logand/shift_right_logical so Note.create can't reintroduce the same class of bug.