nacadmin
/
NAC_Blockchain
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NAC_Blockchain/nac-bridge-contracts/README.md

12 KiB
Raw Blame History

NAC跨链桥Charter智能合约

版本: v1.0.0
语言: Charter
状态: 开发中

📦 合约概述

NAC跨链桥智能合约使用Charter语言编写，实现NAC公链与外部区块链（如以太坊）的跨链资产转移功能。

核心特性

  • ✅ Charter原生：完全使用NAC原生Charter语言，不继承任何以太坊标准
  • ✅ ACC-20C协议：实现NAC包裹资产标准
  • ✅ 宪法收据集成：所有跨链操作需要宪法收据验证
  • ✅ 中继节点验证：多签名中继节点确保安全性
  • ✅ 10%限制：单个包裹资产不超过原资产总量的10%
  • ✅ BLS签名：使用BLS聚合签名提高效率

🏗️ 合约结构

nac-bridge-contracts/
├── src/
│   ├── cross_chain_bridge.charter    # 跨链桥主合约
│   └── wrapped_asset.charter          # ACC-20C包裹资产合约
├── tests/
│   ├── bridge_test.charter            # 桥合约测试
│   └── wrapped_asset_test.charter     # 包裹资产测试
└── README.md

📋 合约详解

1. CrossChainBridge（跨链桥主合约）

核心功能

功能 方法 说明
添加外部链 add_external_chain() 添加支持的外部区块链
添加资产映射 add_asset_mapping() 映射外部资产到NAC包裹资产
提交锁定请求 submit_lock_request() 外部链→NAC：锁定并铸造
提交解锁请求 submit_unlock_request() NAC→外部链：销毁并解锁
查询请求 get_request() 查询跨链请求状态
暂停/恢复 pause()/unpause() 紧急暂停功能

数据结构

ExternalChain（外部链信息）

public struct ExternalChain {
    chain_id: uint64,                    // 链ID（1=以太坊主网）
    chain_name: bytes32,                 // 链名称
    bridge_contract: bytes,              // 外部链桥合约地址
    enabled: bool,                       // 是否启用
    min_confirmations: uint16,           // 最小确认数
    max_lock_amount: uint128             // 单次最大锁定金额
}

CrossChainRequest（跨链请求）

public struct CrossChainRequest {
    request_id: bytes32,                 // 请求ID
    operation: CrossChainOperation,      // Lock/Unlock/Mint/Burn
    source_chain: uint64,                // 源链ID
    target_chain: uint64,                // 目标链ID
    source_address: bytes,               // 源地址
    target_address: [u8; 32],            // 目标地址（NAC地址）
    asset_id: bytes32,                   // 资产ID
    amount: uint128,                     // 数量
    tx_hash: bytes32,                    // 原始交易哈希
    proof: bytes,                        // SPV证明或中继签名
    status: RequestStatus,               // 状态
    created_at: uint64,                  // 创建时间
    completed_at: uint64,                // 完成时间
    relay_signatures: []bytes            // 中继节点签名
}

AssetMapping（资产映射）

public struct AssetMapping {
    external_chain_id: uint64,           // 外部链ID
    external_asset_address: bytes,       // 外部资产合约地址
    nac_wrapped_asset_id: bytes32,       // NAC包裹资产ID
    symbol: bytes32,                     // 符号
    decimals: uint8,                     // 小数位数
    total_locked: uint128,               // 总锁定量
    total_minted: uint128,               // 总铸造量
    enabled: bool                        // 是否启用
}

安全机制

  1. 中继签名验证：需要最少N个中继节点的BLS签名
  2. 10%限制检查：包裹资产总量不超过原资产的10%
  3. 暂停机制：管理员可紧急暂停所有跨链操作
  4. 权限控制：只有管理员可以添加链和资产映射

2. WrappedAsset（ACC-20C包裹资产合约）

核心功能

功能 方法 说明
查询余额 balance_of() 查询账户余额
转账 transfer() 转账给其他账户
授权 approve() 授权其他账户使用额度
授权转账 transfer_from() 从授权额度转账
铸造 mint() 铸造新Token（仅桥合约）
销毁 burn() 销毁Token（仅桥合约）

ACC-20C vs ERC-20

特性 ERC-20 ACC-20C
语言 Solidity Charter
地址格式 20字节 32字节NAC地址
元数据 name/symbol/decimals + GNACS + sovereignty
铸造权限 owner 仅桥合约
销毁权限 任意 仅桥合约
暂停机制 可选 内置

元数据结构

public struct WrappedAssetMetadata {
    name: bytes32,                       // 资产名称
    symbol: bytes32,                     // 资产符号
    decimals: uint8,                     // 小数位数
    original_chain_id: uint64,           // 原始链ID
    original_asset_address: bytes,       // 原始资产地址
    bridge_contract: [u8; 32],           // 桥合约地址
    gnacs: bytes12,                      // GNACS编码
    sovereignty: bytes2                  // 主权级别（C2=跨链资产）
}

🚀 使用示例

1. 部署跨链桥合约

// 部署桥合约
let admin = [0x01; 32];  // 管理员地址
let min_signatures = 3;   // 最少3个中继签名

let bridge = CrossChainBridge::new(admin, min_signatures);

2. 添加以太坊支持

// 添加以太坊主网
bridge.add_external_chain(
    1,                                    // 以太坊主网链ID
    b"Ethereum",                          // 链名称
    b"0x1234...5678",                     // 以太坊桥合约地址
    12,                                   // 12个确认
    1_000_000_000_000_000_000_000        // 最大锁定1000 ETH
);

3. 添加ETH→wETH映射

// 映射ETH到wETH
bridge.add_asset_mapping(
    1,                                    // 以太坊链ID
    b"0x0000000000000000000000000000000000000000",  // ETH地址（0地址）
    compute_asset_id(b"wETH"),            // NAC包裹ETH资产ID
    b"wETH",                              // 符号
    18                                    // 18位小数
);

4. 用户跨链流程（ETH → NAC）

Step 1: 用户在以太坊锁定ETH

// 以太坊侧（用户操作）
EthereumBridge.lockETH{value: 1 ether}(
    nacTargetAddress  // 用户的NAC地址
);

Step 2: 中继节点监听并提交到NAC

// NAC侧（中继节点操作）
let request_id = bridge.submit_lock_request(
    1,                                    // 以太坊链ID
    b"0xUserEthAddress",                  // 用户以太坊地址
    nac_user_address,                     // 用户NAC地址
    b"0x0000000000000000000000000000000000000000",  // ETH地址
    1_000_000_000_000_000_000,            // 1 ETH (wei)
    eth_tx_hash,                          // 以太坊交易哈希
    spv_proof,                            // SPV证明
    relay_signatures                      // 中继签名
);

Step 3: 用户收到wETH

// 查询wETH余额
let weth_asset_id = compute_asset_id(b"wETH");
let balance = WrappedAsset::balance_of(nac_user_address);
// balance = 1_000_000_000_000_000_000 (1 wETH)

5. 用户跨链流程（NAC → ETH）

Step 1: 用户在NAC销毁wETH

// NAC侧（用户操作）
let request_id = bridge.submit_unlock_request(
    1,                                    // 以太坊链ID
    b"0xUserEthAddress",                  // 用户以太坊地址
    weth_asset_id,                        // wETH资产ID
    1_000_000_000_000_000_000             // 1 wETH
);

Step 2: 中继节点监听并在以太坊解锁

// 以太坊侧（中继节点操作）
EthereumBridge.unlockETH(
    userEthAddress,                       // 用户以太坊地址
    1 ether,                              // 1 ETH
    nacTxHash,                            // NAC交易哈希
    relaySignatures                       // 中继签名
);

Step 3: 用户收到ETH

用户在以太坊账户收到1 ETH。

🔒 安全特性

1. 中继节点多签

  • 使用BLS聚合签名
  • 需要至少N个中继节点签名
  • 中继节点公钥存储在合约中
  • 管理员可动态添加/移除中继节点

2. 10%限制

// 检查10%限制
let max_allowed = self.get_max_lockable_amount(nac_asset_id);
require(total_locked + amount <= max_allowed, "Exceeds 10% limit");

3. 暂停机制

// 紧急暂停
bridge.pause();

// 恢复
bridge.unpause();

4. 权限控制

  • 管理员：可以添加链、添加映射、暂停/恢复
  • 桥合约：可以铸造和销毁包裹资产
  • 用户：可以提交解锁请求、转账包裹资产

📊 Charter语言特性

1. 原生类型

Charter类型 说明 示例
uint8 8位无符号整数 18
uint16 16位无符号整数 5000
uint64 64位无符号整数 1 (链ID)
uint128 128位无符号整数 1_000_000_000_000_000_000
bytes 动态字节数组 b"0x1234..."
bytes32 32字节固定数组 请求ID、资产ID
bytes48 48字节固定数组 BLS公钥
[u8; 32] 32字节数组 NAC地址
bool 布尔值 true/false

2. 集合类型

// 映射
map<K, V>

// 动态数组
[]T

// 固定数组
[N]T

3. 合约结构

contract ContractName {
    storage {
        // 存储变量
    }
    
    constructor(params) {
        // 构造函数
    }
    
    pub fn public_function(params) -> ReturnType {
        // 公共函数
    }
    
    fn private_function(params) -> ReturnType {
        // 私有函数
    }
}

4. 事件

event EventName {
    field1: Type1,
    field2: Type2
}

// 触发事件
emit EventName {
    field1: value1,
    field2: value2
};

5. 断言和错误处理

require(condition, "Error message");

🧪 测试

运行测试

charter test src/

测试用例

  1. 桥合约测试

    • 添加外部链
    • 添加资产映射
    • 提交锁定请求
    • 提交解锁请求
    • 验证中继签名
    • 10%限制检查
    • 暂停/恢复

  2. 包裹资产测试

    • 铸造
    • 销毁
    • 转账
    • 授权
    • 授权转账
    • 暂停/恢复

📖 与Solidity对比

特性 Solidity Charter
语言设计 以太坊专用 NAC原生
地址类型 address (20字节) [u8; 32] (32字节)
映射 mapping(K => V) map<K, V>
数组 uint[] []uint
断言 require() require()
事件 event + emit event + emit
继承 is 无继承（组合优于继承）
接口 interface trait
修饰符 modifier 函数内检查

🚀 下一步计划

Phase 1: 合约完善（1周）

  • 实现BLS签名验证
  • 实现宪法收据验证
  • 完善10%限制逻辑
  • 添加事件定义

Phase 2: 测试（1周）

  • 单元测试
  • 集成测试
  • 安全审计

Phase 3: 部署（1周）

  • 部署到NAC测试网
  • 集成到钱包
  • 文档完善

📄 许可证

Copyright © 2026 NAC Wallet Team
All rights reserved.

📞 联系方式

开发团队: NAC Wallet Team
项目地址: /home/ubuntu/NAC_Clean_Dev/nac-bridge-contracts
版本: v1.0.0
状态: 开发中

重要提醒：

  • ✅ 使用Charter语言，不是Solidity
  • ✅ 实现ACC-20C协议，不是ERC-20
  • ✅ NAC原生开发，不继承以太坊标准
  • ✅ 32字节NAC地址，不是20字节以太坊地址