d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c58ccaf6cd1f78131e5e78702a694a1da8a4deb
proxmox/docs/03-deployment/GAS_NATIVE_C_STAR_CW_ROLLOUT_RUNBOOK.md
defiQUG dbd517b279 Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers. 
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains
- Omit embedded publish git dirs and empty placeholders from index

Made-with: Cursor
2026-04-12 06:12:20 -07:00

8.6 KiB
Raw Blame History

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

4. Operator Sequence

  1. Confirm config integrity.
bash scripts/validation/validate-config-files.sh
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
  1. Sync publication env for token-aggregation without touching live operator RPCs.
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.

  1. Verify the explorer-facing publication surface.
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
  1. Inspect gas-lane deployment state before activating routing.
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.

  1. Only after the verifier is clean for a lane, activate public routing in this order:

  2. DODO wrapped-native pool live

  3. DODO stable-quote pool live

  4. Uniswap v3 reference live

  5. Balancer and Curve when supported and funded

  6. 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.
  6. Re-run:
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

# 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
Reference in New Issue View Git Blame Copy Permalink