proxmox/docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md

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