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
56 lines
3.8 KiB
Markdown
56 lines
3.8 KiB
Markdown
# c* → cW* Mapper Mapping (Multi-Chain)
|
||
|
||
**Purpose:** Define the mapping of compliant tokens (c*) on Chain 138 to their wrapped representations (cW*) on other chains for bridge/mapper tooling.
|
||
|
||
## Source of truth
|
||
|
||
- **Config:** [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
|
||
- **`cToCwSymbolMapping`** — Symbol correspondence: each c* symbol maps to its cW* symbol (e.g. `cUSDT` → `cWUSDT`).
|
||
- **Per-pair tokens** — For each `fromChainId: 138` → `toChainId: <chain>` pair, tokens with key `Compliant_*_cW` define: **addressFrom** = c* contract on 138, **addressTo** = cW* contract on the destination chain (or `0x0` placeholder until deployed).
|
||
- **Active overlay:** [`config/gru-transport-active.json`](../../config/gru-transport-active.json)
|
||
- Final activation gate for which c* → cW* mappings are live for routing, public exposure, and MCP visibility.
|
||
- A mapping can exist in `token-mapping-multichain.json` without being active in GRU Transport.
|
||
|
||
## Symbol mapping (c* → cW*)
|
||
|
||
| c* (Chain 138) | cW* (other chains) |
|
||
|----------------|--------------------|
|
||
| cUSDT | cWUSDT |
|
||
| cUSDC | cWUSDC |
|
||
| cEURC | cWEURC |
|
||
| cEURT | cWEURT |
|
||
| cGBPC | cWGBPC |
|
||
| cGBPT | cWGBPT |
|
||
| cAUDC | cWAUDC |
|
||
| cJPYC | cWJPYC |
|
||
| cCHFC | cWCHFC |
|
||
| cCADC | cWCADC |
|
||
| cXAUC | cWXAUC |
|
||
| cXAUT | cWXAUT |
|
||
|
||
## Per-chain address mapping
|
||
|
||
For each destination chain, the mapper (or bridge config) should resolve:
|
||
|
||
- **Compliant_USDT_cW**: Chain 138 cUSDT address → cWUSDT address on destination
|
||
- **Compliant_USDC_cW**: Chain 138 cUSDC address → cWUSDC address on destination
|
||
- **Compliant_EURC_cW**: Chain 138 cEURC address → cWEURC address on destination
|
||
|
||
(Additional c* → cW* pairs can be added to `token-mapping-multichain.json` when those c* and cW* are deployed.)
|
||
|
||
In `token-mapping-multichain.json`, entries with key suffix `_cW` use `addressTo: "0x0000000000000000000000000000000000000000"` as a placeholder until the cW* contract is deployed on that chain. **Operators:** after deploying cW* (e.g. via `DeployCWTokens.s.sol` or equivalent), update the corresponding `addressTo` in the JSON (or in env-driven config that overrides it). The **receiver/bridge on the destination chain must support minting cW*** (e.g. dedicated cW* receiver such as TwoWayTokenBridgeL2, or an extended bridge that calls `cW*.mint(recipient, amount)` in `ccipReceive`); see [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md) and [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md).
|
||
|
||
## Consumer behavior
|
||
|
||
- **Mapper / bridge:** When resolving "cUSDT on 138 → token on chain 56", use:
|
||
- **Native representation:** key `Compliant_USDT` → `addressTo` = that chain’s native USDT (e.g. BSC USDT).
|
||
- **Wrapped representation:** key `Compliant_USDT_cW` → `addressTo` = that chain’s cWUSDT. If `addressTo` is zero, treat as "cW* not deployed" and optionally fall back to native or reject.
|
||
- **Activation gate:** even when a `_cW` mapping exists and `addressTo` is non-zero, treat it as routable only when the corresponding pair is active in `gru-transport-active.json`.
|
||
|
||
- **Loading:** [`config/token-mapping-loader.cjs`](../../config/token-mapping-loader.cjs) builds `addressMapFromTo` / `addressMapToFrom` from `tokens`. Keys `*_cW` are first-class; filter by key suffix or use `cToCwSymbolMapping` for symbol-level logic.
|
||
|
||
## Related
|
||
|
||
- [EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md) — All c* on explorer must be GRU-registered.
|
||
- [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md](../11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md) — Deploying cW* via `DeployCWTokens.s.sol` and `--deploy-cw`.
|