{"id":13604187,"url":"https://github.com/paritytech/substrate-tip-bot","last_synced_at":"2025-08-20T05:12:32.289Z","repository":{"id":37408413,"uuid":"409029773","full_name":"paritytech/substrate-tip-bot","owner":"paritytech","description":"A GitHub bot to submit tips on behalf of contributors","archived":false,"fork":false,"pushed_at":"2024-09-20T08:01:02.000Z","size":2365,"stargazers_count":25,"open_issues_count":3,"forks_count":7,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-07T08:42:17.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paritytech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-22T01:44:51.000Z","updated_at":"2024-11-06T13:37:37.000Z","dependencies_parsed_at":"2023-01-31T07:00:35.383Z","dependency_job_id":"9c00d12d-f753-4a5f-8283-a3f67e52e011","html_url":"https://github.com/paritytech/substrate-tip-bot","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fsubstrate-tip-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fsubstrate-tip-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fsubstrate-tip-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fsubstrate-tip-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paritytech","download_url":"https://codeload.github.com/paritytech/substrate-tip-bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223922085,"owners_count":17225636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:00:41.247Z","updated_at":"2024-11-10T07:11:17.811Z","avatar_url":"https://github.com/paritytech.png","language":"TypeScript","funding_links":[],"categories":["Resources"],"sub_categories":["Tools"],"readme":"# substrate-tip-bot\n\n[![GitHub Issue Sync](https://github.com/paritytech/substrate-tip-bot/actions/workflows/github-issue-sync.yml/badge.svg)](https://github.com/paritytech/substrate-tip-bot/actions/workflows/github-issue-sync.yml)\n\n\u003e A GitHub App built with [Probot](https://github.com/probot/probot) that can submit tips on behalf\n\u003e of a [Substrate](https://github.com/paritytech/substrate) based network.\n\n# Getting started 🌱\n\n## Usage\n\nThis 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.  \n\nPermission 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](https://github.com/orgs/paritytech/teams/tip-bot-approvers)  \n\n### Pull request body\n\n```sh\n{kusama|polkadot|rococo|westend} address: \u003cSS58 Address\u003e\n```\n\nFollowed by a _comment_ on said pull request\n\n### Pull request comment\n\n```sh\n/tip {small | medium | large | \u003ccustom value\u003e}\n```\n\nIn OpenGov, the tip sizes are translated to specific values as follows:\n\nSize | Value on Kusama | Value on Polkadot\n--- | --- | ---\nsmall | 4 KSM | 20 DOT\nmedium | 16 KSM | 80 DOT\nlarge | 30 KSM | 150 DOT\n\n## Local development 🔧\n\nTo use this bot, you'll need to have an `.env` file. Most of the options will\nautomatically be generated by the GitHub application creation process, but you will also need to add\n`ACCOUNT_SEED`, `APPROVERS_GH_ORG` and `APPROVERS_GH_TEAM`.\n\nA reference env file is placed at `.env.example` to copy over\n\n```sh\n$ cp .env.example .env\n```\n\n### Run network locally\n\n- Follow readme in https://github.com/paritytech/polkadot#development to run local network. \n  - Among all dependencies, main steps are (from repo): \n    - Compile `cargo b -r`\n    - Run `./target/release/polkadot --dev`\n  - Alternatively, run a docker container: `docker run -p 9933:9933 -p 9944:9944 parity/polkadot --dev`\n- [Create 2 accounts: for \"bot\" \u0026 for \"contributor\"](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A9944#/accounts) \n  - Save the seeds \u0026 passwords somewhere\n  - Set `ACCOUNT_SEED` as bot's seed in `.env` file  \n- 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\n- Set `LOCALNETWORKS=true` in `.env`, to change the endpoints\n- Transfer some meaningful amount from test accounts (like Alice) to a new bot account (from which bot will send tip to the contributor)\n\n### Create GitHub application for testing\n\n- Note: During app creation save according env variables to `.env` file\n- Read [Getting-started](https://gitlab.parity.io/groups/parity/opstooling/-/wikis/Bots/Development/Getting-started) doc to get a sense of how to work with bots\n- Follow [creating app](https://gitlab.parity.io/groups/parity/opstooling/-/wikis/Bots/Development/Create-a-new-GitHub-App)\nand [installing app](https://gitlab.parity.io/groups/parity/opstooling/-/wikis/Bots/Development/Installing-the-GitHub-App)\nguidance\n- `WEBHOOK_PROXY_URL` you can generate via https://smee.io/new\n\n### Integration tests\n\nThere are integration tests that execute the tip functions against a locally running Polkadot and Kusama nodes.\n\nThe tests will spin up the local nodes automatically.\n\nTo run the tests:\n\nBuild the application image:\n```bash\nyarn build:docker\n```\n\nThen run the tests:\n\n```bash\nyarn test:integration\n```\n\n#### Github app permissions\n\n##### Repository permissions:\n- **Issues**: Read-only\n  - Allows for interacting with the comments API\n- **Pull Requests**: Read \u0026 write\n  - Allows for posting comments on pull requests\n##### Organization permissions\n- **Members**: Read-only\n  - 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\n##### Event subscriptions\n- **Issue comment**\n  - Allows for receiving events for pull request comments\n\n### Start a bot\n\nAfter registering and configuring the bot environment, we can run it.\n\n```sh\n$ yarn start\n```\n\n### Create a PR and test it\nYou'll need 2 gh users: contributor and maintainer (since it's not allowed for contributors to send a tip to themselves)\n\n- From contributor GH account: create a PR and add into PR description `rococo address: \u003ccontributor polkadot address\u003e`\n- From maintainer GH account: write `/tip small` in comments so the bot sends funds to \u003ccontributor polkadot address\u003e\n\n### Docker\n\nTo run the bot via Docker, we need to build and then run it like so\n\n```sh\n$ docker build -t substrate-tip-bot .\n```\n\n```sh\n$ docker run \\\n    -e APP_ID=\u003capp-id\u003e \\\n    -e PRIVATE_KEY=\u003cpem-value\u003e \\\n    substrate-tip-bot\n```\n\n## End-to-end tests\n\nFor the E2E tests, we need a modified Rococo node in a way that speeds up the referenda and treasury.\n\n### Preparing and running Rococo\n\n```bash\ngit clone https://github.com/paritytech/polkadot-sdk.git\ncd polkadot-sdk\ngit checkout polkadot-v1.15.0\ngit apply ../polkadot.e2e.patch\ncargo build --release --locked --features=fast-runtime -p polkadot\n./target/release/polkadot --rpc-external --no-prometheus --no-telemetry --chain=rococo-dev --tmp --alice --execution Native --unsafe-force-node-key-generation --rpc-port 9902\n```\n\nYou might need to fund the treasury (`13UVJyLnbVp9RBZYFwFGyDvVd1y27Tt8tkntv6Q7JVPhFsTB`) if it is broke.\n\n#### Patch\n\nThe `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.\n\nThe patch involves changing the timelines around OpenGov mechanics, so that we can test the whole flow in a reasonable amount of time.\n\n### Running the E2E tests\n\n```bash\nyarn test:e2e\n```\n\nGo make a cup of tea, the tests take ~3 minutes (waiting for the various on-chain stages to pass).\n\nOn CI, the E2E tests are running:\n\n- On every PR and commits pushed to `master`, against a fixed release of `polkadot-sdk`.\n- Periodically, against a most recent release of `polkadot-sdk`.\n\nThe tests are running in a container specified by `E2E_TESTS_CONTAINER` [repository variable](https://docs.github.com/en/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).\n\nThe container version should be kept in sync with the container used in [`polkadot-sdk` CI](https://github.com/paritytech/polkadot-sdk/blob/polkadot-v1.7.2/.github/workflows/fmt-check.yml#L18).\n\n## Contributing\n\nIf you have suggestions for how substrate-tip-bot could be improved, or want to report a bug, open\nan issue! We'd love all and any contributions.\n\nFor more, check out the [Contributing Guide](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE) © 2021 Parity Technologies \u003cadmin@parity.io\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Fsubstrate-tip-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparitytech%2Fsubstrate-tip-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Fsubstrate-tip-bot/lists"}