216 lines
4.4 KiB
Markdown
216 lines
4.4 KiB
Markdown
# 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
|
|
|