midnight-rpc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RPC Interface

RPC 接口

The Remote Procedure Call (RPC) layer lets external clients — dApps, wallets, explorers, services — interact with a running Midnight node over HTTP/HTTPS or WebSocket.

Midnight RPCs follow the JSON-RPC standard.

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

Midnight RPC遵循JSON-RPC标准。

Client ↔ node flow

客户端 ↔ 节点流程

mermaid

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

mermaid

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

What RPC enables

RPC 的功能

Submitting transactions (state transitions)
Querying on-chain contract state
Fetching auxiliary data (off-chain values, metadata)

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

Core Midnight RPC methods

Midnight 核心 RPC 方法

Custom methods focused on ledger state, contract state, and system information:

Method	Purpose
`midnight_jsonContractState`	JSON-encoded smart contract state
`midnight_contractState`	Raw binary-encoded contract state at a block
`midnight_unclaimedAmount`	Unclaimed tokens/rewards for a beneficiary
`midnight_zswapChainState`	ZSwap chain state for a contract
`midnight_apiVersions`	Supported RPC API versions (tooling compatibility)
`midnight_ledgerVersion`	Ledger version at a block

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

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

Method signatures (reference)

方法签名（参考）

rust

#[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>;

Most methods accept an optional

at

block hash; omit for latest block.

mermaid

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

rust

#[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

区块哈希参数；若省略则使用最新区块。

mermaid

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 support

Polkadot SDK RPC 支持

Midnight also exposes default Polkadot SDK methods, including:

Method	Purpose
`system_health`	Node health status
`chain_getBlock`	Fetch block by hash
`state_getStorage`	Read storage at a key
`rpc_methods`	List all supported RPC endpoints

Call

rpc_methods

at any time for the full method list on your node.

Note: Some Midnight RPC methods may not appear in Polkadot JS Apps. See Polkadot SDK RPC docs for overlap; support varies by node version and configuration.

For application-level reads, many dApps prefer the Indexer GraphQL API — see

midnight-indexer/

Midnight 还暴露了 Polkadot SDK 的默认方法，包括：

方法	用途
`system_health`	节点健康状态
`chain_getBlock`	通过哈希获取区块
`state_getStorage`	通过键读取存储数据
`rpc_methods`	列出所有支持的RPC端点

随时调用

rpc_methods

可查看节点上的完整方法列表。

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

对于应用级别的读取，许多dApp更倾向于使用索引器GraphQL API——请查看

midnight-indexer/

。

Partnerchain RPCs

Partnerchain RPC

Midnight exposes Partnerchain-specific RPC methods for block producers and sidechain integration:

Query consensus signals
Relay finality information
Coordinate cross-chain operations

Midnight 暴露了Partnerchain专属的RPC方法，用于区块生产者和侧链集成：

查询共识信号
传递最终性信息
协调跨链操作

Security: block producers

安全性：区块生产者

Warning: Not all RPC methods are safe to expose on public or production nodes.

If you run a block-producing node:

Risk	Mitigation
Sensitive data leakage	Use `--rpc-methods Safe`
External attack surface	Avoid `--rpc-external` unless required
Performance abuse	Limit exposed endpoints to your operational role

mermaid

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

Align RPC configuration with your threat model and role (validator vs observer).

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

如果你运行的是出块节点：

风险	缓解措施
敏感数据泄露	使用 `--rpc-methods Safe`
外部攻击面扩大	除非必要，否则避免使用 `--rpc-external`
性能滥用	根据你的操作角色限制暴露的端点

mermaid

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

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

midnight-rpc

Original

Translation

RPC Interface

RPC 接口

Client ↔ node flow

客户端 ↔ 节点流程

What RPC enables

RPC 的功能

Core Midnight RPC methods

Midnight 核心 RPC 方法

Method signatures (reference)

方法签名（参考）

Polkadot SDK RPC support

Polkadot SDK RPC 支持

Partnerchain RPCs

Partnerchain RPC

Security: block producers

安全性：区块生产者

Related skills

相关技能