Skip to main content

RPC (Remote Procedure Calls) Interface

The RPC layer allows external clients (e.g., DApps, wallets, explorers, or services) to interact with a running Midnight node over HTTP/HTTPS or WebSocket connections. In Midnight, RPCs follow the JSON-RPC standard and expose methods for:

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

These methods form the interface for building tools and applications on top of Midnight.

Core RPC Methods​

Midnight nodes expose a set of custom RPC methods focused on ledger state, contract state, and system information. Key methods include:

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

Returns the JSON-encoded state of a given smart contract.

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

Returns the raw (binary-encoded) contract state at a specific block (or latest).

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

Fetches the amount of unclaimed tokens or rewards for a beneficiary address.

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

Returns the current ZSwap chain state for a contract—used for zero-knowledge state rollups.

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

Lists all supported RPC API versions, useful for tooling compatibility checks.

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

Provides a snapshot of the ledger’s full state at the specified block.

Polkadot SDK RPC Support​

Midnight also supports the default Polkadot SDK RPC methods, such as:

  • system_health

  • chain_getBlock

  • state_getStorage

  • rpc_methods – returns a list of all supported RPC endpoints. NOTE: some RPC methods don't currently appear in the https://polkadot.js.org/ webapp but you will see them here.

You can call rpc_methods at any time to dynamically retrieve the full list of methods exposed by your node.

note

A mostly up-to-date reference list of general polkadot-sdk RPC methods is also available here. Midnight at any time has some overlap of implemented methods with this list.

Partnerchain RPCs​

Midnight exposes partnerchain-specific RPC methods, especially relevant for block producers and sidechain integration. These methods are designed to query consensus signals, relay finality info, or coordinate between chains.

Security Note for Block Producers​

warning

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

If you’re running a block-producing node, be cautious about which RPC endpoints are enabled. Some methods may leak sensitive data or expose performance risks.

To minimize risk:

  • Use the --rpc-methods Safe flag to limit exposed methods to a safer subset.
  • Avoid using --rpc-external unless absolutely necessary, as it exposes RPC interfaces to external networks.

Always review your node’s RPC configuration to ensure it aligns with your intended threat model and operational role (e.g., validator vs. observer).