proxmox/config/README-CONTRACTS-MASTER.md

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:

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):

source scripts/lib/load-contract-addresses.sh

Node / JavaScript

From repo root or any app that can resolve config/contracts-loader.cjs:

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 for the full table and recommendations.

Related

• CONTRACT_ADDRESSES_REFERENCE.md — Human-readable address list and service config.
• 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).