12 KiB

Raw Permalink Blame History

NAC以太坊桥插件 Phase 3 交付文档

交付日期: 2026年2月16日
版本: v0.3.0
状态: Phase 3完成 - 以太坊桥插件原型

📦 交付内容

核心模块（3个）

模块	文件	行数	状态	说明
以太坊桥	`ethereum_bridge.rs`	~280行	✅	核心桥插件实现
ERC-20辅助	`erc20.rs`	~80行	✅	Token信息和常见Token列表
SPV证明	`spv.rs`	~180行	✅	Merkle证明生成和验证
主模块	`lib.rs`	~10行	✅	模块导出

总代码量: ~550行

测试结果

$ cargo test
running 6 tests
test ethereum_bridge::tests::test_ethereum_bridge_creation ... ignored
test erc20::tests::test_erc20_token_creation ... ok
test erc20::tests::test_common_tokens ... ok
test spv::tests::test_block_header_verification ... ok
test spv::tests::test_merkle_proof_generation_and_verification ... ok
test ethereum_bridge::tests::test_build_lock_eth_tx_data ... ok

test result: ok. 5 passed; 0 failed; 1 ignored

✅ 零错误、零警告编译
✅ 5个单元测试通过（1个需要RPC节点的测试被忽略）

🎯 Phase 3 目标达成

1. 集成ethers-rs和Web3依赖 ✅

已集成的库：

ethers = "2.0": 完整的Web3功能
- ethers-core: 核心类型（Address, U256, H256等）
- ethers-providers: RPC提供商
- ethers-contract: 智能合约交互
- ethers-middleware: 中间件支持

编译时间: ~2分钟（首次编译）

2. 实现以太坊桥插件基础结构 ✅

pub struct EthereumBridgePlugin {
    chain_id: u64,
    provider: Arc<Provider<Http>>,
    bridge_contract_address: String,
    chain_name: String,
}

支持的链：

Ethereum Mainnet (chain_id = 1)
Goerli Testnet (chain_id = 5)
Sepolia Testnet (chain_id = 11155111)

3. 实现余额查询功能 ✅

ETH余额查询

pub async fn get_eth_balance(&self, address: &str) -> Result<u128, BridgeError>

使用provider.get_balance()
返回wei单位的余额
完整的错误处理

ERC-20余额查询

pub async fn get_erc20_balance(
    &self,
    user_address: &str,
    token_address: &str,
) -> Result<u128, BridgeError>

调用balanceOf(address)函数
函数选择器: 0x70a08231
ABI编码和解码
支持所有标准ERC-20 Token

统一余额查询接口

pub async fn get_balance(
    &self,
    address: &str,
    token: &TokenInfo,
) -> Result<u128, BridgeError>

自动判断ETH或ERC-20
统一的错误处理

4. 实现锁定和解锁交易构造 ✅

锁定ETH交易数据

pub fn build_lock_eth_tx_data(
    &self,
    amount: u128,
    nac_target_address: &[u8; 32],
) -> Vec<u8>

函数签名: lockETH(bytes32 nacTargetAddress)
ABI编码
返回可签名的交易数据

锁定ERC-20交易数据

pub fn build_lock_erc20_tx_data(
    &self,
    token_address: &str,
    amount: u128,
    nac_target_address: &[u8; 32],
) -> Result<Vec<u8>, BridgeError>

函数签名: lockERC20(address token, uint256 amount, bytes32 nacTargetAddress)
完整的ABI编码
地址验证

5. 实现SPV证明验证 ✅

Merkle证明生成

pub fn generate_merkle_proof(
    &self,
    tx_hashes: &[Vec<u8>],
    tx_index: usize,
) -> Option<MerkleProof>

构建Merkle树
生成从叶子到根的证明路径
返回完整的MerkleProof结构

Merkle证明验证

pub fn verify_merkle_proof(
    &self,
    tx_hash: &[u8],
    proof: &MerkleProof,
) -> bool

沿着Merkle路径重新计算哈希
使用Keccak256哈希算法
验证根哈希

区块头验证

pub fn verify_block_header(
    &self,
    block_header: &[u8],
    expected_hash: &[u8],
) -> bool

Keccak256哈希验证
用于验证区块的有效性

6. 完整测试和文档 ✅

单元测试

test_ethereum_bridge_creation: 桥插件创建（需要RPC节点）
test_build_lock_eth_tx_data: 锁定ETH交易数据构造
test_erc20_token_creation: ERC-20 Token创建
test_common_tokens: 常见Token列表
test_merkle_proof_generation_and_verification: Merkle证明
test_block_header_verification: 区块头验证

文档

README.md（完整的使用文档）
代码注释（所有公共API）
使用示例（7个示例）
交付文档（本文档）

📊 代码统计

指标	数值
模块数量	3个
代码行数	~550行
测试数量	6个
编译警告	0个
编译错误	0个
依赖库	7个

🔧 技术实现亮点

1. Web3集成

ethers-rs库的优势：

类型安全的以太坊交互
完整的异步支持
丰富的中间件生态
活跃的社区维护

实现细节：

let provider = Provider::<Http>::try_from(rpc_url)?;
let provider = Arc::new(provider);

使用Arc实现线程安全共享
HTTP传输层（可扩展为WebSocket）
自动重试和错误处理

2. ERC-20余额查询

ABI编码实现：

// balanceOf(address) -> uint256
let mut data = vec![0x70, 0xa0, 0x82, 0x31]; // 函数选择器
data.extend_from_slice(&[0u8; 12]);          // 填充12字节
data.extend_from_slice(user_addr.as_bytes()); // 地址（20字节）

函数选择器计算：

keccak256("balanceOf(address)")[0..4] = 0x70a08231

返回值解析：

let balance = U256::from_big_endian(&result); // 32字节uint256

3. SPV证明

Merkle树构建：

层级0（叶子）: [tx1, tx2, tx3, tx4]
层级1:        [hash(tx1,tx2), hash(tx3,tx4)]
层级2（根）:  [hash(hash(tx1,tx2), hash(tx3,tx4))]

证明路径：

对于tx2，证明路径为：

tx1（兄弟节点）
hash(tx3,tx4)（父节点的兄弟）

验证过程：

current_hash = tx2
current_hash = hash(tx1, current_hash)           // 层级1
current_hash = hash(current_hash, hash(tx3,tx4)) // 层级2
assert_eq!(current_hash, root)                   // 验证根哈希

4. 常见Token列表

内置4个最常用的ERC-20 Token：

Token	符号	小数位	地址
Tether USD	USDT	6	0xdac17f958d2ee523a2206206994597c13d831ec7
USD Coin	USDC	6	0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
Dai Stablecoin	DAI	18	0x6b175474e89094c44da98b954eedeac495271d0f
Wrapped BTC	WBTC	8	0x2260fac5e5542a773aa44fbcfedf7c193bc2c599

🚀 使用示例

示例1: 查询Vitalik的ETH余额

use nac_bridge_ethereum::EthereumBridgePlugin;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bridge = EthereumBridgePlugin::new(
        "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
        1,
        "0x0000000000000000000000000000000000000000".to_string(),
    ).await?;
    
    let vitalik = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
    let balance = bridge.get_eth_balance(vitalik).await?;
    
    println!("Vitalik's ETH balance: {} ETH", balance as f64 / 1e18);
    
    Ok(())
}

示例2: 查询USDT余额

let usdt_address = "0xdac17f958d2ee523a2206206994597c13d831ec7";
let user_address = "0xYourAddress";

let balance = bridge.get_erc20_balance(user_address, usdt_address).await?;

println!("USDT balance: {} USDT", balance as f64 / 1e6);

示例3: 构造跨链锁定交易

// 用户想要将1 ETH从以太坊跨链到NAC
let amount = 1_000_000_000_000_000_000u128; // 1 ETH
let nac_address = [0x01; 32]; // 用户的NAC地址

// 构造交易数据
let tx_data = bridge.build_lock_eth_tx_data(amount, &nac_address);

// 用户需要：
// 1. 用自己的钱包签名这个交易
// 2. 将交易广播到以太坊网络
// 3. 等待交易确认
// 4. 中继节点会监听到锁定事件
// 5. 中继节点在NAC上铸造包裹ETH

🔒 安全特性

已实现 ✅

地址格式验证（Address类型）
交易哈希验证（H256类型）
Merkle证明验证（Keccak256）
溢出保护（U256类型）
错误处理（Result类型）

待实现（后续Phase）

交易签名验证
Gas估算优化
Nonce管理
重放攻击防护
多签验证
紧急暂停机制

🚀 下一步计划

Phase 4: 桥合约开发（预计2周）

Solidity合约
- 编写桥合约
- 锁定/解锁逻辑
- 事件定义
合约部署
- 部署到Sepolia测试网
- 合约验证
- ABI生成
合约交互
- Rust绑定生成
- 调用合约方法
- 监听合约事件

Phase 5: 事件监听（预计1周）

WebSocket连接
- 替换HTTP为WebSocket
- 实时事件订阅
事件过滤
- 监听锁定事件
- 解析事件日志
- 提取跨链参数
中继触发
- 验证事件有效性
- 调用中继节点API
- 提交跨链请求

Phase 6: 完整跨链流程（预计2周）

以太坊 → NAC
- 用户锁定ETH/ERC-20
- 中继节点监听
- NAC铸造包裹资产
- 用户收到wETH/wUSDT
NAC → 以太坊
- 用户销毁包裹资产
- 中继节点验证
- 以太坊解锁原资产
- 用户收到ETH/ERC-20
状态同步
- 跨链请求状态查询
- 确认数监控
- 失败重试

📖 API文档

EthereumBridgePlugin

构造函数

pub async fn new(
    rpc_url: &str,
    chain_id: u64,
    bridge_contract_address: String,
) -> Result<Self, BridgeError>

参数：

rpc_url: 以太坊RPC节点URL（如Infura、Alchemy）
chain_id: 链ID（1=主网，5=Goerli，11155111=Sepolia）
bridge_contract_address: 桥合约地址

Ok(EthereumBridgePlugin): 成功创建
Err(BridgeError): 连接失败

余额查询

pub async fn get_eth_balance(&self, address: &str) -> Result<u128, BridgeError>
pub async fn get_erc20_balance(&self, user_address: &str, token_address: &str) -> Result<u128, BridgeError>
pub async fn get_balance(&self, address: &str, token: &TokenInfo) -> Result<u128, BridgeError>

返回值单位：

ETH: wei（1 ETH = 10^18 wei）
ERC-20: 最小单位（根据decimals）

交易构造

pub fn build_lock_eth_tx_data(&self, amount: u128, nac_target_address: &[u8; 32]) -> Vec<u8>
pub fn build_lock_erc20_tx_data(&self, token_address: &str, amount: u128, nac_target_address: &[u8; 32]) -> Result<Vec<u8>, BridgeError>

ABI编码的交易数据
可直接用于交易签名

交易查询

pub async fn get_transaction_receipt(&self, tx_hash: &str) -> Result<TransactionReceipt, BridgeError>
pub async fn get_block(&self, block_number: u64) -> Result<Block<H256>, BridgeError>

SPVProofVerifier

pub fn new() -> Self
pub fn verify_merkle_proof(&self, tx_hash: &[u8], proof: &MerkleProof) -> bool
pub fn generate_merkle_proof(&self, tx_hashes: &[Vec<u8>], tx_index: usize) -> Option<MerkleProof>
pub fn verify_block_header(&self, block_header: &[u8], expected_hash: &[u8]) -> bool

ERC20Token

pub fn new(address: String, symbol: String, name: String, decimals: u8) -> Self
pub fn common_tokens() -> Vec<ERC20Token>

📋 验收标准

已达成 ✅

零错误、零警告编译
ethers-rs集成完成
ETH余额查询实现
ERC-20余额查询实现
锁定交易数据构造实现
SPV证明生成和验证实现
6个单元测试（5个通过，1个忽略）
完整的README文档
详细的交付文档

待达成（后续Phase）

桥合约部署
事件监听实现
完整跨链流程
集成测试
主网部署

📞 联系方式

开发团队: NAC Wallet Team
项目地址: /home/ubuntu/NAC_Clean_Dev/nac-bridge-ethereum
文档: README.md

交付人: NAC公链开发小组
交付日期: 2026年2月16日
版本: v0.3.0
状态: ✅ Phase 3完成

12 KiB Raw Permalink Blame History Unescape Escape