# About

A tool to monitor a POA Network blockchain for
[governance events](https://github.com/poanetwork/wiki/wiki/Governance-Overview).

# 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](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 `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
    }