175 lines
8.6 KiB
Markdown
175 lines
8.6 KiB
Markdown
|
# Gas-Native `c*` / `cW*` Rollout Runbook
|
||
|
|
|
||
|
|
**Purpose:** Safely activate the Wave 1 gas-native compliant families without breaking existing live corridors. This runbook covers the operator sequence for registry, env, API publication, bridge readiness, and venue exposure.
|
||
|
|
|
||
|
|
## 1. Scope
|
||
|
|
|
||
|
|
Wave 1 families:
|
||
|
|
|
||
|
|
- `eth_mainnet` on Ethereum Mainnet
|
||
|
|
- `eth_l2` on Optimism, Arbitrum One, and Base
|
||
|
|
- `bnb` on BSC
|
||
|
|
- `pol` on Polygon
|
||
|
|
- `avax` on Avalanche C-Chain
|
||
|
|
- `cro` on Cronos
|
||
|
|
- `xdai` on Gnosis Chain
|
||
|
|
- `celo` on Celo
|
||
|
|
- `wemix` on Wemix
|
||
|
|
|
||
|
|
Canonical gas-family assets live on Chain 138 as `c*`. Mirrored assets live on destination chains as `cW*`. DODO PMM is the compliant edge venue; Uniswap v3 is the mandatory reference venue; Balancer and Curve are same-window only where the protocol exists and the basket design is valid; 1inch is routing exposure only after underlying venues are live.
|
||
|
|
|
||
|
|
## 2. Safety Rules
|
||
|
|
|
||
|
|
- Do not overwrite working bridge env or live pool addresses with placeholders.
|
||
|
|
- Do not mark Balancer, Curve, or 1inch live until the required DODO and Uniswap lanes are already funded and indexed.
|
||
|
|
- Do not promote a lane from `hybrid_cap` to `strict_escrow` by renaming symbols or swapping token identities. Promotion is policy and verifier wiring, not a registry rename.
|
||
|
|
- Keep `eth_mainnet` and `eth_l2` isolated. Cross-lane redemption is only allowed inside the `eth_l2` family.
|
||
|
|
|
||
|
|
## 3. Config Sources
|
||
|
|
|
||
|
|
- Registry: [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
|
||
|
|
- Runtime transport overlay: [`config/gru-transport-active.json`](../../config/gru-transport-active.json)
|
||
|
|
- Public deployment graph: [`cross-chain-pmm-lps/config/deployment-status.json`](../../cross-chain-pmm-lps/config/deployment-status.json)
|
||
|
|
- Publication runtime: [`smom-dbis-138/services/token-aggregation/.env.example`](../../smom-dbis-138/services/token-aggregation/.env.example)
|
||
|
|
|
||
|
|
## 4. Operator Sequence
|
||
|
|
|
||
|
|
1. Confirm config integrity.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bash scripts/validation/validate-config-files.sh
|
||
|
|
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
|
||
|
|
```
|
||
|
|
|
||
|
|
2. Sync publication env for token-aggregation without touching live operator RPCs.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bash scripts/deploy-token-aggregation-for-publication.sh /tmp/token-aggregation-gas-rollout
|
||
|
|
```
|
||
|
|
|
||
|
|
The deploy helper now reads `config/gru-transport-active.json` and syncs every referenced `env` key into the published `.env`, including the gas-family `CW_GAS_*` and `CW_MAX_OUTSTANDING_*` keys.
|
||
|
|
It also publishes `CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` as a neutral reference to the deployed generic gas verifier without auto-activating the live gas-verifier envs.
|
||
|
|
When you want the non-secret gas runtime scaffold locally, run `bash scripts/verify/print-gas-runtime-env-canonical.sh`. It derives per-lane caps from the registry and uses the live canonical `totalSupply()` as the zero-supply baseline for outstanding / escrowed defaults.
|
||
|
|
|
||
|
|
3. Verify the explorer-facing publication surface.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
SKIP_BRIDGE_ROUTES=0 SKIP_BRIDGE_PREFLIGHT=0 SKIP_GAS_REGISTRY=0 \
|
||
|
|
bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
|
||
|
|
|
||
|
|
bash scripts/verify/check-token-aggregation-chain138-api.sh
|
||
|
|
ALLOW_BLOCKED=1 bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
|
||
|
|
```
|
||
|
|
|
||
|
|
4. Inspect gas-lane deployment state before activating routing.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bash scripts/verify/check-gas-public-pool-status.sh
|
||
|
|
bash scripts/verify/check-gas-rollout-deployment-matrix.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
The gas rollout verifier summarizes:
|
||
|
|
|
||
|
|
- runtime-ready vs blocked gas transport pairs
|
||
|
|
- strict-escrow vs hybrid-cap lanes
|
||
|
|
- DODO wrapped-native and stable-quote pool coverage
|
||
|
|
- Uniswap v3 reference visibility
|
||
|
|
- Balancer / Curve support flags
|
||
|
|
- 1inch routing visibility
|
||
|
|
- missing env refs or supply-accounting blockers per lane
|
||
|
|
|
||
|
|
The deployment matrix adds the contract-level audit:
|
||
|
|
|
||
|
|
- whether the canonical gas token actually exists on Chain 138
|
||
|
|
- whether the mirrored gas token actually exists on the destination chain
|
||
|
|
- whether the currently loaded L1/L2 bridge refs resolve to bytecode
|
||
|
|
- whether the gas verifier and vault refs resolve to bytecode
|
||
|
|
- the next deploy or config command for each blocked lane
|
||
|
|
|
||
|
|
Current live baseline as of 2026-04-05:
|
||
|
|
|
||
|
|
- `CWAssetReserveVerifier` is deployed on Chain 138 at `0xbf26a679586663f87f3bf3f52c79479b8aa8d854`, but it is not attached to the live L1 bridge yet.
|
||
|
|
- All 9 Wave 1 canonical gas-family tokens are deployed on Chain 138.
|
||
|
|
- 10 of 11 public mirrors are deployed and have bridge `MINTER_ROLE` / `BURNER_ROLE` granted.
|
||
|
|
- The only undeployed mirror is `cWWEMIX` on chain `1111`.
|
||
|
|
- `wemix` is now carried as **deferred staged metadata** in the registry, not an active transport lane. The active gas rollout matrix therefore covers `10` active transport pairs and `1` deferred pair.
|
||
|
|
- `scripts/verify/check-gas-rollout-deployment-matrix.sh` now also probes each active lane's destination CCIP selector on the live Chain 138 bridge. Current live status is `0/10` destinations wired and the observed Chain 138 bridge exposes only `admin` + `destinations(...)` read paths, so it is reported as `partial_destination_only` rather than full accounting introspection.
|
||
|
|
- `scripts/deployment/print-gas-l1-destination-wiring-commands.sh` prints the exact `configureDestination(address,uint64,address,bool)` commands still needed for the 10 active non-Wemix gas lanes, using the selector metadata resolved from the active GRU transport overlay.
|
||
|
|
- `scripts/deployment/run-gas-l1-destination-wiring.sh` wraps those same 10 commands into a single operator-ready runner. It is echo-only by default and only broadcasts when `EXECUTE_GAS_L1_DESTINATIONS=1` is set.
|
||
|
|
|
||
|
|
5. Only after the verifier is clean for a lane, activate public routing in this order:
|
||
|
|
|
||
|
|
1. DODO wrapped-native pool live
|
||
|
|
2. DODO stable-quote pool live
|
||
|
|
3. Uniswap v3 reference live
|
||
|
|
4. Balancer and Curve when supported and funded
|
||
|
|
5. 1inch routing visibility
|
||
|
|
|
||
|
|
## 5. Required Env Groups
|
||
|
|
|
||
|
|
Publication and operator surfaces should provide:
|
||
|
|
|
||
|
|
- `CHAIN138_L1_BRIDGE`
|
||
|
|
- `CW_BRIDGE_*` for every enabled destination, including `CW_BRIDGE_WEMIX`
|
||
|
|
- `CW_RESERVE_VERIFIER_CHAIN138`
|
||
|
|
- `CW_STABLECOIN_RESERVE_VAULT`
|
||
|
|
- `CW_RESERVE_SYSTEM`
|
||
|
|
- `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138`
|
||
|
|
- `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138`
|
||
|
|
- `CW_GAS_ESCROW_VAULT_CHAIN138`
|
||
|
|
- `CW_GAS_TREASURY_SYSTEM`
|
||
|
|
- `CW_MAX_OUTSTANDING_*`
|
||
|
|
- `CW_GAS_OUTSTANDING_*`
|
||
|
|
- `CW_GAS_ESCROWED_*`
|
||
|
|
- `CW_GAS_TREASURY_BACKED_*`
|
||
|
|
- `CW_GAS_TREASURY_CAP_*`
|
||
|
|
|
||
|
|
For publication-only environments, zero-valued gas accounting is acceptable when the lane has no outstanding supply yet. Live operators should replace those zeros with authoritative values before enabling routing or claiming runtime readiness.
|
||
|
|
`CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` is safe to publish as a neutral reference, but it does not mean the live bridge has been attached to that verifier yet.
|
||
|
|
|
||
|
|
## 6. Lane Promotion Checklist
|
||
|
|
|
||
|
|
To promote a gas lane from `hybrid_cap` to `strict_escrow`:
|
||
|
|
|
||
|
|
1. Deploy or confirm the strict escrow verifier.
|
||
|
|
2. Confirm wrapped-native custody or equivalent escrow source.
|
||
|
|
3. Update the verifier and accounting env refs.
|
||
|
|
4. Keep the same `familyKey`, canonical symbol, mirrored symbol, and pool addresses.
|
||
|
|
5. If you use the generic verifier path, it is valid to point both `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138` and `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138` at the same deployed `CWAssetReserveVerifier` instance and configure the token-specific rules inside that verifier.
|
||
|
|
5. Re-run:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bash scripts/validation/validate-config-files.sh
|
||
|
|
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
|
||
|
|
bash scripts/verify/check-gas-public-pool-status.sh
|
||
|
|
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
|
||
|
|
```
|
||
|
|
|
||
|
|
## 7. Manual / Live-Only Steps
|
||
|
|
|
||
|
|
The repo and live deploys now cover the token-contract layer. These steps still require operator execution:
|
||
|
|
|
||
|
|
- fund DODO and Uniswap lanes
|
||
|
|
- fund the deployer with at least `0.4 WEMIX`, deploy the Wemix CCIP bridges, and set `CW_BRIDGE_WEMIX` before deploying the Wemix mirror
|
||
|
|
- replace the remaining Wemix placeholder mirror address
|
||
|
|
- decide when to attach the generic gas verifier to the live L1 bridge
|
||
|
|
- promote Balancer / Curve / 1inch only after venue proof
|
||
|
|
- wire live treasury and escrow accounting feeds
|
||
|
|
- perform fork or live-dry-run execution for each new lane
|
||
|
|
|
||
|
|
## 8. Related Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Local rollout integrity
|
||
|
|
bash scripts/validation/validate-config-files.sh
|
||
|
|
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
|
||
|
|
|
||
|
|
# Publication health
|
||
|
|
SKIP_BRIDGE_ROUTES=0 SKIP_BRIDGE_PREFLIGHT=0 SKIP_GAS_REGISTRY=0 \
|
||
|
|
bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
|
||
|
|
|
||
|
|
# Runtime readiness
|
||
|
|
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
|
||
|
|
bash scripts/verify/check-gas-public-pool-status.sh
|
||
|
|
```
|