# Charter语言语法指南

**版本**: 0.1.0  
**NAC UDM**: 1.0.0  
**NVM Target**: 2.0  
**日期**: 2026-02-20  

---

## 一、Charter语言简介

Charter是NAC区块链的原生智能合约语言，专为RWA（Real World Assets）资产上链设计。

### 1.1 设计原则

- ❌ **不是Solidity**：Charter是独立设计的语言
- ✅ **RWA专用**：内置资产合规、估值、托管功能
- ✅ **宪法约束**：所有合约受CNNL宪法约束
- ✅ **类型安全**：强类型系统，编译时检查

### 1.2 与Solidity的区别

| 特性 | Solidity | Charter |
|------|----------|---------|
| 地址类型 | 20字节 | 32字节 |
| 哈希算法 | Keccak-256 | SHA3-384 (48字节) |
| 虚拟机 | EVM | NVM |
| 字符串类型 | string | String (大写) |
| 可见性 | public/private | public/private/constitutional |

---

## 二、基本语法

### 2.1 合约声明

```charter
// Charter合约使用contract关键字
contract AssetToken {
    // 合约内容
}
```

### 2.2 状态变量

```charter
contract Example {
    // 基本类型（注意大写）
    String name;           // 字符串类型
    U256 totalSupply;      // 无符号256位整数
    Address owner;         // NAC地址（32字节）
    Bool isActive;         // 布尔类型
    
    // 映射类型
    Mapping<Address, U256> balances;
    
    // 数组类型
    Array<Address> holders;
}
```

### 2.3 函数定义

```charter
contract Example {
    // 构造函数
    constructor(String _name, U256 _supply) {
        name = _name;
        totalSupply = _supply;
        owner = msg.sender;
    }
    
    // 公开函数
    function transfer(Address to, U256 amount) public returns (Bool) {
        require(balances[msg.sender] >= amount, "Insufficient balance");
        balances[msg.sender] -= amount;
        balances[to] += amount;
        return true;
    }
    
    // 只读函数
    function getBalance(Address account) public view returns (U256) {
        return balances[account];
    }
    
    // 宪法约束函数
    function mint(Address to, U256 amount) public constitutional {
        // 此函数受CNNL宪法规则约束
        totalSupply += amount;
        balances[to] += amount;
    }
}
```

---

## 三、数据类型

### 3.1 基本类型

```charter
// 整数类型
U8, U16, U32, U64, U128, U256      // 无符号整数
I8, I16, I32, I64, I128, I256      // 有符号整数

// 字符串和字节
String                              // UTF-8字符串
Bytes                               // 字节数组
Bytes32, Bytes48                    // 固定长度字节

// 布尔和地址
Bool                                // true/false
Address                             // NAC地址（32字节）
Hash                                // NAC哈希（48字节，SHA3-384）
```

### 3.2 复合类型

```charter
// 映射
Mapping<Address, U256> balances;
Mapping<Address, Mapping<Address, U256>> allowances;

// 数组
Array<Address> holders;
Array<U256> amounts;

// 结构体
struct Asset {
    String name;
    U256 value;
    Address owner;
    Bool verified;
}
```

---

## 四、完整示例

### 4.1 简单代币合约

```charter
// NAC Charter代币合约示例
contract SimpleToken {
    // 状态变量
    String public name;
    String public symbol;
    U256 public totalSupply;
    Address public owner;
    
    Mapping<Address, U256> balances;
    Mapping<Address, Mapping<Address, U256>> allowances;
    
    // 事件
    event Transfer(Address indexed from, Address indexed to, U256 value);
    event Approval(Address indexed owner, Address indexed spender, U256 value);
    
    // 构造函数
    constructor(String _name, String _symbol, U256 _initialSupply) {
        name = _name;
        symbol = _symbol;
        totalSupply = _initialSupply;
        owner = msg.sender;
        balances[msg.sender] = _initialSupply;
    }
    
    // 查询余额
    function balanceOf(Address account) public view returns (U256) {
        return balances[account];
    }
    
    // 转账
    function transfer(Address to, U256 amount) public returns (Bool) {
        require(balances[msg.sender] >= amount, "Insufficient balance");
        require(to != Address.zero(), "Invalid recipient");
        
        balances[msg.sender] -= amount;
        balances[to] += amount;
        
        emit Transfer(msg.sender, to, amount);
        return true;
    }
    
    // 授权
    function approve(Address spender, U256 amount) public returns (Bool) {
        allowances[msg.sender][spender] = amount;
        emit Approval(msg.sender, spender, amount);
        return true;
    }
    
    // 查询授权额度
    function allowance(Address _owner, Address spender) public view returns (U256) {
        return allowances[_owner][spender];
    }
    
    // 授权转账
    function transferFrom(Address from, Address to, U256 amount) public returns (Bool) {
        require(balances[from] >= amount, "Insufficient balance");
        require(allowances[from][msg.sender] >= amount, "Insufficient allowance");
        require(to != Address.zero(), "Invalid recipient");
        
        balances[from] -= amount;
        balances[to] += amount;
        allowances[from][msg.sender] -= amount;
        
        emit Transfer(from, to, amount);
        return true;
    }
}
```

### 4.2 RWA资产合约

```charter
// NAC RWA资产合约
contract RealWorldAsset {
    // 资产信息
    String public assetName;
    String public assetType;        // 房产、艺术品、股权等
    U256 public assetValue;         // 资产估值（XTZH）
    Address public custodian;       // 托管方
    Bool public verified;           // 合规验证状态
    
    // 所有权信息
    Address public owner;
    U256 public totalShares;        // 总份额
    Mapping<Address, U256> shareBalances;
    
    // DNA信息
    Bytes48 public assetDNA;        // 资产DNA（唯一标识）
    
    // 事件
    event AssetVerified(Bytes48 dna, U256 value);
    event ShareTransfer(Address indexed from, Address indexed to, U256 shares);
    
    // 构造函数
    constructor(
        String _name,
        String _type,
        U256 _value,
        Address _custodian,
        U256 _totalShares
    ) {
        assetName = _name;
        assetType = _type;
        assetValue = _value;
        custodian = _custodian;
        owner = msg.sender;
        totalShares = _totalShares;
        shareBalances[msg.sender] = _totalShares;
        verified = false;
    }
    
    // 合规验证（仅托管方可调用）
    function verify(Bytes48 _dna) public constitutional {
        require(msg.sender == custodian, "Only custodian can verify");
        require(!verified, "Already verified");
        
        assetDNA = _dna;
        verified = true;
        
        emit AssetVerified(_dna, assetValue);
    }
    
    // 转让份额
    function transferShares(Address to, U256 shares) public returns (Bool) {
        require(verified, "Asset not verified");
        require(shareBalances[msg.sender] >= shares, "Insufficient shares");
        require(to != Address.zero(), "Invalid recipient");
        
        shareBalances[msg.sender] -= shares;
        shareBalances[to] += shares;
        
        emit ShareTransfer(msg.sender, to, shares);
        return true;
    }
    
    // 查询份额
    function sharesOf(Address account) public view returns (U256) {
        return shareBalances[account];
    }
    
    // 更新估值（仅托管方可调用）
    function updateValuation(U256 newValue) public constitutional {
        require(msg.sender == custodian, "Only custodian can update");
        assetValue = newValue;
    }
}
```

---

## 五、编译和部署

### 5.1 编译合约

```bash
# 检查语法
charter check --input contract.charter

# 编译到NVM字节码
charter compile --input contract.charter --output contract.nvm

# 显示AST
charter ast --input contract.charter

# 查看版本
charter version
```

### 5.2 部署合约

```bash
# 使用NAC CLI部署
nac contract deploy --bytecode contract.nvm --args "TokenName,TKN,1000000"
```

---

## 六、内置函数和变量

### 6.1 全局变量

```charter
msg.sender      // 调用者地址
msg.value       // 发送的XTZH数量
block.number    // 当前区块号
block.timestamp // 当前区块时间戳
tx.origin       // 交易发起者
```

### 6.2 内置函数

```charter
require(condition, message)     // 断言，失败时回滚
assert(condition)               // 断言，失败时panic
revert(message)                 // 回滚交易
keccak256(data)                 // 计算哈希（NAC使用SHA3-384）
```

---

## 七、最佳实践

### 7.1 安全建议

1. 总是检查地址有效性
2. 使用`require`进行输入验证
3. 防止重入攻击
4. 避免整数溢出
5. 遵循CNNL宪法规则

### 7.2 代码风格

1. 合约名使用大驼峰（PascalCase）
2. 函数名使用小驼峰（camelCase）
3. 常量使用全大写+下划线
4. 添加详细注释

---

## 八、与CNNL集成

Charter合约可以被CNNL宪法约束：

```charter
contract CompliantToken {
    // constitutional修饰符表示此函数受宪法约束
    function mint(Address to, U256 amount) public constitutional {
        // CNNL会在执行前检查合规性
        totalSupply += amount;
        balances[to] += amount;
    }
}
```

---

## 九、常见错误

### 错误1：类型不匹配
```
❌ string name;  // Solidity风格
✅ String name;  // Charter风格
```

### 错误2：地址长度
```
❌ address(20字节)  // 以太坊
✅ Address(32字节)  // NAC
```

### 错误3：哈希算法
```
❌ keccak256 → 32字节
✅ sha3_384 → 48字节
```

---

## 十、参考资源

- NAC UDM文档: https://docs.newassetchain.io/udm
- NVM规范: https://docs.newassetchain.io/nvm
- CNNL宪法语言: https://docs.newassetchain.io/cnnl
- Charter示例库: https://github.com/newassetchain/charter-examples

---

**文档维护**: NAC技术团队  
**最后更新**: 2026-02-20  
**反馈**: tech@newassetchain.io