Notify (older version)
Client library for a full notification UI experience. Powered by our Mempool API.
We've upgraded Notify with a modern look & feel and added it to web3-onboard. You can access the latest version on https://onboard.blocknative.com/ as part of the core package.
Sample Notifications from Notify v1 (older version)
To see the notify.js library in action, checkout the code sandboxes at the end of this documentation or see the latest on the open source demo site at https://reactdemo.blocknative.com/.
It should take less than 5 minutes to get going with Blocknative Notify.
Setup your Blocknative account at https://explorer.blocknative.com/account?signup=true using an email address. You will receive an email to confirm your account. You can then go to your account page at https://explorer.blocknative.com/account.
On your Account page, create a new API key with your choice of name using the Add new API Key button on the top right. Blocknative will create a default API key for you but it is recommended you create your own as API keys segment analytics data. Consider using different API keys for development, staging, and production releases.
Add new API key button on the Account page
npm install bnc-notify
import Notify from "bnc-notify"
var notify = Notify({
dappId: apiKey, // [String] The API key created by step one above
networkId: networkId // [Integer] The Ethereum network ID your Dapp uses.
});
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.
// get current account
const accounts = await web3.eth.getAccounts();
const address = accounts[0];
// send the transaction using web3.js and get the hash
web3.eth.sendTransaction({
from: address,
to: "0x792ec62e6840bFcCEa00c669521F678CE1236705",
value: "1000000"})
.on('transactionHash', function(hash){
// pass the hash to notify to track it
notify.hash(hash)
};
Sample Notifications
For an example of a basic React demo integration of both Notify.js and Onboard.js, checkout the GitHub repo:
https://github.com/blocknative/onboard-notify-react
and the live demo:
See the above Quickstart guide in a screencast:
Notify.js Quickstart Screencast
See how to add and customize advanced notifications to your Dapp:
Add and Customize Advanced Notifications
import Notify from "bnc-notify"
const options = {
dappId: String,
system: String
networkId: Number,
onerror: Function
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)
transactionHandler: Function,
clientLocale: String, // (default: 'en')
notifyMessages: Object
}
const notify = Notify(options)
Your unique api key that identifies your application. You can generate a dappId by visiting the Blocknative account page and create a free account.
The blockchain system that you would like to track transactions on. Currently supported systems are
'bitcoin' and 'ethereum'.The network id that your application runs on. The following values are valid:
Ethereum
1Main Network3Ropsten Test Network4Rinkeby Test Network5__ Goerli Test Network42Kovan Test Network100xDai POA Network137Polygon Matic Main Network
A function to catch any errors that Notify does not handle internally such as event rate limit errors.
Boolean value sets notification rendering to use light text on dark background. Default is
false.String value sets where notifications appear on mobile devices. Value must be either
top or bottom. Default is top.String value sets where notifications appear on desktop devices. Value must be
bottomLeft, bottomRight, topLeft, or topRight. Default is bottomRight.Number value sets time to wait until approval reminder notification is presented. This notifications reminds user to confirm/approve a transaction for processing by the wallet. Default is
20000 milliseconds (20 seconds).Number value sets time to wait until stall notification is presented if transaction is not detected in the
txPool. Default is 20000 milliseconds (20 seconds).Number value sets time to wait until stall notification is presented if transaction is not confirmed in a block. Default is
90000 milliseconds (90 seconds).The function defined for the
transactionHandler 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:{
emitterResult: Any, // The value that was returned from the emitter for this transaction
transaction: TransactionObject // See below for details
}
Sets the locale for internationalization within notify. Defaults to English (
'en'). See the i18n section for more details.An object that defines all of the transaction messages. Can be used to customize the default messages, and can also be used to add multiple language support for transaction notifications. See the i18n section for more details.
To get notifications for every status that occurs after sending a transaction ("post-flight"), use the
hash function:// Ethereum
// send the transaction using web3.js and get the hash
web3.eth.sendTransaction(txOptions).on("transactionHash", hash => {
// pash the hash in to notify.hash
const { emitter } = notify.hash(hash)
})
// Bitcoin
const { emitter } = notify.hash(txid)
You can register an address with Notify to display notifications for all incoming and outgoing transactions that occur on that account by using the
account function:// Etherum
const accounts = await provider.enable()
// register address for all transactions that occur on the user's account
const { emitter } = notify.account(accounts[0])
// Bitcoin
const { emitter } = notify.account(address)
To get notifications for every status that occurs for the full transaction lifecycle ("pre-flight" and "post-flight"), use the
transaction function:The transaction function only applies to Ethereum transactions
const { emitter, result } = notify.transaction({
estimateGas: Function,
gasPrice: Function,
balance: String,
txDetails: {
to: String,
value: Number || String
},
sendTransaction: Function,
contractCall: {
methodName: String,
params: Array
}
})
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
weitxDetails - [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.contractCall - [repeat transaction check notification]The
contractCall object includes a methodName parameter which is the name of the method on the contract being called and the params parameter is the parameters that the contract method was called with.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.You may want to trigger a notification for a custom event that may not be related to a transaction. You can use the
notification function to do that:const notificationObject = {
eventCode: "dbUpdate"
type: "pending",
message: "Updating the database with your information"
}
const { update, dismiss } = notify.notification(notificationObject)
//.... somewhere else in your code
if (dbUpdated) {
update({
eventCode: "dbUpdateComplete"
type: "success",
message: "Your info is up to date!"
})
} else {
update({
eventCode: "dbUpdateSlow"
type: "pending",
message: "Database update is taking longer than usual, hang in there!"
})
}
The
notification function is called with a notification object with the following parameters:eventCode: a string which is used to keep track of that event for your analytics dashboardtype: a string that defines the style - ['hint' (gray), 'pending' (yellow), 'success' (green), 'error' (red)]message: a message string that is displayed on the notificationautoDismiss: a number in milliseconds before the notification auto dismisses or0for no auto dismissal.successandhinttypes default to4000onclick: a function to call when the notification is clicked by the user
Returned from the notification function is an object that has two functions defined on it:
update: a function that can be called with a new notification object to replace the original notification withdismiss: a function that can be called to dismiss the notification manually
You may want to unsubscribe from an account address or transaction hash that you are watching and stop receiving notifications:
// unsubscribe from watched address
notify.unsubscribe(address)
// unsubscribe from watched transaction
notify.unsubscribe(hash | txid)
Some configuration options can be set or updated after the library is initialized:
notify.config({
networkId: String,
system: String,
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)
clientLocale: String, // (default: 'en')
notifyMessages: Object
})
If a new
networkId or system is passed to the config function, then the current WebSocket connection will automatically be closed and a new connection will be established.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 0 for no autodismiss
onclick: Function // A function to call when the notification is clicked
link: String // a url string that will make the notification a link when clicked on
}
})
// 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
})
function addEtherscan(transaction) {
return {
link: `https://etherscan.io/tx/${transaction.hash}`
}
}
// then on each transaction...
const { emitter } = notify.hash(hash)
emitter.on('all', addEtherscan)
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 usertxRepeat: Transaction has the same value and to address, so may be a repeat transactiontxAwaitingApproval: A previous transaction is awaiting approvaltxConfirmReminder: Transaction has not been confirmed after timeouttxStallPending: Transaction has not been received in the mempool after timeouttxStallConfirmed: Transaction has been in the mempool for longer than the timeouttxError: An error has occurred initiating the transactiontxSendFail: The user rejected the transactiontxUnderpriced: The gas was set too low for the transaction to completetxSent: Transaction has been sent to the network
txPool: Transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a blocktxStuck: Transaction was detected in the "queued" area of the mempool and is not eligible for inclusion in a blocktxConfirmed: Transaction has been confirmedtxFailed: Transaction has failedtxSpeedUp: A new transaction has been submitted with the same nonce and a higher gas price, replacing the original transactiontxCancel: 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.
When using a local network (such as Ganache), Notify has no way of seeing
pending and confirmed statuses for transactions on that network and will not display any notifications. The emitter will also not emit events for those statuses. Notify will set the network to local if a networkId is passed in during initialization that is not one of the supported networksThe 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 (ethereum)
txid: String, // transaction id (bitcoin)
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
gasPriceGwei: Number, // the gasPrice in gwei
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
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 transferred
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
}
},
system: String // 'bitcoin' or 'ethereum'
}
To gain the required specificity to override the default styles, use the class name
.bn-notify-custom plus the class name that you would like to override in your CSS file. For example, if you would like to customize the font-family of the notifications, then you would target the top level ul element that has the class bn-notify-notifications in your CSS file:.bn-notify-custom .bn-notify-notifications {
font-family: Roboto;
}
Below is a list of the main classes that you would target to customize the
CSS:class name | description |
|---|---|
.bn-notify-notifications | container holding all of the notifications |
.bn-notify.notification | top level element of each notification |
.bn-notify-notification-info | notification content container |
.bn-notify-notification-info-message | notification message |
.bn-notify-notification-close | close notification icon container |
Notify has internationalization built in, allowing you to enable transaction notifications that match your user's locale and to give the user an option to switch locale.
Notify will automatically detect the browser's locale and set an internal
clientLocale. If that locale is defined within the notifyMessages object, then it will use that locale for all transaction messages. If it isn't defined, then it will fallback to the default 'en' locale. You can explicitly set the clientLocale for the user by calling the config function or passing it in via initializationObject.This object contains the messages for all the transaction states supported by Notify. The library has default transaction messages for the
'en' clientLocale and can be extended to include transaction messages for additional clientLocale settings. To extend the default notifyMessages object, you can pass in a notifyMessages object to either the config function or to the initializationObject.Below is an example object that implements a
'es' (Spanish) notifyMessages object:const notifyMessages = {
es: {
transaction: {
txRequest: 'Su transacción está esperando que confirme',
nsfFail: 'No tiene fondos suficientes para completar esta transacción.',
txUnderpriced:
'El precio del gas para su transacción es demasiado bajo, intente nuevamente con un precio del gas más alto',
txRepeat: 'Esto podría ser una transacción repetida',
txAwaitingApproval:
'Tienes una transacción anterior esperando que confirmes',
txConfirmReminder:
'Confirme su transacción para continuar, la ventana de transacción puede estar detrás de su navegador',
txSendFail: 'Rechazaste la transacción',
txSent: 'Su transacción ha sido enviada a la red.',
txStallPending:
'Su transacción se ha estancado y no ha ingresado al grupo de transacciones',
txPool: 'Su transacción ha comenzado',
txStallConfirmed:
'Su transacción se ha estancado y no ha sido confirmada.',
txSpeedUp: 'Su transacción ha sido acelerada',
txCancel: 'Tu transacción está siendo cancelada',
txFailed: 'Su transacción ha fallado',
txConfirmed: 'Su transacción ha tenido éxito.',
txError: 'Vaya, algo salió mal, por favor intente nuevamente'
},
watched: {
txPool:
'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
txSpeedUp:
'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
txCancel:
'su cuenta está {verb, select, receiving {recibiendo} sending {enviando}} {formattedValue} {asset} {preposition, select, from {desde} to {a}} {counterpartyShortened}',
txConfirmed:
'su cuenta {verb, select, received {recibió} sent {ha enviado}} con éxito {formattedValue} {asset} {preposition, select, from {de} to {a}} {counterpartyShortened}',
txFailed:
'su cuenta fallado {verb, select, received {recibió} sent {ha enviado}} con éxito {formattedValue} {asset} {preposition, select, from {de} to {a}} {counterpartyShortened}'
},
time: {
minutes: 'min',
seconds: 'sec'
}
}
}
notify.config({ notifyMessages })
The
notifyMessages object above would get merged with Notify's internal notifyMessages object, extending Notify to support both English and Spanish transaction notification messages.You can include as many of the above parameters as you would like in each language object. If Notify gets an
undefined value back from the language object, then it will fallback to the English default included in Notify.Notify uses
format.js under the hood, which uses the ICU message syntax to format messages. Check out their guide to the ICU message syntax here.For each language, you can include a
transaction object, a watched object and a time object.The
transaction object will be referenced for notifications that have been triggered via the hash or transaction function.
The watched object will be referenced for notifications that have been triggered by watching an address via the account function.
The time object will be referenced for expressing the amount of time that has passed during pending states on the notification.Each message will be called with the following inputs that will be formatted in to a message string:
The formatted value of the transaction:
formattedValue - (transaction, watched)The asset that is being sent or received:
asset - (transaction, watched)The correct verb based on whether the transaction is being incoming or outgoing and whether it is confirmed or pending:
verb - (watched)
Possible values are: 'received', 'sent', 'receiving', 'sending'The correct preposition based on the direction of the transaction:
preposition - (watched)
Possible values are: 'from', 'to'A shortened address of the counter party of the transaction:
counterpartyShortened - (watched)You can optionally run Notify.js as a simple notification UI library by not including a
dappId in your initialization options. In this scenario, Notify.js will not initiate a WebSocket connection to the Blocknative servers and all functionality other than the notification function will be disabled.You may run in to an error:
Uncaught TypeError: dist is not a constructor when building with Rollup.js. To fix this issue make sure that you are using @rollup/plugin-commonjs version 16.0.0 and aboveSign up for a free Blocknative Account at https://explorer.blocknative.com/account?signup=true with your work email address.
To see a Notify integration in a simple React app you can check out our
react-demo repo on GitHub: https://github.com/blocknative/react-demo
We have the reactdemo codebase deployed so that you try Notify from an end user perspective: https://reactdemo.blocknative.com/Last modified 27d ago