4.4 KiB
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
-
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
-
Unwrapping (WETH → ETH):
- User sends WETH tokens to WETH contract
- WETH tokens are burned
- ETH is released to user (1:1 ratio)
-
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?
- Simplicity: Standard WETH mechanism, well-understood
- Security: ETH is locked in contract, cannot be lost
- Transparency: 1:1 ratio is verifiable on-chain
- Compatibility: Works with existing WETH infrastructure
Why Both WETH9 and WETH10?
- WETH9: Standard, widely used, but has
decimals()issue - WETH10: Fixed
decimals()issue, better wallet compatibility - User Choice: Users can choose based on their needs
Implementation Details
Wrapping Process
// 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
// User sends WETH to contract
WETH.withdraw(amount);
// Contract:
// 1. Burns WETH tokens
// 2. Releases ETH to user (1:1)
Cross-Chain Bridging
// 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
-
WETH9 Ratio Verification:
./scripts/inspect-weth9-contract.sh -
WETH10 Ratio Verification:
./scripts/inspect-weth10-contract.sh -
Token Mechanism Test Suite (Task 40):
./scripts/test-token-mechanism.sh
Related Documentation
Last Updated: 2025-01-12