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             |
| cAUSDT         | cWAUSDT            |
| cUSDW          | cWUSDW             |
| cEURC          | cWEURC             |
| cEURT          | cWEURT             |
| cGBPC          | cWGBPC             |
| cGBPT          | cWGBPT             |
| cAUDC          | cWAUDC             |
| cJPYC          | cWJPYC             |
| cCHFC          | cWCHFC             |
| cCADC          | cWCADC             |
| cXAUC          | cWXAUC             |
| cXAUT          | cWXAUT             |

**ALL Mainnet (651940) XAU exception:** the generic symbol map above still applies for ordinary public-chain wrapping, but the **138 -> 651940** gold corridor uses an Alltra-specific destination naming rule. Source-leg wrapping is still **`cWXAUC` / `cWXAUT`**, while the bridge-minted ALL Mainnet representation becomes **`cWAXAUC` / `cWAXAUT`**, and unwrapping on ALL Mainnet lands as **`cAXAUC` / `cAXAUT`**.

## 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_AUSDT_cW**: Chain 138 cAUSDT address → cWAUSDT address on destination
- **Compliant_USDW_cW**: Chain 138 cUSDW address → cWUSDW address on destination
- **Compliant_EURC_cW**: Chain 138 cEURC address → cWEURC address on destination

**USD DWIN (CMC-listed native USDW on BSC/Polygon)** is not a Chain 138 `c*`; pins sit under **`dwinUsdWinPublic`** in the same JSON. That asset is the intended **collateral** for minting **cWUSDW** on the wrap leg, alongside GRU bridge mint/burn from **cUSDW**. See **`docs/03-deployment/USD_DWIN_CUSDW_CWUSDW_BRIDGE_CHECKLIST.md`**.

**AUSDT (ALL Mainnet native)** is likewise not a Chain 138 `c*`; pins now sit under **`alltraAusdtOrigin`** in the same JSON. Unlike USDW, this corridor originates on **chain 651940**, so public-chain **cWAUSDT** is treated as the transport mirror for the live **AUSDT -> cWAUSDT -> cAUSDT** flow rather than a native-public collateral wrapper. See **`docs/03-deployment/AUSDT_CAUSDT_CWAUSDT_BRIDGE_CHECKLIST.md`**.

For **gold on ALL Mainnet**, keep the mapper key suffix `_cW` for compatibility, but read the per-pair row notes in `token-mapping-multichain.json`: **`Compliant_XAUC_cW`** and **`Compliant_XAUT_cW`** on the **138 -> 651940** pair denote destination-side **`cWAXAUC` / `cWAXAUT`** wrappers and ALL Mainnet native-unwrapped **`cAXAUC` / `cAXAUT`**.

For the repo-local native wrap path, use **`smom-dbis-138/contracts/bridge/integration/USDWPublicWrapVault.sol`** and **`smom-dbis-138/script/deploy/DeployUSDWPublicWrapVault.s.sol`**. Polygon stays non-live until `cWUSDW` is actually deployed and `Compliant_USDW_cW.addressTo` is updated.

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