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.

```json
{
  "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.

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

### 3. Environment Variables

**File**: `.env`

Contains both genesis and deployed addresses for easy access:

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

## Usage

### Query Mapping from Command Line

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

### Use in Contracts

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

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

### Use in Scripts

```solidity
// 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

```bash
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`:

```bash
ADDRESS_MAPPER=0x...
```

## 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()`:

```solidity
mapper.setMapping(genesisAddress, deployedAddress);
```

### Update .env

Add the new addresses to `.env`:

```bash
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