# IBC v2 与分片

> NeuroChain 上的 IBC v2——后量子提交头、带托管和凭证的 ICS-20 式代币转账、以数据包传递的 VMGuardian 证明、中继器与运营方配置、参数配置、当前状态及测试方式；另含分片的运维。

Source: https://docs.nro.world/zh/operate/ibc

## IBC v2 <Badge type="warning" text="实验性" /> {#ibc-v2}

NeuroChain 通过 **IBC v2** 与其他链互联——这是跨链通信协议（Inter-Blockchain Communication）经过简化、以客户端为中心的版本（也称 *Eureka*）。第一个对手链是 Cosmos 生态，从 Neutron（CosmWasm）开始。

NeuroChain 带来的是**后量子互操作性**：它的提交使用 ML-DSA-65 签名，因此对手链的轻客户端以后量子签名验证 NeuroChain，而不是依赖经典 IBC 所用的 ECDSA / Ed25519 方案。

### 通道上传输的内容

| 数据包 | 线上格式 | 用途 |
|--------|-------------|---------|
| 同质化转账 | `nc-ics20-v1|denom|amount|sender|receiver|channel|memo` | 以 ICS-20 方式在链之间转移 NRO 或凭证 |
| 安全证明 | `nc-ibc-attest-v1|bytecode_hash|score|model|timestamp|subject` | 把 [VMGuardian](/zh/ai/vmguardian) 评分传递到另一条链 |
| 提交头 | `nc-pq-lc-v1|chain_id|height|block_hash|state_root`，以 ML-DSA-65 签名 | 对手链轻客户端所校验的内容 |

证明数据包正是两大核心方向的交汇点：在 NeuroChain 上产生、可供另一条链依赖的 AI 安全证明。

### 代币转账

![IBC v2 转账：用户签署 ibc_transfer；验证者将 NRO 锁入通道托管账户；每 1 000 个区块验证者签署一个提交头；中继器获取提交头、更新对手链客户端并投递数据包；对手链铸造凭证；中继器回执确认，托管资金被销毁；若超时前未收到确认，则向发送方退款](/diagrams/zh/ibc-v2-transfer.svg)

**出站（NeuroChain → 对手链）**

1. `POST /api/v1/ibc/transfer` 将金额锁入通道的托管账户 `neuro:ibc.escrow.<channel>`；数据包状态为 `locked`。
2. 中继器投递数据包；对手链铸造凭证。
3. `POST /api/v1/ibc/ack` 将其标记为 `committed` 并销毁托管资金。
4. 超时内未收到确认 → 自动向发送方退款。

**入站（对手链 → NeuroChain）**

1. 中继器提交 `POST /api/v1/ibc/recv`，附带数据包及其承诺。
2. 接收方被记入一笔 **IBC 凭证**，其 denom 为 `ibc/<SHA-256 of the trace path>`，与 ibc-go 的做法一致。同一个数据包 ID 只能被接收一次。
3. `POST /api/v1/ibc/redeem` 销毁凭证，并通过通道把资产送回。

线上传输的金额是以基础 denom 计的整数（NRO 的基础 denom 为 `unro`）。

### 谁签署什么

| 操作 | 谁可以提交 | 签名 |
|-----------|----------------|-----------|
| `transfer`, `redeem` | 任意账户，针对其自有资金 | 覆盖所有字段——接收方、通道、链、denom、金额 |
| `recv`, `ack`, `channel/open`, `channel/pause`, `client/update`, `attest` | 仅限 **IBC 运营方**：`NEUROCHAIN_IBC_OPERATOR_PUBKEYS` 中列出的密钥 | 同上，由运营方的密钥签署 |

权限依据的是运营方的**公钥**，而不是其声称的地址。所有 IBC 操作都在共识中应用，签名目标为 `neuro:system.ibc`。

### 当前状态与限制

| 组件 | 状态 |
|-------|--------|
| 托管、凭证、denom 追踪、超时、数据包记录 | 已在节点中实现，并有单元测试 |
| 每 1 000 个区块签署一次的 PQ 提交头 | 已实现；通过 `GET /api/v1/ibc/header/latest` 提供 |
| 每个 IBC 操作上的字段绑定签名 | 已实现，并有黄金测试向量 |
| 对手链合约 `neuro-pq-client`（CosmWasm） | 已构建（`neurochain/contracts/neuro_pq_client`）。**尚未实现免信任：** 它检查中继器的受信任密钥和递增的高度；ML-DSA-65 签名由中继器在链下验证 |
| 入站数据包 | 接受来自 IBC 运营方、并带有覆盖入账字段之承诺的数据包；来自对手链的 Merkle 成员证明已提出方案，尚未实现 |
| 与 Neutron 测试网的端到端转账 | **尚未完成**——部署脚本已就绪（`tools/ibc-relayer/deploy_neutron.js`），需要一个有资金的测试网账户 |
| 与 ibc-go 的完整 IBC v2 握手 | 计划中 |

在对手链于链上验证 ML-DSA-65 之前，IBC 通道信任其中继器。在任何承载真实价值的网络上，请将 `NEUROCHAIN_IBC_MAX_PACKET_UNRO` 和 `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO` 设得较低。

**测试方式：** 节点单元测试覆盖锁定、确认、超时退款、凭证入账与赎回、重复数据包、保留的数据包 ID、承诺不匹配、运营方权限以及规范签名消息（`cargo test -p neurochain-node ibc`）。`GET /api/v1/ibc/pq/test-vector` 返回固定的提交头、密钥和签名，让对手链实现能够检查自己编码和验证的是完全相同的字节。

### 运行中继器（实验环境）

```bash
# 1. 启动节点，并允许你的运营方密钥
NEUROCHAIN_IBC_OPERATOR_PUBKEYS=<operator ML-DSA-65 public key hex> ./target/debug/neurochain

# 2. 打开通道（由运营方签名）
#    POST /api/v1/ibc/channel/open  { from, channel, port, counterparty_chain, allowed_denoms, … }

# 3. 在检查点之后，为对手链客户端导出提交头
NODE_RPC=http://localhost:9933 node neurochain/tools/ibc-relayer/export_update_client.js
```

该脚本会输出供 `neuro-pq-client` 使用的 `UpdateClient` 消息。每个 IBC 端点的请求字段见 [REST 参考](/zh/reference/rest#ibc-v2)。

### 配置 {#configuration}

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `NEUROCHAIN_IBC_OPERATOR_PUBKEYS` | 空 | 允许中继和管理通道的公钥，逗号分隔 |
| `NEUROCHAIN_IBC_TRUSTED_PUBKEYS` | 空 | 入站数据包上其提交头签名被接受的 ML-DSA-65 密钥；为空时接受任何有效签名（仅限实验环境） |
| `NEUROCHAIN_IBC_REQUIRE_HEADER` | mainnet 上开启 | 入站数据包必须附带经过验证的提交头 |
| `NEUROCHAIN_IBC_REQUIRE_PACKET_COMMITMENT` | mainnet 上开启 | 入站数据包必须携带覆盖其字段的承诺 |
| `NEUROCHAIN_IBC_TIMEOUT_BLOCKS` | 10 | 未确认的出站数据包被退款前的区块数 |
| `NEUROCHAIN_IBC_MAX_PACKET_UNRO` | 无限制 | 单笔转账上限 |
| `NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO` | 无限制 | 单个通道可托管的最大金额 |
| `NEUROCHAIN_IBC_NATIVE_DENOM` | `unro` | NRO 在线上传输时的基础 denom |

## 分片 <Badge type="warning" text="实验性" /> {#sharding}

每个分片运行各自的共识实例，拥有自己的验证者和高度；账户归属于 `FNV-1a(address) mod n_shards`。跨分片转账如何结算，见[共识 → 分片](/zh/learn/consensus#sharding)。

每个分片运行一个节点：

```bash
NEUROCHAIN_SHARDS=4 NEUROCHAIN_SHARD_ID=0 NEUROCHAIN_DATA_DIR=./data-s0 NEUROCHAIN_RPC_PORT=9933 … ./target/debug/neurochain
NEUROCHAIN_SHARDS=4 NEUROCHAIN_SHARD_ID=1 NEUROCHAIN_DATA_DIR=./data-s1 NEUROCHAIN_RPC_PORT=9934 … ./target/debug/neurochain
```

- 未设置 `NEUROCHAIN_SHARD_ID` 时，节点只运行单个分片，不会产生跨分片转账。
- Gateway 会把每笔交易路由到发送方所在分片的节点。
- 用 `GET /api/v1/cross-shard/queue?status=locked` 监控中继，用 `GET /api/v1/shards` 监控各分片高度。

在内部，跨分片中继与 IBC v2 使用同一个数据包引擎——分片是一种通道端，外部链是另一种。