NAC_Blockchain/docs/standards/CNNL_Language_Syntax_Guide.md

# CNNL (Constitutional Neural Network Language) 语法指南

**版本**: 1.0.0  
**日期**: 2026-02-20  
**类型**: 宪政神经网络语言  

---

## 一、CNNL简介

CNNL (Constitutional Neural Network Language) 是NAC区块链的宪法编程语言，用于定义链上治理规则、合规约束和智能合约行为边界。

### 1.1 核心概念

- **宪法优先**：所有链上行为必须符合CNNL定义的宪法规则
- **神经网络**：规则之间可以形成依赖关系网络
- **形式化验证**：支持数学证明和自动验证
- **动态演化**：宪法可以通过治理机制修改

### 1.2 与传统智能合约的区别

| 特性 | 智能合约 | CNNL宪法 |
|------|---------|---------|
| 层级 | 应用层 | 协议层 |
| 作用域 | 单个合约 | 全链约束 |
| 优先级 | 低 | 最高 |
| 可修改性 | 不可变 | 可治理修改 |

---

## 二、基本语法结构

### 2.1 宪法声明

```cnnl
Constitution NAC_Mainnet {
    version: "1.0.0"
    effective_date: "2026-01-31"
    chain_id: 20260131
    
    // 宪法内容
}
```

### 2.2 条款（Clause）

条款是CNNL的基本单元，定义具体的规则：

```cnnl
Clause TransferLimit {
    description: "单笔转账金额限制"
    priority: high
    
    condition {
        amount <= 1000000 XTZH
    }
    
    action {
        approve()
    }
    
    violation {
        reject("Transfer amount exceeds limit")
    }
}
```

---

## 三、完整语法

### 3.1 宪法结构

```cnnl
Constitution <Name> {
    // 元数据
    version: "<版本号>"
    effective_date: "<生效日期>"
    chain_id: <链ID>
    author: "<作者>"
    
    // 导入其他宪法
    import: [
        "NAC_Base_Constitution",
        "RWA_Compliance_Rules"
    ]
    
    // 全局变量
    variables {
        max_transfer_amount: U256 = 1000000
        min_stake_amount: U256 = 10000
        governance_threshold: U8 = 67
    }
    
    // 条款定义
    Clause <ClauseName> {
        // 条款内容
    }
    
    // 更多条款...
}
```

### 3.2 条款详细语法

```cnnl
Clause <ClauseName> {
    // 描述（必需）
    description: "<条款说明>"
    
    // 优先级（必需）
    priority: critical | high | medium | low
    
    // 适用范围（可选）
    scope: [
        "transfer",
        "contract_call",
        "governance"
    ]
    
    // 前置条件（可选）
    precondition {
        // 布尔表达式
    }
    
    // 主条件（必需）
    condition {
        // 布尔表达式
    }
    
    // 通过时的动作（必需）
    action {
        approve()
        // 或其他动作
    }
    
    // 违反时的处理（必需）
    violation {
        reject("<错误信息>")
        // 或其他处理
    }
    
    // 后置条件（可选）
    postcondition {
        // 验证结果状态
    }
}
```

---

## 四、数据类型

### 4.1 基本类型

```cnnl
U8, U16, U32, U64, U128, U256      // 无符号整数
I8, I16, I32, I64, I128, I256      // 有符号整数
Bool                                // 布尔值
String                              // 字符串
Address                             // NAC地址
Hash                                // NAC哈希
Timestamp                           // 时间戳
```

### 4.2 复合类型

```cnnl
Array<T>                            // 数组
Set<T>                              // 集合
Map<K, V>                           // 映射
```

---

## 五、表达式和运算符

### 5.1 比较运算符

```cnnl
==, !=                              // 相等、不等
<, <=, >, >=                        // 大小比较
in, not_in                          // 包含关系
```

### 5.2 逻辑运算符

```cnnl
and, or, not                        // 逻辑与、或、非
```

### 5.3 算术运算符

```cnnl
+, -, *, /, %                       // 加减乘除模
```

---

## 六、内置函数

### 6.1 验证函数

```cnnl
is_verified(address: Address) -> Bool
is_blacklisted(address: Address) -> Bool
has_role(address: Address, role: String) -> Bool
```

### 6.2 查询函数

```cnnl
get_balance(address: Address) -> U256
get_stake(address: Address) -> U256
get_reputation(address: Address) -> U256
```

### 6.3 动作函数

```cnnl
approve()                           // 批准操作
reject(message: String)             // 拒绝操作
require_approval(authority: Address) // 需要授权
emit_event(name: String, data: Any) // 发出事件
```

---

## 七、完整示例

### 7.1 基础宪法

```cnnl
Constitution NAC_Basic_Rules {
    version: "1.0.0"
    effective_date: "2026-01-31"
    chain_id: 20260131
    author: "NAC Foundation"
    
    variables {
        max_transfer: U256 = 1000000
        min_balance: U256 = 1000
    }
    
    // 条款1：转账金额限制
    Clause TransferAmountLimit {
        description: "单笔转账不得超过100万XTZH"
        priority: high
        scope: ["transfer"]
        
        condition {
            tx.amount <= max_transfer
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Transfer amount exceeds maximum limit")
        }
    }
    
    // 条款2：最小余额要求
    Clause MinimumBalanceRequirement {
        description: "账户余额不得低于1000 XTZH"
        priority: medium
        scope: ["transfer"]
        
        condition {
            sender.balance - tx.amount >= min_balance
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Insufficient balance after transfer")
        }
    }
    
    // 条款3：黑名单检查
    Clause BlacklistCheck {
        description: "禁止黑名单地址交易"
        priority: critical
        scope: ["transfer", "contract_call"]
        
        condition {
            not is_blacklisted(tx.sender) and
            not is_blacklisted(tx.recipient)
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Address is blacklisted")
        }
    }
}
```

### 7.2 RWA合规宪法

```cnnl
Constitution RWA_Compliance {
    version: "1.0.0"
    effective_date: "2026-01-31"
    chain_id: 20260131
    
    import: ["NAC_Basic_Rules"]
    
    variables {
        kyc_required: Bool = true
        min_asset_value: U256 = 10000
        max_asset_value: U256 = 100000000
    }
    
    // 条款1：KYC验证要求
    Clause KYC_Verification {
        description: "所有RWA交易需要KYC验证"
        priority: critical
        scope: ["rwa_transfer", "rwa_mint"]
        
        precondition {
            kyc_required == true
        }
        
        condition {
            is_verified(tx.sender) and
            is_verified(tx.recipient)
        }
        
        action {
            approve()
        }
        
        violation {
            reject("KYC verification required")
        }
    }
    
    // 条款2：资产估值范围
    Clause AssetValuationRange {
        description: "RWA资产估值必须在合理范围内"
        priority: high
        scope: ["rwa_mint", "rwa_update"]
        
        condition {
            asset.value >= min_asset_value and
            asset.value <= max_asset_value
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Asset valuation out of range")
        }
    }
    
    // 条款3：托管方验证
    Clause CustodianVerification {
        description: "托管方必须经过认证"
        priority: critical
        scope: ["rwa_mint"]
        
        condition {
            has_role(asset.custodian, "certified_custodian")
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Custodian not certified")
        }
    }
    
    // 条款4：DNA唯一性
    Clause DNA_Uniqueness {
        description: "资产DNA必须唯一"
        priority: critical
        scope: ["rwa_mint"]
        
        condition {
            not exists_dna(asset.dna)
        }
        
        action {
            approve()
            register_dna(asset.dna)
        }
        
        violation {
            reject("Asset DNA already exists")
        }
    }
}
```

### 7.3 治理宪法

```cnnl
Constitution NAC_Governance {
    version: "1.0.0"
    effective_date: "2026-01-31"
    chain_id: 20260131
    
    variables {
        proposal_threshold: U256 = 100000
        voting_period: U64 = 604800  // 7天（秒）
        quorum: U8 = 51              // 51%
        approval_threshold: U8 = 67  // 67%
    }
    
    // 条款1：提案资格
    Clause ProposalEligibility {
        description: "提案者必须质押足够的XTZH"
        priority: high
        scope: ["governance_propose"]
        
        condition {
            get_stake(tx.sender) >= proposal_threshold
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Insufficient stake for proposal")
        }
    }
    
    // 条款2：投票权重
    Clause VotingWeight {
        description: "投票权重基于质押金额"
        priority: medium
        scope: ["governance_vote"]
        
        condition {
            get_stake(tx.sender) > 0
        }
        
        action {
            approve()
            set_vote_weight(get_stake(tx.sender))
        }
        
        violation {
            reject("No stake, no vote")
        }
    }
    
    // 条款3：提案通过条件
    Clause ProposalApproval {
        description: "提案需要达到法定人数和批准阈值"
        priority: critical
        scope: ["governance_execute"]
        
        condition {
            proposal.participation >= quorum and
            proposal.approval_rate >= approval_threshold
        }
        
        action {
            approve()
            execute_proposal(proposal.id)
        }
        
        violation {
            reject("Proposal did not meet approval requirements")
        }
    }
}
```

---

## 八、编译和部署

### 8.1 编译CNNL

```bash
# 编译宪法文件
cnnl constitution.cnnl --output ./output

# 启用形式化验证
cnnl constitution.cnnl --verify --output ./output

# 生成调试信息
cnnl constitution.cnnl --debug --output ./output

# 不生成状态文件
cnnl constitution.cnnl --no-state --output ./output
```

### 8.2 部署宪法

```bash
# 使用NAC CLI部署
nac constitution deploy --file constitution.cnnl

# 更新现有宪法
nac constitution update --id <constitution_id> --file new_constitution.cnnl
```

---

## 九、形式化验证

CNNL支持形式化验证，确保宪法规则的正确性：

```cnnl
Constitution Verified_Rules {
    version: "1.0.0"
    
    // 定义不变量
    invariant {
        forall address in all_addresses:
            get_balance(address) >= 0
    }
    
    // 定义前置条件
    precondition transfer {
        sender.balance >= amount
    }
    
    // 定义后置条件
    postcondition transfer {
        sender.balance == old(sender.balance) - amount and
        recipient.balance == old(recipient.balance) + amount
    }
    
    Clause SafeTransfer {
        description: "安全转账"
        priority: critical
        
        condition {
            sender.balance >= amount
        }
        
        action {
            approve()
        }
        
        violation {
            reject("Insufficient balance")
        }
        
        // 验证不变量保持
        verify {
            invariant_preserved()
        }
    }
}
```

---

## 十、最佳实践

### 10.1 设计原则

1. **最小权限原则**：只授予必要的权限
2. **防御性编程**：假设所有输入都可能有问题
3. **清晰的优先级**：critical > high > medium > low
4. **完整的错误信息**：帮助用户理解拒绝原因

### 10.2 性能优化

1. 避免复杂的嵌套条件
2. 使用缓存减少重复查询
3. 合理设置条款优先级
4. 定期清理过期规则

### 10.3 安全建议

1. 所有critical条款必须经过形式化验证
2. 定期审计宪法规则
3. 建立应急暂停机制
4. 保持宪法版本历史

---

## 十一、与Charter集成

CNNL宪法自动约束所有Charter合约：

```charter
// Charter合约
contract Token {
    // constitutional修饰符表示受CNNL约束
    function transfer(Address to, U256 amount) public constitutional {
        // 执行前会自动检查CNNL规则
        balances[msg.sender] -= amount;
        balances[to] += amount;
    }
}
```

---

## 十二、常见错误

### 错误1：缺少必需字段
```
❌ Clause Test { condition { ... } }
✅ Clause Test { 
    description: "..."
    priority: high
    condition { ... }
    action { ... }
    violation { ... }
}
```

### 错误2：优先级拼写错误
```
❌ priority: "high"  // 字符串
✅ priority: high    // 关键字
```

### 错误3：条件表达式语法
```
❌ if amount > 1000  // 不是if语句
✅ amount > 1000     // 布尔表达式
```

---

## 十三、参考资源

- CNNL规范: https://docs.newassetchain.io/cnnl
- 形式化验证指南: https://docs.newassetchain.io/verification
- 宪法示例库: https://github.com/newassetchain/cnnl-examples
- 治理文档: https://docs.newassetchain.io/governance

---

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