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
81 lines
4.2 KiB
Markdown
81 lines
4.2 KiB
Markdown
# Master Smart Contracts (JSON)
|
|
|
|
**Machine-readable contract map:** `config/smart-contracts-master.json` (when the file exists in your clone).
|
|
|
|
- **Safe to publish** — no secrets (no keys, no RPC URLs with credentials).
|
|
- **Used by:** Bash scripts (via `scripts/lib/load-contract-addresses.sh`), Node/JS (via `config/contracts-loader.cjs`), and docs.
|
|
- **If the file is absent:** loaders continue with `.env` only; Chain 138 **bytecode checks** use the embedded address list in `scripts/verify/check-contracts-on-chain-138.sh` (see also `docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md`). When you introduce `smart-contracts-master.json`, populate `chains["138"].contracts` with the **complete** set for that chain — the check script uses JSON addresses instead of its fallback when the file is present.
|
|
|
|
## Layout
|
|
|
|
- **`smart-contracts-master.json`** — Chains keyed by chain id (`138`, `1`). Each chain has:
|
|
- `contracts`: map of contract name → address.
|
|
- `envVarMap`: map of env var name (e.g. `CCIP_ROUTER`) → contract key (for backward compatibility with .env).
|
|
|
|
## Bash
|
|
|
|
Contract addresses are loaded automatically when you source project env:
|
|
|
|
```bash
|
|
source scripts/lib/load-project-env.sh
|
|
# Addresses from .env are used first; any missing are filled from smart-contracts-master.json
|
|
echo $CCIP_ROUTER
|
|
echo $CONTRACTS_138_CCIP_Router
|
|
```
|
|
|
|
Or source the contract loader only (after setting `PROJECT_ROOT`):
|
|
|
|
```bash
|
|
source scripts/lib/load-contract-addresses.sh
|
|
```
|
|
|
|
## Node / JavaScript
|
|
|
|
From repo root or any app that can resolve `config/contracts-loader.cjs`:
|
|
|
|
```javascript
|
|
const {
|
|
getContractAddress,
|
|
getChainContracts,
|
|
loadContractsIntoProcessEnv
|
|
} = require('./config/contracts-loader.cjs');
|
|
|
|
// By contract key
|
|
getContractAddress(138, 'CCIP_Router'); // => '0x42DA...' (canonical; legacy direct: CCIP_Router_Direct_Legacy)
|
|
getContractAddress(138, 'CCIPWETH9_Bridge');
|
|
getContractAddress(1, 'CCIP_Relay_Router');
|
|
|
|
// By env var name (resolved via envVarMap)
|
|
getContractAddress(138, 'CCIP_ROUTER');
|
|
getContractAddress(138, 'CCIPWETH9_BRIDGE_CHAIN138');
|
|
|
|
// All contracts for a chain
|
|
getChainContracts(138);
|
|
|
|
// Fill process.env for chain 138 and 1 (only where not already set)
|
|
loadContractsIntoProcessEnv();
|
|
```
|
|
|
|
## Overrides
|
|
|
|
- **.env** (e.g. `smom-dbis-138/.env`, `services/relay/.env`): Values set there take precedence over the master JSON. Use .env for local or per-service overrides. For **`ADDRESS_MAPPER`** on Chain 138, keep **`ADDRESS_MAPPER`** equal to **`chains["138"].contracts.AddressMapper`** unless you have a deliberate fork: a legacy duplicate on Core shares bytecode with the canonical mapper (see `docs/11-references/ADDRESS_MATRIX_AND_STATUS.md`, section 1.5).
|
|
- **Publishing:** Commit `smart-contracts-master.json`; do not commit `.env` or any file containing `PRIVATE_KEY` or API secrets.
|
|
|
|
## Updating addresses
|
|
|
|
1. Edit `config/smart-contracts-master.json` (add/change under `chains.<id>.contracts` and, if needed, `envVarMap`).
|
|
2. Keep `docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md` in sync for human-readable tables.
|
|
3. Re-run scripts or restart Node services to pick up changes; no rebuild required for JSON.
|
|
|
|
## Token mapping (Chain 138 ↔ Mainnet)
|
|
|
|
- **`token-mapping.json`** — Single source of truth for cross-chain token addresses (Chain 138 → Ethereum Mainnet). Lists which tokens have a Mainnet address and whether the relay bridge supports them (currently only WETH9).
|
|
- **`token-mapping-loader.cjs`** — Node API: `getRelayTokenMapping()` returns `{ chain138Address: mainnetAddress }`; `getTokenList()` returns full token list with `relaySupported` and notes. Used by the relay service (`smom-dbis-138/services/relay`).
|
|
|
|
See [TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](../docs/07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) for the full table and recommendations.
|
|
|
|
## Related
|
|
|
|
- [CONTRACT_ADDRESSES_REFERENCE.md](../docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md) — Human-readable address list and service config.
|
|
- [contract-addresses.conf](contract-addresses.conf) — Legacy shell config for Blockscout verification; still sourced by `load-contract-addresses.sh`. Keep Oracle (and other) addresses aligned with `smart-contracts-master.json` (chains.138.contracts).
|