Install

npm install bnc-notify

Quick Start

import Notify from "bnc-notify"
import web3 from "./web3"
​
const options = {
  dappId: "Your dappId here",
  networkId: 1,
  transactionEvents: event =>
    console.log("Transaction Event:", event.transaction)
}
​
// initialize notify
const notify = Notify(options)
​
// send a transaction and get the hash
const transactionHash = await web3.eth.sendTransaction({
  to: "0xa1C5E103Dfd56CBC3f6B6a526d2044598fD1cf1F",
  value: 100000000000000,
  from: "0x54c43790da9F8bd5d9bef06f56f798Eb16c53A91"
})
​
// pass the hash in to notify to receive "post-flight" notifications
const { emitter } = notify.hash(transactionHash)
​
// listen to transaction events
emitter.on("txSent", console.log)
emitter.on("txPool", console.log)
emitter.on("txConfirmed", console.log)
emitter.on("txSpeedUp", console.log)
emitter.on("txCancel", console.log)
emitter.on("txFailed", console.log)
emitter.on("all", console.log)

Initialization

import Notify from "bn-notify"
​
const options = {
  dappId: "Your dappId here",
  networkId: 1,
  transactionEvents: event =>
    console.log("Transaction Event:", event.transaction)
}
​
const notify = Notify(options)

Options

const options = {
  dappId: String,
  networkId: Number,
  transactionEvents: Function
}

dappId - [REQUIRED]

Your unique apiKey that identifies your application. You can generate a dappId by visiting the Blocknative account page and create 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

transactionEvents - [OPTIONAL]

The function defined for the transactionEvents parameter will be called once for every status update for every transaction that is associated with a watched address or a watched transaction. This is useful as a global handler for all transactions and status updates. The callback is called with the following object:

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

Notifications

hash

To get notifications for every status that occurs after sending a transaction ("post-flight"), use the hash function:

// send the transaction using web3.js and get the hash
const hash = await web3.eth.sendTransaction(txOptions)
​
// pash the hash in to notify.hash
const { emitter } = notify.hash(hash)

Check out the Emitter Section for details on the emitter object

transaction

To get notifications for every status that occurs for the full transaction lifecycle ("pre-flight" and "post-flight"), use the transaction function:

const { emitter, result } = notify.transaction({
  estimateGas: Function,
  gasPrice: Function,
  balance: String,
  txDetails: {
    to: String,
    value: Number || String
  },
  sendTransaction: Function
})

result is a promise that resolves with the id of the transaction or rejects with an error if there was an error initiating the transaction. The id is useful for when you would like to initiate the transaction yourself and didn't pass a sendTransaction function in to transaction. You can then send the transaction yourself, receive the hash, and then call notify.hash(hash, id). By passing in the id to hash you enable notify to link the preflight notifications to the post send transaction notifications, ensuring a consistent UX.

The transaction function takes an object as the argument which allows you to progressively opt in to which checks and corresponding notifications that you would like during the "pre-flight" phase of the transaction lifecycle. Below is a list of the parameters, what is expected for each of those parameters, and the corresponding notifications you will get by including those parameters:

estimateGas - [balance check notification]

The estimateGas function must return a Promise that resolves with a String that is the gas estimate in wei. This function can vary depending on whether it is a contract transaction or just a regular send transaction call.

gasPrice - [balance check notification]

The gasPrice function must return a Promise that resolves with a String that is the gas price in wei.

balance - [balance check notification]

The users' balance in wei

txDetails - [repeat transaction check notification]

The txDetails object includes a to parameter which is the address the transaction is being sent to and the value parameter, which is the value of the transaction.

sendTransaction - [send transaction error, approval reminder, and stall notifications]

The sendTransaction function must return a Promise that resolves with a String that is the transaction hash.

config

There are some configuration options available:

notify.config({
  darkMode: Boolean, // (default: false)
  mobilePosition: String, // 'top', 'bottom' (default: 'top')
  desktopPosition: String, // 'bottomLeft', 'bottomRight', 'topLeft', 'topRight' (default: 'bottomRight')
  txApproveReminderTimeout: Number, // (default: 20000)
  txStallPendingTimeout: Number, // (default: 20000)
  txStallConfirmedTimeout: Number // (default: 90000)
})

Emitter

The emitter object returned is used to listen for transaction events:

emitter.on("txRepeat", transaction => {
  // return false for no notification
  // no return (or return undefined) to show default notification
  // return custom notification object to show custom notifications, can return all or one of the following parameters:
  return {
    type: String, // ['hint' (gray), 'pending' (yellow), 'success' (green), 'error' (red)]
    message: String, // The message you would like to display
    autoDismiss: Number // The number of milliseconds before the notification automatically hides or false for no autodismiss
  }
})
​
// You can also use the `all` event to register a listener for all events for that transaction. The `all` listener will only be called if there isn't a listener defined for the particular event:
​
emitter.on("all", transaction => {
  // called on every event that doesn't have a listener defined on this transaction
})

Event Codes

The following event codes are valid events to listen to on the transaction emitter:

• txRequest: Transaction has been initiated and is waiting approval from the user

• txRepeat: Transaction has the same value and to address, so may be a repeat transaction

• txAwaitingApproval: A previous transaction is awaiting approval

• txConfirmReminder: Transaction has not been confirmed after timeout

• txStallPending: Transaction has not been received in the mempool after timeout

• txStallConfirmed: Transaction has been in the mempool for longer than the timeout

• txError: An error has occurred with the transaction

• txSendFail: The user rejected the transaction

• txUnderpriced: The gas was set too low for the transaction to complete

• 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. NOTE: Transaction could reappear in mempool.

Transaction Object

The callback that is registered for events on the emitter will be called with the following transaction object:

{
  status: String, // current status of the transaction
  hash: String, // transaction hash
  to: String, // the address the transaction is being sent to
  from: String, // the address the transaction is being sent from
  gas: Number, // the gas in wei
  gasPrice: String, // the gasPrice in wei
  nonce: Number, // the nonce of the transaction
  value: String, // the value being sent
  eventCode: String, // the event code for this status
  blockHash: String, // the hash of the block that this transaction was included in
  blockNumber: Number, // the block number of the block that this transaction was included in
  input: String, // hex string of the input data
  transactionIndex: Number, // same as the nonce
  r: String, // transaction signature
  s: String, // transaction signature
  v: String, // transaction signature
  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, // the address of the contract that has been called
    contractType: String, // the contract type eg: ERC20, ERC721
    methodName: String, // the name of the method that was called
    params: {
      // params that the contract method was called with
    }
  }
}