# Charter标准库（中文版）

**版本**: v1.0.0  
**语言**: 简体中文  
**对应英文版**: charter-std v1.0.0

---

## 📚 简介

Charter标准库（中文版）是NAC原生智能合约语言Charter的中文标准库，提供了完整的中文关键字和API接口，让中文开发者能够使用母语进行区块链智能合约开发。

**设计原则**：
- ✅ **原生中文** - 不是翻译，而是原生中文实现
- ✅ **功能完整** - 与英文版功能完全一致
- ✅ **语义清晰** - 中文命名更符合中文思维习惯
- ✅ **易于学习** - 降低中文开发者的学习门槛

---

## 📦 模块结构

```
charter-std-zh/
├── acc/              # 资产凭证合约（Asset Certificate Contract）
│   ├── acc20.ch      # ACC-20可替代资产协议
│   ├── acc721.ch     # ACC-721非同质化资产协议
│   ├── acc1155.ch    # ACC-1155多资产协议
│   └── acc20c.ch     # ACC-20C跨链资产协议
├── asset/            # 资产管理模块
│   ├── gnacs.ch      # GNACS资产分类系统
│   ├── lifecycle.ch  # 资产生命周期管理
│   └── metadata.ch   # 资产元数据管理
├── defi/             # 去中心化金融模块
│   ├── lending.ch    # 借贷协议
│   ├── liquidity.ch  # 流动性协议
│   └── marketplace.ch# 市场协议
├── governance/       # 治理模块
│   ├── proposal.ch   # 提案系统
│   └── voting.ch     # 投票系统
├── sovereignty/      # 主权管理模块
│   ├── compliance.ch # 合规管理
│   ├── registry.ch   # 注册管理
│   └── rules.ch      # 规则引擎
└── utils/            # 工具模块
    ├── crypto.ch     # 密码学工具
    └── math.ch       # 数学工具
```

---

## 🔤 中英文关键字对照表

### 基本关键字

| 中文 | 英文 | 说明 |
|------|------|------|
| 合约 | contract | 智能合约 |
| 接口 | interface | 接口定义 |
| 函数 | function | 函数 |
| 构造函数 | constructor | 构造函数 |
| 事件 | event | 事件 |
| 修饰符 | modifier | 修饰符 |
| 使用 | use | 导入模块 |
| 实现 | implements | 实现接口 |
| 继承 | extends | 继承合约 |

### 访问控制

| 中文 | 英文 | 说明 |
|------|------|------|
| 公开 | public | 公开访问 |
| 私有 | private | 私有访问 |
| 内部 | internal | 内部访问 |
| 外部 | external | 外部访问 |

### 数据类型

| 中文 | 英文 | 说明 |
|------|------|------|
| 地址 | Address | 地址类型 |
| 字符串 | String | 字符串类型 |
| 布尔 | bool | 布尔类型 |
| 映射 | mapping | 映射类型 |
| 数组 | array | 数组类型 |

### 控制流

| 中文 | 英文 | 说明 |
|------|------|------|
| 如果 | if | 条件判断 |
| 否则 | else | 否则分支 |
| 循环 | for | 循环 |
| 当 | while | 当型循环 |
| 返回 | return | 返回值 |
| 中断 | break | 中断循环 |
| 继续 | continue | 继续循环 |

### 特殊关键字

| 中文 | 英文 | 说明 |
|------|------|------|
| 要求 | require | 条件检查 |
| 断言 | assert | 断言检查 |
| 回退 | revert | 回退交易 |
| 触发 | emit | 触发事件 |
| 消息 | msg | 消息对象 |
| 区块 | block | 区块对象 |
| 交易 | tx | 交易对象 |

### 常量

| 中文 | 英文 | 说明 |
|------|------|------|
| 真 | true | 真值 |
| 假 | false | 假值 |
| 空 | null | 空值 |

---

## 📖 使用示例

### 1. 创建ACC-20代币合约

```charter
使用 acc::acc20::ACC20基础;
使用 资产::gnacs::GNACS编码;
使用 主权::规则::主权类型;

/// 我的代币合约
合约 我的代币 继承 ACC20基础 {
    构造函数() 
        ACC20基础(
            "我的代币",           // 名称
            "MTK",               // 符号
            18,                  // 小数位
            GNACS编码::从字符串("940100..."),  // GNACS编码
            主权类型::完全主权,   // 主权类型
            1000000 * 10**18     // 初始供应量
        ) 
    {
        // 构造函数逻辑
    }
    
    /// 批量转账
    公开 函数 批量转账(接收者列表: 数组<地址>, 数额列表: 数组<u256>) -> bool {
        要求(接收者列表.长度() == 数额列表.长度(), "长度不匹配");
        
        循环 i 在 0..接收者列表.长度() {
            转移(接收者列表[i], 数额列表[i]);
        }
        
        返回 真;
    }
}
```

### 2. 使用GNACS资产分类

```charter
使用 资产::gnacs::{GNACS编码, 资产大类, 资产中类};

/// 房地产资产合约
合约 房地产资产 {
    私有 _gnacs编码: GNACS编码;
    
    构造函数(房产编号: 字符串) {
        // 940100... 表示房地产资产
        _gnacs编码 = GNACS编码::新建(
            资产大类::不动产,
            资产中类::住宅,
            房产编号
        );
    }
    
    公开 函数 获取资产分类() -> 字符串 {
        返回 _gnacs编码.转为字符串();
    }
}
```

### 3. 实现治理投票

```charter
使用 治理::投票::{投票合约, 提案状态};
使用 治理::提案::提案;

/// 社区治理合约
合约 社区治理 实现 投票合约 {
    私有 _提案列表: 映射<u256, 提案>;
    私有 _提案计数: u256;
    
    /// 创建提案
    公开 函数 创建提案(标题: 字符串, 描述: 字符串) -> u256 {
        _提案计数 += 1;
        
        _提案列表[_提案计数] = 提案::新建(
            _提案计数,
            标题,
            描述,
            消息.发送者
        );
        
        返回 _提案计数;
    }
    
    /// 投票
    公开 函数 投票(提案编号: u256, 支持: 布尔) {
        要求(_提案列表[提案编号].状态() == 提案状态::进行中, "提案未进行中");
        
        _提案列表[提案编号].投票(消息.发送者, 支持);
    }
}
```

---

## 🎯 与英文版的对应关系

每个中文标准库文件都对应一个英文版文件：

| 中文版 | 英文版 | 功能 |
|--------|--------|------|
| acc/acc20.ch | acc/acc20.ch | ACC-20协议 |
| acc/acc721.ch | acc/acc721.ch | ACC-721协议 |
| asset/gnacs.ch | asset/gnacs.ch | GNACS系统 |
| defi/lending.ch | defi/lending.ch | 借贷协议 |
| governance/voting.ch | governance/voting.ch | 投票系统 |
| sovereignty/compliance.ch | sovereignty/compliance.ch | 合规管理 |
| utils/crypto.ch | utils/crypto.ch | 密码学工具 |
| utils/math.ch | utils/math.ch | 数学工具 |

---

## 🔧 编译器集成

Charter编译器（charterc）会根据配置自动选择对应的标准库：

```toml
# charterc.toml
[compiler]
language = "zh-CN"  # 使用中文标准库
# language = "en-US"  # 使用英文标准库
```

编译器会自动：
1. 解析中文关键字
2. 加载中文标准库
3. 生成相同的NVM字节码

**重要**：中英文版本生成的字节码完全一致，可以互操作！

---

## 📚 文档

- [Charter语言规范（中文版）](../docs/CHARTER_LANGUAGE_SPECIFICATION_ZH.md)
- [ACC-20协议详解](./acc/ACC20_GUIDE.md)
- [GNACS使用指南](./asset/GNACS_GUIDE.md)
- [治理系统教程](./governance/GOVERNANCE_TUTORIAL.md)

---

## 🤝 贡献指南

欢迎贡献中文标准库！

### 贡献流程
1. Fork本仓库
2. 创建功能分支
3. 编写中文标准库代码
4. 确保与英文版功能一致
5. 提交Pull Request

### 命名规范
- 使用清晰的中文命名
- 保持与英文版的语义对应
- 遵循NAC原生规范

---

## 📄 许可证

MIT License

---

**Charter标准库（中文版） v1.0.0**  
**让中文开发者用母语编写区块链智能合约 🚀**