# 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
```