dbd517b279
- 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
128 lines
6.7 KiB
Markdown
128 lines
6.7 KiB
Markdown
# GRU Transport Active JSON
|
|
|
|
**Purpose:** Define the active-policy overlay for the **GRU Monetary Transport Layer**.
|
|
|
|
## File
|
|
|
|
- **Config:** [`config/gru-transport-active.json`](../../config/gru-transport-active.json)
|
|
- **Standards profile:** [`config/gru-standards-profile.json`](../../config/gru-standards-profile.json)
|
|
|
|
## What it gates
|
|
|
|
This file is the final activation gate for:
|
|
|
|
- enabled canonical `c*` assets on Chain 138
|
|
- enabled public destination chains for `cW*`
|
|
- authoritative destination `ccipChainSelector` metadata for each enabled bridge lane
|
|
- approved `CWMultiTokenBridgeL1` / `CWMultiTokenBridgeL2` peers
|
|
- reserve-verifier policy references for hard-peg eligible pairs
|
|
- required `maxOutstanding` policy per canonical token / destination chain
|
|
- public-pool exposure in token-aggregation
|
|
- pool routing eligibility in token-aggregation
|
|
- MCP visibility eligibility for public pools
|
|
|
|
The active overlay does **not** replace the existing universe/config files. It sits on top of them.
|
|
|
|
## Runtime readiness
|
|
|
|
The overlay now exposes two different readiness views through token-aggregation:
|
|
|
|
- **`eligible`**: the pair is structurally valid according to JSON policy, mappings, deployment status, and declared config refs.
|
|
- **`runtimeReady`**: the pair also has live bridge addresses, reserve-verifier refs, and required `maxOutstanding` values resolved in the current runtime environment.
|
|
|
|
This distinction matters operationally:
|
|
|
|
- A pair can be `eligible` but not `runtimeReady` if secrets or deploy-time env vars have not been loaded yet.
|
|
- `/api/v1/token-mapping/transport/active` reports both the structural pair data and summary counts such as `runtimeReadyTransportPairs`.
|
|
- `/api/v1/bridge/status` and `/api/v1/bridge/metrics` surface the same runtime-readiness view for operators.
|
|
- `/api/v1/bridge/preflight` focuses the output down to blocked pairs and the exact `runtimeMissingRequirements` / `eligibilityBlockers` that must be cleared.
|
|
|
|
## Relationship to other JSONs
|
|
|
|
- [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
|
|
Holds the full mapping universe for canonical `c*`, native public assets, and mirrored `cW*`.
|
|
- [`config/routing-registry.json`](../../config/routing-registry.json)
|
|
Holds the broader route-topology registry, including legacy WETH routes.
|
|
- [`cross-chain-pmm-lps/config/deployment-status.json`](../../cross-chain-pmm-lps/config/deployment-status.json)
|
|
Holds deployed `cW*` addresses and public PMM pool status.
|
|
- [`cross-chain-pmm-lps/config/pool-matrix.json`](../../cross-chain-pmm-lps/config/pool-matrix.json)
|
|
Defines the intended first local edge pools per chain.
|
|
|
|
## Activation model
|
|
|
|
An active GRU transport pair is only valid when all of the following agree:
|
|
|
|
1. The canonical token is enabled in `gru-transport-active.json`.
|
|
2. The destination chain is enabled in `gru-transport-active.json`.
|
|
3. The pair exists in `token-mapping-multichain.json`.
|
|
4. The mirrored `cW*` token is deployed in `deployment-status.json`.
|
|
5. The approved bridge peer is present in `gru-transport-active.json`.
|
|
6. A `maxOutstanding` policy reference is set for the pair.
|
|
7. Required reserve-verifier wiring references are present.
|
|
|
|
For gas-native rollout lanes, the overlay also carries the destination CCIP selector in both
|
|
`enabledDestinationChains[]` and `approvedBridgePeers[]`. Token-aggregation resolves that into
|
|
`destinationChainSelector` on each active transport pair so verifier and deployment scripts can
|
|
check whether the live Chain 138 bridge has actually wired the destination.
|
|
|
|
## Standard methodology
|
|
|
|
The repo now treats GRU Transport as the canonical standard for public-chain monetary transport:
|
|
|
|
- **Chain 138** keeps the canonical `c*` asset.
|
|
- A compatible public chain receives the mirrored **`cW*`** asset.
|
|
- The transport method is **lock canonical `c*` on 138, mint mirrored `cW*` on destination**.
|
|
- Local trading remains **chain-local edge pools**, not literal cross-chain pools.
|
|
- Legacy WETH bridge routes remain separate and are not part of GRU Transport.
|
|
|
|
Compatibility is intentionally strict. A destination chain belongs in this overlay only when:
|
|
|
|
1. a multichain mapping exists
|
|
2. the `cW*` deployment is non-zero
|
|
3. `bridgeAvailable` is true
|
|
4. the chain is explicitly enabled here
|
|
|
|
## Public pools
|
|
|
|
Public pools remain **chain-local edge pools**, not literal cross-chain pools.
|
|
|
|
Operators should:
|
|
|
|
1. Deploy the pool.
|
|
2. Record the pool address in `deployment-status.json`.
|
|
3. Mark the pool `active` in `gru-transport-active.json`.
|
|
4. Only then enable `routingEnabled` and/or `mcpVisible`.
|
|
|
|
Until a pool is marked active in the overlay, token-aggregation hides GRU `cW*` pools that touch mirrored assets on public chains.
|
|
|
|
## ISO-4217 GRU bridge: native c* v2 to wrapped cW* v2
|
|
|
|
Canonical `c*` on Chain 138 and mirrored `cW*` on public chains are tied together by the GRU transport bridge model (escrow / lock on L1, mint on L2; burn on L2, release on L1), implemented by `CWMultiTokenBridgeL1` / `CWMultiTokenBridgeL2` and `CompliantWrappedToken` with mint/burn roles. See [CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md](../07-ccip/CW_HARD_PEG_DESIGN_CWUSDC_CWUSDT.md).
|
|
|
|
For each enabled canonical token, `enabledCanonicalTokens[].bridge` carries:
|
|
|
|
- `canonicalAssetVersion`: `v1` or `v2` — which compliant native contract L1 escrows.
|
|
- `mirroredAssetVersion`: `v1` or `v2` — which `cW*` contract L2 mints/burns.
|
|
|
|
`config/token-mapping-multichain.json` section **`gruIso4217Bridge`** holds Chain 138 addresses per `Compliant_*_cW` mapping key and optional **`mirroredV2ByMappingKeyAndChain`** (per destination `chainId`). `config/token-mapping-loader.cjs` resolves `canonicalAddress` / `mirroredAddress` for `getActiveTransportPairs()` from these settings. Defaults remain **v1/v1** until you deploy `cW*` v2 on each destination, fill non-null mirrored v2 addresses, update `cross-chain-pmm-lps/config/deployment-status.json` `cwTokens`, register supported tokens on the live L1/L2 bridge contracts, then flip both versions to `v2`.
|
|
|
|
## v1 defaults
|
|
|
|
The current overlay enables:
|
|
|
|
- canonical assets: `cUSDT`, `cUSDC`
|
|
- live ecosystem extension lane: `cAUSDT -> cWAUSDT`
|
|
- gas-native GRU families such as `cETH`, `cETHL2`, `cBNB`, `cPOL`, `cAVAX`, `cCRO`, `cXDAI`, `cCELO`, and `cWEMIX`
|
|
- destination chains: `25`, `56`, `137`, `43114`, `42161`, `8453`, `10`, `100`, `1`
|
|
- transport form: **Compliant Wrapped ISO-4217 M1**
|
|
|
|
Important boundary:
|
|
|
|
- `cUSDW -> cWUSDW` is already modeled in `config/token-mapping-multichain.json`, but it is **not yet an enabled canonical token** in this active overlay. Treat it as staged until the wrap-vault and transport activation steps are completed.
|
|
|
|
## Related
|
|
|
|
- [C_TO_CW_MAPPER_MAPPING.md](C_TO_CW_MAPPER_MAPPING.md)
|
|
- [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md)
|
|
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md)
|