chronik-client
v4.4.0
Published
A client for accessing the Chronik Indexer API
Readme
Chronik Indexer Client
Access Chronik Indexer via browser or Node.
Installation
npm install chronik-client
yarn add chronik-client
Usage
import { ChronikClient, ConnectionStrategy } from 'chronik-client';
// Create a Chronik client with Strategy
// ConnectionStrategy.ClosestFirst - Selects url based on latency
// ConnectionStrategy.AsOrdered - Uses url in the provided order
// If the first url is non-responsive it will cycle through the rest of the array.
const chronik = await ChronikClient.useStrategy(
ConnectionStrategy.ClosestFirst,
[
'https://yourFirstChronikServerUrl.com',
'https://yourSecondChronikServerUrl.com',
'https://yourThirdChronikServerUrl.com',
],
);
// Get Genesis block:
const block = await chronik.block(
'000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f',
);
// Get the first 11 blocks of the chain:
const blocks = await chronik.blocks(0, 10);
// Get SLP tx details:
const tx = await chronik.tx(
'0f3c3908a2ddec8dea91d2fe1f77295bbbb158af869bff345d44ae800f0a5498',
);
// Get token details for a given token ID
const tokenDetails = await chronik.token(
'0daf200e3418f2df1158efef36fbb507f12928f1fdcf3543703e64e75a4a9073',
);
const GENESIS_PK =
'04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc' +
'3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f';
// Get first page of tx history of the Genesis pubkey, most recent first:
const history = await chronik
.script('p2pk', GENESIS_PK)
.history(/*page=*/ 0, /*page_size=*/ 10);
// Get all UTXOs of the Genesis pubkey:
const utxos = await chronik.script('p2pk', GENESIS_PK).utxos();
// Listen to updates on scripts:
const ws = chronik.ws({
onMessage: msg => {
console.log('Got update: ', msg);
},
onConnect: () => {
// Reconnect (including pause/resume) re-sends whatever is already
// in ws.subs. Do not call subscribeTo* again here — that would
// record a second copy of each subscription.
},
onReconnect: e => {
// Fired before a reconnect attempt is made:
console.log('Reconnecting websocket, disconnection cause: ', e);
},
// Optional: ping the ws every 30s to reduce disconnects
keepAlive: true,
});
// Wait for WS to be connected:
await ws.waitForOpen();
// Subscribe to blocks
ws.subscribeToBlocks();
// Subscribe to scripts:
ws.subscribeToScript('p2pkh', 'b8ae1c47effb58f72f7bca819fe7fc252f9e852e');
// Unsubscribe:
ws.unsubscribeFromScript('p2pkh', 'b8ae1c47effb58f72f7bca819fe7fc252f9e852e');
// You may also subscribe to addresses, tokenIds, lokadIds, and plugins. See integration tests.Changelog
- 0.10.1 - Deprecate client-side ping keepAlive. Server-side is now available.
- 0.11.0 - Add support for
chronikInfo()method toChronikClientNode - 0.11.1 - Do not try next server if error is unrelated to server failure
- 0.12.0 - Add support for
block(hashOrHeight)andblocks(startHeight, endHeight)methods toChronikClientNode - 0.13.0 - Add support for
blockTxs(hashOrHeight, page, pageSize)andtx(txid)methods toChronikClientNode - 0.14.0 - Add support for
rawTx(txid)method toChronikClientNode - 0.15.0 - Add support for
scriptendpointshistory()andutxos()toChronikClientNode - 0.16.0 - Add support for
broadcastTxandbroadcastTxsendpoints toChronikClientNode - 0.17.0 - Add support for token proto to endpoints that return
Tx_InNodetoChronikClientNode - 0.18.0 - Add support for websocket connections to
ChronikClientNode - 0.19.0 - Add support for token data in tx inputs and outputs to
ChronikClientNode - 0.20.0 - Add support for calling script endpoints by address to
ChronikClientNode - 0.21.0 - Skipped as accidentally published 0.22.0 before diff approval at 0.21.1-rc.1
- 0.22.0 - Add support for
tokenIdendpoints and token data in utxos toChronikClientNode - 0.22.1 - Return
scriptkey for utxos fetched fromtokenIdendpoint - 0.23.0 - Add support for returning
TokenInfofromchronik.token(tokenId)calls toChronikClientNode - 0.24.0 - Support
subscribeToAddressandunsubscribeFromAddressmethods in theChronikClientNodewebsocket - 0.25.0 - Organize websocket subscriptions for
ChronikClientNodeunder object instead of array - 0.25.1 - Move
ecashaddrjsfrom dev dependency to dependency - 0.25.2 - Fix this package to work in the browser without requiring
Buffershim - 0.26.0 - Add
confirmedTxsandunconfirmedTxstoscriptendpoint - 0.26.1 - If websocket takes longer than 5s to connect, try the next ws
- 0.26.2 - Return type
numberfortimeFirstSeenfromchronik.token()endpoint inChronikClientNode - 0.27.0 - Support for
lokadIdendpoints and websocket subscriptions - 0.28.0 - Support for websocket subscriptions by
tokenID - 0.28.1 - Upgrading dependencies D16375
- 0.28.2 - Improve failoverProxy to switch servers on error state D16584
- 0.29.0 - Support for
pluginsendpoints:utxosandgroupsD16605 - 1.0.0 - (Breaking change) Deprecate NNG chronik and rename all
InNodeclasses and types D16627. Users may no longer importChronikClientNodeclass to run in-node chronik-client and must importChronikClient(which is no longer the NNG class). D16710 - 1.1.0 - Support websocket subscriptions to plugins D16783
- 1.2.0 - Support
history,confirmedTxs, andunconfirmedTxsmethods forpluginsendpoints D16786 - 1.3.0 - Support an avalanche invalidated websocket block message type and return extra block data for disconnected and avalanche invalidated blocks D16812
- 1.3.1 - Install
ecashaddrjsfrom npm before publishing to remove manual peer dependency D16815 - 1.4.0 - Add
isFinalkey toTxobject D17177 - 2.0.0 - (Breaking change) Change
authinGenesisInfoto hex string instead ofUint8Array, maintaining consistency with other API behavior D17194 - 2.1.0 - Add support for
validateRawTxendpoint D15631 - 2.1.1 - Upgrade to dependency-free
ecashaddrjsD17269 - 3.0.0 - Proto update;
atomsinstead ofamountandsatsinstead ofvalueD17650 - 3.0.1 - Patch
failoverProxyto recognize another type of server error D17814 - 3.1.0 - Add support for automatic node selection using
useStrategymethod D17913 - 3.1.1 - Fix WebSocket retry loop issues during disconnection D17974
- 3.2.0 - Add "UNKNOWN" token protocol type D18155
- 3.3.0 - Add support for
subscribetoTxidandunsubscribeFromTxidwebsocket methods D18251 - 3.4.0 - Add support for transactions finalization and invalidation websocket messages D18482
- 3.4.1 - Add
longas a dependency. This should be resolved as a dependency of protobufjs, but for some package managers (e.g.pnpm) this is having issues. D18831 - 3.5.0 - Add
pauseandresumemethods to support use ofchronik-clientwebsockets in mobile apps D18960 - 3.6.0 - Add new websocket subscription method
subscribeToTxsto listen to all txs on the network D18993 - 3.6.1 - Patch for CI publication including correct
ecashaddrjsdep D18997 - 3.7.0 - Add support for
unconfirmedTxsmethod to return mempool txs for a given chronik server D19050 - 4.0.0 - (Breaking change) Remove pagination params from
unconfirmedTxsmethods that do not actually support pagination; no change in behavior as these params were previously not working, but any callsites using them are now expected to throw or fail type checks D19059 - 4.1.0 - Add new methods
broadcastAndFinalizeTxandbroadcastAndFinalizeTxs. D19136 - 4.2.0 - Add new method
batchUtxosto fetch utxos for several scripts in a single request D19909 - 4.3.0 - Add new method
batchSummaryto fetch a summary of the history/utxos for several scripts in a single request D19983 - 4.3.1 - Fix reconnect re-subscription doubling every subscription and never restoring plugin subscriptions. Restore is send-only and automatic on socket open (including
pause()/resume()). D20536 - 4.3.2 - Close the websocket and reconnect when a frame fails to decode. An undecodable frame is no longer an unhandled rejection. D20775
- 4.3.3 - Patch bump to catch the latest
ecashaddrjsD20822 - 4.3.4 - Retry websocket reconnects with exponential backoff when every Chronik endpoint is down. Call
onErrorfor socket errors and failed reconnects.waitForOpenrejects if the handshake times out or the socket closes before it opens. D20878 - 4.4.0 - Throw
ChronikError, with the HTTPstatuscode, for error responses from a working Chronik server. The message is unchanged. D20906
