Skip to main content
Last updated

Chainweb streaming client

Kadena Chainweb client libraries are application programming interfaces that provide TypeScript-based calls for interacting with Chainweb nodes on the Kadena network. The chainweb-stream-client for browsers and node.js enables you to stream account, module, and event transactions, including their confirmation depth.

The chainweb-stream client introduces and normalizes the following features across environments:

  • Reconnect with exponential backoff
  • Initial connection timeout
  • Stale connection detection
  • Transaction confirmation status classification (unconfirmed/confirmed)
  • Server/client configuration compatibility checks

Status

Alpha version / unstable.

Install

You can install this package with npm or yarn.

To install using npm, run the following command:

sh
npm install @kadena/chainweb-stream-client
sh
npm install @kadena/chainweb-stream-client

To install using yarn, run the following command:

sh
yarn add @kadena/chainweb-stream-client
sh
yarn add @kadena/chainweb-stream-client

Usage

js
import { ChainwebStreamClient } from '@kadena/chainweb-stream-client'; const client = new ChainwebStreamClient({  network: 'mainnet01',  type: 'event',  id: 'coin',  host: 'http://localhost:4000/',}); client.on('confirmed', (txn) => console.log('confirmed', txn)); client.connect();
js
import { ChainwebStreamClient } from '@kadena/chainweb-stream-client'; const client = new ChainwebStreamClient({  network: 'mainnet01',  type: 'event',  id: 'coin',  host: 'http://localhost:4000/',}); client.on('confirmed', (txn) => console.log('confirmed', txn)); client.connect();

Find more detailed examples under src/examples.

Constructor options

KeyRequiredDescriptionExample Values
networkYesChainweb networkmainnet01/testnet04/...
typeYesTransaction type to stream (event/account)event/account
idYesAccount ID or module/event namek:abcdef01234..
hostYesChainweb-stream backend URLhttp://localhost:4000
limitNoInitial data load limit100
connectTimeoutNoConnection timeout in ms10_000
heartbeatTimeoutNoStale connection timeout in ms30_000
maxReconnectsNoHow many reconnections to attempt before giving up5
confirmationDepthNoHow many confirmations for a transaction to be considered final6

Ensure configuration compatibility

Make sure that your client and server confirmationDepth values are compatible.

If your client confirmationDepth is larger than the server's, the confirmed event will never fire. The client will automatically detect this condition, emit an error event and disconnect.

If your client's configured network does not match the server's, the client will emit an error event and disconnect.

If your client heartbeatTimeout is smaller than the server heartbeat interval, the client will automatically adapt its heartbeat timeout to 2500ms larger than the server value.

Handle temporary and permanent connection failures

When the connection is interrupted or determined to be stale (no heartbeats received within the heartbeatTimeout interval), a reconnection attempt will be made (up to maxReconnects times.)

It is recommended to handle the fired will-reconnect and error events.

Events

ChainwebStreamClient is an EventEmitter. You can subscribe to the following events using .on('event-name', callback).

You can look up named types in src/types.ts.

connect

Emitted when the connection to the backend is first established. Reconnections to not fire this event, see reconnect instead.

Callback type: () => void

reconnect

Emitted when a reconnection is established. If a connection is dropped or intentionally killed (e.g. due to staleness/heartbeat timeout) the client will attempt reconnections at exponential intervals.

Callback type: () => void

confirmed

Emitted when a confirmed transaction is received from the backend. Confirmation depends on the CONFIRMATION_DEPTH

Callback type: (txn: ITransaction) => void

unconfirmed

Emitted when an unconfirmed transaction is received from the backend. Multiple unconfirmed events will be fire for the same transaction, as each time the backend detects a confirmation depth update, it will send the data again with the latest confirmation depth.

Hint: You can rely on the .meta.id value to de-duplicate the underlying unconfirmed transactions

Callback type: (txn: ITransaction) => void

heights

Emitted when a heights event is received by the server. This carries the maximum height as seen from stream-server's corresponding chainweb-data. This event is mostly intended for calculating minheight when reconnecting, but the event itself is exposed to users in case they have use cases beyond that, such as detecting a stalled cw-data.

Callback type: (maxChainwebDataHeight: number) => void

data

Emitted when any transaction payload is received (unconfirmd and confirmed.)

warn

Emitted when the client encounters a retryable error, such as a stale connection that will be disconnected and retried.

Callback type: (message: string) => void

error

Emitted when the client encounters a non-retryable error, such as when connection retries are exhausted.

Callback type: (message: string) => void

will-reconnect

Emitted when the client encounters an error that will be retried, signaling intent to reconnect.

Callback type: ({ attempts: number, timeout: number, message: string }) => void

debug

Developer event emitted whenever anything significant happens. You can attach a console log to see what is going on internally if you are encountering unexpected behaviors.

Callback type: (dbg: IDebugMsgObject) => void