RPC Proxy

Direct proxy to the Midnight node with method whitelisting. Forwards standard Substrate JSON-RPC calls without wrapping them in the Shroud tool format.

Endpoint

POST /v1/midnight/rpc

Authentication

Authorization: Bearer shroud_prod_...
Content-Type: application/json

How It Works

The RPC proxy forwards JSON-RPC calls directly to the underlying Midnight node. Only methods explicitly whitelisted by the server operator are accessible — calls to non-whitelisted methods return an error.

This is useful when you need raw Substrate RPC access without the Shroud tool abstraction.

Request Format

Standard Substrate JSON-RPC format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_getFinalizedHead",
  "params": []
}

Batch Requests

The proxy supports JSON-RPC batch requests — send an array of up to 50 requests in a single call:

[
  {"jsonrpc": "2.0", "id": 1, "method": "chain_getFinalizedHead", "params": []},
  {"jsonrpc": "2.0", "id": 2, "method": "system_chain",          "params": []}
]

Each request in the batch is validated independently. Responses are returned as a JSON array in the same order.

Whitelisted Methods

The whitelist is operator-configured. The list below is a representative subset; for the live list of methods exposed by a given deployment, call the midnight_listMethods tool via the JSON-RPC API (also shown in Listing available methods below).

System

Method	Description	CU Cost
`system_chain`	Chain name (e.g. `"Midnight Preprod"`)	0.1
`system_chainType`	Chain type (`Live`, `Development`, `Local`)	0.1
`system_name`	Node software name	0.1
`system_version`	Node software version string	0.1
`system_properties`	Chain properties (token decimals, token symbol, SS58 prefix)	0.1
`system_accountNextIndex`	Next valid nonce for an account. Params: `[accountId]`	0.5
`system_dryRun`	Dry-run an extrinsic without submitting (full WASM execution; heavy). Params: `[hexExtrinsic]`	10.0
`system_dryRunAt`	Dry-run at a specific block. Params: `[hexExtrinsic, blockHash]`	10.0
`account_nextIndex`	Alias for `system_accountNextIndex`. Params: `[accountId]`	0.5

Chain

Method	Description	CU Cost
`chain_getBlock`	Full signed block. Params: `[blockHash?]`	1.0
`chain_getBlockHash`	Block hash by number. Params: `[blockNumber?]`	0.2
`chain_getHeader`	Block header only. Params: `[blockHash?]`	0.2
`chain_getFinalizedHead`	Hash of the last finalized block	0.1
`chain_getHead`	Hash of the best (latest) block	0.1
`chain_getRuntimeVersion`	Runtime version at the best block. Params: `[blockHash?]`	0.2

State

Method	Description	CU Cost
`state_getMetadata`	Full runtime metadata (300-600 KB). Params: `[blockHash?]`	2.0
`state_getRuntimeVersion`	Runtime version info. Params: `[blockHash?]`	0.2
`state_getStorage`	Single storage value by key. Params: `[storageKey, blockHash?]`	0.5
`state_getStorageHash`	Blake2-256 hash of a storage value. Params: `[storageKey, blockHash?]`	0.2
`state_getKeysPaged`	Paginated storage keys. Params: `[prefix, count, startKey?, blockHash?]`	1.0
`state_queryStorageAt`	Query multiple storage values at a single block. Params: `[keys[], blockHash?]`	1.5
`state_call`	Execute a runtime API function via WASM. Params: `[method, data, blockHash?]`	5.0

*At variants (e.g. state_getStorageAt, state_queryStorage) are also whitelisted; see the live midnight_listMethods output for the complete list.

Transaction pool

Method	Description	CU Cost
`author_pendingExtrinsics`	List pending extrinsics in the pool	1.0

Midnight-specific

Method	Description	CU Cost
`midnight_apiVersions`	Midnight API versions supported by this node	0.1
`midnight_contractState`	Full contract state by address. Reads entire contract storage including verification keys, state vars, coin holdings. Size proportional to contract complexity. Params: `[address, blockHash?]`	2.5
`midnight_ledgerVersion`	Midnight ledger version	0.1
`midnight_zswapStateRoot`	ZSwap protocol state root (Merkle commitment root, 33 bytes). Params: `[blockHash?]`	1.0

Sidechain, GRANDPA, BEEFY, MMR

sidechain_*, grandpa_*, beefy_*, and mmr_* read methods are also whitelisted. Use midnight_listMethods to enumerate them per deployment.

Examples

Get the finalized head

curl -X POST https://shroud.us/v1/midnight/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getFinalizedHead","params":[]}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xabc123..."
}

Get block by number

# Step 1: Get block hash
curl -X POST https://shroud.us/v1/midnight/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getBlockHash","params":[100]}'

# Step 2: Get block by hash
curl -X POST https://shroud.us/v1/midnight/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getBlock","params":["0xabc123..."]}'

Identify the chain

curl -X POST https://shroud.us/v1/midnight/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"system_chain","params":[]}'

Listing available methods

To see which methods the server allows, use the midnight_listMethods tool via JSON-RPC:

curl -X POST https://shroud.us/rpc \
  -H "Authorization: Bearer shroud_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools.call",
    "params": {
      "tool": "midnight_listMethods",
      "params": {}
    }
  }'

Differences from Shroud Tools

Feature	RPC Proxy (`/v1/midnight/rpc`)	Shroud Tools (`/rpc`)
Format	Raw Substrate JSON-RPC	Wrapped in `tools.call`
Methods	Only whitelisted Substrate methods	Shroud tool catalog
Decoding	Raw responses from node	Decoded extrinsics, events
Billing	Per-request CU	Per-tool CU
Use case	Low-level node access	High-level blockchain queries

Last modified: 08 May 2026