proxmox/docs/03-deployment/CW_TOKEN_USD_PRICING_RUNBOOK.md

cW Token USD Pricing (Ethereum Mainnet)

This runbook explains how to attach USD context to wrapped basket tokens (cW*) when block explorers show balance but $0 value (no listed market price).

Tooling

From the repo root:

./scripts/deployment/price-cw-token-mainnet.sh
./scripts/deployment/price-cw-token-mainnet.sh --json | jq .

The script sources scripts/lib/load-project-env.sh when present so addresses match your smom-dbis-138/.env (or overrides).

Dependencies: cast (Foundry), python3, and jq (for --json).

What the script reports

1. Accounting assumption (1 cWUSDT ≈ 1 USD)
   Use only if your policy treats the wrapper as tracking the underlying stable 1:1. Appropriate for internal books and dashboards where you need a single consistent mark without relying on DEX liquidity.

2. DODO PMM integration — getPoolPriceOrOracle / getPoolPrice
   Reads DODO_PMM_INTEGRATION_MAINNET for the configured pool (POOL_CWUSDT_USDC_MAINNET). The integration returns a uint256 scaled by 1e18 in the project docs when the oracle is aligned with “USD.”
   Important: For stable/stable pools, the raw integration mid can disagree with reserve-implied prices depending on base/quote orientation and PMM parameters. Treat this as one signal, not the only mark.

3. Implied from vault reserves
   Uses getPoolReserves on the same integration for base and quote raw balances, then applies token decimals() for cWUSDT and mainnet canonical USDC (USDC_MAINNET, default 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48).
   Computes USDC per 1 cWUSDT when base/quote order matches the pool (cWUSDT vs USDC). This is a strong sanity check for deep stable pools; thin or imbalanced pools skew the ratio.

4. Chainlink ETH/USD (macro only)
   Optional reference to the standard ETH/USD feed (CHAINLINK_ETH_USD_FEED). This is not a direct cW* price; it is useful for macro context or cross-checking RPC health.

Environment overrides

Variable	Role
ETHEREUM_MAINNET_RPC	Mainnet JSON-RPC endpoint
DODO_PMM_INTEGRATION_MAINNET	DODO PMM integration contract
POOL_CWUSDT_USDC_MAINNET	cWUSDT/USDC pool address
CWUSDT_MAINNET	cWUSDT token
USDC_MAINNET	Mainnet canonical USDC (do not substitute Chain 138 OFFICIAL_USDC_ADDRESS for this script)
CHAINLINK_ETH_USD_FEED	Chainlink ETH/USD aggregator

Etherscan and “$0 value”

Explorers derive the Value column from external price feeds (Etherscan relies heavily on CoinGecko / similar for Ethereum Mainnet ERC-20 USD). Custom cW* tokens usually have no listing for that contract on chain ID 1, so USD shows as zero even when balances and pools are real.

• Internal / treasury marks: use this script’s accounting line, reserve-implied USDC ratio, or policy—not Etherscan’s Value column.
• Actually changing Etherscan’s Value: requires off-chain listing so aggregators publish a USD price for the Mainnet contract. Step-by-step: ETHERSCAN_USD_VALUE_MAINNET_TOKENS.md (CoinGecko/CMC submission ties to CMC_COINGECKO_SUBMISSION_RUNBOOK.md).

Broader cW* price table

A generated multi-chain table (mid prices from PMM where available) lives in:

docs/03-deployment/CW_PUBLIC_NETWORK_PRICES.md

Extending to other tokens

The shell script is parameterized by env vars for cWUSDT and its USDC pool. For other cW* assets, point CWUSDT_MAINNET, POOL_*, and (if needed) quote token at the correct mainnet addresses and re-run. For portfolio-level marks (CoinGecko, OTC, fund admin), use your external pricing process; this repo script stays on-chain and policy-transparent.