A CLI tool for monitoring a blockchain for POA Network governance ballots.
poa-governance-notificationsA CLI tool for monitoring a blockchain for POA Network governance ballots. This tool can be used to
monitor any chain that uses POA Network’s governance contracts.
More info regarding governance can be found in
POA Network’s Wiki.
POA Network’s governance contracts can be found in thepoa-network-consensus-contracts repo,
all Solidity files prefixed with “Voting” are classified as a “governance contract”.
The poagov command line tool is distributed as a binary for Linux and
OSX. The poagov binary can be built from source for both OSX and Linux using the code in this repo.
poagov BinaryNote: 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.
# Download `poagov` for Debian/Ubuntu:$ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v2.0.0/poagov-2.0.0-linux-x86_64.tar.gz$ tar -xvzf poagov-2.0.0-linux-x86_64.tar.gz$ rm poagov-2.0.0-linux-x86_64.tar.gz$ cd poa-governance-notifications$ mv sample.env .env# Optionally rename binary from `poagov-2.0.0-linux-x86_64` to `poagov`:$ mv poagov-2.0.0-linux-x86_64 poagov# Or download `poagov` for OSX:$ curl -OL https://github.com/poanetwork/poa-governance-notifications/releases/download/v2.0.0/poagov-2.0.0-osx-x86_64.tar.gz$ tar -xvzf poagov-2.0.0-osx-x86_64.tar.gz$ rm poagov-2.0.0-osx-x86_64.tar.gz$ cd poa-governance-notifications$ mv sample.env .env# Optionally rename binary from `poagov-2.0.0-osx-x86_64` to `poagov`:$ mv poagov-2.0.0-osx-x86_64 poagov# If you did not rename your binary in the previous step, replace "poagov"# in the following commands with your Linux or OSX binary's name:$ chmod +x poagov$ ./poagov --help
poagov from SourceTo build the poagov CLI tool from source, clone this repo and run:
$ cargo build --release
poagov can be built with Rust 1.31.0-stable or later and requires libssl;
see the “Running and Building poagov Requires libssl“ section in this README for more information.
poagovYou can run poagov‘s tests to ensure that everything is working properly:
$ cargo test --release
poagov Requires libsslSMTP 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.
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.
You can use dpkg to check to see if you have libssl installed, and if so
which version(s) are installed:
$ dpkg -l | grep libssl
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, oropenssl-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.
The above solution comes from the linked Stack Overflow thread.
More information on common issues encountered while installing theopenssl Rust crate can be found here.
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 --helppoagov 2.0.0Monitors a POA Network blockchain for governance events.USAGE:poagov [FLAGS] [OPTIONS]FLAGS:--core Monitors POA Network's Core Network for governance ballots--sokol Monitors POA Network's Sokol network for governance ballots--xdai Monitors the xDai Network for governance ballots--v1 Monitors the v1 governance contracts--v2 [default] Monitors the v2 governance contracts, if no contract version CLI argument is given by-k, --keys Monitors the blockchain for ballots to change keys-t, --threshold Monitors the blockchain for ballots to change the minimum thresholdthe user, we set this CLI flag-p, --proxy Monitors the blockchain for ballots to change the proxy address-e, --emission Monitors the blockchain for ballots to manage emission funds--earliest Monitor for governance events starting at the blockchain's first block--latest Monitor for governance events starting at the blockchain's most recently mined block--email Enables email notifications (SMTP configuration options must be set in your `.env` file)--log-emails Logs the full email body for each notification generated, this option does not require the`--email` flag to be set--log-file Logs are written to files in the ./logs directory, logs are rotated chronologically across 3files, each file has a max size of 4MB-h, --help Prints help information-V, --version Prints version informationOPTIONS:--block-time <value> The average number of seconds it takes to mine a new block-n, --limit <value> Stops `poagov` after this many notifications have been generated (this option can beuseful when testing `poagov`)--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 mined block
Hitting [ctrl-c] while poagov is running will cause the process to gracefully shutdown.
Each time you run poagov, three CLI arguments are required:
--core, --sokol, --xdai.--keys, --threshold, --proxy, --emission.--earliest, --latest, --start=<block_number>, --tail=<value>.--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 occurred
after the above hardfork dates.
We default to --v2 being set as it will monitor the currently deployed contract.
Providing the --v1 flag will tell poagov to look for ballots corresponding
to the hardfork #1 governance contracts. The hardfork #1 contracts are not
currently being by POA Network and not new governance notifications will be
generated, however you can use poagov to view all past --v1 ballots that
have occurred using:
$ poagov <--core, --sokol> --v1 --earliest -ktp
Providing the --email flag will enable governance notification via email. To
use this option, you must first configure SMTP in your .env file.
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 thelogs/ 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.
.env FileWhen 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.
In order to enable email notifications, you must change the name of thesample.env file to .env. Then, you must add values for the following
SMTP config options in your .env file:
SMTP_HOST_DOMAIN=SMTP_PORT=SMTP_USERNAME=SMTP_PASSWORD=OUTGOING_EMAIL_ADDRESS=EMAIL_RECIPIENTS=
Add a comma-separated list of email address to the EMAIL_RECIPIENTS config
option in your .env file. These addresses will be sent emails when poagov
encounters new ballots.
Note poagov forces SMTP email notifcations to be sent over TLS/STARTTLS, 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 any port for which your outgoing email server is listening; port 465 is
commonly used for TLS.
Your SMTP configuration should look something like the following:
SMTP_HOST_DOMAIN=mail.riseup.netSMTP_PORT=587SMTP_USERNAME=evariste_galoisSMTP_PASSWORD='finteFIELDS#$!'OUTGOING_EMAIL_ADDRESS=evariste_galois@riseup.netEMAIL_RECIPIENTS=alice@poa.network,bob@poa.network
$ 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 are written to stderr by default; if the --log-file CLI flag is set,
then logs will be written to a file in the logs. directory. Logged
information includes: the generation of governance notifications, sending an
email successfully, failing to send an email, blocks that we have finished
monitoring, email bodies generated (using the --log-emails CLI option).
The following is an example command with its corresponding logs:
$ poagov --sokol --v1 --threshold --earliest --limit=3Oct 10 15:18:09.863 INFO starting poagov...Oct 10 15:18:10.287 INFO governance notification, block_number: 525296, ballot_id: 0, ballot: ThresholdOct 10 15:18:10.287 INFO governance notification, block_number: 599789, ballot_id: 1, ballot: ThresholdOct 10 15:18:10.287 INFO governance notification, block_number: 1078816, ballot_id: 2, ballot: ThresholdOct 10 15:18:10.287 WARN reached notification limit, gracefully shutting down..., limit: 3