docs: 完成charter-std深度分析
- 11,364行Charter代码，18个.ch文件 - 6大模块：ACC协议、资产管理、DeFi、治理、主权合规、工具 - RWA特色：GNACS编码、主权类型、七层合规验证 - 完成度80%，需补充文档和测试 已完成模块分析: 6/46 (13%)
This commit is contained in:
NAC Development Team
parent
7759e24b19
commit
263b746519
|
|
@ -0,0 +1,489 @@
|
|||
# charter-std 模块深度分析报告
|
||||
|
||||
**分析日期**: 2026-02-18
|
||||
**模块版本**: N/A (标准库)
|
||||
**分析状态**: ✅ 完成
|
||||
|
||||
---
|
||||
|
||||
## 一、模块概述
|
||||
|
||||
**模块名称**: charter-std
|
||||
**功能定位**: Charter语言标准库 - 提供智能合约开发的标准功能和协议实现
|
||||
**开发语言**: Charter (NAC智能合约语言)
|
||||
**模块类型**: 标准库
|
||||
|
||||
Charter标准库是NAC公链智能合约开发的基础设施，提供了ACC协议、资产管理、DeFi功能、治理、主权合规等标准实现。开发者可以直接导入使用，无需从零开发。
|
||||
|
||||
---
|
||||
|
||||
## 二、目录结构
|
||||
|
||||
```
|
||||
charter-std/
|
||||
├── README.md # 模块说明（待完善）
|
||||
├── acc/ # ACC协议标准（4个文件，2641行）
|
||||
│ ├── acc20.ch # ACC-20可替代资产协议（557行）
|
||||
│ ├── acc20_enhanced.ch # ACC-20增强版（733行）
|
||||
│ ├── acc20c.ch # ACC-20C合规版（584行）
|
||||
│ └── acc721.ch # ACC-721非同质化资产协议（771行）
|
||||
├── asset/ # 资产管理（3个文件，1567行）
|
||||
│ ├── gnacs.ch # GNACS编码系统（300行）
|
||||
│ ├── lifecycle.ch # 资产生命周期管理（711行）
|
||||
│ └── metadata.ch # 资产元数据管理（556行）
|
||||
├── defi/ # DeFi功能（3个文件，2501行）
|
||||
│ ├── lending.ch # 借贷协议（819行）
|
||||
│ ├── liquidity.ch # 流动性池（807行）
|
||||
│ └── marketplace.ch # 资产交易市场（875行）
|
||||
├── governance/ # 治理（2个文件，1503行）
|
||||
│ ├── proposal.ch # 提案系统（703行）
|
||||
│ └── voting.ch # 投票系统（800行）
|
||||
├── sovereignty/ # 主权合规（3个文件，2194行）
|
||||
│ ├── compliance.ch # 合规验证（837行）
|
||||
│ ├── registry.ch # 主权注册表（765行）
|
||||
│ └── rules.ch # 主权规则（592行）
|
||||
└── utils/ # 工具函数（3个文件，954行）
|
||||
├── crypto.ch # 加密工具（380行）
|
||||
├── math.ch # 数学库（476行）
|
||||
└── time.ch # 时间处理（98行）
|
||||
```
|
||||
|
||||
**代码统计**:
|
||||
- 总行数: 11,364行
|
||||
- Charter文件数: 18个
|
||||
- 模块分类: 6个（acc, asset, defi, governance, sovereignty, utils）
|
||||
|
||||
---
|
||||
|
||||
## 三、核心模块详细分析
|
||||
|
||||
### 3.1 ACC协议标准（acc/）
|
||||
|
||||
**总代码量**: 2641行
|
||||
**核心功能**: 定义NAC资产协议标准
|
||||
|
||||
#### 3.1.1 acc20.ch - ACC-20可替代资产协议
|
||||
|
||||
**文件大小**: 557行
|
||||
**核心功能**: 类似ERC-20，但专为RWA设计
|
||||
|
||||
**接口定义**:
|
||||
```charter
|
||||
interface ACC20 {
|
||||
// 查询函数
|
||||
fn totalSupply() -> u256;
|
||||
fn holdingsOf(owner: Address) -> u256;
|
||||
fn name() -> String;
|
||||
fn symbol() -> String;
|
||||
fn decimals() -> u8;
|
||||
fn gnacsCode() -> u48;
|
||||
fn sovereigntyType() -> SovereigntyType;
|
||||
|
||||
// 转账函数
|
||||
fn transfer(to: Address, amount: u256) -> bool;
|
||||
fn transferFrom(from: Address, to: Address, amount: u256) -> bool;
|
||||
|
||||
// 授权函数
|
||||
fn approve(spender: Address, amount: u256) -> bool;
|
||||
fn allowance(owner: Address, spender: Address) -> u256;
|
||||
fn increaseAllowance(spender: Address, addedValue: u256) -> bool;
|
||||
fn decreaseAllowance(spender: Address, subtractedValue: u256) -> bool;
|
||||
|
||||
// RWA扩展函数
|
||||
fn freeze(account: Address) -> bool;
|
||||
fn unfreeze(account: Address) -> bool;
|
||||
fn isFrozen(account: Address) -> bool;
|
||||
fn complianceStatus(account: Address) -> u4;
|
||||
}
|
||||
```
|
||||
|
||||
**事件定义**:
|
||||
- `Transfer` - 转账事件
|
||||
- `Approval` - 授权事件
|
||||
- `Mint` - 铸造事件
|
||||
- `Burn` - 销毁事件
|
||||
- `Freeze` - 冻结事件
|
||||
- `Unfreeze` - 解冻事件
|
||||
|
||||
**标准实现**:
|
||||
```charter
|
||||
certificate ACC20Token with Sovereignty<A0> implements ACC20 {
|
||||
let _name: String;
|
||||
let _symbol: String;
|
||||
let _decimals: u8;
|
||||
let _gnacs_code: u48;
|
||||
let _sovereignty_type: SovereigntyType;
|
||||
let _total_supply: u256;
|
||||
let _holdings: Map<Address, u256>;
|
||||
let _allowances: Map<Address, Map<Address, u256>>;
|
||||
let _frozen_accounts: Set<Address>;
|
||||
let _compliance_status: Map<Address, u4>;
|
||||
let _admin: Address;
|
||||
|
||||
// 完整的函数实现...
|
||||
}
|
||||
```
|
||||
|
||||
**RWA特色功能**:
|
||||
1. **账户冻结**: 支持冻结/解冻账户，用于合规管理
|
||||
2. **合规状态**: 每个账户有合规状态标记
|
||||
3. **GNACS编码**: 集成GNACS资产分类系统
|
||||
4. **主权类型**: 支持主权类型标记（A0, C0-C2, D0-D2）
|
||||
|
||||
#### 3.1.2 acc20_enhanced.ch - ACC-20增强版
|
||||
|
||||
**文件大小**: 733行
|
||||
**扩展功能**:
|
||||
- 批量转账
|
||||
- 时间锁定
|
||||
- 快照功能
|
||||
- 暂停/恢复
|
||||
- 黑白名单
|
||||
|
||||
#### 3.1.3 acc20c.ch - ACC-20C合规版
|
||||
|
||||
**文件大小**: 584行
|
||||
**合规功能**:
|
||||
- KYC/AML集成
|
||||
- 交易限额
|
||||
- 地域限制
|
||||
- 合规报告
|
||||
|
||||
#### 3.1.4 acc721.ch - ACC-721非同质化资产协议
|
||||
|
||||
**文件大小**: 771行
|
||||
**核心功能**: 类似ERC-721，用于NFT和独特资产
|
||||
|
||||
---
|
||||
|
||||
### 3.2 资产管理（asset/）
|
||||
|
||||
**总代码量**: 1567行
|
||||
**核心功能**: 资产分类、生命周期、元数据管理
|
||||
|
||||
#### 3.2.1 gnacs.ch - GNACS编码系统
|
||||
|
||||
**文件大小**: 300行
|
||||
**核心功能**: 全球新资产分类系统（Global New Asset Classification System）
|
||||
|
||||
**GNACS编码结构**:
|
||||
```
|
||||
48位编码 = 8个层级 × 6位
|
||||
1.1.1.1.1.1.1.1
|
||||
│ │ │ │ │ │ │ └─ L8: 子类别
|
||||
│ │ │ │ │ │ └─── L7: 类别
|
||||
│ │ │ │ │ └───── L6: 组
|
||||
│ │ │ │ └─────── L5: 类
|
||||
│ │ │ └───────── L4: 门
|
||||
│ │ └─────────── L3: 界
|
||||
│ └───────────── L2: 域
|
||||
└─────────────── L1: 超域
|
||||
```
|
||||
|
||||
**功能**:
|
||||
- GNACS编码验证
|
||||
- 编码解析
|
||||
- 层级查询
|
||||
- 编码转换
|
||||
|
||||
#### 3.2.2 lifecycle.ch - 资产生命周期管理
|
||||
|
||||
**文件大小**: 711行
|
||||
**核心功能**: 管理资产从创建到销毁的完整生命周期
|
||||
|
||||
**生命周期阶段**:
|
||||
1. **创建** (Creation)
|
||||
2. **激活** (Activation)
|
||||
3. **流通** (Circulation)
|
||||
4. **冻结** (Frozen)
|
||||
5. **暂停** (Suspended)
|
||||
6. **退出** (Exit)
|
||||
7. **销毁** (Destroyed)
|
||||
|
||||
#### 3.2.3 metadata.ch - 资产元数据管理
|
||||
|
||||
**文件大小**: 556行
|
||||
**核心功能**: 资产元数据的存储和管理
|
||||
|
||||
**元数据字段**:
|
||||
- 基础信息（名称、描述、图片）
|
||||
- 属性（键值对）
|
||||
- 文件（IPFS/Arweave链接）
|
||||
- 版本控制
|
||||
|
||||
---
|
||||
|
||||
### 3.3 DeFi功能（defi/）
|
||||
|
||||
**总代码量**: 2501行
|
||||
**核心功能**: 去中心化金融协议
|
||||
|
||||
#### 3.3.1 lending.ch - 借贷协议
|
||||
|
||||
**文件大小**: 819行
|
||||
**核心功能**: 资产抵押借贷
|
||||
|
||||
**功能**:
|
||||
- 存款/取款
|
||||
- 借款/还款
|
||||
- 利率计算
|
||||
- 清算机制
|
||||
- 健康因子
|
||||
|
||||
#### 3.3.2 liquidity.ch - 流动性池
|
||||
|
||||
**文件大小**: 807行
|
||||
**核心功能**: AMM流动性池
|
||||
|
||||
**功能**:
|
||||
- 添加/移除流动性
|
||||
- 交换（Swap）
|
||||
- LP代币
|
||||
- 手续费分配
|
||||
- 价格预言机
|
||||
|
||||
#### 3.3.3 marketplace.ch - 资产交易市场
|
||||
|
||||
**文件大小**: 875行
|
||||
**核心功能**: RWA资产交易市场
|
||||
|
||||
**功能**:
|
||||
- 挂单/撤单
|
||||
- 购买/出售
|
||||
- 竞价
|
||||
- 拍卖
|
||||
- 托管
|
||||
|
||||
---
|
||||
|
||||
### 3.4 治理（governance/）
|
||||
|
||||
**总代码量**: 1503行
|
||||
**核心功能**: DAO治理系统
|
||||
|
||||
#### 3.4.1 proposal.ch - 提案系统
|
||||
|
||||
**文件大小**: 703行
|
||||
**核心功能**: 提案创建和管理
|
||||
|
||||
**提案类型**:
|
||||
- 参数修改
|
||||
- 资金支出
|
||||
- 合约升级
|
||||
- 成员管理
|
||||
|
||||
#### 3.4.2 voting.ch - 投票系统
|
||||
|
||||
**文件大小**: 800行
|
||||
**核心功能**: 投票机制
|
||||
|
||||
**投票方式**:
|
||||
- 简单多数
|
||||
- 绝对多数
|
||||
- 加权投票
|
||||
- 二次方投票
|
||||
|
||||
---
|
||||
|
||||
### 3.5 主权合规（sovereignty/）
|
||||
|
||||
**总代码量**: 2194行
|
||||
**核心功能**: 主权类型和合规验证
|
||||
|
||||
#### 3.5.1 compliance.ch - 合规验证
|
||||
|
||||
**文件大小**: 837行
|
||||
**核心功能**: 七层合规验证框架
|
||||
|
||||
**验证层级**:
|
||||
1. KYC/AML验证
|
||||
2. 资产真实性验证
|
||||
3. 法律合规验证
|
||||
4. 财务合规验证
|
||||
5. 技术合规验证
|
||||
6. 运营合规验证
|
||||
7. 宪政合规验证
|
||||
|
||||
#### 3.5.2 registry.ch - 主权注册表
|
||||
|
||||
**文件大小**: 765行
|
||||
**核心功能**: 主权实体注册和管理
|
||||
|
||||
**注册类型**:
|
||||
- 个人（A0）
|
||||
- 企业（C0-C2）
|
||||
- 政府（D0-D2）
|
||||
|
||||
#### 3.5.3 rules.ch - 主权规则
|
||||
|
||||
**文件大小**: 592行
|
||||
**核心功能**: 主权类型规则定义
|
||||
|
||||
**主权类型**:
|
||||
```charter
|
||||
enum SovereigntyType {
|
||||
A0, // 个人主权
|
||||
C0, // 企业主权（一般）
|
||||
C1, // 企业主权（上市公司）
|
||||
C2, // 企业主权（国有企业）
|
||||
D0, // 政府主权（地方）
|
||||
D1, // 政府主权（省级）
|
||||
D2, // 政府主权（国家）
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.6 工具函数（utils/）
|
||||
|
||||
**总代码量**: 954行
|
||||
**核心功能**: 通用工具函数
|
||||
|
||||
#### 3.6.1 crypto.ch - 加密工具
|
||||
|
||||
**文件大小**: 380行
|
||||
**功能**:
|
||||
- SHA256/SHA3哈希
|
||||
- ECDSA签名验证
|
||||
- Merkle树
|
||||
- 随机数生成
|
||||
|
||||
#### 3.6.2 math.ch - 数学库
|
||||
|
||||
**文件大小**: 476行
|
||||
**功能**:
|
||||
- 安全算术（防溢出）
|
||||
- 百分比计算
|
||||
- 幂运算
|
||||
- 平方根
|
||||
- 最大公约数/最小公倍数
|
||||
|
||||
#### 3.6.3 time.ch - 时间处理
|
||||
|
||||
**文件大小**: 98行
|
||||
**功能**:
|
||||
- 时间戳转换
|
||||
- 日期计算
|
||||
- 时间间隔
|
||||
|
||||
---
|
||||
|
||||
## 四、使用示例
|
||||
|
||||
### 创建ACC-20代币
|
||||
|
||||
```charter
|
||||
use charter_std::acc::acc20::ACC20Token;
|
||||
|
||||
contract MyToken {
|
||||
let token: ACC20Token;
|
||||
|
||||
constructor() {
|
||||
self.token = ACC20Token::new(
|
||||
"My Token",
|
||||
"MTK",
|
||||
18,
|
||||
0x010101010101, // GNACS编码
|
||||
1000000 * 10**18 // 初始供应量
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 使用借贷协议
|
||||
|
||||
```charter
|
||||
use charter_std::defi::lending::LendingPool;
|
||||
|
||||
contract MyLending {
|
||||
let pool: LendingPool;
|
||||
|
||||
fn deposit(amount: u256) {
|
||||
self.pool.deposit(msg.sender, amount);
|
||||
}
|
||||
|
||||
fn borrow(amount: u256) {
|
||||
self.pool.borrow(msg.sender, amount);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、依赖关系
|
||||
|
||||
### 内部依赖
|
||||
- `asset::gnacs` ← 被acc、sovereignty使用
|
||||
- `sovereignty::rules` ← 被acc、asset使用
|
||||
- `utils::math` ← 被defi使用
|
||||
- `utils::crypto` ← 被governance使用
|
||||
|
||||
### 外部依赖
|
||||
- **nac-udm**: 提供基础类型定义
|
||||
- **charter-compiler**: 编译标准库代码
|
||||
|
||||
---
|
||||
|
||||
## 六、优缺点分析
|
||||
|
||||
### 优点
|
||||
1. ✅ 功能完整，覆盖ACC协议、DeFi、治理、合规等
|
||||
2. ✅ 代码量大（11,364行），实现详细
|
||||
3. ✅ 模块化设计，易于导入使用
|
||||
4. ✅ RWA特色功能（GNACS、主权类型、合规）
|
||||
5. ✅ 文档注释完善（Charter文档注释）
|
||||
6. ✅ 支持契约式编程（requires/ensures）
|
||||
|
||||
### 缺点
|
||||
1. ⚠️ README文档不完整（"待补充"）
|
||||
2. ⚠️ 缺少使用示例和教程
|
||||
3. ⚠️ 缺少单元测试
|
||||
4. ⚠️ 缺少版本管理（没有Cargo.toml）
|
||||
5. ⚠️ 缺少标准库文档网站
|
||||
|
||||
---
|
||||
|
||||
## 七、待完成工作
|
||||
|
||||
1. ⏳ 完善README文档
|
||||
2. ⏳ 添加完整的使用示例
|
||||
3. ⏳ 编写单元测试（使用Charter测试框架）
|
||||
4. ⏳ 创建标准库文档网站
|
||||
5. ⏳ 添加版本管理
|
||||
6. ⏳ 创建标准库包管理器
|
||||
7. ⏳ 添加更多DeFi协议（Staking、Options等）
|
||||
8. ⏳ 添加跨链桥接标准
|
||||
|
||||
---
|
||||
|
||||
## 八、与其他模块的关系
|
||||
|
||||
### 上游依赖
|
||||
- **nac-udm**: 提供类型系统
|
||||
- **charter-compiler**: 编译标准库
|
||||
|
||||
### 下游使用
|
||||
- **所有Charter智能合约**: 导入使用标准库
|
||||
- **nac-contract-deployer**: 部署使用标准库的合约
|
||||
|
||||
### 编译方式
|
||||
标准库文件在编译时被charter-compiler链接到用户合约中，类似于Rust的std库。
|
||||
|
||||
---
|
||||
|
||||
## 九、总结
|
||||
|
||||
charter-std是一个功能丰富、设计完善的智能合约标准库。它提供了11,364行高质量的Charter代码，涵盖ACC协议、资产管理、DeFi、治理、合规等NAC公链开发的核心功能。
|
||||
|
||||
标准库的设计充分体现了NAC公链的RWA特色，包括GNACS编码、主权类型、七层合规验证等独特功能。代码质量高，文档注释完善，模块化设计使其易于使用和扩展。
|
||||
|
||||
主要不足在于缺少README文档、使用示例和测试。建议优先完善文档和示例，然后添加测试框架和标准库文档网站。
|
||||
|
||||
**完成度**: 80%
|
||||
**生产就绪**: ⚠️ 需要补充文档和测试
|
||||
**建议**: 补充文档和测试后可用于生产环境
|
||||
|
||||
---
|
||||
|
||||
**分析完成时间**: 2026-02-18 23:30
|
||||
**下一个模块**: nac-udm（统一定义模块）
|
||||
Loading…
Reference in New Issue