# 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协议