359 lines
7.9 KiB
Markdown
359 lines
7.9 KiB
Markdown
# NAC跨链桥接使用文档
|
||
|
||
## 概述
|
||
|
||
NAC跨链桥接模块提供了在NAC公链和其他区块链（如以太坊）之间安全转移资产的能力。本文档详细说明如何使用桥接系统。
|
||
|
||
## 系统架构
|
||
|
||
NAC跨链桥接系统由以下组件组成：
|
||
|
||
1. **资产锁定器（AssetLocker）**：在源链上锁定资产
|
||
2. **资产解锁器（AssetUnlocker）**：在目标链上解锁资产
|
||
3. **验证器池（ValidatorPool）**：管理验证器和多签验证
|
||
4. **中继节点（Relayer）**：在链之间传递跨链消息
|
||
5. **以太坊监听器（EthereumListener）**：监听以太坊链上的事件
|
||
6. **桥接管理器（BridgeManager）**：统一管理桥接系统
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
### 2. 配置桥接
|
||
|
||
创建配置文件`config.toml`：
|
||
|
||
```toml
|
||
[bridge]
|
||
min_validator_signatures = 2
|
||
max_lock_amount = 1000000000000000000000000 # 1,000,000 tokens
|
||
is_paused = false
|
||
|
||
[database]
|
||
path = "./data/bridge.db"
|
||
|
||
[ethereum]
|
||
rpc_url = "https://mainnet.infura.io/v3/YOUR_API_KEY"
|
||
bridge_contract = "0x..."
|
||
```
|
||
|
||
### 3. 启动中继节点
|
||
|
||
```bash
|
||
cargo run --bin nac-bridge-relay -- \
|
||
--config config.toml \
|
||
--nac-rpc http://localhost:8545 \
|
||
--eth-rpc https://mainnet.infura.io/v3/YOUR_API_KEY
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
### 场景1：从NAC转移资产到以太坊
|
||
|
||
#### 步骤1：锁定资产
|
||
|
||
```rust
|
||
use nac_cross_chain_bridge::locker::{AssetLocker, AssetLockerImpl};
|
||
use nac_cross_chain_bridge::types::*;
|
||
|
||
// 创建锁定器
|
||
let db = Arc::new(sled::open("./data/bridge.db")?);
|
||
let config = BridgeConfig::default();
|
||
let locker = AssetLockerImpl::new(db, config);
|
||
|
||
// 定义资产信息
|
||
let asset = AssetInfo {
|
||
asset_id: Hash::from([1u8; 48]), // NAC的48字节哈希
|
||
name: "NAC Token".to_string(),
|
||
symbol: "NAC".to_string(),
|
||
decimals: 18,
|
||
chain_id: ChainId::NAC,
|
||
};
|
||
|
||
// 锁定资产
|
||
let amount = 1000 * 10u128.pow(18); // 1000 NAC
|
||
let target_chain = ChainId::Ethereum;
|
||
let receiver = [0x12, 0x34, ...]; // 以太坊接收地址（32字节）
|
||
|
||
let receipt = locker.lock_asset(
|
||
asset,
|
||
amount,
|
||
target_chain,
|
||
receiver
|
||
).await?;
|
||
|
||
println!("Asset locked: {:?}", receipt.lock_id);
|
||
```
|
||
|
||
#### 步骤2：等待验证器确认
|
||
|
||
中继节点会自动：
|
||
1. 监听锁定事件
|
||
2. 收集验证器签名
|
||
3. 在以太坊上铸造对应的代币
|
||
|
||
#### 步骤3：查询锁定状态
|
||
|
||
```rust
|
||
let status = locker.get_lock_status(receipt.lock_id).await?;
|
||
println!("Lock status: {:?}", status);
|
||
```
|
||
|
||
### 场景2：从以太坊转移资产回NAC
|
||
|
||
#### 步骤1：在以太坊上销毁代币
|
||
|
||
在以太坊上调用桥接合约的`burn`函数：
|
||
|
||
```solidity
|
||
bridge.burn(tokenAddress, amount, nacReceiver);
|
||
```
|
||
|
||
#### 步骤2：提交解锁证明
|
||
|
||
```rust
|
||
use nac_cross_chain_bridge::unlocker::{AssetUnlocker, AssetUnlockerImpl};
|
||
|
||
// 创建解锁器
|
||
let unlocker = AssetUnlockerImpl::new(db, config);
|
||
|
||
// 构造解锁证明
|
||
let proof = UnlockProof {
|
||
burn_tx_hash: Hash::from([...]), // 以太坊销毁交易哈希
|
||
burn_block_number: 12345,
|
||
burn_block_hash: Hash::from([...]),
|
||
merkle_proof: vec![...],
|
||
signatures: vec![sig1, sig2, ...], // 验证器签名
|
||
};
|
||
|
||
// 解锁资产
|
||
let unlock_receipt = unlocker.unlock_asset(
|
||
lock_id,
|
||
proof
|
||
).await?;
|
||
|
||
println!("Asset unlocked: {:?}", unlock_receipt.unlock_id);
|
||
```
|
||
|
||
### 场景3：注册为验证器
|
||
|
||
```rust
|
||
use nac_cross_chain_bridge::validator::{ValidatorPool, ValidatorPoolImpl};
|
||
|
||
// 创建验证器池
|
||
let validator_pool = ValidatorPoolImpl::new(db, config);
|
||
|
||
// 注册验证器
|
||
let validator = ValidatorInfo {
|
||
address: [0x56, 0x78, ...], // 验证器地址（32字节）
|
||
stake_amount: 10000 * 10u128.pow(18), // 最小质押10000 NAC
|
||
reputation: 100,
|
||
is_active: true,
|
||
};
|
||
|
||
validator_pool.register_validator(validator).await?;
|
||
println!("Validator registered successfully");
|
||
```
|
||
|
||
## API参考
|
||
|
||
### AssetLocker
|
||
|
||
#### lock_asset
|
||
|
||
锁定资产以进行跨链转移。
|
||
|
||
```rust
|
||
async fn lock_asset(
|
||
&self,
|
||
asset: AssetInfo,
|
||
amount: Amount,
|
||
target_chain: ChainId,
|
||
receiver: Address,
|
||
) -> Result<LockReceipt>
|
||
```
|
||
|
||
**参数**：
|
||
- `asset`: 资产信息（包含48字节的asset_id）
|
||
- `amount`: 锁定数量（u128）
|
||
- `target_chain`: 目标链ID
|
||
- `receiver`: 接收者地址（32字节）
|
||
|
||
**返回**：
|
||
- `LockReceipt`: 锁定收据（包含48字节的lock_id）
|
||
|
||
#### get_lock_status
|
||
|
||
查询锁定状态。
|
||
|
||
```rust
|
||
async fn get_lock_status(&self, lock_id: Hash) -> Result<LockStatus>
|
||
```
|
||
|
||
### AssetUnlocker
|
||
|
||
#### unlock_asset
|
||
|
||
解锁资产。
|
||
|
||
```rust
|
||
async fn unlock_asset(
|
||
&self,
|
||
lock_id: Hash,
|
||
proof: UnlockProof,
|
||
) -> Result<UnlockReceipt>
|
||
```
|
||
|
||
**参数**：
|
||
- `lock_id`: 锁定ID（48字节哈希）
|
||
- `proof`: 解锁证明（包含验证器签名）
|
||
|
||
**返回**：
|
||
- `UnlockReceipt`: 解锁收据（包含48字节的unlock_id）
|
||
|
||
### ValidatorPool
|
||
|
||
#### register_validator
|
||
|
||
注册验证器。
|
||
|
||
```rust
|
||
async fn register_validator(&self, validator: ValidatorInfo) -> Result<()>
|
||
```
|
||
|
||
**要求**：
|
||
- 最小质押：10,000 NAC
|
||
- 地址：32字节
|
||
- 签名：96字节（NAC原生签名）
|
||
|
||
## 安全注意事项
|
||
|
||
1. **私钥安全**：妥善保管验证器私钥，使用硬件钱包或HSM
|
||
2. **质押要求**：验证器需要质押至少10,000 NAC
|
||
3. **多签验证**：默认需要至少2个验证器签名
|
||
4. **金额限制**：单次锁定金额不超过1,000,000 NAC
|
||
5. **重放攻击**：系统自动防止消息重放
|
||
6. **暂停机制**：管理员可以在紧急情况下暂停桥接
|
||
|
||
## 类型系统说明
|
||
|
||
### NAC原生类型
|
||
|
||
- **Address**: 32字节（与以太坊相同）
|
||
- **Hash**: 48字节（SHA3-384，不是以太坊的32字节）
|
||
- **Signature**: 96字节（NAC原生签名，不是以太坊的65字节）
|
||
|
||
### 类型转换
|
||
|
||
系统提供了NAC和以太坊类型之间的转换工具：
|
||
|
||
```rust
|
||
use nac_cross_chain_bridge::types::{address_converter, hash_converter};
|
||
|
||
// NAC地址（32字节）转以太坊地址（20字节）
|
||
let eth_addr = address_converter::nac_to_eth(&nac_addr);
|
||
|
||
// 以太坊地址转NAC地址
|
||
let nac_addr = address_converter::eth_to_nac(ð_addr);
|
||
|
||
// NAC哈希（48字节）转以太坊哈希（32字节）
|
||
let eth_hash = hash_converter::nac_to_eth(&nac_hash);
|
||
|
||
// 以太坊哈希转NAC哈希
|
||
let nac_hash = hash_converter::eth_to_nac(ð_hash);
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 问题1：锁定失败
|
||
|
||
**原因**：金额超过限制或桥接已暂停
|
||
|
||
**解决方案**：
|
||
```rust
|
||
// 检查桥接状态
|
||
let status = manager.get_status().await?;
|
||
if status.is_paused {
|
||
println!("Bridge is paused");
|
||
}
|
||
|
||
// 检查金额限制
|
||
if amount > config.max_lock_amount {
|
||
println!("Amount exceeds limit");
|
||
}
|
||
```
|
||
|
||
### 问题2：解锁失败
|
||
|
||
**原因**：签名不足或证明无效
|
||
|
||
**解决方案**：
|
||
```rust
|
||
// 确保有足够的验证器签名
|
||
if proof.signatures.len() < config.min_validator_signatures {
|
||
println!("Insufficient signatures");
|
||
}
|
||
|
||
// 验证每个签名的有效性
|
||
for sig in &proof.signatures {
|
||
// 签名必须是96字节
|
||
assert_eq!(sig.as_bytes().len(), 96);
|
||
}
|
||
```
|
||
|
||
### 问题3：中继节点无法启动
|
||
|
||
**原因**：配置错误或端口占用
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 检查配置文件
|
||
cat config.toml
|
||
|
||
# 检查端口占用
|
||
netstat -tulpn | grep 8545
|
||
|
||
# 查看日志
|
||
tail -f logs/relay.log
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
1. **批量处理**：中继节点支持批量处理跨链消息
|
||
2. **缓存优化**：使用sled数据库进行高效存储
|
||
3. **并发处理**：使用tokio异步运行时提高并发性能
|
||
4. **连接池**：复用RPC连接减少延迟
|
||
|
||
## 监控和日志
|
||
|
||
### 日志级别
|
||
|
||
```bash
|
||
# 设置日志级别
|
||
export RUST_LOG=nac_cross_chain_bridge=info
|
||
|
||
# 启动中继节点
|
||
cargo run --bin nac-bridge-relay
|
||
```
|
||
|
||
### 监控指标
|
||
|
||
系统提供以下监控指标：
|
||
|
||
- 锁定资产总量
|
||
- 解锁资产总量
|
||
- 活跃验证器数量
|
||
- 中继消息成功率
|
||
- 平均处理时间
|
||
|
||
## 支持
|
||
|
||
如有问题，请访问：
|
||
- 文档：https://docs.newassetchain.io
|
||
- GitHub：https://github.com/newassetchain/nac-cross-chain-bridge
|
||
- 社区：https://discord.gg/nac
|