explorer-monorepo/docs/TOKEN_MECHANISM_DOCUMENTATION.md

# Token Mechanism Documentation

**Date**: 2025-01-12  
**Network**: ChainID 138

---

## Overview

This document describes the token mechanism used for WETH9 and WETH10 tokens in the CCIP bridging system.

---

## Token Mechanism: Lock & Release / Lock & Mint

### Mechanism Type
**Lock & Release / Lock & Mint** - Standard WETH wrapping mechanism

### How It Works

1. **Wrapping (ETH → WETH)**:
   - User sends ETH to WETH contract
   - WETH contract locks ETH
   - WETH tokens are minted to user (1:1 ratio)
   - ETH is held in WETH contract

2. **Unwrapping (WETH → ETH)**:
   - User sends WETH tokens to WETH contract
   - WETH tokens are burned
   - ETH is released to user (1:1 ratio)

3. **Cross-Chain Bridging**:
   - Source Chain: WETH tokens are locked/burned
   - Destination Chain: WETH tokens are minted/released
   - Maintains 1:1 ratio across chains

---

## WETH9 Token

### Contract Address
- **Address**: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
- **Standard**: WETH9 (with known `decimals()` issue)

### Key Functions

#### `deposit()`
Wraps ETH to WETH9.
- Sends ETH to contract
- Mints WETH9 tokens (1:1 ratio)

#### `withdraw(uint256)`
Unwraps WETH9 to ETH.
- Burns WETH9 tokens
- Releases ETH (1:1 ratio)

#### `totalSupply()`
Returns total WETH9 supply.

**Note**: `decimals()` returns 0 (known issue with WETH9 standard).

### 1:1 Ratio Verification

The contract maintains a 1:1 ratio between:
- Contract ETH balance
- WETH9 total supply

**Verification Script**: `scripts/inspect-weth9-contract.sh`

**Status**: ✅ Verified - 1:1 ratio confirmed

---

## WETH10 Token

### Contract Address
- **Address**: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
- **Standard**: WETH10 (fixed `decimals()` issue)

### Key Functions

#### `deposit()`
Wraps ETH to WETH10.
- Sends ETH to contract
- Mints WETH10 tokens (1:1 ratio)

#### `withdraw(uint256)`
Unwraps WETH10 to ETH.
- Burns WETH10 tokens
- Releases ETH (1:1 ratio)

#### `totalSupply()`
Returns total WETH10 supply.

#### `decimals()`
Returns 18 (fixed in WETH10 standard).

### 1:1 Ratio Verification

The contract maintains a 1:1 ratio between:
- Contract ETH balance
- WETH10 total supply

**Verification Script**: `scripts/inspect-weth10-contract.sh`

**Status**: ✅ Verified - 1:1 ratio confirmed

---

## Rationale

### Why Lock & Release / Lock & Mint?

1. **Simplicity**: Standard WETH mechanism, well-understood
2. **Security**: ETH is locked in contract, cannot be lost
3. **Transparency**: 1:1 ratio is verifiable on-chain
4. **Compatibility**: Works with existing WETH infrastructure

### Why Both WETH9 and WETH10?

1. **WETH9**: Standard, widely used, but has `decimals()` issue
2. **WETH10**: Fixed `decimals()` issue, better wallet compatibility
3. **User Choice**: Users can choose based on their needs

---

## Implementation Details

### Wrapping Process

```solidity
// User sends ETH to WETH contract
WETH.deposit{value: amount}();

// Contract:
// 1. Receives ETH
// 2. Mints WETH tokens to user (1:1)
// 3. ETH remains in contract
```

### Unwrapping Process

```solidity
// User sends WETH to contract
WETH.withdraw(amount);

// Contract:
// 1. Burns WETH tokens
// 2. Releases ETH to user (1:1)
```

### Cross-Chain Bridging

```solidity
// Source Chain:
// 1. User wraps ETH → WETH
// 2. User approves bridge
// 3. Bridge locks/burns WETH
// 4. CCIP message sent

// Destination Chain:
// 1. CCIP message received
// 2. Bridge mints/releases WETH
// 3. User receives WETH (1:1)
```

---

## Verification Results

### WETH9 Verification
- **Date**: 2025-01-12
- **Contract Balance**: Matches total supply
- **Total Supply**: Matches contract balance
- **Status**: ✅ 1:1 ratio verified

### WETH10 Verification
- **Date**: 2025-01-12
- **Contract Balance**: Matches total supply
- **Total Supply**: Matches contract balance
- **Status**: ✅ 1:1 ratio verified

---

## Testing

### Test Scripts

1. **WETH9 Ratio Verification**:
   ```bash
   ./scripts/inspect-weth9-contract.sh
   ```

2. **WETH10 Ratio Verification**:
   ```bash
   ./scripts/inspect-weth10-contract.sh
   ```

3. **Token Mechanism Test Suite** (Task 40):
   ```bash
   ./scripts/test-token-mechanism.sh
   ```

---

## Related Documentation

- [WETH9 1:1 Ratio Verification](./WETH9_1_TO_1_RATIO_VERIFICATION.md)
- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)

---

**Last Updated**: 2025-01-12