7.9 KiB

Raw Permalink Blame History

NAC跨链桥接使用文档

概述

NAC跨链桥接模块提供了在NAC公链和其他区块链（如以太坊）之间安全转移资产的能力。本文档详细说明如何使用桥接系统。

系统架构

NAC跨链桥接系统由以下组件组成：

资产锁定器（AssetLocker）：在源链上锁定资产
资产解锁器（AssetUnlocker）：在目标链上解锁资产
验证器池（ValidatorPool）：管理验证器和多签验证
中继节点（Relayer）：在链之间传递跨链消息
以太坊监听器（EthereumListener）：监听以太坊链上的事件
桥接管理器（BridgeManager）：统一管理桥接系统

快速开始

1. 安装依赖

cargo build --release

2. 配置桥接

创建配置文件config.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. 启动中继节点

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：锁定资产

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：等待验证器确认

中继节点会自动：

监听锁定事件
收集验证器签名
在以太坊上铸造对应的代币

步骤3：查询锁定状态

let status = locker.get_lock_status(receipt.lock_id).await?;
println!("Lock status: {:?}", status);

场景2：从以太坊转移资产回NAC

步骤1：在以太坊上销毁代币

在以太坊上调用桥接合约的burn函数：

bridge.burn(tokenAddress, amount, nacReceiver);

步骤2：提交解锁证明

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：注册为验证器

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

锁定资产以进行跨链转移。

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

查询锁定状态。

async fn get_lock_status(&self, lock_id: Hash) -> Result<LockStatus>

AssetUnlocker

unlock_asset

解锁资产。

async fn unlock_asset(
    &self,
    lock_id: Hash,
    proof: UnlockProof,
) -> Result<UnlockReceipt>

参数：

lock_id: 锁定ID（48字节哈希）
proof: 解锁证明（包含验证器签名）

UnlockReceipt: 解锁收据（包含48字节的unlock_id）

ValidatorPool

register_validator

注册验证器。

async fn register_validator(&self, validator: ValidatorInfo) -> Result<()>

要求：

最小质押：10,000 NAC
地址：32字节
签名：96字节（NAC原生签名）

安全注意事项

私钥安全：妥善保管验证器私钥，使用硬件钱包或HSM
质押要求：验证器需要质押至少10,000 NAC
多签验证：默认需要至少2个验证器签名
金额限制：单次锁定金额不超过1,000,000 NAC
重放攻击：系统自动防止消息重放
暂停机制：管理员可以在紧急情况下暂停桥接

类型系统说明

NAC原生类型

Address: 32字节（与以太坊相同）
Hash: 48字节（SHA3-384，不是以太坊的32字节）
Signature: 96字节（NAC原生签名，不是以太坊的65字节）

类型转换

系统提供了NAC和以太坊类型之间的转换工具：

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：锁定失败

原因：金额超过限制或桥接已暂停

解决方案：

// 检查桥接状态
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：解锁失败

原因：签名不足或证明无效

解决方案：

// 确保有足够的验证器签名
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：中继节点无法启动

原因：配置错误或端口占用

解决方案：

# 检查配置文件
cat config.toml

# 检查端口占用
netstat -tulpn | grep 8545

# 查看日志
tail -f logs/relay.log

性能优化

批量处理：中继节点支持批量处理跨链消息
缓存优化：使用sled数据库进行高效存储
并发处理：使用tokio异步运行时提高并发性能
连接池：复用RPC连接减少延迟

监控和日志

日志级别

# 设置日志级别
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

7.9 KiB Raw Permalink Blame History Unescape Escape

NAC跨链桥接使用文档

概述

系统架构

快速开始

1. 安装依赖

2. 配置桥接

3. 启动中继节点

使用场景

场景1：从NAC转移资产到以太坊

步骤1：锁定资产

步骤2：等待验证器确认

步骤3：查询锁定状态

场景2：从以太坊转移资产回NAC

步骤1：在以太坊上销毁代币

步骤2：提交解锁证明

场景3：注册为验证器

API参考

AssetLocker

lock_asset

get_lock_status

AssetUnlocker

unlock_asset

ValidatorPool

register_validator

安全注意事项

类型系统说明

NAC原生类型

类型转换

故障排除

问题1：锁定失败

问题2：解锁失败

问题3：中继节点无法启动

性能优化

监控和日志

日志级别

监控指标

支持

7.9 KiB

Raw Permalink Blame History