453 lines
12 KiB
Markdown
453 lines
12 KiB
Markdown
# 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<K, V>
|
||
|
||
// 动态数组
|
||
[]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<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字节以太坊地址
|