midnight-rpc

RPC Interface

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.

Client ↔ node flow

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

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

---

Core Midnight RPC methods

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

Method signatures (reference)

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

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

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/.

---

Partnerchain RPCs

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

• Query consensus signals
• Relay finality information
• Coordinate cross-chain operations

---

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

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).

---

Related skills

• midnight-onchain-logic/ — what state RPC methods read
• midnight-indexer/ — GraphQL alternative for dApp data
• midnight-transactions/ — submitting proof-based transactions via RPC