Awesome

substrate-tip-bot

A GitHub App built with Probot that can submit tips on behalf of a Substrate based network.

Getting started 🌱

Usage

This bot relies on GitHub pull request that opt in via a body text comment (or text in profile bio) to specify what Substrate network and address to send tips to.

Permission to send out tips is limited for a GitHub team, that's configured with APPROVERS_GH_ORG + APPROVERS_GH_TEAM environment variables. For production, it's @paritytech/tip-bot-approvers

Pull request body

{kusama|polkadot|rococo|westend} address: <SS58 Address>

Followed by a comment on said pull request

Pull request comment

/tip {small | medium | large | <custom value>}

In OpenGov, the tip sizes are translated to specific values as follows:

Size	Value on Kusama	Value on Polkadot
small	4 KSM	20 DOT
medium	16 KSM	80 DOT
large	30 KSM	150 DOT

Local development 🔧

To use this bot, you'll need to have an .env file. Most of the options will automatically be generated by the GitHub application creation process, but you will also need to add ACCOUNT_SEED, APPROVERS_GH_ORG and APPROVERS_GH_TEAM.

A reference env file is placed at .env.example to copy over

$ cp .env.example .env

Run network locally

Follow readme in https://github.com/paritytech/polkadot#development to run local network.
- Among all dependencies, main steps are (from repo):
  - Compile cargo b -r
  - Run ./target/release/polkadot --dev
- Alternatively, run a docker container: docker run -p 9933:9933 -p 9944:9944 parity/polkadot --dev
Create 2 accounts: for "bot" & for "contributor"
- Save the seeds & passwords somewhere
- Set ACCOUNT_SEED as bot's seed in .env file
Create a team in GitHub for the org that you control, and set APPROVERS_GH_ORG and APPROVERS_GH_TEAM in .env to said org and team
Set LOCALNETWORKS=true in .env, to change the endpoints
Transfer some meaningful amount from test accounts (like Alice) to a new bot account (from which bot will send tip to the contributor)

Create GitHub application for testing

Note: During app creation save according env variables to .env file
Read Getting-started doc to get a sense of how to work with bots
Follow creating app and installing app guidance
WEBHOOK_PROXY_URL you can generate via https://smee.io/new

Integration tests

There are integration tests that execute the tip functions against a locally running Polkadot and Kusama nodes.

The tests will spin up the local nodes automatically.

To run the tests:

Build the application image:

yarn build:docker

Then run the tests:

yarn test:integration

Github app permissions

Repository permissions:

Issues: Read-only
- Allows for interacting with the comments API
Pull Requests: Read & write
- Allows for posting comments on pull requests

Organization permissions

Members: Read-only
- Related to $ALLOWED_ORGANIZATIONS: this permission enables the bot to request the organization membership of the command's requester even if their membership is private

Event subscriptions

Issue comment
- Allows for receiving events for pull request comments

Start a bot

After registering and configuring the bot environment, we can run it.

$ yarn start

Create a PR and test it

You'll need 2 gh users: contributor and maintainer (since it's not allowed for contributors to send a tip to themselves)

From contributor GH account: create a PR and add into PR description rococo address: <contributor polkadot address>
From maintainer GH account: write /tip small in comments so the bot sends funds to <contributor polkadot address>

Docker

To run the bot via Docker, we need to build and then run it like so

$ docker build -t substrate-tip-bot .

$ docker run \
    -e APP_ID=<app-id> \
    -e PRIVATE_KEY=<pem-value> \
    substrate-tip-bot

End-to-end tests

For the E2E tests, we need a modified Rococo node in a way that speeds up the referenda and treasury.

Preparing and running Rococo

git clone https://github.com/paritytech/polkadot-sdk.git
cd polkadot-sdk
git checkout polkadot-v1.15.0
git apply ../polkadot.e2e.patch
cargo build --release --locked --features=fast-runtime -p polkadot
./target/release/polkadot --rpc-external --no-prometheus --no-telemetry --chain=rococo-dev --tmp --alice --execution Native --unsafe-force-node-key-generation --rpc-port 9902

You might need to fund the treasury (13UVJyLnbVp9RBZYFwFGyDvVd1y27Tt8tkntv6Q7JVPhFsTB) if it is broke.

Patch

The polkadot-sdk code is patched (see the line doing git apply) - that's why we have to build the code from source, instead of using a released binary or docker image.

The patch involves changing the timelines around OpenGov mechanics, so that we can test the whole flow in a reasonable amount of time.

Running the E2E tests

yarn test:e2e

Go make a cup of tea, the tests take ~3 minutes (waiting for the various on-chain stages to pass).

On CI, the E2E tests are running:

On every PR and commits pushed to master, against a fixed release of polkadot-sdk.
Periodically, against a most recent release of polkadot-sdk.

The tests are running in a container specified by E2E_TESTS_CONTAINER repository variable.

The container version should be kept in sync with the container used in polkadot-sdk CI.

Contributing

If you have suggestions for how substrate-tip-bot could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.