# 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**（外部链信息） ```charter public struct ExternalChain { chain_id: uint64, // 链ID（1=以太坊主网） chain_name: bytes32, // 链名称 bridge_contract: bytes, // 外部链桥合约地址 enabled: bool, // 是否启用 min_confirmations: uint16, // 最小确认数 max_lock_amount: uint128 // 单次最大锁定金额 } ``` **CrossChainRequest**（跨链请求） ```charter 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**（资产映射） ```charter 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 | **仅桥合约** | | 销毁权限 | 任意 | **仅桥合约** | | 暂停机制 | 可选 | **内置** | #### 元数据结构 ```charter 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. 部署跨链桥合约 ```charter // 部署桥合约 let admin = [0x01; 32]; // 管理员地址 let min_signatures = 3; // 最少3个中继签名 let bridge = CrossChainBridge::new(admin, min_signatures); ``` ### 2. 添加以太坊支持 ```charter // 添加以太坊主网 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映射 ```charter // 映射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 ```solidity // 以太坊侧（用户操作） EthereumBridge.lockETH{value: 1 ether}( nacTargetAddress // 用户的NAC地址 ); ``` #### Step 2: 中继节点监听并提交到NAC ```charter // 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 ```charter // 查询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 ```charter // 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: 中继节点监听并在以太坊解锁 ```solidity // 以太坊侧（中继节点操作） EthereumBridge.unlockETH( userEthAddress, // 用户以太坊地址 1 ether, // 1 ETH nacTxHash, // NAC交易哈希 relaySignatures // 中继签名 ); ``` #### Step 3: 用户收到ETH 用户在以太坊账户收到1 ETH。 --- ## 🔒 安全特性 ### 1. 中继节点多签 - 使用BLS聚合签名 - 需要至少N个中继节点签名 - 中继节点公钥存储在合约中 - 管理员可动态添加/移除中继节点 ### 2. 10%限制 ```charter // 检查10%限制 let max_allowed = self.get_max_lockable_amount(nac_asset_id); require(total_locked + amount <= max_allowed, "Exceeds 10% limit"); ``` ### 3. 暂停机制 ```charter // 紧急暂停 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. 集合类型 ```charter // 映射 map // 动态数组 []T // 固定数组 [N]T ``` ### 3. 合约结构 ```charter contract ContractName { storage { // 存储变量 } constructor(params) { // 构造函数 } pub fn public_function(params) -> ReturnType { // 公共函数 } fn private_function(params) -> ReturnType { // 私有函数 } } ``` ### 4. 事件 ```charter event EventName { field1: Type1, field2: Type2 } // 触发事件 emit EventName { field1: value1, field2: value2 }; ``` ### 5. 断言和错误处理 ```charter require(condition, "Error message"); ``` --- ## 🧪 测试 ### 运行测试 ```bash charter test src/ ``` ### 测试用例 1. **桥合约测试** - 添加外部链 - 添加资产映射 - 提交锁定请求 - 提交解锁请求 - 验证中继签名 - 10%限制检查 - 暂停/恢复 2. **包裹资产测试** - 铸造 - 销毁 - 转账 - 授权 - 授权转账 - 暂停/恢复 --- ## 📖 与Solidity对比 | 特性 | Solidity | Charter | |------|----------|---------| | 语言设计 | 以太坊专用 | **NAC原生** | | 地址类型 | `address` (20字节) | **`[u8; 32]` (32字节)** | | 映射 | `mapping(K => V)` | **`map`** | | 数组 | `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字节以太坊地址