npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

chainweb

v2.0.4

Published

Javascript bindings for the Kadena Chainweb API

Downloads

697

Readme

High level Javascript bindings for the Kadena Chainweb REST API.

This package does not include the Pact REST API endpoints. High level bindings for the Pact API are provided by the pact-lang-api package.

API Documentation

Usage Examples

const chainweb = require('chainweb');

Common parameters:

  • network: the Kadena Chainweb network identifier. Default is mainnet01.
  • host: the Chainweb API host URL, including the schema and possibly the port. Default is https://api.chainweb.com.

Currently, no authentication or extra headers are supported. If you need these features, you may request support by submitting an new issue in the Github repository.

Some functions require a chainId parameter (or an array of chain IDs). Chain IDs should be provided as numbers from the set of supported chains of the respective network. There is no default value.

When a depth parameter is required, a value of 3 or larger is a save choice.

Functions return items in order ascending by block height. Because the server usually returns items in reverse order, functions buffer all items from possibly several pages, which can take some time. When fetching larger numbers of items it is recommended to use the functions in the package iteratively and possibly also asynchronously in order to increase performance.

Cuts

chainweb.cut.peers().then(x => console.log("Cut Peers:", x));
chainweb.cut.current().then(x => console.log("Current Cut:", x));

Chain Items

Chain items only include items from the currently winning branch of the chain. Orphaned blocks from past forks are not included. In order to avoid retrieving items from a currently winning fork that is orphaned later on it is recommended to only retrieve confirmed items by using an appropriate the depth parameter.

There are functions for three kinds of chain items:

  • Headers: these are just the block headers. These functions are generally the most efficient.
  • Blocks: these include the block headers and the block payloads, including transaction outputs. Querying payloads with outputs requires an extra round-trip.
  • Transactions: these are just the transactions along with the transaction output. Transactions from various blocks are flattened into a single array or stream. Each item contains a height property that indicates the block height at which it occurred.
  • Events: these are just the events from transaction outputs. Events from various blocks are flattened into a single array or stream. Each item contains a height property that indicates the block height at which it occurred.

Block Chain Items By Height

chainweb.header.height(0, 1000000).then(x => console.log("Header:", x));
chainweb.block.height(0, 1000000).then(x => console.log("Block:", x));
chainweb.transaction.height(0, 1000000).then(x => console.log("Transactions:", x));
chainweb.event.height(0, 1000000).then(x => console.log("Events:", x));

The parameters, in order, are: chain id and block height.

Block Chain Items By Block Hash

const bh = 'k0an0qEORusqQg9ZjKrxa-0Bo0-hQVYLXqWi5LHxg3k';
chainweb.header.blockHash(0, bh).then(x => console.log("Header:", x));
chainweb.block.blockHash(0, bh).then(x => console.log("Block:", x));
chainweb.transaction.blockHash(0, bh).then(x => console.log("Transactions:", x));
chainweb.event.blockHash(0, bh).then(x => console.log("Events:", x));

The parameters, in order, are: chain id and block hash.

Recent Block Chain Items

These functions return items from recent blocks in the block history starting at a given depth.

The depth parameter is useful to avoid receiving items from orphaned blocks.

chainweb.header.recent(0, 3, 10).then(x => console.log("Headers:", x));
chainweb.block.recent(0, 3, 10).then(x => console.log("Blocks:", x));
chainweb.transaction.recent(0, 3, 50).then(x => console.log("Transactions:", x));
chainweb.event.recent(0, 3, 1000).then(x => console.log("Events:", x));

The parameters, in order, are: chain id, depth, and maximum number of returned items.

Ranges of Block Chain Items

These functions query items from a range of block heights and return the result as an array.

chainweb.header.range(0, 1500000, 1500010).then(x => console.log("Headers:", x));
chainweb.block.range(0, 1500000, 1500010).then(x => console.log("Blocks:", x));
chainweb.transaction.range(0, 1500000, 1500010).then(x => console.log("Transactions:", x));
chainweb.event.range(0, 1500000, 1500010).then(x => console.log("Events:", x));

The parameters, in order, are: chain id, start height, and end height.

Streams

Streams are backed by EventSource clients that retrieve header update events from the Chainweb API.

The depth parameter is useful to avoid receiving items from orphaned blocks.

The functions buffer, filter, and transform the original events and generate a stream of derived items to which a callback is applied.

The functions also return the underlying EventSource object, for more advanced low-level control.

const chains = [0,1,9];

const hs = chainweb.header.stream(2, chains, console.log);
const bs = chainweb.block.stream(2, chains, console.log);
const ts = chainweb.transaction.stream(2, chains, x => { console.log(x); });
const es = chainweb.event.stream(2, chains, console.log);

The parameters, in order, are: depths, included chains, and a function that is called for each item in the stream.

Streams are online and only return items from blocks that got mined after the stream was started. They are thus useful for prompt notification of new items. In order of exhaustively querying all, including old, items, one should also use range or recent queries for the respective type of item.

Example Values

Example of a block object:

{
  header: {
    creationTime: 1617709987033643,
    parent: 'xv73bXWz1gnrqTisA_gPk1uQsAB5mbpcc1K28hbc1-g',
    height: 1510411,
    hash: 'uq_j7n0Oi_kn_MOCzCnab5ceJoTh1107ovP6sEupL_g',
    chainId: 14,
    weight: 'ANTVgl6hNGp2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
    featureFlags: 0,
    epochStart: 1617707264590744,
    adjacents: {
      '4': 'QjY3cD3SI3ZXFLJSEBs9vQ4inE6kttzloHr7Xw7Jb1Q',
      '13': 'pVCx1m9vdwkUuL2IY1a4YFH5pR26LYuDlvTB5EET1lc',
      '15': 'suYkkMMTC91ezPrL0lWPJfb4jMdPwDrAZ5QDbTHa094'
    },
    payloadHash: 'uRNlKTYUX8le57PUU7PegH6R4sQ_BRcbyM_8X0SmqGU',
    chainwebVersion: 'mainnet01',
    target: 'HaIMMhav3qFjTsesHlofQs1qXtA03KwCoAkAAAAAAAA',
    nonce: '5090157328105015810'
  },
  payload: {
    transactions: [],
    minerData: {
      account: '6d87fd6e5e47185cb421459d2888bddba7a6c0f2c4ae5246d5f38f993818bb89',
      predicate: 'keys-all',
      'public-keys': [Array]
    },
    transactionsHash: 'PZA7NIdgDatkTRZ8AOSI7dOOJzhGAhe7JkovnMp1xks',
    outputsHash: 'RJVkqVIwW2U6na2pExx866Ld_q2Hw0ZxHC_PScDpsZo',
    payloadHash: 'uRNlKTYUX8le57PUU7PegH6R4sQ_BRcbyM_8X0SmqGU',
    coinbase: {
      gas: 0,
      result: [Object],
      reqKey: 'Inh2NzNiWFd6MWducnFUaXNBX2dQazF1UXNBQjVtYnBjYzFLMjhoYmMxLWci',
      logs: 'NI1wv5IbNktRCAQXB4NNuiZHqzyvhjXIrndkgEGLtUg',
      metaData: null,
      continuation: null,
      txId: 671318
    }
  }
}

Example of a transaction object:

{
  transaction: {
    hash: 'h2oKMgCpT_QOGLL-vZj59gCn9bvp7_UW3_tufsJM_-c',
    sigs: [ [Object] ],
    cmd: {
      networkId: 'mainnet01',
      payload: [Object],
      signers: [Array],
      meta: [Object],
      nonce: '"\\"2021-04-06T19:03:18.773Z\\""'
    }
  },
  output: {
    gas: 392,
    result: { status: 'success', data: [Object] },
    reqKey: 'h2oKMgCpT_QOGLL-vZj59gCn9bvp7_UW3_tufsJM_-c',
    logs: 'Go2w3KEnTqjgry8l5ucz2u3nmVGJN6sEdxI6YGiTF7Q',
    metaData: null,
    continuation: {
      executed: null,
      pactId: 'h2oKMgCpT_QOGLL-vZj59gCn9bvp7_UW3_tufsJM_-c',
      stepHasRollback: false,
      step: 0,
      yield: [Object],
      continuation: [Object],
      stepCount: 2
    },
    txId: 2026960
  },
  height: 1511402

Example of an event object:

{
  params: [
    '4677a09ea1602e4e09fe01eb1196cf47c0f44aa44aac903d5f61be7da3425128',
    'f6357785d8b147c1fac66cdbd607a0b1208d62996d7d62cc92856d0ab229bea2',
    10462.28
  ],
  name: 'TRANSFER',
  module: { namespace: null, name: 'coin' },
  moduleHash: 'ut_J_ZNkoyaPUEJhiwVeWnkSQn9JT9sQCWKdjjVVrWo',
  height: 1511601
}