{"id":13565569,"url":"https://github.com/eco-stake/restake","last_synced_at":"2025-04-03T22:31:42.422Z","repository":{"id":36992596,"uuid":"464294313","full_name":"eco-stake/restake","owner":"eco-stake","description":"Auto-compounder script for Cosmos Validators using REStake","archived":false,"fork":false,"pushed_at":"2024-08-12T12:50:49.000Z","size":3578,"stargazers_count":359,"open_issues_count":26,"forks_count":311,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-04T19:41:55.822Z","etag":null,"topics":["authz","autocompound","cosmos-sdk","nodejs","restake","tendermint","validators"],"latest_commit_sha":null,"homepage":"https://restake.app","language":"JavaScript","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/eco-stake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-28T00:56:07.000Z","updated_at":"2024-10-30T14:16:49.000Z","dependencies_parsed_at":"2023-02-17T18:16:12.149Z","dependency_job_id":"e13c9cb5-6c1e-4a1e-8420-d59dc3ca1ee5","html_url":"https://github.com/eco-stake/restake","commit_stats":null,"previous_names":[],"tags_count":284,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eco-stake%2Frestake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eco-stake%2Frestake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eco-stake%2Frestake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eco-stake%2Frestake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eco-stake","download_url":"https://codeload.github.com/eco-stake/restake/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247090273,"owners_count":20881941,"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":["authz","autocompound","cosmos-sdk","nodejs","restake","tendermint","validators"],"created_at":"2024-08-01T13:01:50.349Z","updated_at":"2025-04-03T22:31:41.777Z","avatar_url":"https://github.com/eco-stake.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# [REStake](https://restake.app)\n\nREStake allows delegators to grant permission for a validator to compound their rewards, and provides a script validators can run to find their granted delegators and send the compounding transactions automatically.\n\nREStake is also a convenient staking tool, allowing you to claim and compound your rewards individually or in bulk. This can save transaction fees and time, and many more features are planned.\n\n[![](./docs/screenshot.png)](https://restake.app)\n\nTry it out at [restake.app](https://restake.app).\n\nThe REStake UI has it's own dedicated repository at [eco-stake/restake-ui](https://github.com/eco-stake/restake-ui).\n\n## How it works / Authz\n\nAuthz is a new feature for Tendermint chains which lets you grant permission to another wallet to carry out certain transactions for you. These transactions are sent by the grantee on behalf of the granter, meaning the validator will send and pay for the TX, but actions will affect your wallet (such as claiming rewards).\n\nREStake specifically lets you grant a validator permission to send `Delegate` transactions for their validator only. The validator cannot send any other transaction types, and has no other access to your wallet. You authorize this using Keplr as normal. REStake no longer requires a `Withdraw` permission to autostake.\n\nA script is also provided which allows a validator to automatically search their delegators, check each for the required grants, and if applicable carry out the claim and delegate transactions on their behalf in a single transaction. This script should be run daily, and the time you will run it can be specified when you [add your operator](#become-an-operator).\n\n## Limitations\n\n- Authz is also not fully supported yet. Many chains are yet to update. The REStake UI will fall back to being a manual staking app with useful manual compounding features.\n- Currently REStake needs the browser extension version of Keplr, but WalletConnect and Keplr iOS functionality will be added ASAP.\n- REStake requires Nodejs version 20.x or later, it will not work with earlier versions.\n\n## Become an operator\n\nBecoming an operator is pretty easy, the overall process is as follows:\n\n1. Setup your bot wallet\n2. Setup the autostaking script\n3. Setup a cron or timer to run the script on a schedule\n4. Submit your operator to Validator Registry\n\n### Setup a hot wallet\n\nGenerate a new hot wallet you will use to automatically carry out the staking transactions. The mnemonic will need to be provided to the script so **use a dedicated wallet and only keep enough funds for transaction fees**. The ONLY mnemonic required here is for the hot wallet, do not put your validator operator mnemonic anywhere.\n\nYou only need a single mnemonic for multiple Cosmos chains, and the script will check each network in the [networks.json](./src/networks.json) file for a matching bot address.\n\n#### Derivation Paths (IMPORTANT)\n\nRight now, the REStake autostaking script uses the standard 118 derivation path by default. Some networks prefer a different path and apps like Keplr will honour this. **The address the autostake script uses might not match Keplr**.\n\nAs there are existing operators using the 118 path, operators will need to opt in to the correct path when they want to upgrade. **New operators should use the correct path before they get grants**.\n\nThe correct path can be set in one of two ways using a [config override](#customise-restake-and-use-your-own-node) file. `\"correctSlip44\": true` will use the slip44 defined in the Chain Registry. Alternatively set a specific path using `\"slip44\": 69`. You should use `\"correctSlip44\": true` if possible.\n\n```jsonc\n{\n  \"desmos\": {\n    \"prettyName\": \"Desmos 852\",\n    \"autostake\": {\n      \"correctSlip44\": true\n    }\n  }\n}\n```\n\nIn the future, `correctSlip44` will become the default and you will need to set `slip44` explicitly if you want to use the 118 path.\n\n### Setup the autostaking script\n\nYou can run the autostaking script using `docker-compose` or using `npm` directly. In both cases you will need to provide your mnemonic in a `MNEMONIC` environment variable.\n\n#### Instructions for Docker Compose\n\n##### Install Docker and Docker Compose\n\nBest bet is to follow the Docker official guides. Install Docker first, then Docker Compose. In recent versions, Docker and Docker Compose may combined into a single installation.\n\nDocker: [docs.docker.com/get-docker](https://docs.docker.com/get-docker/)\n\nDocker Compose: [docs.docker.com/compose/install](https://docs.docker.com/compose/install/)\n\n##### Clone the repository and setup .env\n\nClone the repository and copy the sample `.env` file ready for your mnemonic.\n\n```bash\ngit clone https://github.com/eco-stake/restake\ncd restake\ncp .env.sample .env\n```\n\n**Populate your new .env file with your mnemonic.**\n\n#### Instructions for NPM\n\n##### Install nodejs@v20\n\n```bash\ncurl -sL https://deb.nodesource.com/setup_20.x -o /tmp/nodesource_setup.sh\n# read the script file and when you're sure it's safe run it\nchmod +x /tmp/nodesource_setup.sh\n/tmp/nodesource_setup.sh\napt install nodejs -y\nnode --version\n\u003e v20.9.0\nnpm --version\n\u003e 10.1.0\n```\n\n##### Clone the repository and build it\n\n```bash\ngit clone https://github.com/eco-stake/restake\ncd restake\nnpm install\ncp .env.sample .env\n```\n\n**Populate your new .env file with your mnemonic.**\n\n#### Updating your local version\n\nREStake is MVP. Very MVP. Updates are happening all the time and there are bugs that still need fixing. Make sure you update often.\n\nUpdate your local repository and pre-build your Docker containers with the following commands:\n\n```bash\ngit pull\ndocker-compose run --rm app npm install\ndocker-compose build --no-cache\n```\n\nor with NPM:\n\n```bash\ngit pull\nnpm install\n```\n\n#### Running the script\n\nRunning the autostake script manually is then simple.\n\n**If you use Docker then you should prefix the below commands with `docker-compose run --rm app`.**\n\nNote you might need `sudo` depending on your docker install, and some docker versions utilize `docker compose` instead of `docker-compose`. If you run into issues, try substituting `docker compose`.\n\n```bash\ndocker-compose run --rm app npm run autostake\n```\n\nAlternatively if you use NPM you can ignore the `docker-compose run --rm app` prefix:\n\n```bash\nnpm run autostake\n```\n\nPass network names to restrict the script to certain networks.\n\n```bash\nnpm run autostake osmosis akash regen\n```\n\nA _Dry Run_ script is also included, which runs the normal autostake script but skips sending the final TXs, and skips any health check pings.\n\n```bash\nnpm run dryrun osmosis\n```\n\n**You should expect to see a warning that you are 'not an operator' until your REStake operator information is submitted in [Submitting your operator](#submitting-your-operator)**\n\n### Customise REStake and use your own node\n\nYou will likely want to customise your networks config, e.g. to set your own node URLs to ensure your autocompounding script completes successfully.\n\nCreate a `src/networks.local.json` file and specify the networks you want to override. Alternatively, set the `NETWORKS_OVERRIDE_PATH` environment variable containing the filepath. The below is just an example, **you should only override a config if you need to**.\n\n```json\n{\n  \"osmosis\": {\n    \"prettyName\": \"Osmosis\",\n    \"restUrl\": [\n      \"https://rest.cosmos.directory/osmosis\"\n    ],\n    \"gasPrice\": \"0.0025uosmo\",\n    \"autostake\": {\n      \"retries\": 3,\n      \"batchPageSize\": 100,\n      \"batchQueries\": 25,\n      \"batchTxs\": 50,\n      \"delegationsTimeout\": 20000,\n      \"queryTimeout\": 5000,\n      \"queryThrottle\": 100,\n      \"gasModifier\": 1.1\n    },\n    \"operator\": {\n      \"address\": \"OVERRIDE_BOT_ADDRESS\",\n      \"minimumReward\": \"OVERRIDE_BOT_MINIMUM_REWARD\"\n    },\n    \"healthCheck\": {\n      \"uuid\": \"XXXXX-XXX-XXXX\"\n    }\n  },\n  \"desmos\": {\n    \"prettyName\": \"Desmos 118\",\n    \"autostake\": {\n      \"correctSlip44\": true\n    }\n  },\n  \"cosmoshub\": {\n    \"enabled\": false\n  }\n}\n```\n\nAny values you specify will override the `networks.json` file. These are examples, you can override as much or little as you need.\n\nArrays will be replaced and not merged. The file is `.gitignore`'d so it won't affect upstream updates.\n\nNote that REStake requires a node with indexing enabled and minimum gas prices matching the `networks.json` gas price (or your local override).\n\n### Setting up cron/timers to run the script on a schedule\n\nYou should setup your script to run at the same time each day. 2 methods are described below; using `crontab` or using `systemd-timer`.\n\nIn both cases, ensure your system time is correct and you know what time the script will run in UTC, as that will be required later. Both examples below are for 21:00.\n\nDon't forget to [update often](#updating-your-local-version)!\n\n#### Using `crontab`\n\nNote: A helpful calculator for determining your REStake timer for `crontab` can be found here: \u003chttps://crontab.guru/\u003e.\n\nUpdated versions utilize `docker compose` instead of `docker-compose`. If you run into issues, try substituting `docker compose`.\n\n```bash\ncrontab -e\n\n0 21 * * * /bin/bash -c \"cd restake \u0026\u0026 docker compose run --rm app npm run autostake\" \u003e ./restake.log 2\u003e\u00261\n```\n\nor with NPM:\n\n```bash\ncrontab -e\n\n0 21 * * * /bin/bash -c \"cd restake \u0026\u0026 npm run autostake\" \u003e ./restake.log 2\u003e\u00261\n```\n\nWarning: Using crontab with docker without the `--rm` flag will continuously create docker images. Add another cronjob to tear down the images weekly if required:\n\n```bash\ncrontab -e\n\n0 0 * * */7 /usr/bin/docker image prune -a -f\n```\n\n#### Using `systemd-timer`\n\nSystemd-timer allows to run a one-off service with specified rules. This method is arguably preferable to Cron.\n\n##### Create a systemd unit file\n\nThe unit file describes the application to run.  We define a dependency with the timer with the `Wants` statement.\n\n```bash\nsudo vim /etc/systemd/system/restake.service\n```\n\n```bash\n[Unit]\nDescription=restake service with docker compose\nRequires=docker.service\nAfter=docker.service\nWants=restake.timer\n\n[Service]\nType=oneshot\nWorkingDirectory=/path/to/restake\nExecStart=/usr/bin/docker-compose run --rm app npm run autostake\n\n[Install]\nWantedBy=multi-user.target\n```\n\nFor NPM installs, remove `Requires` and `After` directives, and change `ExecStart` to `ExecStart=/usr/bin/npm run autostake`.\n\n##### Create a systemd timer file\n\nThe timer file defines the rules for running the restake service every day. All rules are described in the [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.timer.html).\n\nNote: Helpful calculator for determining restake times for `OnCalendar` can also be found at \u003chttps://crontab.guru/\u003e.\n\n```bash\nsudo vim /etc/systemd/system/restake.timer\n```\n\n```bash\n[Unit]\nDescription=Restake bot timer\n\n[Timer]\nAccuracySec=1min\nOnCalendar=*-*-* 21:00:00\n\n[Install]\nWantedBy=timers.target\n```\n\n##### Enable and start everything\n\n```bash\nsystemctl enable restake.service\nsystemctl enable restake.timer\nsystemctl start restake.timer\n```\n\n##### Check your timer\n\n`$ systemctl status restake.timer`\n\u003cpre\u003e\u003cfont color=\"#8AE234\"\u003e\u003cb\u003e●\u003c/b\u003e\u003c/font\u003e restake.timer - Restake bot timer\n     Loaded: loaded (/etc/systemd/system/restake.timer; enabled; vendor preset: enabled)\n     Active: \u003cfont color=\"#8AE234\"\u003e\u003cb\u003eactive (waiting)\u003c/b\u003e\u003c/font\u003e since Sun 2022-03-06 22:29:48 UTC; 2 days ago\n    Trigger: Wed 2022-03-09 21:00:00 UTC; 7h left\n   Triggers: ● restake.service\n\u003c/pre\u003e\n\n`$ systemctl status restake.service`\n\u003cpre\u003e● restake.service - stakebot service with docker compose\n     Loaded: loaded (/etc/systemd/system/restake.service; enabled; vendor preset: enabled)\n     Active: inactive (dead) since Tue 2022-03-08 21:00:22 UTC; 16h ago\nTriggeredBy: \u003cfont color=\"#8AE234\"\u003e\u003cb\u003e●\u003c/b\u003e\u003c/font\u003e restake.timer\n    Process: 86925 ExecStart=/usr/bin/docker-compose run --rm app npm run autostake (code=exited, status=0/SUCCESS)\n   Main PID: 86925 (code=exited, status=0/SUCCESS)\n\u003c/pre\u003e\n\n### Monitoring\n\nThe REStake autostaking script can integrate with [healthchecks.io](https://healthchecks.io/) to report the script status for each network. [healthchecks.io](https://healthchecks.io/) can then integrate with many notification platforms like email, Discord and Slack to make sure you know about any failures.\n\nOnce configured, REStake will ping [healthchecks.io](https://healthchecks.io/) when the script starts, succeeds, or fails. It will include relevant error information in the check log and is simple to configure.\n\nSetup a Check for each network you run the script for, and configure the expected schedule. E.g. add a check for Osmosis every 12 hours, Akash every 1 hour etc. Set a timeout in the region of 5 minutes, or slightly longer than you expect the script to run.\n\nAdd your Check UUID to the relevant network in your `networks.local.json` config as below. You can also optionally set the `address` attribute if you want to [self-host the healthchecks.io platform](https://healthchecks.io/docs/self_hosted/).\n\n```JSON\n{\n  \"osmosis\": {\n    \"healthCheck\": {\n      \"uuid\": \"77f02efd-c521-46cb-70g8-fa5v275au873\"\n    }\n  }\n}\n```\n\nIf you wish for your health checks to be created automatically, you can provide an [API key](https://healthchecks.io/docs/api/) to manage it for you.\nThe default behavior is for the check to be named after the network, but this can be overridden with the `name` property.\n\n**Note that the `uuid` is not necessary when using an `apiKey` to create checks automatically.**\n\n```JSON\n{\n  \"cheqd\": {\n    \"healthCheck\": {\n      \"apiKey\": \"12_CanM1Q3T72uGH4kc32G14BdA4Emc4y\",\n      \"name\": \"cheqd every 12 hours\", // optional, defaults to the network name\n      \"timeout\": 43200, // optional, expected seconds between each run\n      \"gracePeriod\": 86400, // optional, grace period seconds before it notifies\n    }\n  }\n}\n```\n\n### Submitting your operator\n\n#### Setup your REStake operator\n\nYou now need to update the [Validator Registry](https://github.com/eco-stake/validator-registry) to add your operator information to any networks you want to auto-compound for. Check the README and existing validators for examples, but the config for a network looks like this:\n\n```json\n{\n  \"name\": \"akash\",\n  \"address\": \"akashvaloper1xgnd8aach3vawsl38snpydkng2nv8a4kqgs8hf\",\n  \"restake\": {\n    \"address\": \"akash1yxsmtnxdt6gxnaqrg0j0nudg7et2gqczud2r2v\",\n    \"run_time\": [\n      \"09:00\",\n      \"21:00\"\n    ],\n    \"minimum_reward\": 1000\n  }\n},\n```\n\n`address` is your validator's address, and `restake.address` is the address from your new hot wallet you generated earlier.\n\n`restake.run_time` is the time _in UTC_ that you intend to run your bot, and there are a few options. Pass a single time, e.g. `09:00` to specify a single run at 9am UTC. Use an array for multiple specified times, e.g. `[\"09:00\", \"21:00\"]`. Use an interval string for multiple times per hour/day, e.g. `\"every 15 minutes\"`.\n\n`restake.minimum_reward` is the minimum reward to trigger autostaking, otherwise the address is skipped. This could be set higher for more frequent restaking. Note this is in the base denomination, e.g. `uosmo`.\n\nRepeat this config for all networks you want to REStake for.\n\nNote that the `restake.address` is the address which will be granted by the delegator in the UI to carry out their restaking transactions.\n\n#### Submit your operator to the Validator Registry\n\nYou can now submit your [Validator Registry](https://github.com/eco-stake/validator-registry) update to that repository in a pull request which will be merged as soon as possible. REStake automatically updates within 15 minutes of changes being merged.\n\n## Contributing\n\n### Adding/updating a network\n\nNetwork information is sourced from the [Chain Registry](https://github.com/cosmos/chain-registry) via the [registry.cosmos.directory](https://registry.cosmos.directory) API. Chains in the master branch are automatically added to REStake assuming enough basic information is provided.\n\nThe `networks.json` file defines which chains appear as 'supported' in REStake; so long as the chain name matches the directory name from the Chain Registry, all chain information will be sourced automatically. Alternatively chains _can_ be supported in `networks.json` alone, but this is not a documented feature.\n\nTo add or override a chain in REStake, add the required information to `networks.json` as follows:\n\n```json\n{\n  \"name\": \"osmosis\",\n  \"prettyName\": \"Osmosis\",\n  \"gasPrice\": \"0.025uosmo\",\n  \"authzSupport\": true\n}\n```\n\nNote that most attributes from Chain Registry can be overridden by defining the camelCase version in networks.json.\n\n### Running the UI\n\nThe REStake UI now has it's own dedicated repository at [eco-stake/restake-ui](https://github.com/eco-stake/restake-ui).\n\nCheck the project README for instructions on running your own UI.\n\n## Ethos\n\nThe REStake UI is both validator and network agnostic. Any validator can be added as an operator and run this tool to provide an auto-compounding service to their delegators, but they can also run their own UI if they choose and adjust the branding to suit themselves.\n\nFor this to work, we need a common source of chain information, and a common source of 'operator' information. Chain information is sourced from the [Chain Registry](https://github.com/cosmos/chain-registry), via an API provided by [cosmos.directory](https://github.com/eco-stake/cosmos-directory). Operator information lives in the [Validator Registry](https://github.com/eco-stake/validator-registry).\n\nNow we have a common source of operator information, applications can integrate with REStake validators easier using the data directly from GitHub, or via the [cosmos.directory](https://github.com/eco-stake/cosmos-directory) project.\n\n## Disclaimer\n\nThe initial version of REStake was built quickly to take advantage of the new authz features. I'm personally not a React or Javascript developer, and this project leans extremely heavily on the [CosmJS project](https://github.com/cosmos/cosmjs) and other fantastic codebases like [Keplr Wallet](https://github.com/chainapsis/keplr-wallet) and [Osmosis Zone frontend](https://github.com/osmosis-labs/osmosis-frontend). It functions very well and any attack surface is very limited however. Any contributions, suggestions and ideas from the community are extremely welcome.\n\n## ECO Stake 🌱\n\nECO Stake is a climate positive validator, but we care about the Cosmos ecosystem too. We built REStake to make it easy for all validators to run an autocompounder with Authz, and it's one of many projects we work on in the ecosystem. [Delegate with us](https://ecostake.com) to support more projects like this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feco-stake%2Frestake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feco-stake%2Frestake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feco-stake%2Frestake/lists"}