414 lines
9.8 KiB
Markdown
414 lines
9.8 KiB
Markdown
# 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
|