# ACC-20C兼容层实现记录

## 决策日期
2026-02-07

## 背景

### 为什么需要ACC-20C？

ACC-20C不是"妥协"，而是**战略性桥梁**：

1. **现实情况**
   - 以太坊生态拥有数百万用户和成熟基础设施
   - NAC是新生态，需要冷启动
   - 完全隔离会导致流动性不足

2. **战略价值**
   - **短期（1-2年）**: 让ACC-20资产在OpenSea等市场流通
   - **中期（2-3年）**: 逐步引导用户使用NAC原生工具
   - **长期（3年+）**: ACC-20C变成可选而非必需

3. **合规不妥协**
   - 即使包装成ERC-721，仍保留KYC/AML检查
   - 合规状态在NAC链上验证
   - 冻结机制跨链同步

## 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                NAC原生生态（核心）                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  ACC-20 Enhanced + GNACS + 主权管理 + 合规引擎    │   │
│  └──────────────────────────────────────────────────┘   │
│                          ↕                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │         ACC-20C兼容层（战略桥梁）                   │   │
│  │  - 包装器合约                                      │   │
│  │  - 状态同步引擎                                    │   │
│  │  - 元数据生成器                                    │   │
│  │  - 权限代理系统                                    │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│          以太坊生态（流动性来源）                          │
│  ERC-721标准 + OpenSea + MetaMask + DeFi协议             │
└─────────────────────────────────────────────────────────┘
```

## 实现的模块

### 1. 包装器合约（wrapper.rs）- 537行

**核心功能**：
- 锁定ACC-20资产
- 铸造ERC-721 NFT
- 解包装流程
- 冻结/解冻机制

**关键结构**：
```rust
pub struct ACC20CWrapper {
    pub nac_contract_address: Address,
    pub erc721_contract_address: Address,
    pub underlying_asset: Address,
    pub config: WrapperConfig,
    pub wrapped_assets: HashMap<u256, WrappedAsset>,
    pub locked_holdings: HashMap<Address, u128>,
}
```

**包装流程**：
1. 验证包装器状态
2. 验证合规性
3. 锁定ACC-20资产
4. 生成ERC-721 NFT
5. 记录包装信息

**解包装流程**：
1. 验证TokenId存在
2. 验证所有权
3. 销毁ERC-721 NFT
4. 解锁ACC-20资产
5. 转回原始所有者

### 2. 状态同步引擎（sync_engine.rs）- 695行

**核心功能**：
- 监听两条链的事件
- 同步状态变更
- 处理跨链消息
- 重试机制

**同步类型**：
- Wrap: NAC → ETH（包装）
- Unwrap: ETH → NAC（解包装）
- Transfer: ETH内部（转账）
- Freeze: NAC → ETH（冻结）
- Unfreeze: NAC → ETH（解冻）

**关键结构**：
```rust
pub struct SyncEngine {
    pub nac_chain_id: u64,
    pub eth_chain_id: u64,
    pub nac_bridge_address: Address,
    pub eth_bridge_address: EthAddress,
    pub pending_syncs: VecDeque<SyncTask>,
    pub completed_syncs: HashMap<Hash, SyncTask>,
}
```

### 3. 元数据生成器（metadata_generator.rs）- 328行

**核心功能**：
- 生成ERC-721元数据
- 包含GNACS信息
- 符合OpenSea标准

**元数据属性**：
1. Asset Symbol - 资产符号
2. Wrapped Amount - 包装数量
3. GNACS Code - GNACS编码
4. Asset Category - 资产类别
5. Sovereignty Type - 主权类型
6. Compliance Level - 合规级别
7. Jurisdiction - 司法辖区
8. Risk Level - 风险等级
9. Compliance Status - 合规状态
10. Fragmentable - 是否可碎片化
11. Cross-Chain Enabled - 是否启用跨链
12. Valuation (XTZH) - 估值
13. Created At - 创建时间

**关键结构**：
```rust
pub struct ERC721Metadata {
    pub name: String,
    pub description: String,
    pub image: String,
    pub external_url: Option<String>,
    pub attributes: Vec<MetadataAttribute>,
    pub background_color: Option<String>,
}
```

### 4. 权限代理系统（permission_proxy.rs）- 481行

**核心功能**：
- 跨链权限验证
- 合规检查代理
- 白名单/黑名单管理
- KYC/AML缓存

**检查流程**：
1. 获取NAC地址（从以太坊地址映射）
2. 检查黑名单
3. 检查白名单（如果启用）
4. 检查KYC
5. 检查AML

**关键结构**：
```rust
pub struct PermissionProxy {
    pub nac_proxy_address: Address,
    pub eth_proxy_address: EthAddress,
    pub address_mapping: HashMap<EthAddress, Address>,
    pub kyc_cache: HashMap<Address, KYCRecord>,
    pub aml_cache: HashMap<Address, AMLRecord>,
    pub whitelist: HashMap<Address, WhitelistEntry>,
    pub blacklist: HashMap<Address, BlacklistEntry>,
}
```

## 代码统计

| 模块 | 文件 | 行数 | 功能 |
|------|------|------|------|
| 模块主文件 | mod.rs | 111 | 模块导出和文档 |
| 包装器合约 | wrapper.rs | 537 | 包装/解包装逻辑 |
| 状态同步引擎 | sync_engine.rs | 695 | 跨链状态同步 |
| 元数据生成器 | metadata_generator.rs | 328 | ERC-721元数据 |
| 权限代理系统 | permission_proxy.rs | 481 | 权限验证 |
| **总计** | **5个文件** | **2,152行** | **完整实现** |

## NAC合规性

✅ **术语NAC化**：
- Holdings（不是balance）
- Asset（不是Token）
- Certificate（不是NFT）
- Address（不是account）

✅ **哈希算法**：
- Blake3（不是SHA256/Keccak256）

✅ **合规内置**：
- KYC级别验证
- AML状态检查
- 司法辖区验证
- 白名单/黑名单

✅ **主权管理**：
- A0-G5主权类型
- 主权规则验证
- 转让限制检查

## 重要说明

⚠️ **ACC-20C不是NAC的核心，而是生态扩展**

- NAC的核心是ACC-20 Enhanced + GNACS + 主权管理
- ACC-20C只是为了冷启动和流动性
- 随着NAC生态成熟，ACC-20C的重要性会逐渐降低
- 最终目标是建立完全独立的NAC原生生态

## 下一步

### 阶段3：完善主权管理系统
- 实现主权转换逻辑
- 添加主权规则验证
- 实现主权历史追踪

### 阶段4：扩展Charter标准库
- 添加`charter-std/acc/acc20c.ch`
- 添加`charter-std/bridge/`模块
- 创建完整示例

### 阶段5：集成测试和打包交付
- 端到端测试
- 性能测试
- 文档完善
- 打包交付

## 参考文档

- 《NAC原生技术栈完全去以太坊化架构设计（GNACS增强版）》
- 《ACC-20兼容层协议（ACC-20C）完整阐述》
- NAC核心原则（nac_core_principles.md）