Multichain trading vault: Sui hub / Robinhood spoke (full plan implementation)

[ewitulsk]

Implements docs/multichain-vault-plan.md end to end: Sui hub / Robinhood spoke multichain trading vault with hub-master accounting, a dumb spoke vault, transport-agnostic messaging (LayerZero primary, CCIP secondary, dev relayer for CI), and no hub↔spoke fund movement (rebalance integration is a mainnet launch gate).

What's in here

Wire format (phase 1) — rust-backend/crates/vault-messages: canonical big-endian fixed-width layout for the 7 hub↔spoke messages + committed golden fixtures. The Move and Solidity codecs are pinned to those fixtures byte-for-byte (tests in all three languages).

Hub Move (phase 2) — contracts/trading-vault-v2 gains wire, spoke, endpoint (+ shared EndpointRegistry), endpoint_relayer (dev/CI transport), multichain (spoke binding, ordered-lane handlers, ConfigSync), asset_markers. Key semantics:

• Event-sourced hub books: deposit notices mint ledger shares into the same TrancheBook as wallet positions (tranches supported; entry/exit haircuts, lockups, exit-crystallized fees identical to hub deposits); StateSync is a freshness proof + reconciliation cross-check, never a value source.
• Withdrawals burn in full at ACK; payables are netted out of NAV (§5.1); protocol fee cut mints into an admin-claimable escrow position (cash lives on the spoke).
• Relayer-side faults abort (lane frozen, retryable); spoke-side conditions reject with explicit codes (lane advances) — a bad request can never wedge the lane.
• Appraisals require a fresh spoke leg per bound spoke (record_spoke_state); a dark spoke blocks NAV vault-wide (fail-safe). Close is blocked until spokes are drained + unbound.
• Layout-incompatible (TradingVault.spokes, Appraisal spoke fields): ships via fresh publish, per API_DELTA.md.
• 141/141 Move tests (115 pre-existing + 26 new), and the pinned deploy-compiler build test passes (now also building both endpoint packages).

EVM spoke (phase 3) — new evm-contracts/ Foundry workspace: SpokeVault (pending/active/reserved fund states, per-chain depositor whitelist, deposit/reclaim, per-tranche withdraw + FIFO payout queue, native fee pot, endpoint-gated handleMessage with strict seq, ConfigSync-driven curator/endpoint/integration-set — none of those are local roles, stale-heartbeat freeze, OZ AccessControlDefaultAdminRules two-step admin), Relayer/LayerZero/CCIP endpoints, TUSDG faucet mock, vendored OZ v5.4.0 (contracts only). 63/63 forge tests incl. golden fixtures, an endpoint-switch drill, and the deploy-script tests below.

Transports (phases 5–6) — contracts/endpoint-layerzero (real OApp integration: lz_receive/lz_send/confirm, peer + eid mapping) and contracts/endpoint-ccip (receiver-registry + Any2SuiMessage consume, OnRamp ccip_send), both building against pinned upstream LayerZero-v2 / chainlink-sui packages, both in the Move CI matrix.

Off-chain (phase 4) — rust-backend/services/vault-messenger: ordered per-lane delivery queues in Postgres, hub PTB construction (appraisal legs + attestations + handler + send), EVM delivery, syncState/ConfigSync cranks, alerting per tx-alerting convention (tx-failed-vault-messenger, queue-stalled, payout-queue-aged, fee-pot-low), small HTTP API, deployment registration mirroring cctp-relay. 24/24 unit tests.

Frontend (phase 7) — /spoke screen (viem-only injected wallet): deposit/reclaim with pending→active status, per-tranche withdraw + payout-queue view, status strip (pause/risk-off/heartbeat/fee pot), testnet TUSDG faucet. Typecheck + production build pass.

One place to write addresses (follow-up in this same PR)

The redeploy pipeline is now the single writer of every multichain address, and token-info the single server:

• Schema — crates/deployments gains endpointLayerzero / endpointCcip / multichain { endpointRegistryId, hubChainId, spokes. } blocks on PackageInfo (all optional, absent-not-null; serde round-trip tests). token-info serves PackageInfo verbatim, so /package-info picks these up with zero service changes; token-info-client gains typed accessors.
• Writer — deployment-manager gains --deploy-endpoints (publishes both Sui transport packages, extracts LzTransport/OApp/CcipTransport shared objects, refreshes multichain.endpointRegistryId from the trading-vault publish, cctp-style carry-forward), --hub-chain-id, and --record-evm-spoke (validating read-merge-write of the forge deploy artifact into multichain.spokes).
• EVM deploys in redeploy-contract.yml — new dispatch inputs deploy_endpoints and deploy_evm_spoke; the latter runs evm-contracts/script/DeploySpoke.s.sol (foundry-toolchain, repo secrets SPOKE_RPC_URL + EVM_DEPLOYER_KEY, params in repo variable EVM_SPOKE_PARAMS) and folds the artifact into deployments.json before the existing commit step — EVM addresses ride the same commit, bundle, and token-info restart as Sui ids. Proven end-to-end against anvil (script deploy → cast checks → --record-evm-spoke merge in the exact reader shape).
• Consumers — vault-messenger resolves every package/object id and spoke address from token-info at boot (TOML fields are now break-glass overrides; vault_id, RPCs, intervals stay config); the frontend populates the spoke config from /package-info's multichain block (static map reduced to rpc/explorer metadata). deployment-manager 12/12, deployments 7/7, vault-messenger 24/24, forge 63/63.

Not done in this PR (honest gaps)

• No live-lane verification: LayerZero/CCIP transport packages compile against pinned upstream and pass config-surface tests, but their receive/send paths need a real testnet endpoint to exercise; same for publish-effects extraction shapes in --deploy-endpoints and the messenger's PTB shapes (each fails loudly if wrong).
• Registry seeding + transport wiring + bind + fee-pot funding remain ceremony steps (runbook §2/4/5); the pipeline covers publishes, EVM deploys, and address recording.
• Per the locked plan: no bridging, no Hyperliquid, no rebalance integration (mainnet launch gate), spoke shares non-transferable.
• Branch note (resolved): a session credential outage forced the last few commits through the GitHub API, which initially left rust-backend/Cargo.lock one line short (the file exceeded the API payload limit). Fixed on-branch: a temporary push-triggered workflow regenerated the lock on a runner (commit f0856e2, byte-identical to the local tree) and was then removed (fbf5fa4/f9fe1e8 add it, a9580fe deletes it). cargo build --locked works on the branch.

Verification

• sui move test (testnet-v1.78.1): trading-vault-v2 141/141; endpoint-layerzero 2/2; endpoint-ccip 2/2.
• cargo test -p deployment-manager --test deploy_build (pinned deploy compiler): pass, incl. both endpoint packages.
• forge test: 63/63; anvil deploy-script proof run green.
• cargo check workspace; cargo test for vault-messages, vault-messenger (24/24), deployments (7/7), deployment-manager (12/12), token-info-client (6/6).
• Frontend typecheck + vite build: pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EHimiGNoVjEP65m8dch776

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
exchange-dashboard	Ready	Preview	Aug 30, 2026 11:16am
sui-options	Ready	Preview	Aug 30, 2026 11:16am