Polkadot Basic Notifications 🔴 📣

A dead-simple, yet highly effective notification system for Polkadot and its parachains (or, any substrate-based chain, most specifically).

The underlying workings of this program is as follows: We have a list of accounts which we want to monitor, stored as ss58 string representation. The script then listens to incoming blocks of any given chain, and does a full-text search of the account strings in the stringified representation of both the transactions in the block, and entire events that are emitted at this block.

This is super simple, yet enough to detect any interaction to or from your accounts of interest. Some covered examples are:

Any transaction signed by your accounts is detected, successful or unsuccessful.
Your staking rewards are detected both via the Rewarded and Deposited events.
Any transfer to your account is detected, both since your account will be an argument of the transfer transaction, and the Deposited event.

Nonetheless, the list goes way beyond this. The only known shortcoming of this is the lack of support for pallet-indices, which is essentially an alternative, shorter way to identify accounts.

Any of such events creates a report. Any block that contains a non-zero number of reports is passed to an arbitrary number of Reporters for delivery. The Reporters are essentially the transport mechanism, i.e. how you want to be notified. Current implementations are:

Matrix, using matrix-js-sdk.
Email, optionally supporting GPG encryption as well.
File system, writing to a file.
Console, only sensible for testing.

How to use

You need to provide one configuration file to the program, which specifies 3 things:

which accounts you want to monitor.
which chains you want to monitor.
which reporters you want to use.

A documented examples is as follows:

", " "] // [" ", " "]. For chains that use ethereum based accounts (e.g. // moonbeam), just use your account's public key as hex (`0xabc..`). "accounts": [ [" ", " "], [" ", " "], [" ", " "], ], // a list of ws-endpoint to which we start to listen. For example, Polkadot's is "wss://rpc. // polkadot.io". The cool thing here is that ANY substrate-based chain will work, so you can add // accounts from parachains (Acala, Statemine), solo-chains (Aleph-zero), or even ethereum-based // chains like moonbeam. "endpoints": [ "wss://rpc.polkadot.io", "wss://statemine-rpc.polkadot.io", "wss://acala-polkadot.api.onfinality.io/public-ws", "wss://wss.api.moonbeam.network", "wss://ws.azero.dev" ], // This is where you specify which reporters you want to use. "reporters": { // if provided, report all events to a matrix room. "matrix": { // the user if of some user from which you will send the message. "userId": "@your-username:matrix.org", // the access token of the aforementioned user. "accessToken": "..", // the id of the room to which you will send the message. "roomId": "!ggiWRxQNogSKcQWUiu:matrix.parity.io", // the serve in which your user exist. "server": "https://matrix.org" }, // if provided, report all events to a set of email addresses. "email": { // the address from which you send the emails. It must be owned by the `transporter.auth` credentials once authenticated with `transporter.host`. "from": "[email protected]", // The list of addresses that get notified. "to": ["[email protected]", "[email protected]"], // optional: if provided, your messages will be encrypted, but the formatting might not be as good. "gpgpubkey": "./pub.key", // this must be exactly the same object as used in the nodemailer library. See here for // more information: https://nodemailer.com/smtp/ "transporter": { "host": "smtp.youremail.org", "port": 587, "secure": false, "auth": { "user": "...", "pass": "..." } } }, // if provided, writes all reports to the file at the given path. The file is appended to "fs": { "path": "./out1.log" }, // enabling this will print all reports to console as well. "console": {}, } } ">

{
	// your list of accounts. It should be ["
             
              ", "
              
               "]
              
             
	// ["
             
              ", "
              
               "]. For chains that use ethereum based accounts (e.g.
              
             
	// moonbeam), just use your account's public key as hex (`0xabc..`).
	"accounts": [
		["
             
              "
             , "
             
              "
             ],
		["
             
              "
             , "
             
              "
             ],
		["
             
              "
             , "
             
              "
             ],
	],
	// a list of ws-endpoint to which we start to listen. For example, Polkadot's is "wss://rpc.
	// polkadot.io". The cool thing here is that ANY substrate-based chain will work, so you can add
	// accounts from parachains (Acala, Statemine), solo-chains (Aleph-zero), or even ethereum-based
	// chains like moonbeam.
	"endpoints": [
		"wss://rpc.polkadot.io",
		"wss://statemine-rpc.polkadot.io",
		"wss://acala-polkadot.api.onfinality.io/public-ws",
		"wss://wss.api.moonbeam.network",
		"wss://ws.azero.dev"
	],
	// This is where you specify which reporters you want to use.
	"reporters": {
		// if provided, report all events to a matrix room.
		"matrix": {
			// the user if of some user from which you will send the message.
			"userId": "@your-username:matrix.org",
			// the access token of the aforementioned user.
			"accessToken": "..",
			// the id of the room to which you will send the message.
			"roomId": "!ggiWRxQNogSKcQWUiu:matrix.parity.io",
			// the serve in which your user exist.
			"server": "https://matrix.org"
		},

		// if provided, report all events to a set of email addresses.
		"email": {
			// the address from which you send the emails. It must be owned by the `transporter.auth` credentials once authenticated with `transporter.host`.
			"from": "[email protected]",
			// The list of addresses that get notified.
			"to": ["[email protected]", "[email protected]"],
			// optional: if provided, your messages will be encrypted, but the formatting might not be as good.
			"gpgpubkey": "./pub.key",
			// this must be exactly the same object as used in the nodemailer library. See here for // more information: https://nodemailer.com/smtp/
			"transporter": {
				"host": "smtp.youremail.org",
				"port": 587,
				"secure": false,
				"auth": {
					"user": "...",
					"pass": "..."
				}
			}
		},

		// if provided, writes all reports to the file at the given path. The file is appended to
		"fs": {
			"path": "./out1.log"
		},

		// enabling this will print all reports to console as well.
		"console": {},
	}
}

You can mix and match different reporters with different configs together.

Deployment

I made this project to be as easy as possible to deploy, so that you don't need to rely on a 3rd party service to receive notifications for your accounts. Although, in the above examples, you are still relying on the honesty of the ws-nodes to which you connect. To take it a step further, you can consider running your own nodes.

The easiest way to deploy this application is using pm2, or any other typical node-js deployment service. There is already a template pm2.config.js provided, which you can use as

$ yarn run deploy:pm2

Alternatively, you can build a docker image from from this application based on the provided Dockerfile. To build the image:

$ docker build . -t polkadot-basic-notification
$ # note how the config file must be passed as an environment variable.
$ docker run -e CONF=config.json polkadot-basic-notification

Comments

How could I find extrinsic hash

Hi ,

I am trying to located Balance , Transfers , Where From/To and amount are found.

However extrinsic hash for the transfer can not be found .

could you help me figure it out ?

Thank you !

opened by turndealer 2
Optional `ignore_methods` and `listen_methods`
if none is provided, everything is notified (current behavior).

if ignore_methods is provided, everything except these methods are notified.

if listen_methods is provided, nothing except these methods are notified.

Both are case sensitive, and mutually exclusive options.
opened by kianenigma 1
A lot of more features for v1
User facing:

closes #2 closes #4

[x] Full config checking

[x] telegram reporter

[x] bulk reporting

[x] improve missed blocks (aleph zero not working)

Code:

[x] idiomatic union types

[x] solid formatting + styles

[x] CI

Breaking changes:

method_subscription is now fully typed. e.g.

{ type: "all" } { type: "only", only: [...] } { type: "ignore", ignore: [...] }
opened by kianenigma 0
Makes "listen" parameter optional and minor improvements.

The configuration example did not show a required "listen" field, this PR makes it optional. If it is not set in the config, or it has a non 'ApiSubscription' value, it defaults to 'ApiSubscription.Finalized'

Minor improvemens: package.json used to template values Renames missingFiled to MissingField in src/index.ts

opened by parutger 0
Batch reports

For some noise reports, it would be awesome to be able to batch reports together. You would accumulate the reports, and send them all at once.

One problem is that the current application is relatively junky and breaks quite often, meaning that we heavily rely on pm2 retarting us, so keeping anything in memory is moot.

What we could do instead is to have a new reporter that is a combination of Fs and Email. It would write stuff to a file, and every so often it will pick them up and pass them to any other reporter.
enhancement

opened by kianenigma 0

Releases(v1.0.0-rc0)

v1.0.0-rc0(Oct 16, 2022)
Notable existing features:

Email and matrix reporter.

Filter events and extrinsics.

Compatible with all substrate based chains.

Notable changes:

Full config checking

Telegram reporter

Batch reporting

Breaking changes to config file:

method_subscription is now fully typed. e.g.

{ type: "all" } { type: "only", only: [...] } { type: "ignore", ignore: [...] }

What's Changed

Makes "listen" parameter optional and minor improvements. by @parutger in https://github.com/kianenigma/polkadot-basic-notification/pull/5

Backport changes for now by @kianenigma in https://github.com/kianenigma/polkadot-basic-notification/pull/8

Fix dependencies issue inside container (#8) by @kianenigma in https://github.com/kianenigma/polkadot-basic-notification/pull/9

A lot of more features for v1 by @kianenigma in https://github.com/kianenigma/polkadot-basic-notification/pull/11

New Contributors

@parutger made their first contribution in https://github.com/kianenigma/polkadot-basic-notification/pull/5

@kianenigma made their first contribution in https://github.com/kianenigma/polkadot-basic-notification/pull/8

Full Changelog: https://github.com/kianenigma/polkadot-basic-notification/commits/v1.0.0-rc0
Source code(tar.gz)
Source code(zip)