From ec3f90ce8e267e9c05f67ef7acba1760c16e9b2d Mon Sep 17 00:00:00 2001 From: NAC Development Team Date: Tue, 17 Feb 2026 21:45:01 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90charter-std-zh?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E6=B7=B1=E5=BA=A6=E5=88=86=E6=9E=90=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=EF=BC=88384=E8=A1=8C=EF=BC=8C5%=E5=AE=8C=E6=88=90?= =?UTF-8?q?=EF=BC=8C=E4=BB=85ACC-20=E4=B8=AD=E6=96=87=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/modules/charter-std-zh分析报告.md | 887 +++++++++++++++++++++ 1 file changed, 887 insertions(+) create mode 100644 docs/modules/charter-std-zh分析报告.md diff --git a/docs/modules/charter-std-zh分析报告.md b/docs/modules/charter-std-zh分析报告.md new file mode 100644 index 0000000..766bb8a --- /dev/null +++ b/docs/modules/charter-std-zh分析报告.md @@ -0,0 +1,887 @@ +# charter-std-zh 模块深度分析报告 + +**模块名称**: charter-std-zh +**版本**: v1.0 +**分析日期**: 2026-02-18 +**分析人员**: NAC开发团队 + +--- + +## 📋 模块概览 + +**功能定位**: Charter语言中文标准库 - 提供Charter智能合约的中文API +**英文全称**: Charter Standard Library (Chinese) +**代码行数**: 384行（仅1个文件） +**完成度**: 5% +**测试覆盖**: 0% (无测试) +**编译状态**: ⚠️ 未测试（无编译器） + +--- + +## 🏗️ 架构设计 + +### 核心功能 + +charter-std-zh是Charter语言的中文标准库，目前只包含一个模块： + +1. **ACC-20**: 可替代资产协议（Asset Certificate Contract - 20） + +### 设计目标 + +1. **中文编程**: 使用中文关键字和函数名 +2. **RWA专用**: 专为实物资产（Real World Asset）设计 +3. **GNACS集成**: 集成GNACS资产分类编码 +4. **主权支持**: 支持资产主权类型 + +### 目录结构 + +``` +charter-std-zh/ +├── README.md +├── acc/ +│ └── acc20.ch (384行) - ACC-20协议实现 +├── asset/ (空) +├── defi/ (空) +├── governance/ (空) +├── sovereignty/ (空) +└── utils/ (空) +``` + +**问题**: 除了acc20.ch外，其他目录都是空的 + +--- + +## 🔍 核心功能详解 + +### 1. ACC-20接口定义 + +#### 1.1 接口概述 + +```charter +接口 ACC20 { + // 查询函数 + 函数 总供应量() -> u256; + 函数 持有量(持有者: 地址) -> u256; + 函数 名称() -> 字符串; + 函数 符号() -> 字符串; + 函数 小数位() -> u8; + 函数 GNACS编码() -> GNACS编码; + 函数 主权类型() -> 主权类型; + 函数 授权额度(持有者: 地址, 代理人: 地址) -> u256; + + // 交易函数 + 函数 转移(接收者: 地址, 数额: u256) -> bool; + 函数 授权(代理人: 地址, 数额: u256) -> bool; + 函数 代理转移(发送者: 地址, 接收者: 地址, 数额: u256) -> bool; + 函数 增发(接收者: 地址, 数额: u256) -> bool; + 函数 销毁(数额: u256) -> bool; +} +``` + +**对比ERC-20**: + +| 功能 | ERC-20 | ACC-20 | 说明 | +|------|--------|--------|------| +| 总供应量 | totalSupply | 总供应量 | ✅ 相同 | +| 余额查询 | balanceOf | 持有量 | ✅ 相同 | +| 转账 | transfer | 转移 | ✅ 相同 | +| 授权 | approve | 授权 | ✅ 相同 | +| 授权额度 | allowance | 授权额度 | ✅ 相同 | +| 代理转账 | transferFrom | 代理转移 | ✅ 相同 | +| 名称 | name | 名称 | ✅ 相同 | +| 符号 | symbol | 符号 | ✅ 相同 | +| 小数位 | decimals | 小数位 | ✅ 相同 | +| GNACS编码 | - | GNACS编码 | ✨ 新增 | +| 主权类型 | - | 主权类型 | ✨ 新增 | +| 增发 | - | 增发 | ✨ 新增 | +| 销毁 | - | 销毁 | ✨ 新增 | + +**创新点**: +1. **GNACS编码**: 48位资产分类编码 +2. **主权类型**: 资产主权属性 +3. **增发/销毁**: 内置铸造和销毁功能 + +--- + +#### 1.2 查询函数 + +##### 基础查询 + +```charter +函数 总供应量() -> u256; +函数 持有量(持有者: 地址) -> u256; +函数 名称() -> 字符串; +函数 符号() -> 字符串; +函数 小数位() -> u8; +``` + +**说明**: 与ERC-20完全相同 + +--- + +##### RWA专用查询 + +```charter +函数 GNACS编码() -> GNACS编码; +函数 主权类型() -> 主权类型; +``` + +**GNACS编码**: 全球NAC资产分类系统 +- 48位二进制编码 +- 标识资产类型、地区、行业 + +**主权类型**: 资产主权属性 +- 完全主权 +- 部分主权 +- 共享主权 +- 无主权 + +--- + +##### 授权查询 + +```charter +函数 授权额度(持有者: 地址, 代理人: 地址) -> u256; +``` + +**说明**: 查询持有者授权给代理人的额度 + +--- + +#### 1.3 交易函数 + +##### 转移 + +```charter +函数 转移(接收者: 地址, 数额: u256) -> bool; +``` + +**功能**: 将资产从调用者转移到接收者 + +**事件**: `转移事件(发送者, 接收者, 数额)` + +--- + +##### 授权 + +```charter +函数 授权(代理人: 地址, 数额: u256) -> bool; +``` + +**功能**: 授权代理人使用一定数额的资产 + +**事件**: `授权事件(持有者, 代理人, 数额)` + +--- + +##### 代理转移 + +```charter +函数 代理转移(发送者: 地址, 接收者: 地址, 数额: u256) -> bool; +``` + +**功能**: 代理人代表持有者转移资产 + +**事件**: `转移事件(发送者, 接收者, 数额)` + +--- + +##### 增发 + +```charter +函数 增发(接收者: 地址, 数额: u256) -> bool; +``` + +**功能**: 增发新的资产（仅发行者） + +**权限**: 仅发行者 + +**事件**: +- `增发事件(接收者, 数额)` +- `转移事件(零地址, 接收者, 数额)` + +--- + +##### 销毁 + +```charter +函数 销毁(数额: u256) -> bool; +``` + +**功能**: 销毁调用者的资产 + +**事件**: +- `销毁事件(持有者, 数额)` +- `转移事件(持有者, 零地址, 数额)` + +--- + +### 2. ACC-20事件定义 + +#### 2.1 转移事件 + +```charter +事件 转移事件 { + 发送者: 地址, + 接收者: 地址, + 数额: u256, +} +``` + +**触发时机**: +- 转移 +- 代理转移 +- 增发（发送者为零地址） +- 销毁（接收者为零地址） + +--- + +#### 2.2 授权事件 + +```charter +事件 授权事件 { + 持有者: 地址, + 代理人: 地址, + 数额: u256, +} +``` + +**触发时机**: 授权 + +--- + +#### 2.3 增发事件 + +```charter +事件 增发事件 { + 接收者: 地址, + 数额: u256, +} +``` + +**触发时机**: 增发 + +--- + +#### 2.4 销毁事件 + +```charter +事件 销毁事件 { + 持有者: 地址, + 数额: u256, +} +``` + +**触发时机**: 销毁 + +--- + +### 3. ACC-20基础实现 + +#### 3.1 状态变量 + +```charter +私有 _名称: 字符串; +私有 _符号: 字符串; +私有 _小数位: u8; +私有 _gnacs编码: GNACS编码; +私有 _主权类型: 主权类型; +私有 _总供应量: u256; +私有 _持有量: 映射<地址, u256>; +私有 _授权: 映射<地址, 映射<地址, u256>>; +私有 _发行者: 地址; +``` + +**存储结构**: +- 基础信息: 名称、符号、小数位 +- RWA信息: GNACS编码、主权类型 +- 供应量: 总供应量 +- 持有量: 地址 → 余额 +- 授权: 持有者 → 代理人 → 额度 +- 发行者: 发行者地址 + +--- + +#### 3.2 构造函数 + +```charter +构造函数( + 名称: 字符串, + 符号: 字符串, + 小数位: u8, + gnacs编码: GNACS编码, + 主权类型: 主权类型, + 初始供应量: u256 +) { + _名称 = 名称; + _符号 = 符号; + _小数位 = 小数位; + _gnacs编码 = gnacs编码; + _主权类型 = 主权类型; + _发行者 = 消息.发送者; + + 如果 初始供应量 > 0 { + _总供应量 = 初始供应量; + _持有量[消息.发送者] = 初始供应量; + 触发 转移事件 { + 发送者: 地址::零地址(), + 接收者: 消息.发送者, + 数额: 初始供应量, + }; + } +} +``` + +**功能**: +1. 初始化基础信息 +2. 设置发行者为部署者 +3. 如果初始供应量>0，铸造给部署者 + +--- + +#### 3.3 转移实现 + +```charter +函数 转移(接收者: 地址, 数额: u256) -> bool { + 要求(接收者 != 地址::零地址(), "ACC20: 不能转移到零地址"); + 要求(_持有量[消息.发送者] >= 数额, "ACC20: 余额不足"); + + _持有量[消息.发送者] -= 数额; + _持有量[接收者] += 数额; + + 触发 转移事件 { + 发送者: 消息.发送者, + 接收者: 接收者, + 数额: 数额, + }; + + 返回 真; +} +``` + +**验证**: +1. 接收者不能是零地址 +2. 发送者余额充足 + +**操作**: +1. 扣除发送者余额 +2. 增加接收者余额 +3. 触发转移事件 + +--- + +#### 3.4 代理转移实现 + +```charter +函数 代理转移(发送者: 地址, 接收者: 地址, 数额: u256) -> bool { + 要求(接收者 != 地址::零地址(), "ACC20: 不能转移到零地址"); + 要求(_持有量[发送者] >= 数额, "ACC20: 余额不足"); + 要求(_授权[发送者][消息.发送者] >= 数额, "ACC20: 授权额度不足"); + + _持有量[发送者] -= 数额; + _持有量[接收者] += 数额; + _授权[发送者][消息.发送者] -= 数额; + + 触发 转移事件 { + 发送者: 发送者, + 接收者: 接收者, + 数额: 数额, + }; + + 返回 真; +} +``` + +**验证**: +1. 接收者不能是零地址 +2. 发送者余额充足 +3. 代理人授权额度充足 + +**操作**: +1. 扣除发送者余额 +2. 增加接收者余额 +3. 扣除授权额度 +4. 触发转移事件 + +--- + +#### 3.5 增发实现 + +```charter +函数 增发(接收者: 地址, 数额: u256) -> bool { + 要求(消息.发送者 == _发行者, "ACC20: 仅发行者可以增发"); + 要求(接收者 != 地址::零地址(), "ACC20: 不能增发到零地址"); + + _总供应量 += 数额; + _持有量[接收者] += 数额; + + 触发 增发事件 { + 接收者: 接收者, + 数额: 数额, + }; + + 触发 转移事件 { + 发送者: 地址::零地址(), + 接收者: 接收者, + 数额: 数额, + }; + + 返回 真; +} +``` + +**验证**: +1. 调用者是发行者 +2. 接收者不能是零地址 + +**操作**: +1. 增加总供应量 +2. 增加接收者余额 +3. 触发增发事件和转移事件 + +--- + +#### 3.6 销毁实现 + +```charter +函数 销毁(数额: u256) -> bool { + 要求(_持有量[消息.发送者] >= 数额, "ACC20: 余额不足"); + + _持有量[消息.发送者] -= 数额; + _总供应量 -= 数额; + + 触发 销毁事件 { + 持有者: 消息.发送者, + 数额: 数额, + }; + + 触发 转移事件 { + 发送者: 消息.发送者, + 接收者: 地址::零地址(), + 数额: 数额, + }; + + 返回 真; +} +``` + +**验证**: 调用者余额充足 + +**操作**: +1. 扣除调用者余额 +2. 减少总供应量 +3. 触发销毁事件和转移事件 + +--- + +## 🐛 发现的问题 + +### 问题1: 标准库几乎为空 + +**严重程度**: ⚠️ 极高 + +**描述**: 除了ACC-20外，其他目录都是空的 + +**缺失模块**: +- asset/ - 资产管理 +- defi/ - DeFi协议 +- governance/ - 治理模块 +- sovereignty/ - 主权模块 +- utils/ - 工具函数 + +**建议**: 添加完整的标准库 +``` +charter-std-zh/ +├── acc/ +│ ├── acc20.ch (已有) +│ ├── acc721.ch (NFT协议) +│ └── acc1400.ch (证券型资产) +├── asset/ +│ ├── gnacs.ch (GNACS编码) +│ ├── valuation.ch (估值) +│ └── metadata.ch (元数据) +├── defi/ +│ ├── swap.ch (交换) +│ ├── lending.ch (借贷) +│ └── staking.ch (质押) +├── governance/ +│ ├── voting.ch (投票) +│ ├── proposal.ch (提案) +│ └── timelock.ch (时间锁) +├── sovereignty/ +│ ├── types.ch (主权类型) +│ ├── rules.ch (主权规则) +│ └── transfer.ch (主权转移) +└── utils/ + ├── math.ch (数学) + ├── string.ch (字符串) + └── address.ch (地址) +``` + +**状态**: ❌ 待实现 + +--- + +### 问题2: 缺少编译器支持 + +**严重程度**: ⚠️ 极高 + +**描述**: Charter编译器不支持中文语法 + +**影响**: 无法编译和测试 + +**建议**: 扩展charter-compiler +```rust +// charter-compiler/src/parser.rs +pub enum Keyword { + // 英文关键字 + Contract, + Function, + Event, + // 中文关键字 + 合约, + 函数, + 事件, +} +``` + +**状态**: ❌ 待实现 + +--- + +### 问题3: 缺少测试 + +**严重程度**: ⚠️ 高 + +**描述**: 没有任何测试 + +**建议**: 添加测试 +```charter +// tests/acc20_test.ch +测试 ACC20基础功能 { + // 部署合约 + 让 合约 = 部署 ACC20基础( + 名称: "测试资产", + 符号: "TEST", + 小数位: 18, + gnacs编码: GNACS::新建(0x123456), + 主权类型: 主权类型::完全主权, + 初始供应量: 1000000 + ); + + // 测试总供应量 + 断言(合约.总供应量() == 1000000); + + // 测试转移 + 合约.转移(地址::新建("0x..."), 100); + 断言(合约.持有量(地址::新建("0x...")) == 100); +} +``` + +**状态**: ❌ 待添加 + +--- + +### 问题4: 缺少文档 + +**严重程度**: ⚠️ 中等 + +**描述**: README几乎为空 + +**建议**: 添加完整文档 +```markdown +# charter-std-zh + +Charter语言中文标准库 + +## 模块 + +### ACC-20 - 可替代资产协议 + +ACC-20是NAC公链的可替代资产协议，类似于以太坊的ERC-20，但专为RWA设计。 + +#### 特性 + +- ✅ 兼容ERC-20 +- ✨ GNACS资产分类编码 +- ✨ 主权类型支持 +- ✨ 内置增发/销毁 + +#### 使用示例 + +\`\`\`charter +使用 acc::acc20::ACC20基础; + +合约 我的资产 继承 ACC20基础 { + 构造函数() { + 父::构造函数( + 名称: "我的资产", + 符号: "MYA", + 小数位: 18, + gnacs编码: GNACS::新建(0x123456), + 主权类型: 主权类型::完全主权, + 初始供应量: 1000000 + ); + } +} +\`\`\` +``` + +**状态**: ❌ 待添加 + +--- + +### 问题5: 缺少示例 + +**严重程度**: ⚠️ 中等 + +**描述**: 没有示例代码 + +**建议**: 添加examples目录 +``` +charter-std-zh/ +├── examples/ +│ ├── basic_token.ch (基础代币) +│ ├── real_estate.ch (房产代币) +│ ├── art_token.ch (艺术品代币) +│ └── security_token.ch (证券型代币) +``` + +**状态**: ❌ 待添加 + +--- + +### 问题6: 中文关键字不一致 + +**严重程度**: ⚠️ 低 + +**描述**: 中文关键字的选择可能不够直观 + +**建议**: 统一关键字 +```charter +// 当前 +接口 ACC20 { ... } +合约 ACC20基础 实现 ACC20 { ... } +函数 转移(...) -> bool { ... } + +// 建议 +接口 ACC20 { ... } +合约 ACC20基础 实现 ACC20 { ... } +函数 转移(...) -> 布尔 { ... } // bool → 布尔 +``` + +**状态**: ⏳ 待讨论 + +--- + +## 📊 完成度评估 + +| 功能模块 | 代码行数 | 完成度 | 状态 | +|---------|---------|--------|------| +| ACC-20协议 | 384行 | 90% | ✅ 基本完成 | +| ACC-721协议 | 0行 | 0% | ❌ 未实现 | +| ACC-1400协议 | 0行 | 0% | ❌ 未实现 | +| 资产管理 | 0行 | 0% | ❌ 未实现 | +| DeFi协议 | 0行 | 0% | ❌ 未实现 | +| 治理模块 | 0行 | 0% | ❌ 未实现 | +| 主权模块 | 0行 | 0% | ❌ 未实现 | +| 工具函数 | 0行 | 0% | ❌ 未实现 | +| 测试覆盖 | 0行 | 0% | ❌ 无测试 | +| **总计** | **384行** | **5%** | **🚧 刚起步** | + +### 待完善功能 + +1. **高优先级**: + - ❌ 添加编译器支持 + - ❌ 实现ACC-721（NFT） + - ❌ 实现ACC-1400（证券） + - ❌ 添加测试 + +2. **中优先级**: + - ❌ 实现资产管理模块 + - ❌ 实现DeFi协议 + - ❌ 实现治理模块 + - ❌ 添加文档和示例 + +3. **低优先级**: + - ⏳ 实现主权模块 + - ⏳ 实现工具函数 + - ⏳ 统一中文关键字 + +--- + +## 🌟 设计亮点 + +1. **中文编程** + - 使用中文关键字 + - 降低学习门槛 + +2. **RWA专用** + - GNACS编码 + - 主权类型 + +3. **兼容ERC-20** + - 保留ERC-20核心功能 + - 易于迁移 + +4. **内置增发/销毁** + - 简化资产管理 + - 适合RWA场景 + +--- + +## 🔗 模块依赖关系 + +``` +charter-std-zh +├── 依赖 +│ ├── 资产::gnacs::GNACS编码 +│ └── 主权::规则::主权类型 +├── 被依赖 +│ └── 所有使用ACC-20的合约 +└── 协作模块 + ├── charter-std (英文版) + └── charter-compiler (编译器) +``` + +--- + +## 📝 开发建议 + +### 短期目标 (1周) + +1. **添加编译器支持** (优先级P1) + - 扩展词法分析器 + - 支持中文关键字 + - 测试编译 + +2. **实现ACC-721** (优先级P1) + - NFT协议 + - 元数据支持 + - 枚举功能 + +3. **添加测试** (优先级P1) + - ACC-20测试 + - 集成测试 + - 边界测试 + +### 中期目标 (2周) + +4. **实现ACC-1400** (优先级P2) + - 证券型资产 + - 分区管理 + - 合规检查 + +5. **实现资产管理模块** (优先级P2) + - GNACS编码 + - 估值系统 + - 元数据管理 + +6. **添加文档和示例** (优先级P2) + - 完善README + - 添加示例代码 + - API文档 + +### 长期目标 (1个月) + +7. **实现DeFi协议** (优先级P3) + - 交换协议 + - 借贷协议 + - 质押协议 + +8. **实现治理模块** (优先级P3) + - 投票系统 + - 提案系统 + - 时间锁 + +9. **实现主权模块** (优先级P4) + - 主权类型定义 + - 主权规则 + - 主权转移 + +--- + +## 💡 使用示例 + +### 示例1: 基础代币 + +```charter +使用 acc::acc20::ACC20基础; + +合约 基础代币 继承 ACC20基础 { + 构造函数() { + 父::构造函数( + 名称: "基础代币", + 符号: "BASIC", + 小数位: 18, + gnacs编码: GNACS::新建(0x000000000001), + 主权类型: 主权类型::完全主权, + 初始供应量: 1000000 * 10**18 + ); + } +} +``` + +--- + +### 示例2: 房产代币 + +```charter +使用 acc::acc20::ACC20基础; + +合约 房产代币 继承 ACC20基础 { + 构造函数() { + 父::构造函数( + 名称: "北京朝阳区房产A", + 符号: "BJ-CY-A", + 小数位: 0, // 不可分割 + gnacs编码: GNACS::新建(0x010203040506), // 房产类GNACS编码 + 主权类型: 主权类型::完全主权, + 初始供应量: 100 // 100份 + ); + } +} +``` + +--- + +### 示例3: 艺术品代币 + +```charter +使用 acc::acc20::ACC20基础; + +合约 艺术品代币 继承 ACC20基础 { + 构造函数() { + 父::构造函数( + 名称: "梵高《向日葵》", + 符号: "VG-SF", + 小数位: 18, + gnacs编码: GNACS::新建(0x020304050607), // 艺术品类GNACS编码 + 主权类型: 主权类型::部分主权, // 艺术品可能有版权限制 + 初始供应量: 1000000 * 10**18 + ); + } +} +``` + +--- + +## 🔄 与charter-std的关系 + +charter-std-zh是charter-std的中文版本，两者功能完全相同，只是语言不同。 + +**对比**: + +| 特性 | charter-std | charter-std-zh | +|------|-------------|----------------| +| 语言 | 英文 | 中文 | +| 功能 | 完整 | 仅ACC-20 | +| 完成度 | 90% | 5% | +| 目标用户 | 国际开发者 | 中文开发者 | + +**建议**: 保持两者同步更新 + +--- + +**分析完成时间**: 2026-02-18 +**下一步**: 添加编译器支持并实现ACC-721协议