History

NAC Development Team 6de7fd246a Initial commit: NAC公链核心模块 - 生产级别代码		2026-02-16 19:19:43 -05:00
..
build	Initial commit: NAC公链核心模块 - 生产级别代码	2026-02-16 19:19:43 -05:00
src	Initial commit: NAC公链核心模块 - 生产级别代码	2026-02-16 19:19:43 -05:00
README.md	Initial commit: NAC公链核心模块 - 生产级别代码	2026-02-16 19:19:43 -05:00

README.md

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                        // 是否启用
}

安全机制

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

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/

测试用例

桥合约测试
- 添加外部链
- 添加资产映射
- 提交锁定请求
- 提交解锁请求
- 验证中继签名
- 10%限制检查
- 暂停/恢复
包裹资产测试
- 铸造
- 销毁
- 转账
- 授权
- 授权转账
- 暂停/恢复

📖 与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测试网
集成到钱包
文档完善

📄 许可证

📞 联系方式

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

重要提醒：

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

README.md Unescape Escape

NAC跨链桥Charter智能合约

📦 合约概述

核心特性

🏗️ 合约结构

📋 合约详解

1. CrossChainBridge（跨链桥主合约）

核心功能

数据结构

安全机制

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

核心功能

ACC-20C vs ERC-20

元数据结构

🚀 使用示例

1. 部署跨链桥合约

2. 添加以太坊支持

3. 添加ETH→wETH映射

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

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

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

Step 3: 用户收到wETH

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

Step 1: 用户在NAC销毁wETH

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

Step 3: 用户收到ETH

🔒 安全特性

1. 中继节点多签

2. 10%限制

3. 暂停机制

4. 权限控制

📊 Charter语言特性

1. 原生类型

2. 集合类型

3. 合约结构

4. 事件

5. 断言和错误处理

🧪 测试

运行测试

测试用例

📖 与Solidity对比

🚀 下一步计划

Phase 1: 合约完善（1周）

Phase 2: 测试（1周）

Phase 3: 部署（1周）

📄 许可证

📞 联系方式

README.md