Skip to main content
Version: v1
For the complete documentation index, see llms.txt

RPC interface

The Remote Procedure Call (RPC) layer lets external clients, such as dApps, wallets, explorers, and services, 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, which trigger state transitions
  • Querying on-chain contract state
  • Fetching auxiliary data, such as off-chain values or metadata

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

Core RPC methods​

Midnight nodes expose the following custom RPC methods in the midnight_ namespace. They return contract state, ledger state roots, and version information. The optional at parameter is a block hash. If you omit it, the query runs against the node's best block, which might not be final yet.

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

Returns the state of a deployed smart contract as a hex-encoded string. Pass the contract address as a hex string without the 0x prefix.

#[method(name = "midnight_zswapStateRoot")]
fn get_zswap_state_root(&self, at: Option<BlockHash>) -> Result<Vec<u8>, StateRpcError>;

Returns the Merkle root of the Zswap coin commitment tree as an array of bytes.

#[method(name = "midnight_ledgerStateRoot")]
fn get_ledger_state_root(&self, at: Option<BlockHash>) -> Result<Vec<u8>, StateRpcError>;

Returns the root of the ledger state as an array of bytes. The array is either a 0 byte followed by the 32-byte Merkle root hash, or a 1 byte followed by the root node itself. The second form appears when the root node is small enough to store inline, so the length can change from block to block.

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

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

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

Returns the version of the ledger that the node uses for the specified block, as a string such as =8.1.2. The value comes from the node's build, so for older blocks it can be newer than the version the network ran at the time.

Polkadot SDK RPC support​

Midnight also supports default Polkadot SDK RPC methods, including:

  • system_health
  • chain_getBlock
  • state_getStorage
  • rpc_methods, which returns a list of all supported RPC endpoints.

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

note

Some RPC methods exposed by Midnight might not appear in the Polkadot JS web app. For a general reference, see the Polkadot SDK RPC method documentation. Midnight implementations overlap with this list, but support can differ by node version and configuration.

Partnerchain RPCs​

Midnight exposes partnerchain-specific RPC methods, especially for block producers and sidechain integration. These methods query consensus signals, relay finality information, and coordinate between chains.

Security note for block producers​

warning

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

If you run a block-producing node, be cautious about which RPC endpoints you enable. Some methods can leak sensitive data or increase performance risk.

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 threat model and operational role (for example, validator vs. observer).