JSON-RPC

Overview

JSON-RPC is a remote procedure call protocol that represents method requests, results, errors, notifications, and identifiers as JSON objects. It is used to provide a lightweight, transport-independent way to call node or service methods. It differs from REST, which commonly models resources and HTTP semantics instead of named procedures.

A typical implementation works as follows: A client sends a jsonrpc version, method, optional params, and ID; the server returns a matching result or error, while notifications omit a response. Testing JSON-RPC should include provider disagreement, reorganization or indexing delay, malformed data, and an unavailable node when relevant to the method.

Important failure modes include wrong parameter order, unsupported methods, reused identifiers, batch ambiguity, and exposing privileged node methods. These failures can create errors or security risk. A JSON-RPC client should validate network identity, units, encoding, and method semantics before acting on provider data.

Core controls require teams to validate version and parameters, restrict methods, authenticate access, limit batches, preserve numeric precision, and correlate every response. Common risks include wrong parameter order and unsupported methods.

Operational evidence should include endpoint, method, request ID, parameter hash, result or error code, latency, and node version. JSON-RPC should be documented alongside RPC Endpoint, API Call, and API Error Object. When nodes disagree during JSON-RPC, the application should preserve both observations and defer irreversible action until the authoritative chain state is clear.

The JSON-RPC recovery procedure should distinguish a rejected RPC call from a transaction that was broadcast but not acknowledged. For JSON-RPC, the client should retain chain, method, block or transaction reference, provider response, and the final on-chain observation.