Open source GitHub repo: https://github.com/blocknative/sdk​

Quickstart

It should take less than 5 minutes to get going with the Blocknative Notify SDK.

Create a Blocknative Account

Go to the Account Dashboard at https://account.blocknative.com/ and setup an account with an email address. You will receive an email to confirm your account.

Create your API Key

On the Account Dashboard, create an API key with your choice of name using the API Keys link (https://account.blocknative.com/api-keys). API keys segment analytics data. Consider using different API keys for development, staging, and production releases.

Install the library using npm

npm install bnc-sdk

Initialize the Library

import blocknativeSdk from 'bnc-sdk'
import Web3 from 'web3'
import WebSocket from 'ws' // only neccessary in server environments
​
// create options object
const options = {
  dappId: 'Your dappId here',
  networkId: 1,
  transactionHandlers: [event => console.log(event.transaction)],
  ws: WebSocket // only neccessary in server environments
}
​
// initialize and connect to the api
const blocknative = blocknativeSdk(options)
​
// get the client index from initialized sdk
// clientIndex allows for separated notification channels
// and is passed in when tracking transactions or accounts
const { clientIndex } = blocknative

Track transactions

Send a transaction using web3.js and get the transaction hash while its processing. Let Notify know the hash and it will track its progress through the mempool and into a block.

// initialize web3
const web3 = new Web3(window.ethereum)
​
// get current account
const accounts = await web3.eth.getAccounts();
const address = accounts[0];
​
// create transaction options object
const txOptions = {
  from: address,
  to: "0x792ec62e6840bFcCEa00c669521F678CE1236705",
  value: "1000000"
}
​
// initiate a transaction via web3.js
web3.eth.sendTransaction(txOptions).on('transactionHash', hash => {
  // call with the clientIndex and the transaction hash of the
  // transaction that you would like to receive status updates for
  const { emitter } = blocknative.transaction(clientIndex, hash)
​
  // listen to some events
  emitter.on('txPool', transaction => {
    console.log(`Sending ${transaction.value} wei to ${transaction.to}`)
  })
​
  emitter.on('txConfirmed', transaction => {
    console.log('Transaction is confirmed!')
  })
​
  // catch every other event that occurs and log it
  emitter.on('all', transaction => {
    console.log(`Transaction event: ${transaction.eventCode}`)
  })

And you are live!

Screencasts

See how to get started with Notify SDK in this screencast:

Configuration Options

The following options object needs to be passed when initializing and connecting

const options = {
  dappId: String,
  networkId: Number,
  transactionHandlers: Array,
  ws: WebSocket
}

dappId - [REQUIRED]

Your unique API key that identifies your application. You can generate a dappId by visiting the Blocknative account page and creating a free account.

networkId - [REQUIRED]

The Ethereum network id that your application runs on. The following values are valid:

• 1 Main Network

• 3 Ropsten Test Network

• 4 Rinkeby Test Network

• 5 Goerli Test Network

• 42 Kovan Test Network

transactionHandlers - [OPTIONAL]

An array of functions that will each be called once for every status update for every transaction that is associated with this connection on a watched address or a watched transaction.

const handleTransactionEvent = event => {
  const {
    transaction, // transaction object
    emitterResult // data that is returned from the transaction event listener defined on the emitter
  } = event
  
  console.log(transaction)
}
​
const options = {
  // other options
  transactionHandlers: [handleTransactionEvent]
}

See the Transaction Object section for more info on what is included in the transaction parameter.

ws - [OPTIONAL]

If you are running the sdk in a server environment, there won't be a native WebSocket instance available for the sdk to use, so you will need to pass one in. You can use any WebSocket library that you prefer as long as it correctly implements the WebSocket specifications. We recommend ws.

Initialize and Connect

Import and initialize the SDK with the configuration options described above for client and server environments.

Client/Browser Environment

import blocknativeSdk from 'bn-sdk'
​
// create options object
const options = {
  dappId: 'Your dappId here',
  networkId: 1,
  transactionHandlers: [event => console.log(event.transaction)]
}
​
// initialize and connect to the api
const blocknative = blocknativeSdk(options)
​
// get the client index from initialized sdk
// clientIndex allows for separated notification channels
// and is passed in when tracking transactions and accounts
const { clientIndex } = blocknative

Server/Node.js Environment

import blocknativeSdk from 'bn-sdk'
import WebSocket from 'ws'
​
// create options object
const options = {
  dappId: 'Your dappId here',
  networkId: 1,
  transactionHandlers: [event => console.log(event.transaction)],
  ws: WebSocket
}
​
// initialize and connect to the api
const blocknative = blocknativeSdk(options)
​
// get the client index from initialized sdk
// clientIndex allows for separated notification channels
// and is passed in when tracking transactions and accounts
const { clientIndex } = blocknative

The returned instance has a clientIndex property which allows for multiple separated "channels" of communication on the one WebSocket connection. Another separate SDK instance can be created and the clientIndex property will be incremented. The Notify.js and Onboard.js libraries use this mechanism to maintain separate notification channels. The clientIndex value must be passed in to all calls to track transactions or watch accounts, so that the correct "channel" will be notified about the transaction event.

Notifications

Watch a Transaction Hash

Now that your application is successfully connected via a WebSocket connection to the Blocknative back-end, you can register transactions to watch for updates (notifications). Once you have initiated a transaction and have received the transaction hash, you can pass it in to the transaction function:

// initiate a transaction via web3.js
web3.eth.sendTransaction(txOptions).on('transactionHash', hash => {
  // call with the transaction hash of the transaction that you would like to receive status updates for
  const {
    emitter, // emitter object to listen for status updates
    details // initial transaction details which are useful for internal tracking: hash, timestamp, eventCode
  } = blocknative.transaction(clientIndex, hash)
})
​
​

The emitter is used to listen for status updates. See the Emitter Section for details on how to use the emitter object to handle specific transaction state changes.

The details object contains the initial transaction details which are useful for internal tracking.

If the library was initialized with transaction handlers, those handlers will also be called on each status change for the watched transaction.

Watch an Account Address

You can also register an account address to listen to any incoming and outgoing transactions that occur on that address using the account method:

// get the current accounts list of the user via web3.js
const accounts = await web3.eth.getAccounts()
​
// grab the primary account
const address = accounts[0]
​
// call with the address of the account that you would like to receive status updates for
const {
  emitter, // emitter object to listen for status updates
  details // initial account details which are useful for internal tracking: address
} = blocknative.account(clientIndex, address)

This will tell the Blocknative back-end to watch for any transactions that occur involving this address and any updates to the transaction status over time. The return object from successful calls to account will include an event emitter that you can use to listen for those events and a details object which includes the address that is being watched.

Log an Event

You may want to log an event that isn't associated with a transaction for analytics purposes. Events are collated and displayed in the developer portal and are segmented by your dappId. To log an event, simple call event with a categoryCode and an eventCode, both of which can be any String that you like:

blocknative.event({
  categoryCode: String, // [REQUIRED] - The general category of the event
  eventCode: String // [REQUIRED] - The specific event
})

Emitter

The emitter object is returned from calls to account and transaction and is used to listen to status updates via callbacks registered for specific event codes.

// register a callback for a txPool event
emitter.on("txPool", transaction => {
  console.log("Transaction is pending")
})

The first parameter is the eventCode string of the event that you would like to register a callback for. For a list of the valid event codes, see the event codes section.

The second parameter is the callback that you would like to register to handle that event and will be called with a transaction object that includes all of the relevant details for that transaction. See the Transaction Object section for more info on what is included.

Any data that is returned from the listener callback for transaction emitters will be included in the object that the global transactionHandlers are called with under the emitterResult property.

Transaction Object

The callback that is registered for events on an emitter or included in the transactionHandlers array will be called with the following transaction object:

{
  status: String, // current status of the transaction
  hash: String,
  to: String,
  from: String,
  gas: Number,
  gasPrice: String,
  nonce: Number,
  value: String,
  eventCode: String,
  blockHash: String,
  blockNumber: Number,
  input: String,
  transactionIndex: Number,
  r: String,
  s: String,
  v: String,
  counterParty: String, // address of the counterparty of the transaction when watching an account
  direction: String, // the direction of the transaction in relation to the account that is being watched ("incoming" or "outgoing")
  watchedAddress: String, // the address of the account being watched
  originalHash: String, // if a speedup or cancel status, this will be the hash of the original transaction
  asset: String, // the asset that was transfered
  contractCall: { // if transaction was a contract call otherwise undefined
    contractAddress: String,
    contractType: String,
    methodName: String,
    params: {
      // params that the contract method was called with
    }
  }
}

Internal Transactions

The SDK will send confirmednotifications when a watchedAddress is detected in the internal transactions of a contract call. In this case, the confirmed transaction object will include details of the internal transactions and balance changes resulting from those internal transactions. Fields are not ordered.

"internalTransactions": [],
"netBalanceChanges": Object

The internalTransactions array contains details on each internal transaction executed by the contract call of the parent (main) transaction. Fields are not ordered.

"internalTransactions": [
  {      
    "type": String,
    "from": String,
    "to": String,
    "input": String,
    "gas": Number,
    "gasUsed": Number,
    "value": String,
    "contractCall": Object (optional, contains an additional param 'contractAlias' which will be the symbol of the token if this is an erc20 transfer or transferFrom)
  },
  ...
]

The netBalanceChanges object contains details of all the balance changes resulting from the internal transactions details in the internalTransactions array.

"netBalanceChanges": {
    "<address>": [
      {
        "delta": String,
        "asset": {
          "type": String,
          "symbol": String
        },
        "breakdown": [
          {
            "counterparty": Atring,
            "amount": String
          }
        ]
      }
    ],
    ...
  }

Event Codes

The following is a list of event codes that are valid, and the events that they represent:

• all: Will be called for all events that are associated with that emitter. If a more specific listener exists for that event, then that will be called instead. This is useful to catch any remaining events that you haven't specified a handler for

• txSent: Transaction has been sent to the network

• txPool: Transaction is in the mempool and is pending

• txConfirmed: Transaction has been mined

• txFailed: Transaction has failed

• txSpeedUp: A new transaction has been submitted with the same nonce and a higher gas price, replacing the original transaction

• txCancel: A new transaction has been submitted with the same nonce, a higher gas price, a value of zero and sent to an external address (not a contract)

• txDropped: Transaction was dropped from the mempool without being added to a block

Get Started Today

Sign up for a free Blocknative Account at https://account.blocknative.com/ with your work email address.

If you have any questions, connect with the team on our discord​