midnight-rpc

RPC 接口

**远程过程调用（RPC）**层让外部客户端（dApp、钱包、区块浏览器、服务）通过 HTTP/HTTPS 或 WebSocket 与正在运行的 Midnight 节点交互。

Midnight RPC 遵循 JSON-RPC 标准。

客户端 ↔ 节点流程

flowchart LR
  subgraph Clients
    DApp["dApp / wallet"]
    Explorer["Block explorer"]
    Svc["Backend service"]
  end

  subgraph Node["Midnight node"]
    RPC["JSON-RPC layer"]
    RT["Runtime / pallet-midnight"]
    Store["State storage"]
  end

  DApp -->|HTTP / WSS| RPC
  Explorer --> RPC
  Svc --> RPC
  RPC --> RT
  RT --> Store

RPC 的功能

• 提交交易（状态转换）
• 查询链上合约状态
• 获取辅助数据（链下值、元数据）

---

Midnight 核心 RPC 方法

专注于账本状态、合约状态和系统信息的自定义方法：

方法	用途
midnight_jsonContractState	JSON 编码的智能合约状态
midnight_contractState	区块处原始二进制编码的合约状态
midnight_unclaimedAmount	受益人尚未领取的代币/奖励
midnight_zswapChainState	合约的 ZSwap 链状态
midnight_apiVersions	支持的 RPC API 版本（工具兼容性）
midnight_ledgerVersion	区块处的账本版本

方法签名（参考）

#[method(name = "midnight_jsonContractState")]
fn get_json_state(
    &self,
    contract_address: String,
    at: Option<BlockHash>,
) -> Result<String, StateRpcError>;

#[method(name = "midnight_contractState")]
fn get_state(
    &self,
    contract_address: String,
    at: Option<BlockHash>,
) -> Result<String, StateRpcError>;

#[method(name = "midnight_unclaimedAmount")]
fn get_unclaimed_amount(
    &self,
    beneficiary: String,
    at: Option<BlockHash>,
) -> Result<u128, StateRpcError>;

#[method(name = "midnight_zswapChainState")]
fn get_zswap_chain_state(
    &self,
    contract_address: String,
    at: Option<BlockHash>,
) -> Result<String, StateRpcError>;

#[method(name = "midnight_apiVersions")]
fn get_supported_api_versions(&self) -> RpcResult<Vec<u32>>;

#[method(name = "midnight_ledgerVersion")]
fn get_ledger_version(&self, at: Option<BlockHash>) -> Result<String, BlockRpcError>;

大多数方法都接受可选的 at 区块哈希；省略时使用最新区块。

flowchart TB
  Q["Client query"] --> M{"Method type"}
  M -->|Contract| CS["midnight_contractState / jsonContractState"]
  M -->|ZSwap| ZS["midnight_zswapChainState"]
  M -->|Rewards| UA["midnight_unclaimedAmount"]
  M -->|Meta| LV["midnight_ledgerVersion / apiVersions"]
  CS --> Block["Resolve at block hash or latest"]
  ZS --> Block
  UA --> Block
  LV --> Block

---

Polkadot SDK RPC 支持

Midnight 还提供默认的 Polkadot SDK 方法，包括：

方法	用途
system_health	节点健康状态
chain_getBlock	按哈希获取区块
state_getStorage	读取指定键的存储
rpc_methods	列出所有受支持的 RPC 端点

随时调用 rpc_methods，即可查看节点的完整方法列表。

**注意：**某些 Midnight RPC 方法可能不会显示在 Polkadot JS Apps 中。有关重叠部分，请参阅 Polkadot SDK RPC 文档；支持情况因节点版本和配置而异。

对于应用级读取，许多 dApp 更倾向于使用 Indexer GraphQL API——参见 midnight-indexer/。

---

Partnerchain RPC

Midnight 提供 Partnerchain 专用 RPC 方法，供区块生产者和侧链集成使用：

• 查询共识信号
• 中继最终性信息
• 协调跨链操作

---

安全：区块生产者

**警告：**并非所有 RPC 方法都适合在公共节点或生产节点上公开。

如果你运行的是区块生产节点：

风险	缓解措施
敏感数据泄露	使用 --rpc-methods Safe
外部攻击面	除非必要，否则避免使用 --rpc-external
性能滥用	根据运维职责限制公开的端点

flowchart TD
  Role{"Node role?"}
  Role -->|Validator / block producer| Safe["--rpc-methods Safe<br/>No --rpc-external"]
  Role -->|Observer / archive| Review["Review threat model<br/>May expose read-only RPC"]
  Safe --> Audit["Audit rpc_methods list"]
  Review --> Audit

根据你的威胁模型和角色（验证者或观察者）调整 RPC 配置。

---

相关技能

• midnight-onchain-logic/ — RPC 方法读取哪些状态
• midnight-indexer/ — 面向 dApp 数据的 GraphQL 替代方案
• midnight-transactions/ — 通过 RPC 提交基于证明的交易