# Charter标准库 (Charter Standard Library)

**版本**: v1.0.0  
**代码量**: 9,949行  
**模块数**: 15个  
**状态**: ✅ 开发完成

---

## 📖 简介

Charter标准库是为NAC (NewAssetChain) RWA原生公链设计的完整标准库实现，提供了资产管理、主权控制、DeFi协议和治理系统等核心功能。

**核心特性**:
- ✅ **NAC合规**: 严格遵循NAC核心原则和术语规范
- ✅ **模块化设计**: 6大功能域，15个独立模块
- ✅ **RWA专用**: 完整的RWA资产管理功能
- ✅ **生产就绪**: 9,949行经过设计的代码

---

## 📊 模块概览

| 功能域 | 模块数 | 代码量 | 占比 |
|--------|--------|--------|------|
| 资产模块 (asset/) | 3 | 1,567行 | 15.8% |
| 主权模块 (sovereignty/) | 3 | 2,194行 | 22.1% |
| ACC协议 (acc/) | 2 | 1,328行 | 13.3% |
| 工具库 (utils/) | 2 | 856行 | 8.6% |
| DeFi模块 (defi/) | 3 | 2,501行 | 25.1% |
| 治理模块 (governance/) | 2 | 1,503行 | 15.1% |
| **总计** | **15** | **9,949行** | **100%** |

---

## 📁 目录结构

```
charter-std/
├── asset/                  # 资产基础模块 (1,567行)
│   ├── gnacs.ch           # GNACS编码系统 (300行)
│   ├── metadata.ch        # 元数据管理 (556行)
│   └── lifecycle.ch       # 生命周期管理 (711行)
│
├── sovereignty/            # 主权管理模块 (2,194行)
│   ├── rules.ch           # 主权规则 A0-G5 (592行)
│   ├── registry.ch        # 链上登记系统 (765行)
│   └── compliance.ch      # 合规检查 KYC/AML (837行)
│
├── acc/                    # ACC资产协议 (1,328行)
│   ├── acc20.ch           # ACC-20 可替代资产 (557行)
│   └── acc721.ch          # ACC-721 唯一资产 NFT (771行)
│
├── utils/                  # 工具库 (856行)
│   ├── math.ch            # 数学运算库 (476行)
│   └── crypto.ch          # 加密函数库 (380行)
│
├── defi/                   # DeFi模块 (2,501行)
│   ├── marketplace.ch     # 去中心化交易市场 (875行)
│   ├── lending.ch         # 借贷协议 (819行)
│   └── liquidity.ch       # 流动性池 AMM (807行)
│
└── governance/             # 治理模块 (1,503行)
    ├── voting.ch          # 投票系统 (800行)
    └── proposal.ch        # 提案管理 (703行)
```

---

## 🎯 核心功能

### 1. 资产模块 (asset/)

#### GNACS编码系统 (gnacs.ch)
- 48位GNACS编码结构
- 9种资产类别（实物资产、金融工具、数字资产等）
- 编码解析和验证
- 司法辖区和合规状态管理

#### 元数据管理 (metadata.ch)
- 资产元数据（名称、符号、描述、图片）
- 自定义属性系统
- 估值信息管理
- 所有权历史追踪
- 文档哈希验证

#### 生命周期管理 (lifecycle.ch)
- 7种生命周期状态
- 完整的状态转换流程
- 审核员权限控制
- 有效期管理

### 2. 主权模块 (sovereignty/)

#### 主权规则 (rules.ch)
- **A0**: 绝对所有权
- **B1**: 使用权
- **C2**: 收益权
- **D0**: 担保主权
- **E3**: 知识产权
- **F4**: 临时监管权
- **G5**: 共有权

#### 链上登记系统 (registry.ch)
- 资产登记
- 主权登记
- 抵押登记
- 登记审批流程

#### 合规检查 (compliance.ch)
- KYC验证（5个级别）
- AML风险检查（4个级别）
- 白名单/黑名单管理
- 地域限制
- 制裁对象标记

### 3. ACC协议 (acc/)

#### ACC-20 (acc20.ch)
- 可替代资产标准协议
- 转账、授权、查询
- RWA扩展（冻结、合规）
- 铸造和销毁

#### ACC-721 (acc721.ch)
- 唯一资产（NFT）标准协议
- 完整的NFT功能
- RWA扩展
- 接收器接口

### 4. 工具库 (utils/)

#### 数学运算 (math.ch)
- 安全算术运算（防溢出）
- 百分比和比例计算
- 金融函数（复利、APY/APR转换）
- 数组统计

#### 加密函数 (crypto.ch)
- Blake3哈希（NAC标准）
- Ed25519/ECDSA签名验证
- Merkle树
- Base58编码/解码

### 5. DeFi模块 (defi/)

#### 交易市场 (marketplace.ch)
- 订单簿系统
- 自动撮合引擎
- 限价单和市价单
- 手续费管理

#### 借贷协议 (lending.ch)
- 动态利率模型
- 抵押借贷
- 健康因子计算
- 自动清算机制

#### 流动性池 (liquidity.ch)
- AMM自动做市商
- 添加/移除流动性
- 交换功能
- LP代币和奖励

### 6. 治理模块 (governance/)

#### 投票系统 (voting.ch)
- 投票创建和管理
- 投票权重计算
- 委托投票
- 投票结果计算

#### 提案管理 (proposal.ch)
- 提案创建和提交
- 提案执行（时间锁）
- 提案元数据
- 提案历史

---

## 🚀 快速开始

### 1. 导入模块

```charter
// 导入GNACS编码系统
use charter_std::asset::gnacs;

// 导入ACC-20协议
use charter_std::acc::acc20;

// 导入数学工具
use charter_std::utils::math;
```

### 2. 使用示例

#### 创建ACC-20资产

```charter
use charter_std::acc::acc20::ACC20;
use charter_std::asset::gnacs::GNACS;

certificate MyAsset {
    let asset: ACC20;
    
    constructor(name: String, symbol: String, gnacs: GNACS) {
        self.asset = ACC20::new(name, symbol, gnacs);
    }
    
    pub fn transfer(to: Address, amount: u256) -> bool {
        return self.asset.transfer(to, amount);
    }
}
```

#### 使用GNACS编码

```charter
use charter_std::asset::gnacs::{GNACS, create_gnacs, parse_gnacs};

// 创建GNACS编码
let gnacs = create_gnacs(
    1,   // 资产类别: 实物资产
    100, // 子类别: 房地产
    156, // 司法辖区: 中国
    1    // 合规状态: 已验证
);

// 解析GNACS编码
let info = parse_gnacs(gnacs);
```

#### 使用安全数学运算

```charter
use charter_std::utils::math::{safe_add, safe_mul, percentage};

let a = 100u256;
let b = 200u256;

// 安全加法（防溢出）
let sum = safe_add(a, b);

// 计算百分比
let result = percentage(1000, 15); // 1000的15% = 150
```

---

## ✅ NAC合规性

所有模块严格遵循NAC核心原则：

### 1. 术语合规
- ✅ Asset（不是Token）
- ✅ Certificate（不是Contract）
- ✅ Holdings（不是Balance）
- ✅ Address（不是account）

### 2. 加密算法合规
- ✅ Blake3哈希（不是SHA256/Keccak256）
- ✅ Ed25519/ECDSA签名

### 3. 类型系统合规
- ✅ Asset<GNACS>类型系统
- ✅ Sovereignty<X>主权注解
- ✅ 48位GNACS编码

### 4. RWA专用特性
- ✅ 合规状态管理（KYC/AML）
- ✅ 账户冻结/解冻
- ✅ 估值管理
- ✅ 所有权历史追踪
- ✅ 链上登记系统
- ✅ 生命周期管理

---

## 📚 文档

- [Charter语言规范](../docs/CHARTER_LANGUAGE_SPECIFICATION.md)
- [开发决策记录](../memory/decisions/charter_stdlib_development.md)
- [NAC核心原则](../memory/principles/nac_core_principles.md)

---

## 🔧 编译

使用Charter编译器编译标准库：

```bash
cd charter-compiler
cargo build --release

# 编译单个模块
./target/release/charter-compiler ../charter-std/asset/gnacs.ch

# 编译所有模块
for file in ../charter-std/**/*.ch; do
    ./target/release/charter-compiler "$file"
done
```

---

## 🧪 测试

```bash
# 运行单元测试
cargo test

# 运行集成测试
cargo test --test integration
```

---

## 📈 开发进度

- ✅ **第一阶段**: 核心模块（6个，2,861行）
- ✅ **第二阶段**: 扩展模块（4个，3,084行）
- ✅ **第三阶段**: DeFi和治理（5个，4,004行）
- ✅ **总计**: 15个模块，9,949行代码

---

## 🤝 贡献

欢迎贡献！请遵循以下原则：

1. 严格遵循NAC核心原则
2. 使用NAC专用术语
3. 保持模块化设计
4. 编写完整的文档
5. 添加单元测试

---

## 📄 许可证

MIT License

---

## 📞 联系方式

- **项目**: NAC (NewAssetChain)
- **网站**: https://newassetchain.org
- **邮箱**: dev@newassetchain.org

---

**Charter标准库 - 为RWA资产通证化而生** 🚀