# NAC RPC 方法规范

版本：1.0  
制定方：NAC CLI工具组  
日期：2026-02-18

## 概述

NAC是原生RWA公链，使用自己的RPC方法命名规范，不继承以太坊的`eth_*`方法。

## 命名规范

**格式**: `<模块>_<操作>`

- `nac_*` - 核心链功能
- `xtzh_*` - XTZH预言机
- `acc_*` - ACC协议系列
- `charter_*` - Charter智能合约

## 核心方法列表

### 1. 账户相关 (nac_account_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `nac_account_getBalance` | `address: Address` | `Balance` | 获取账户余额 |
| `nac_account_getNonce` | `address: Address` | `u64` | 获取账户nonce |
| `nac_account_getInfo` | `address: Address` | `AccountInfo` | 获取账户完整信息 |
| `nac_account_listAssets` | `address: Address` | `Asset[]` | 列出账户持有的RWA资产 |

### 2. 交易相关 (nac_tx_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `nac_tx_send` | `SignedTransaction` | `Hash` | 发送已签名交易 |
| `nac_tx_get` | `hash: Hash` | `Transaction` | 获取交易详情 |
| `nac_tx_getReceipt` | `hash: Hash` | `Receipt` | 获取交易收据 |
| `nac_tx_getStatus` | `hash: Hash` | `TxStatus` | 获取交易状态 |
| `nac_tx_estimateGas` | `Transaction` | `u64` | 估算Gas费用 |

### 3. 区块相关 (nac_block_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `nac_block_getByNumber` | `number: u64` | `Block` | 按高度获取区块 |
| `nac_block_getByHash` | `hash: Hash` | `Block` | 按哈希获取区块 |
| `nac_block_getLatest` | - | `Block` | 获取最新区块 |
| `nac_block_getHeight` | - | `u64` | 获取当前区块高度 |
| `nac_block_getTransactions` | `number: u64` | `Transaction[]` | 获取区块中的交易 |

### 4. Charter合约相关 (charter_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `charter_deploy` | `bytecode: bytes, args: any[]` | `Address` | 部署Charter合约 |
| `charter_call` | `address: Address, method: string, args: any[]` | `any` | 调用合约方法（只读） |
| `charter_send` | `address: Address, method: string, args: any[]` | `Hash` | 发送合约交易 |
| `charter_getCode` | `address: Address` | `bytes` | 获取合约字节码 |
| `charter_getStorage` | `address: Address, key: bytes32` | `bytes32` | 获取合约存储 |

### 5. ACC协议相关 (acc_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `acc_asset_create` | `AssetParams` | `Hash` | 创建RWA资产 |
| `acc_asset_get` | `asset_id: string` | `Asset` | 获取资产信息 |
| `acc_asset_transfer` | `from, to, asset_id` | `Hash` | 转移资产 |
| `acc_asset_listByOwner` | `address: Address` | `Asset[]` | 列出所有者的资产 |
| `acc_compliance_verify` | `asset_id: string` | `ComplianceReport` | 验证资产合规性 |

### 6. 宪法系统相关 (constitution_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `constitution_getClause` | `clause_id: string` | `Clause` | 获取宪法条款 |
| `constitution_listClauses` | `layer: ClauseLayer` | `Clause[]` | 列出指定层级的条款 |
| `constitution_verifyTx` | `tx: Transaction` | `ConstitutionalReceipt` | 验证交易的宪法合规性 |
| `constitution_getReceipt` | `receipt_id: Hash` | `ConstitutionalReceipt` | 获取宪法收据 |

### 7. CBPP共识相关 (cbpp_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `cbpp_getValidators` | - | `Validator[]` | 获取验证者列表 |
| `cbpp_getProposal` | `proposal_id: u64` | `Proposal` | 获取提案详情 |
| `cbpp_submitProposal` | `Proposal` | `Hash` | 提交提案 |
| `cbpp_voteProposal` | `proposal_id, vote` | `Hash` | 对提案投票 |

### 8. XTZH预言机相关 (xtzh_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `xtzh_getRate` | `features: i32[]` | `RateResponse` | 获取XTZH汇率 |
| `xtzh_submitReceipt` | `ReceiptSubmission` | `SubmissionAck` | 提交汇率收据 |
| `xtzh_health` | - | `HealthResponse` | 健康检查 |

### 9. 节点相关 (node_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `node_getInfo` | - | `NodeInfo` | 获取节点信息 |
| `node_getPeers` | - | `Peer[]` | 获取对等节点列表 |
| `node_getHealth` | - | `HealthStatus` | 获取节点健康状态 |
| `node_getVersion` | - | `string` | 获取节点版本 |

### 10. 网络相关 (net_*)

| 方法名 | 参数 | 返回 | 说明 |
|--------|------|------|------|
| `net_version` | - | `string` | 获取网络版本 |
| `net_peerCount` | - | `u64` | 获取对等节点数量 |
| `net_listening` | - | `bool` | 是否正在监听 |

## 数据类型

### Address
NAC原生地址格式（32字节）

### Hash  
NAC原生哈希格式（48字节，SHA3-384）

### Transaction
```json
{
  "from": "Address",
  "to": "Address",
  "value": "u128",
  "data": "bytes",
  "nonce": "u64",
  "gas_limit": "u64",
  "gas_price": "u128",
  "signature": "Signature"
}
```

### Block
```json
{
  "number": "u64",
  "hash": "Hash",
  "parent_hash": "Hash",
  "timestamp": "u64",
  "transactions": "Transaction[]",
  "validator": "Address"
}
```

### Asset (RWA资产)
```json
{
  "asset_id": "string (GNACS编码)",
  "owner": "Address",
  "asset_type": "AssetType",
  "value": "u128",
  "metadata": "object",
  "dna": "CryptoDNA"
}
```

## 错误码

| 错误码 | 说明 |
|--------|------|
| -32700 | 解析错误 |
| -32600 | 无效请求 |
| -32601 | 方法不存在 |
| -32602 | 无效参数 |
| -32603 | 内部错误 |
| -40001 | 宪法验证失败 |
| -40002 | 合规检查失败 |
| -40003 | 资产不存在 |
| -40004 | 余额不足 |

## 示例

### 获取账户余额
```json
{
  "jsonrpc": "2.0",
  "method": "nac_account_getBalance",
  "params": {
    "address": "0x1234...abcd"
  },
  "id": 1
}
```

### 发送交易
```json
{
  "jsonrpc": "2.0",
  "method": "nac_tx_send",
  "params": {
    "from": "0x1234...abcd",
    "to": "0x5678...efgh",
    "value": "1000000000000000000",
    "data": "0x",
    "nonce": 5,
    "gas_limit": 21000,
    "gas_price": "1000000000",
    "signature": "0x..."
  },
  "id": 2
}
```

### 获取XTZH汇率
```json
{
  "jsonrpc": "2.0",
  "method": "xtzh_getRate",
  "params": {
    "features": []
  },
  "id": 3
}
```

## 注意事项

1. **不要使用以太坊方法名** - NAC是原生链，不继承ERC-20/ERC-721
2. **使用NAC原生类型** - Address(32字节)、Hash(48字节)
3. **遵循CBPP共识** - 所有交易需要宪法验证
4. **支持RWA资产** - 使用ACC协议系列
5. **集成XTZH预言机** - 汇率数据来自AI模型

## 版本历史

- v1.0 (2026-02-18) - 初始版本