285 lines
12 KiB
Markdown
285 lines
12 KiB
Markdown
[![Build Status](https://travis-ci.org/poanetwork/poa-governance-notifications.svg?branch=master)](https://travis-ci.org/poanetwork/poa-governance-notifications)
|
|
|
|
# `poa-governance-notifications`
|
|
|
|
A tool to monitor a POA Network blockchain for
|
|
[governance events](https://github.com/poanetwork/wiki/wiki/Governance-Overview).
|
|
|
|
The `poagov` command line tool is distributed as a binary for Linux and
|
|
OSX; it can also be built from source for both platforms.
|
|
|
|
You can find the source code for the currently deployed governance contracts
|
|
[here](https://github.com/poanetwork/poa-network-consensus-contracts/tree/master/contracts).
|
|
|
|
You can find the addresses for governance contracts currently deployed to Core
|
|
[here](https://github.com/poanetwork/poa-chain-spec/blob/core/contracts.json)
|
|
and Sokol
|
|
[here](https://github.com/poanetwork/poa-chain-spec/blob/sokol/contracts.json).
|
|
|
|
# Installing the `poagov` Binary
|
|
|
|
*Note:* the `poagov` binary requires libssl to be installed prior to
|
|
usage, if you do not have libssl installed, go to the "Requires libssl"
|
|
section in this README to find out how to download it.
|
|
|
|
On Debian/Ubuntu:
|
|
|
|
$ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v1.0.0/poagov-1.0.0-linux-x86_64.tar.gz
|
|
$ tar -xvzf poagov-1.0.0-linux-x86_64.tar.gz
|
|
$ rm poagov-1.0.0-linux-x86_64.tar.gz
|
|
$ cd poagov
|
|
$ chmod +x poagov
|
|
$ ./poagov --help
|
|
|
|
On OSX:
|
|
|
|
$ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v1.0.0/poagov-1.0.0-osx-x86_64.tar.gz
|
|
$ tar -xvzf poagov-1.0.0-osx-x86_64.tar.gz
|
|
$ rm poagov-1.0.0-osx-x86_64.tar.gz
|
|
$ cd poagov
|
|
$ chmod +x poagov
|
|
$ ./poagov --help
|
|
|
|
|
|
# Building `poagov` from Source
|
|
|
|
To build the `poagov` CLI tool, run the following:
|
|
|
|
$ git clone https://github.com/poanetwork/poa-governance-notifications.git
|
|
$ cd poa-governance-notifications
|
|
$ cargo build --release
|
|
|
|
`poagov` can be built with Rust 1.29.1-stable or later and requires `libssl`;
|
|
see the following "Requires libssl" section for more information.
|
|
|
|
### Testing
|
|
|
|
You can run `poagov`'s tests to ensure that everything is working properly:
|
|
|
|
$ cargo test --release
|
|
|
|
The test suite will verify: that the required env-vars are found in the `.env`
|
|
file, that each network's JSON-RPC server can be reached, and that each
|
|
contract ABI can be loaded.
|
|
|
|
# Requires `libssl`
|
|
|
|
SMTP over TLS requires that you have a native TLS library installed on your
|
|
machine, the preferred library for Linux and OSX is OpenSSL >= 1.0.1,
|
|
otherwise known as `libssl` (you will need more than just the OpenSSL
|
|
binary that you may or may not already have installed at
|
|
`/usr/bin/openssl`).
|
|
|
|
If running `cargo build --release` panics with an error like:
|
|
|
|
"error: failed to run custom build command for `openssl-sys v0.9.28
|
|
...
|
|
Could not find directory of OpenSSL installation
|
|
..."
|
|
|
|
you probably do not have `libssl` installed.
|
|
|
|
To install `libssl` on Debian/Ubuntu run the following:
|
|
|
|
$ sudo apt update
|
|
$ sudo apt-get install -y pkg-config libssl-dev
|
|
|
|
To install libssl on MacOS run the following:
|
|
|
|
$ brew update
|
|
$ brew install openssl
|
|
|
|
Then try to rebuild `poagov` using:
|
|
|
|
$ cargo clean
|
|
$ cargo build --release
|
|
|
|
If you are on OSX and installed OpenSSL using Homebrew and continue to get
|
|
compilation errors for any of the Rust crates: `openssl`, `openssl-sys`, or
|
|
`openssl-sys-extras`, try building with the following:
|
|
|
|
$ cargo clean
|
|
$ OPENSSL_INCLUDE_DIR=$(brew --prefix openssl)/include \
|
|
OPENSSL_LIB_DIR=$(brew --prefix openssl)/lib \
|
|
cargo build --release
|
|
|
|
There is a known issue regarding the `openssl-sys` crate not being able to
|
|
find `libssl` installed with Homebrew on OSX; more information can be found on
|
|
[Stack Overflow](https://stackoverflow.com/questions/34612395/openssl-crate-fails-compilation-on-mac-os-x-10-11/34615626#34615626).
|
|
The above solution comes from the linked Stack Overflow thread.
|
|
|
|
More information on common issues encountered while installing the
|
|
`openssl` Rust crate can be found [here](https://crates.io/crates/openssl).
|
|
|
|
# Usage
|
|
|
|
Once you have built or downloaded `poagov`, you can print out the CLI usage by
|
|
running:
|
|
|
|
# If you downloaded the `poagov` binary run:
|
|
$ poagov --help
|
|
# Or, if you built `poagov` from source run:
|
|
$ target/release/poagov --help
|
|
|
|
poagov 1.0.0
|
|
Monitors a POA Network blockchain for governance events.
|
|
|
|
USAGE:
|
|
poagov [FLAGS] [OPTIONS]
|
|
|
|
FLAGS:
|
|
--core monitor voting contracts deployed to the Core network
|
|
--sokol monitor voting contracts deployed to the Sokol network
|
|
--v1 monitors the v1 voting contracts
|
|
--v2 monitors the v2 voting contracts
|
|
-k, --keys monitors the blockchain for ballots to change keys
|
|
-p, --proxy monitors the blockchain for ballots to change the proxy address
|
|
-t, --threshold monitors the blockchain for ballots to change the minimum threshold
|
|
-e, --emission monitors the blockchain for ballots to manage emission funds
|
|
--earliest begin monitoring for governance events starting at the first block in the blockchain
|
|
--latest begin monitoring for governance events starting at the last block mined
|
|
--email enables email notifications (SMTP configurations must be set in your `.env` file)
|
|
--log-emails logs each notification's email body; does not require the --email flag to be set
|
|
--log-file logs are written to files in the ./logs directory, log files are rotated when they reach a size of 4MB
|
|
-h, --help prints help information
|
|
-V, --version prints version information
|
|
|
|
OPTIONS:
|
|
--block-time <value> the average number of seconds it takes to mine a new block
|
|
-n, --limit <value> shutdown `poagov` after this many notifications have been generated, useful when testing
|
|
--start <value> start monitoring for governance events at this block (inclusive)
|
|
--tail <value> start monitoring for governance events for the `n` blocks prior to the last block mined
|
|
|
|
Hitting `[ctrl-c]` while `poagov` is running will cause the process to gracefully shutdown.
|
|
|
|
### Required Arguments
|
|
|
|
Each time you run `poagov`, four CLI arguments are required:
|
|
|
|
1. The chain (specify only one): `--core`, `--sokol`.
|
|
2. The contracts to monitor (specify at least one): `--keys`, `--threshold`, `--proxy`, `--emission`.
|
|
2. The hardfork version (specify only one): `--v1`, `--v2`.
|
|
4. The block in the chain from where to start monitoring (specify only one): `--earliest`, `--latest`, `--start=<block_number>`, `--tail=<value>`.
|
|
|
|
### Notes on the hardfork version options `--v1` and `--v2`
|
|
|
|
`--v1` indicates that you want to monitor for governance events prior to the
|
|
Sokol and Core hardforks that will occur in September-2018 and November-2018
|
|
respectively.
|
|
|
|
`--v2` indicates that you want to monitor for governance events that occured
|
|
after the above hardfork dates.
|
|
|
|
- More information regarding the planned hardforks for the Sokol and Core
|
|
chains in September and November 2018 can be found
|
|
[here](https://medium.com/poa-network/poa-network-news-and-updates-36-2e6e00550c15).
|
|
|
|
### Optional Arguments
|
|
|
|
Providing the `--email` flag will enable governance notification emails. To use
|
|
this option, you must first configure SMTP in your `.env`.
|
|
|
|
Providing the `--block-time=<value>` will set how often `poagov` will query the
|
|
blockchain for new governance events. Defaults to 30 seconds.
|
|
|
|
Providing the `--log-emails` flag will print the full text for a notification
|
|
email to stderr when governance events are found. When this option is set,
|
|
email text will be logged regardless of whether or not the `--email` flag is
|
|
set.
|
|
|
|
Setting the `--log-file` flag will write logs to a file in the `./logs/`
|
|
directory. Logs are rotated chronologically across three files. Once the
|
|
`logs` directory has reached its max number of files, the oldest log file will
|
|
be deleted to make room for the next log file. Log files have a max size of
|
|
4MB; the log files will rotated once the current log file has reached the max
|
|
file size.
|
|
|
|
Setting the `--limit=<value>` option will cause `poagov` to stop once `value`
|
|
number of notifications have been generated. This option is useful when testing.
|
|
|
|
# Setting up the `.env` File
|
|
|
|
When the `poagov` CLI tool is run, the process' environment variables are
|
|
loaded via an `.env` file. The `.env` file contains configuration variables
|
|
that are not specified via the command line. You are required to have an `.env`
|
|
file in the same directory as your `Cargo.toml` or `poagov` binary.
|
|
|
|
If you downloaded a `.tar.gz` compressed archive containing the `poagov` binary
|
|
and you do not have an `.env` file in the unarchived directory, manually copy
|
|
the `sample.env` file in this repo into a file called `.env` in the same
|
|
directory as the `poagov` binary.
|
|
|
|
When building from source, the `sample.env` file will be copied into the `.env`
|
|
file.
|
|
|
|
The default `.env` file will contain the default configuration values required
|
|
to run `poagov`. If you wish to enable email notifications, you must add the
|
|
required SMTP config values to your `.env` file. See the "Setting up Email
|
|
Notifications" section for details.
|
|
|
|
### Setting up Email Notifications
|
|
|
|
In order to enable email notifications, you must change the name of the
|
|
`sample.env` file to `.env`. Then, you must add values for the following
|
|
SMTP config options in your `.env` file:
|
|
|
|
EMAIL_RECIPIENTS=
|
|
SMTP_HOST_DOMAIN=
|
|
SMTP_PORT=
|
|
SMTP_USERNAME=
|
|
SMTP_PASSWORD=
|
|
OUTGOING_EMAIL_ADDRESS=
|
|
|
|
Add a comma-separated list of email address to the "VALIDATORS" config
|
|
option in your .env file. These addresses will be sent emails when `poagov`
|
|
encounters governance events on the POA blockchain.
|
|
|
|
*Note* `poagov` forces SMTP email notifcations to be sent over an encrypted
|
|
channel, if your SMTP Host does not support TLS or STARTTLS, `poagov` will
|
|
panic. You may notice that we default `SMTP_PORT` to port 587 for STARTTLS,
|
|
but you may use port 465 for TLS, or any other port that your outgoing
|
|
email server is lisening for secure connections. If you require unencrypted
|
|
SMTP, submit an issue and I can add it.
|
|
|
|
Your SMTP configuration should look something like the following:
|
|
|
|
EMAIL_RECIPIENTS=alice@poa.network,bob@poa.network
|
|
SMTP_HOST_DOMAIN=mail.riseup.net
|
|
SMTP_PORT=587
|
|
SMTP_USERNAME=evariste_galois
|
|
SMTP_PASSWORD='finteFIELDS#$!'
|
|
OUTGOING_EMAIL_ADDRESS=evariste_galois@riseup.net
|
|
|
|
# An Explained Example
|
|
|
|
$ poagov --sokol --v1 -kt --earliest --email --log-emails --limit=1
|
|
|
|
- `--sokol` monitors the Sokol chain.
|
|
- `--v1` monitors the governance contracts deployed prior to September-2018.
|
|
- `-k` monitors the `VotingToChangeKeys` contract.
|
|
- `-t` monitors the `VotingToChangeMinThreshold` contract.
|
|
- `--earliest` start monitoring from the first block in the blockchain.
|
|
- `--email` sends out email notifications to each address in the `EMAIL_RECIPIENTS` env-var.
|
|
- `--log-emails` for each governance notification generated, log the corresponding email body.
|
|
- `--limit=1` stop running `poagov` after one ballot notification has been generated.
|
|
|
|
# Logs
|
|
|
|
Logs are output to `stderr` unless the `--log-file` CLI flag is set. Events
|
|
that are logged include: the generation of governance notifications, sending an
|
|
email successesfully or failing to send an email, aned what range of blocks
|
|
from the chain have been successfully monitored for governance events.
|
|
Optionally, you can log the email body for each governance notification
|
|
generated by setting the `--log-emails` CLI flag.
|
|
|
|
The following is an example command with its corresponding logs:
|
|
|
|
$ poagov --sokol --v1 --threshold --earliest --limit=3
|
|
|
|
Oct 10 15:18:09.863 INFO starting poagov...
|
|
Oct 10 15:18:10.287 INFO governance notification, block_number: 525296, ballot_id: 0, ballot: Threshold
|
|
Oct 10 15:18:10.287 INFO governance notification, block_number: 599789, ballot_id: 1, ballot: Threshold
|
|
Oct 10 15:18:10.287 INFO governance notification, block_number: 1078816, ballot_id: 2, ballot: Threshold
|
|
Oct 10 15:18:10.287 WARN reached notification limit, gracefully shutting down..., limit: 3
|
|
|