fc5289f326
Added travis ci file to build the poagov binary on Rust's nightly channel. |
||
---|---|---|
abis | ||
src | ||
.gitignore | ||
.travis.yml | ||
Cargo.toml | ||
LICENSE | ||
README.md | ||
sample.env |
README.md
About
A tool to monitor a POA Network blockchain for governance events.
Building
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
Requires Rust Nightly
poagov
uses experimental Rust features that are currently only available
in Rust version >= 1.26.0-nightly. You can check which version of Rust that
you are using by running:
$ rustc --version
If you are not using Rust >= 1.26.0-nightly, you can switch to it using:
$ rustup default nightly
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-get update -y
$ 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
There is a known issue regarding the openssl-sys crate not being able to find libssl installed with Homebrew on OSX that is well documented on Stack Overflow. 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.
Usage
Once you have built poagov
, you can print out the CLI usage by running:
$ ./target/release/poagov --help
poagov 1.0
Monitores the POA Network's blockchain for governance events.
USAGE:
poagov [FLAGS] [OPTIONS]
FLAGS:
--core monitor voting contracts deployed to the Core network (same as using --network=core)
--earliest start monitoring for goverance events starting from the first block in the chain
--email send governance notifications via email
-h, --help prints help information
-k monitor the blockchain for ballots to change keys (same as --monitor=keys)
--latest start monitoring for goverance events starting from the most recently mined block in the chain
--local monitor voting contracts deployed to a locally running POA chain (same as using --network=local)
-p monitor the change for ballots to change the proxy address (same as --monitor=proxy)
--push send governance notifications via push notification
--sokol monitor voting contracts deployed to the Sokol test network (same as using --network=sokol)
-t monitor the chain for ballots to change the minimum threshold (same as --monitor=threshold)
-V, --version prints version information
OPTIONS:
--block-time <value> the average time it takes to mine a new block
--monitor <value> a comma-separated list of ballot types to monitor for governance events; the available values are: keys, threshold, proxy
--network <value> the name of the network to monitor for ballots; the values available for this option are: core, sokol, local
--rpc <value> the URL for the RPC endpoint
--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 in the chain
Setting up the Config File
When the poagov
CLI tool is run, the process' environment variables are
loaded via a .env
file. An example .env
file can be found at
sample.env
. Before running this tool change the name of sample.env
to
.env
using:
$ mv sample.env .env
This will enable poagov's
default configuration. You can update your
config file to allow poagov
to use a locally running chain, governance
contracts that you have deployed locally, and to setup email
notifications.
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:
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.
An Explained Example
$ ./target/release/poagov --sokol --earliest -kt --email
--sokol
is used to monitor contracts deployed to POA's test network.--earliest
starts monitoring from the first block in the blockchain.-k
get notifications for ballots to change keys.-t
get notifications for ballots to change the min threshold.--email
sends out email notifications to each address in the "VALIDATORS" config value (located in the .env file).
Press [ctrl-c] to exit poagov
.
Logs
Logs are output to stderr. Any notifications that were generated, sent,
or failed to be sent will be logged. The following is an example log for a
a notification for a ballot to change the min threshold that was generated
using the command $ poagov --earliest -t
:
Apr 21 08:31:54.219 INFO notification, data: ThresholdNotification {
network: Sokol,
endpoint: "https://sokol.poa.network",
block_number: 1078816,
contract_type: Threshold,
ballot_type: ChangeMinThreshold,
ballot_id: 2,
start_time: 2018-02-23T05:28:22Z,
end_time: 2018-02-25T05:33:00Z,
memo: "*TEST* ballot to increase the consensus threshold to 51% (rounded to the higher integer) of the total number of validators. The idea is to legitimize passing the ballot by the majority participation.",
proposed_value: 4
}