@cosmjs/json-rpc

JSON-RPC 2.0 protocol implementation

JSON-RPC 2.0 protocol implementation used by @cosmjs/tendermint-rpc for HTTP and WebSocket RPC communication.

npm install @cosmjs/json-rpc

JsonRpcClient

Sends JSON-RPC requests over a generic messaging connection.

Method	Parameters	Returns
constructor	connection: SimpleMessagingConnection<JsonRpcRequest, JsonRpcResponse>	JsonRpcClient
run	request: JsonRpcRequest	Promise<JsonRpcSuccessResponse>

interface SimpleMessagingConnection<Request, Response> {
  readonly responseStream: Stream<Response>;
  readonly sendRequest: (request: Request) => void;
}

JsonRpcClient uses the instantiation SimpleMessagingConnection<JsonRpcRequest, JsonRpcResponse>: the stream emits already-parsed responses, and sendRequest receives structured request objects (not strings).

Parsing Functions

Function	Parameters	Returns
parseJsonRpcResponse	data: unknown	JsonRpcResponse
parseJsonRpcSuccessResponse	data: unknown	JsonRpcSuccessResponse
parseJsonRpcErrorResponse	data: unknown	JsonRpcErrorResponse
parseJsonRpcRequest	data: unknown	JsonRpcRequest
parseJsonRpcId	data: unknown	JsonRpcId | null (returns null if no valid id is present)

Type Guards

Function	Parameters	Returns
isJsonRpcSuccessResponse	response: JsonRpcResponse	response is JsonRpcSuccessResponse
isJsonRpcErrorResponse	response: JsonRpcResponse	response is JsonRpcErrorResponse

import { parseJsonRpcResponse, isJsonRpcErrorResponse } from "@cosmjs/json-rpc";

const response = parseJsonRpcResponse(data);

if (isJsonRpcErrorResponse(response)) {
  console.error("RPC error:", response.error.message);
} else {
  console.info("Result:", response.result);
}

ID Generation

Function	Parameters	Returns
makeJsonRpcId	—	number (assignable to JsonRpcId)

Key Types

JsonRpcRequest

interface JsonRpcRequest {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId;
  readonly method: string;
  readonly params: JsonCompatibleArray | JsonCompatibleDictionary;
}

JsonRpcSuccessResponse

interface JsonRpcSuccessResponse {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId;
  readonly result: any;
}

JsonRpcErrorResponse

interface JsonRpcErrorResponse {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId | null;
  readonly error: JsonRpcError;
}

JsonRpcError

interface JsonRpcError {
  readonly code: number;
  readonly message: string;
  readonly data?: JsonCompatibleValue;
}

JsonRpcId

type JsonRpcId = number | string;

JsonRpcResponse

type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;

Error Codes

The jsonRpcCode object provides standard JSON-RPC 2.0 error codes:

Code	Constant	Description
-32700	parseError	Invalid JSON
-32600	invalidRequest	JSON is not a valid request
-32601	methodNotFound	Method does not exist
-32602	invalidParams	Invalid method parameters
-32603	internalError	Internal JSON-RPC error
-32000	jsonRpcCode.serverError.default	Server error (default slot of the -32000 to -32099 implementation-defined range)