# 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(&eth_addr);

// NAC哈希（48字节）转以太坊哈希（32字节）
let eth_hash = hash_converter::nac_to_eth(&nac_hash);

// 以太坊哈希转NAC哈希
let nac_hash = hash_converter::eth_to_nac(&eth_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