NAC_Blockchain/docs/standards/Charter_Language_Syntax_Guide.md

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合约使用contract关键字
contract AssetToken {
    // 合约内容
}

2.2 状态变量

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

2.3 函数定义

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 基本类型

// 整数类型
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 复合类型

// 映射
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 简单代币合约

// 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资产合约

// 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 编译合约

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

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

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

# 查看版本
charter version

5.2 部署合约

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

---

六、内置函数和变量

6.1 全局变量

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

6.2 内置函数

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宪法约束：

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