JSON-RPC & Reactive Streams

Understanding the JSON-RPC protocol and stream utilities used by CosmJS transports

CosmJS uses JSON-RPC 2.0 for all transport-level communication and xstream-based reactive streams for event subscriptions. These are low-level building blocks that most applications interact with indirectly through higher-level clients.

JSON-RPC Protocol

All transports use the JSON-RPC 2.0 protocol, implemented in @cosmjs/json-rpc. The package provides:

• Type definitions — JsonRpcRequest, JsonRpcSuccessResponse, JsonRpcErrorResponse
• Parsing — parseJsonRpcResponse() validates and type-guards responses
• ID generation — makeJsonRpcId() produces incrementing numeric IDs
• Error codes — standard JSON-RPC error codes (parseError, invalidRequest, methodNotFound, etc.)

You generally don’t interact with this package directly — the RPC clients handle serialization and parsing internally.

Reactive Streams

The @cosmjs/stream package provides utilities built on xstream for working with event streams:

Utility	Description
firstEvent(stream)	Resolves with the first event from a stream
toListPromise(stream, count)	Collects count events into an array
fromListPromise(promise)	Creates a stream from a promise of an iterable
concat(...streams)	Concatenates streams with buffering
dropDuplicates(keyFn)	Deduplicates stream events by key
ValueAndUpdates	Synchronous current value + update stream (used for connection status)
DefaultValueProducer	Producer that holds a current value and emits updates
Reducer	Reduces a stream into accumulated state

These are primarily used internally by the WebSocket transport and subscription system, but they’re available if you need to compose or transform event streams.