smom-dbis-138/docs/ADDRESS_MAPPING.md

Address Mapping Documentation

Overview

This document describes the address mapping system that maps reserved addresses from genesis.json to actual deployed contract addresses.

Problem

The genesis.json file contains reserved addresses for WETH9 and WETH10:

• WETH9: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
• WETH10: 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F

These are Ethereum mainnet addresses that were originally deployed using CREATE (not CREATE2), so they cannot be recreated with CREATE2 on ChainID 138.

Solution

We deploy the contracts to new addresses and maintain a mapping from the genesis addresses to the deployed addresses.

Actual Deployed Addresses

• WETH9: 0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6
• WETH10: 0x105F8A15b819948a89153505762444Ee9f324684

Mapping Components

1. JSON Configuration File

File: config/address-mapping.json

Contains the mapping in JSON format for easy reference and tooling.

{
  "mappings": {
    "WETH9": {
      "genesisAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "deployedAddress": "0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6"
    }
  }
}

2. On-Chain Contract

Contract: AddressMapper.sol

Provides on-chain address mapping that can be queried by other contracts.

AddressMapper mapper = AddressMapper(mapperAddress);
address deployed = mapper.getDeployedAddress(genesisAddress);

3. Environment Variables

File: .env

Contains both genesis and deployed addresses for easy access:

WETH9_GENESIS_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
WETH9_DEPLOYED_ADDRESS=0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6
WETH10_GENESIS_ADDRESS=0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F
WETH10_DEPLOYED_ADDRESS=0x105F8A15b819948a89153505762444Ee9f324684

Usage

Query Mapping from Command Line

# Get mapped address for a genesis address
./scripts/utils/get-mapped-address.sh 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Use in Contracts

import {AddressMapper} from "./utils/AddressMapper.sol";

AddressMapper mapper = AddressMapper(0x...); // Deploy AddressMapper first
address weth9 = mapper.getDeployedAddress(0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2);

Use in Scripts

// In Foundry scripts
address weth9Genesis = 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2;
address weth9Deployed = 0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6;

// Or use AddressMapper contract
AddressMapper mapper = AddressMapper(mapperAddress);
address weth9 = mapper.getDeployedAddress(weth9Genesis);

Deployment

Deploy AddressMapper Contract

forge script script/DeployAddressMapper.s.sol:DeployAddressMapper \
    --rpc-url $RPC_URL \
    --broadcast \
    --private-key $PRIVATE_KEY \
    --legacy

After deployment, add the AddressMapper address to .env:

ADDRESS_MAPPER=0x...

On Chain 138, the canonical mapper is documented in the parent repo at docs/11-references/ADDRESS_MATRIX_AND_STATUS.md (0x439Fcb2d2ab2f890DCcAE50461Fa7d978F9Ffe1A); inventory also lists ADDRESS_MAPPER_LEGACY_DUPLICATE in config/address-inventory.chain138.json. Prefer the canonical address in .env.

Best Practices

1. Always use deployed addresses for contract interactions
2. Keep genesis addresses in genesis.json for reference/compatibility
3. Use AddressMapper contract for on-chain lookups
4. Update mappings if contracts are redeployed

Adding New Mappings

Update JSON File

Edit config/address-mapping.json and add the new mapping.

Update AddressMapper Contract

If AddressMapper is deployed, call setMapping():

mapper.setMapping(genesisAddress, deployedAddress);

Update .env

Add the new addresses to .env:

NEW_CONTRACT_GENESIS_ADDRESS=0x...
NEW_CONTRACT_DEPLOYED_ADDRESS=0x...

See Also

• config/address-mapping.json - JSON mapping file
• contracts/utils/AddressMapper.sol - On-chain mapping contract
• script/DeployAddressMapper.s.sol - Deployment script
• scripts/utils/get-mapped-address.sh - Utility script