503 lines
12 KiB
Markdown
503 lines
12 KiB
Markdown
# ACC-20C: 兼容层协议使用指南
|
||
|
||
## 概述
|
||
|
||
ACC-20C是NAC与以太坊生态之间的**战略性桥梁**，而非妥协。它提供双向包装机制，让NAC原生的ACC-20资产能够在以太坊生态（OpenSea等）中流通，同时保留NAC的合规特性。
|
||
|
||
## 核心理念
|
||
|
||
**NAC是核心，ACC-20C是流动性入口**
|
||
|
||
### 为什么需要ACC-20C？
|
||
|
||
1. **现实情况**
|
||
- 以太坊生态拥有数百万用户和成熟基础设施
|
||
- NAC是新生态，需要冷启动
|
||
- 完全隔离会导致流动性不足
|
||
|
||
2. **战略价值**
|
||
- **短期（1-2年）**: 让ACC-20资产在OpenSea等市场流通
|
||
- **中期（2-3年）**: 逐步引导用户使用NAC原生工具
|
||
- **长期（3年+）**: ACC-20C变成可选而非必需
|
||
|
||
3. **合规不妥协**
|
||
- 即使包装成ERC-721，仍保留KYC/AML检查
|
||
- 合规状态在NAC链上验证
|
||
- 冻结机制跨链同步
|
||
|
||
## 架构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ NAC原生生态（核心） │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ ACC-20 Enhanced + GNACS + 主权管理 + 合规引擎 │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ↕ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ ACC-20C兼容层（战略桥梁） │ │
|
||
│ │ - 包装器合约 │ │
|
||
│ │ - 状态同步引擎 │ │
|
||
│ │ - 元数据生成器 │ │
|
||
│ │ - 权限代理系统 │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↕
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 以太坊生态（流动性来源） │
|
||
│ ERC-721标准 + OpenSea + MetaMask + DeFi协议 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心组件
|
||
|
||
### 1. 包装器合约（Wrapper）
|
||
- 锁定ACC-20资产
|
||
- 铸造ERC-721 NFT
|
||
- 管理包装/解包装流程
|
||
|
||
### 2. 状态同步引擎（SyncEngine）
|
||
- 监听两条链的事件
|
||
- 同步状态变更
|
||
- 处理跨链消息
|
||
|
||
### 3. 元数据生成器（MetadataGenerator）
|
||
- 生成ERC-721元数据
|
||
- 包含GNACS信息
|
||
- 符合OpenSea标准
|
||
|
||
### 4. 权限代理系统（PermissionProxy）
|
||
- 跨链权限验证
|
||
- 合规检查代理
|
||
- 主权规则验证
|
||
|
||
## 使用流程
|
||
|
||
### 包装（Wrap）
|
||
```text
|
||
1. 用户在NAC链上调用wrap()
|
||
2. 锁定ACC-20资产
|
||
3. 生成包装记录
|
||
4. 同步引擎监听事件
|
||
5. 在以太坊链铸造ERC-721
|
||
6. 用户可在OpenSea交易
|
||
```
|
||
|
||
### 解包装（Unwrap）
|
||
```text
|
||
1. 用户在以太坊链销毁ERC-721
|
||
2. 同步引擎监听事件
|
||
3. 在NAC链验证合规性
|
||
4. 解锁ACC-20资产
|
||
5. 转回用户账户
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 添加依赖
|
||
|
||
```toml
|
||
[dependencies]
|
||
nac-sdk = "0.1.0"
|
||
nac-udm = "0.1.0"
|
||
tokio = { version = "1.0", features = ["full"] }
|
||
```
|
||
|
||
### 2. 创建客户端
|
||
|
||
```rust
|
||
use nac_sdk::client::NacLensClient;
|
||
use nac_sdk::protocols::ACC20C;
|
||
|
||
let client = NacLensClient::new("https://rpc.newassetchain.io");
|
||
let acc20c = ACC20C::new(client);
|
||
```
|
||
|
||
### 3. 包装ACC-20为ERC-721
|
||
|
||
```rust
|
||
use nac_udm::primitives::Address;
|
||
use nac_udm::l1_protocol::acc20c::EthAddress;
|
||
|
||
// 准备地址
|
||
let wrapper_address = Address::from_hex("0x1234...")?;
|
||
let nac_owner = Address::from_hex("0x2234...")?;
|
||
let eth_recipient = EthAddress([0u8; 20]); // 以太坊地址
|
||
|
||
// 包装
|
||
let amount = 5_000_000_000_000_000_000u128; // 5 ACC-20
|
||
let token_id = acc20c.wrap(
|
||
&wrapper_address,
|
||
&nac_owner,
|
||
ð_recipient,
|
||
amount,
|
||
).await?;
|
||
|
||
println!("ERC-721 Token ID: {}", token_id.low);
|
||
```
|
||
|
||
### 4. 解包装ERC-721为ACC-20
|
||
|
||
```rust
|
||
let nac_recipient = Address::from_hex("0x3234...")?;
|
||
|
||
let unwrapped_amount = acc20c.unwrap(
|
||
&wrapper_address,
|
||
token_id,
|
||
ð_recipient,
|
||
&nac_recipient,
|
||
).await?;
|
||
|
||
println!("Unwrapped amount: {}", unwrapped_amount);
|
||
```
|
||
|
||
## API参考
|
||
|
||
### 包装/解包装操作
|
||
|
||
#### wrap
|
||
包装ACC-20为ERC-721
|
||
|
||
```rust
|
||
pub async fn wrap(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
owner: &Address,
|
||
eth_recipient: &EthAddress,
|
||
amount: u128,
|
||
) -> Result<u256>
|
||
```
|
||
|
||
**参数**：
|
||
- `wrapper_address` - 包装器合约地址
|
||
- `owner` - NAC链上的所有者地址
|
||
- `eth_recipient` - 以太坊链上的接收者地址
|
||
- `amount` - 包装数量
|
||
|
||
**返回**：ERC-721 Token ID
|
||
|
||
#### unwrap
|
||
解包装ERC-721为ACC-20
|
||
|
||
```rust
|
||
pub async fn unwrap(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
token_id: u256,
|
||
eth_owner: &EthAddress,
|
||
nac_recipient: &Address,
|
||
) -> Result<u128>
|
||
```
|
||
|
||
**参数**：
|
||
- `wrapper_address` - 包装器合约地址
|
||
- `token_id` - ERC-721 Token ID
|
||
- `eth_owner` - 以太坊链上的所有者地址
|
||
- `nac_recipient` - NAC链上的接收者地址
|
||
|
||
**返回**：解包装的ACC-20数量
|
||
|
||
### 查询方法
|
||
|
||
#### get_wrapped_asset
|
||
查询包装资产信息
|
||
|
||
```rust
|
||
pub async fn get_wrapped_asset(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
token_id: u256,
|
||
) -> Result<WrappedAsset>
|
||
```
|
||
|
||
#### get_locked_holdings
|
||
查询锁定的持有量
|
||
|
||
```rust
|
||
pub async fn get_locked_holdings(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
owner: &Address,
|
||
) -> Result<u128>
|
||
```
|
||
|
||
#### get_wrapper_config
|
||
查询包装器配置
|
||
|
||
```rust
|
||
pub async fn get_wrapper_config(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
) -> Result<WrapperConfig>
|
||
```
|
||
|
||
#### get_wrapper_status
|
||
查询包装器状态
|
||
|
||
```rust
|
||
pub async fn get_wrapper_status(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
) -> Result<WrapperStatus>
|
||
```
|
||
|
||
#### get_metadata_uri
|
||
获取元数据URI
|
||
|
||
```rust
|
||
pub async fn get_metadata_uri(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
token_id: u256,
|
||
) -> Result<String>
|
||
```
|
||
|
||
### 管理方法
|
||
|
||
#### freeze_wrapped_asset
|
||
冻结包装资产
|
||
|
||
```rust
|
||
pub async fn freeze_wrapped_asset(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
token_id: u256,
|
||
) -> Result<()>
|
||
```
|
||
|
||
#### unfreeze_wrapped_asset
|
||
解冻包装资产
|
||
|
||
```rust
|
||
pub async fn unfreeze_wrapped_asset(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
token_id: u256,
|
||
) -> Result<()>
|
||
```
|
||
|
||
### 手续费计算
|
||
|
||
#### calculate_wrap_fee
|
||
计算包装手续费
|
||
|
||
```rust
|
||
pub async fn calculate_wrap_fee(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
amount: u128,
|
||
) -> Result<u128>
|
||
```
|
||
|
||
#### calculate_unwrap_fee
|
||
计算解包装手续费
|
||
|
||
```rust
|
||
pub async fn calculate_unwrap_fee(
|
||
&self,
|
||
wrapper_address: &Address,
|
||
amount: u128,
|
||
) -> Result<u128>
|
||
```
|
||
|
||
## 数据结构
|
||
|
||
### WrappedAsset
|
||
包装后的资产
|
||
|
||
```rust
|
||
pub struct WrappedAsset {
|
||
pub token_id: u256,
|
||
pub original_holdings: u128,
|
||
pub original_owner: Address,
|
||
pub current_owner: EthAddress,
|
||
pub gnacs_code: GNACSCode,
|
||
pub wrapped_at: Timestamp,
|
||
pub metadata_uri: String,
|
||
pub compliance_snapshot: ComplianceSnapshot,
|
||
pub status: WrappedAssetStatus,
|
||
}
|
||
```
|
||
|
||
### WrapperConfig
|
||
包装器配置
|
||
|
||
```rust
|
||
pub struct WrapperConfig {
|
||
pub acc20_per_nft: u128,
|
||
pub allow_partial_wrap: bool,
|
||
pub wrap_fee_bps: u16,
|
||
pub unwrap_fee_bps: u16,
|
||
pub fee_recipient: Address,
|
||
pub preserve_compliance: bool,
|
||
pub min_wrap_amount: u128,
|
||
pub max_wrap_amount: u128,
|
||
}
|
||
```
|
||
|
||
### ComplianceSnapshot
|
||
合规快照
|
||
|
||
```rust
|
||
pub struct ComplianceSnapshot {
|
||
pub kyc_level: u8,
|
||
pub aml_status: u8,
|
||
pub compliance_level: u8,
|
||
pub jurisdiction: u8,
|
||
pub snapshot_at: Timestamp,
|
||
pub snapshot_hash: Hash,
|
||
}
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 跨链流程示例
|
||
|
||
```rust
|
||
use nac_sdk::client::NacLensClient;
|
||
use nac_sdk::protocols::ACC20C;
|
||
use nac_udm::primitives::Address;
|
||
use nac_udm::l1_protocol::acc20c::EthAddress;
|
||
|
||
#[tokio::main]
|
||
async fn main() -> Result<()> {
|
||
// 1. 创建客户端
|
||
let client = NacLensClient::new("https://rpc.newassetchain.io");
|
||
let acc20c = ACC20C::new(client);
|
||
|
||
// 2. 准备地址
|
||
let wrapper_address = Address::from_hex("0x1234...")?;
|
||
let nac_owner = Address::from_hex("0x2234...")?;
|
||
let eth_trader = EthAddress([0x33; 20]);
|
||
|
||
// 3. 包装ACC-20
|
||
let amount = 5_000_000_000_000_000_000u128;
|
||
let token_id = acc20c.wrap(
|
||
&wrapper_address,
|
||
&nac_owner,
|
||
ð_trader,
|
||
amount,
|
||
).await?;
|
||
|
||
println!("✓ Wrapped: Token ID {}", token_id.low);
|
||
|
||
// 4. 在OpenSea交易（模拟）
|
||
let new_eth_owner = EthAddress([0x44; 20]);
|
||
println!("✓ Traded on OpenSea");
|
||
|
||
// 5. 解包装回NAC
|
||
let new_nac_owner = Address::from_hex("0x3234...")?;
|
||
let unwrapped = acc20c.unwrap(
|
||
&wrapper_address,
|
||
token_id,
|
||
&new_eth_owner,
|
||
&new_nac_owner,
|
||
).await?;
|
||
|
||
println!("✓ Unwrapped: {} ACC-20", unwrapped);
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 包装前检查
|
||
|
||
- 验证包装器状态是否为Active
|
||
- 检查包装数量是否在允许范围内
|
||
- 计算手续费，确保用户了解成本
|
||
|
||
### 2. 合规保留
|
||
|
||
- 包装前确保通过KYC/AML检查
|
||
- 定期验证合规快照
|
||
- 发现问题及时冻结资产
|
||
|
||
### 3. 手续费管理
|
||
|
||
- 使用基点（bps）计算手续费：1基点 = 0.01%
|
||
- 包装和解包装都会收取手续费
|
||
- 手续费由包装器配置决定
|
||
|
||
### 4. 状态同步
|
||
|
||
- 包装后等待同步引擎确认
|
||
- 解包装前验证ERC-721所有权
|
||
- 监听跨链事件确保状态一致
|
||
|
||
### 5. 元数据管理
|
||
|
||
- 元数据URI符合ERC-721标准
|
||
- 包含GNACS编码信息
|
||
- 在OpenSea上正确显示
|
||
|
||
## 与ERC-721的对比
|
||
|
||
| 特性 | 标准ERC-721 | ACC-20C包装的ERC-721 |
|
||
|------|-------------|---------------------|
|
||
| 基础功能 | ✅ | ✅ |
|
||
| 合规检查 | ❌ | ✅ |
|
||
| 冻结机制 | ❌ | ✅ |
|
||
| GNACS编码 | ❌ | ✅ |
|
||
| 合规快照 | ❌ | ✅ |
|
||
| 双向包装 | ❌ | ✅ |
|
||
| 跨链同步 | ❌ | ✅ |
|
||
|
||
## 错误处理
|
||
|
||
```rust
|
||
use nac_sdk::error::{NACError, Result};
|
||
|
||
match acc20c.wrap(&wrapper_address, &owner, ð_recipient, amount).await {
|
||
Ok(token_id) => println!("Success: {}", token_id.low),
|
||
Err(NACError::InvalidAddress(e)) => eprintln!("Invalid address: {}", e),
|
||
Err(NACError::InvalidResponse(e)) => eprintln!("Invalid response: {}", e),
|
||
Err(e) => eprintln!("Error: {:?}", e),
|
||
}
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行单元测试：
|
||
|
||
```bash
|
||
cargo test acc20c
|
||
```
|
||
|
||
运行集成测试（需要NAC节点和以太坊测试网）：
|
||
|
||
```bash
|
||
cargo test --test acc20c_integration_test -- --ignored
|
||
```
|
||
|
||
## 示例代码
|
||
|
||
完整的示例代码请参考：`examples/acc20c_example.rs`
|
||
|
||
运行示例：
|
||
|
||
```bash
|
||
cargo run --example acc20c_example
|
||
```
|
||
|
||
## 重要说明
|
||
|
||
⚠️ **ACC-20C不是NAC的核心，而是生态扩展**
|
||
|
||
- NAC的核心是ACC-20 Enhanced + GNACS + 主权管理
|
||
- ACC-20C只是为了冷启动和流动性
|
||
- 随着NAC生态成熟，ACC-20C的重要性会逐渐降低
|
||
- 最终目标是建立完全独立的NAC原生生态
|
||
|
||
## 相关资源
|
||
|
||
- [NAC技术白皮书](https://newassetchain.io/whitepaper)
|
||
- [ACC-20C兼容层协议文档](https://newassetchain.io/acc20c)
|
||
- [OpenSea集成指南](https://newassetchain.io/opensea)
|
||
- [跨链桥接安全指南](https://newassetchain.io/bridge-security)
|
||
|
||
## 许可证
|
||
|
||
MIT License
|