RPC Client Interface

Understanding the transport layer between CosmJS clients and blockchain nodes

CosmJS communicates with Cosmos SDK chains through Tendermint/CometBFT RPC. The transport layer sits between the high-level clients (StargateClient, CosmWasmClient) and the blockchain node, handling request encoding, response parsing, connection management, and event subscriptions.

All transports implement the same RpcClient interface from @cosmjs/tendermint-rpc, so the upper layers are transport-agnostic.

RpcClient & RpcStreamingClient

Every transport implements at least RpcClient:

interface RpcClient {
  readonly execute: (request: JsonRpcRequest) => Promise<JsonRpcSuccessResponse>;
  readonly disconnect: () => void;
}

Transports that support event subscriptions additionally implement RpcStreamingClient:

interface RpcStreamingClient extends RpcClient {
  readonly listen: (request: JsonRpcRequest) => Stream<SubscriptionEvent>;
}

You can check at runtime with instanceOfRpcStreamingClient(client).

Automatic Transport Selection

When you call StargateClient.connect(endpoint) or connectComet(endpoint), the transport is selected based on the URL protocol:

Endpoint	Transport
http://... or https://...	HttpClient
ws://... or wss://...	WebsocketClient
HttpEndpoint object	HttpClient (always)

// HTTP transport (default for most use cases)
const client = await StargateClient.connect("https://rpc.my-chain.network");

// WebSocket transport (needed for subscriptions)
const client = await StargateClient.connect("wss://rpc.my-chain.network");

Manual Transport Configuration

The automatic connect() methods don’t expose transport-level options like timeouts or batching. For full control, construct the RPC client manually and pass it through the create() factory:

import { StargateClient } from "@cosmjs/stargate";
import { Comet38Client, HttpClient } from "@cosmjs/tendermint-rpc";

// HTTP with 15-second timeout
const rpcClient = new HttpClient("https://rpc.my-chain.network", 15_000);
const cometClient = Comet38Client.create(rpcClient);
const client = StargateClient.create(cometClient);

import { StargateClient } from "@cosmjs/stargate";
import { Comet38Client, HttpBatchClient } from "@cosmjs/tendermint-rpc";

// Batched HTTP with custom options
const rpcClient = new HttpBatchClient("https://rpc.my-chain.network", {
  batchSizeLimit: 10,
  dispatchInterval: 50,
  httpTimeout: 15_000,
});
const cometClient = Comet38Client.create(rpcClient);
const client = StargateClient.create(cometClient);

When using manual transport configuration, you need to know the CometBFT version of your target chain. Use Comet38Client for CometBFT 0.38, Comet1Client for CometBFT 1.x, or Tendermint37Client for Tendermint 0.37. If you’re not sure, use connectComet() for auto-detection — though this only accepts an endpoint string or HttpEndpoint, not a pre-built RPC client.

Package Summary

Package	Role
@cosmjs/tendermint-rpc	RPC client implementations (HttpClient, HttpBatchClient, WebsocketClient) and CometBFT client wrappers
@cosmjs/json-rpc	JSON-RPC 2.0 types, parsing, and ID generation
@cosmjs/socket	WebSocket wrapper with reconnection, queueing, and connection status
@cosmjs/stream	Reactive stream utilities (xstream-based)