7ac74f432b
- Institutional / JVMTM / reserve-provenance / GRU transport + standards JSON - Validation and verify scripts (Blockscout labels, x402, GRU preflight, P1 local path) - Wormhole wiring in AGENTS, MCP_SETUP, MASTER_INDEX, 04-configuration README - Meta docs, integration gaps, live verification log, architecture updates - CI validate-config workflow updates Operator/LAN items, submodule working trees, and public token-aggregation edge routes remain follow-up (see TODOS_CONSOLIDATED P1). Made-with: Cursor
81 lines
6.8 KiB
Markdown
81 lines
6.8 KiB
Markdown
# cW* Bridge Approach (Chosen Strategy)
|
||
|
||
**Created:** 2026-02-27
|
||
**Status:** Decided — Option 2 (dedicated cW* receiver)
|
||
**Related:** [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md), [CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md](CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md)
|
||
|
||
---
|
||
|
||
## 1. Decision (A1)
|
||
|
||
**Chosen: Option 2 — Deploy dedicated cW* receiver per chain.**
|
||
|
||
In operator terminology, this dedicated cW stack is the **GRU Monetary Transport Layer** (short name: **GRU Transport**). Chain 138 remains the canonical monetary layer for `c*`, while public chains carry `cW*` as **Compliant Wrapped ISO-4217 M1** instruments.
|
||
|
||
- **Option 1 (extend existing bridge):** Would require changing CCIPWETH9Bridge / CCIPRelayBridge to accept more than WETH9 and mint cW* in `ccipReceive`. That mixes WETH and cW* in one contract and complicates upgrades.
|
||
- **Option 2 (dedicated receiver):** Use a contract that only handles cW* mint-on-receive and burn-on-send (e.g. **TwoWayTokenBridgeL2** or a minimal **CCIPReceiverCW**). Keeps WETH bridges unchanged; cW* flow is separate and easier to reason about.
|
||
|
||
**Concrete choice:** Use **TwoWayTokenBridgeL2** (or equivalent) per (chain, token) — one deployment per chain for cWUSDT and one for cWUSDC, or a generic receiver that supports multiple cW* via message data. **CompliantWrappedToken** is extended with **burnFrom** so TwoWayTokenBridgeL2’s outbound `burnFrom` works (Phase C1).
|
||
|
||
For the hard-peg rollout described in [CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md](CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md), the stricter production path is now the dedicated multi-token pair:
|
||
|
||
- [`CWMultiTokenBridgeL1.sol`](../../smom-dbis-138/contracts/bridge/CWMultiTokenBridgeL1.sol) on Chain 138 with canonical-token allowlists, locked-balance accounting, and per-destination outstanding ceilings
|
||
- [`CWReserveVerifier.sol`](../../smom-dbis-138/contracts/bridge/integration/CWReserveVerifier.sol) on Chain 138 to gate new outbound wraps using vault-backing and reserve-system checks
|
||
- [`CWMultiTokenBridgeL2.sol`](../../smom-dbis-138/contracts/bridge/CWMultiTokenBridgeL2.sol) on the destination chain with frozen token-pair / peer config plus minted/burned supply telemetry
|
||
|
||
Activation and public exposure for that stack are now gated by [`config/gru-transport-active.json`](../../config/gru-transport-active.json), which sits on top of the broader mapping and deployment JSONs.
|
||
|
||
Standardization rule: the GRU transport overlay should enable every public chain that is already structurally compatible for the active canonical set, meaning the repo has a `138 -> chain` mapping, non-zero `cW*` deployment addresses, and `bridgeAvailable: true`. This keeps the methodology consistent across public chains without overstating chains that are still design-only.
|
||
|
||
---
|
||
|
||
## 2. Flow 138 → chain (lock c* on 138, mint cW* on destination)
|
||
|
||
1. **User on Chain 138** locks cUSDT (or cUSDC) in a sender contract (e.g. UniversalCCIPBridge, or a dedicated c*→cW* bridge on 138).
|
||
2. **Sender** sends a CCIP message to the **destination chain** with:
|
||
- **Receiver:** Dedicated cW* receiver (e.g. TwoWayTokenBridgeL2 instance for cWUSDT on that chain).
|
||
- **Data:** `abi.encode(recipient, amount)` (same as TwoWayTokenBridgeL2).
|
||
- **Token amounts:** Either none (lock-and-mint: 138 locks c*, destination mints cW*) or source token as specified by the bridge design.
|
||
3. **On destination chain,** the **cW* receiver**’s `ccipReceive` is called by the CCIP router. It decodes `(recipient, amount)` and calls **cWUSDT.mint(recipient, amount)** (receiver must have MINTER_ROLE on the cW* token).
|
||
4. **User on destination** receives cWUSDT.
|
||
|
||
**Contracts implementing receive:** Dedicated cW* receiver (e.g. TwoWayTokenBridgeL2 with `mirroredToken` = cWUSDT or cWUSDC). Not CCIPWETH9Bridge / CCIPRelayBridge (they remain WETH-only).
|
||
|
||
**Contracts implementing send (138 side):** UniversalCCIPBridge (if extended for c* and destination = cW* receiver), or a dedicated “Lock c* and send CCIP” contract that configures receiver = TwoWayTokenBridgeL2 on the target chain.
|
||
|
||
---
|
||
|
||
## 3. Flow chain → 138 (burn cW* on chain, release c* on 138)
|
||
|
||
1. **User on destination chain** calls the **cW* receiver**’s outbound function (e.g. TwoWayTokenBridgeL2.**burnAndSend**(destSelector, recipient, amount)).
|
||
2. **Receiver** burns cW* from the user (`cWUSDT.burnFrom(user, amount)` — requires CompliantWrappedToken to implement **burnFrom**; see Phase C1) and sends a CCIP message to **Chain 138** with receiver = L1 bridge and data `(recipient, amount)`.
|
||
3. **On Chain 138,** the L1 bridge (or release contract) receives the message and releases cUSDT to the recipient (e.g. transfer from escrow or mint if L1 is mintable).
|
||
|
||
**Contracts implementing burn-and-send:** Same dedicated cW* receiver (TwoWayTokenBridgeL2) that has BURNER_ROLE on the cW* token and implements **burnAndSend**. CompliantWrappedToken must expose **burnFrom** for TwoWayTokenBridgeL2.
|
||
|
||
**Contracts implementing receive on 138:** L1 bridge or release contract that holds or mints c* and credits the recipient.
|
||
|
||
---
|
||
|
||
## 4. Contract summary
|
||
|
||
| Role | Contract(s) |
|
||
|------|-------------|
|
||
| **cW* token (destination chain)** | CompliantWrappedToken (cWUSDT, cWUSDC). MINTER_ROLE and BURNER_ROLE granted to the dedicated receiver (e.g. TwoWayTokenBridgeL2). |
|
||
| **Receive on destination (mint cW*)** | TwoWayTokenBridgeL2 (or CCIPReceiverCW). Constructor(router, cWUSDT, feeToken). Implements ccipReceive → mint(recipient, amount). |
|
||
| **Send from destination (burn cW*, send CCIP)** | Same TwoWayTokenBridgeL2. burnAndSend → burnFrom(user) → ccipSend to 138. |
|
||
| **Send from 138 (lock c*, send CCIP)** | UniversalCCIPBridge (with c* and cW* receiver config) or dedicated lock-and-send contract. Receiver address = TwoWayTokenBridgeL2 on destination. |
|
||
| **Receive on 138 (release c*)** | L1 bridge or release contract (existing or new) that credits recipient when message received from destination chain. |
|
||
|
||
For hard-peg bridge pairs, replace the generic sender/receiver row above with `CWMultiTokenBridgeL1` + `CWReserveVerifier` + `CWMultiTokenBridgeL2` and complete the extra strict-mode wiring in [CW_DEPLOY_AND_WIRE_RUNBOOK.md](CW_DEPLOY_AND_WIRE_RUNBOOK.md).
|
||
|
||
---
|
||
|
||
## 5. References
|
||
|
||
- [TwoWayTokenBridgeL2.sol](../../smom-dbis-138/contracts/bridge/TwoWayTokenBridgeL2.sol) — Mint on receive, burnAndSend for outbound.
|
||
- [CompliantWrappedToken.sol](../../smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol) — mint, burn, burnFrom (Phase C1).
|
||
- [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md) — Full task list and phases.
|
||
- [CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md](CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md) — Concrete hard 1:1 redemption-peg architecture for `cWUSDC` and `cWUSDT`.
|
||
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](CW_DEPLOY_AND_WIRE_RUNBOOK.md) — Operator steps to deploy cW*, wire config, verify.
|