{"id":19096850,"url":"https://github.com/makerdao/plunger","last_synced_at":"2025-04-30T14:29:24.361Z","repository":{"id":46807214,"uuid":"104694110","full_name":"makerdao/plunger","owner":"makerdao","description":"Tool for overriding Ethereum transactions stuck in the pool","archived":false,"fork":false,"pushed_at":"2022-07-15T18:40:46.000Z","size":106,"stargazers_count":16,"open_issues_count":3,"forks_count":11,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-03-30T16:51:15.598Z","etag":null,"topics":["ethereum","maker-keeper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/makerdao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-25T02:24:55.000Z","updated_at":"2022-01-01T11:55:46.000Z","dependencies_parsed_at":"2022-09-12T07:40:57.140Z","dependency_job_id":null,"html_url":"https://github.com/makerdao/plunger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makerdao%2Fplunger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makerdao%2Fplunger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makerdao%2Fplunger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makerdao%2Fplunger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makerdao","download_url":"https://codeload.github.com/makerdao/plunger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249517937,"owners_count":21284861,"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":["ethereum","maker-keeper"],"created_at":"2024-11-09T03:37:59.164Z","updated_at":"2025-04-18T16:31:28.645Z","avatar_url":"https://github.com/makerdao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plunger\n\nTool helping to deal with Ethereum transactions stuck in the pool.\n\n![Build Status](https://github.com/makerdao/plunger/actions/workflows/.github/workflows/tests.yaml/badge.svg?branch=master)\n[![codecov](https://codecov.io/gh/makerdao/plunger/branch/master/graph/badge.svg)](https://codecov.io/gh/makerdao/plunger)\n[![Code Climate](https://codeclimate.com/github/makerdao/plunger/badges/gpa.svg)](https://codeclimate.com/github/makerdao/plunger)\n[![Issue Count](https://codeclimate.com/github/makerdao/plunger/badges/issue_count.svg)](https://codeclimate.com/github/makerdao/plunger)\n\n\u003chttps://chat.makerdao.com/channel/keeper\u003e\n\n\n## Rationale\n\nDue to periodic Ethereum network congestion, transactions can easily get stuck in the\ntransaction pool for many hours if not days. _plunger_ is a tool that helps to deal\nwith such situations by either overriding them with zero-valued transactions with\nhigher gas price, or just waiting for them to clear themselves. It also allows you\nto list pending transactions for manual inspection.\n\n_plunger_ has been created during development of the Maker Keeper Framework.\nIt is essential to run each keeper from an individual address that does not\nhave any pending transactions. That is why before starting each keeper, doing\na `plunger --source parity_txqueue --wait 0x.....` is recommended.\n\nIf you want to discuss this tool, the best place is the _#keeper_ channel\nin the Maker RocketChat, linked above.\n\n\n## Installation\n\nThis project uses *Python 3.6.6*.\n\nIn order to clone the project and install required third-party packages please execute:\n```\ngit clone https://github.com/makerdao/plunger.git\ncd plunger\ngit submodule update --init --recursive\n./install.sh\n```\n\n### Known macOS issues\n\nIn order for the requirements to install correctly on _macOS_, please install\n`openssl`, `libtool` and `pkg-config` using [Homebrew](https://brew.sh/):\n```\nbrew install openssl libtool pkg-config\n```\n\nand set the `LDFLAGS` environment variable before you run `pip3 install -r requirements.txt`:\n```\nexport LDFLAGS=\"-L$(brew --prefix openssl)/lib\" CFLAGS=\"-I$(brew --prefix openssl)/include\" \n```\n\n\n## Usage\n\n```\nusage: plunger [-h] [--rpc-host RPC_HOST] [--rpc-port RPC_PORT]\n               [--gas-price GAS_PRICE] --source SOURCE [-j]\n               (--list | --wait | --override-with-zero-txs) [-s]\n               [--ethgasstation-api-key ETHGASSTATION_API_KEY]\n               [--etherscan-api-key ETHERSCAN_API_KEY]\n               [--poanetwork-url POANETWORK_URL] [--eth-key ETH_KEY]\n               address\n\npositional arguments:\n  address               Ethereum address to check for pending transactions\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --rpc-host RPC_HOST   JSON-RPC host (default: `localhost')\n  --rpc-port RPC_PORT   JSON-RPC port (default: `8545')\n  --gas-price GAS_PRICE\n                        Gas price (in Wei) for overriding transactions\n  --source SOURCE       Comma-separated list of sources to use for pending\n                        transaction discovery (available: parity_txqueue,\n                        jsonrpc_getblock)\n  -j, --json            Generate result as JSON\n  --list                List pending transactions\n  --wait                Wait for the pending transactions to clear\n  --override-with-zero-txs\n                        Override the pending transactions with zero-value txs\n  -s, --smart-gas       Use smart gas strategy to plunge\n  --ethgasstation-api-key ETHGASSTATION_API_KEY\n                        ethgasstation API key\n  --etherscan-api-key ETHERSCAN_API_KEY\n                        etherscan API key\n  --poanetwork-url POANETWORK_URL\n                        Alternative POANetwork URL\n  --eth-key ETH_KEY     Ethereum private key to use (e.g.\n                        'key_file=aaa.json,pass_file=aaa.pass') for unlocking\n                        account\n```\n\n### Listing pending transactions\n\nIf you want _plunger_ to only list pending transactions originating from the specified address,\ncall it with the `--list` argument:\n\n```bash\nbin/plunger --source parity_txqueue,jsonrpc_getblock --list 0x0101010101010101010101010101010101010101\n```\n\n### Waiting for pending transactions to clear\n\nIf you want _plunger_ to just wait for the pending transactions from the specified address\nto get processed by the network (i.e. to get mined), run it with the `--wait` argument:\n\n```bash\nbin/plunger --source parity_txqueue,jsonrpc_getblock --wait 0x0101010101010101010101010101010101010101\n```\n\nThis is a completely passive mode i.e. no Ethereum transactions get sent by _plunger_\nif called with `--wait`.\n\n_Plunger_ will not terminate until all pending transactions get mined. If it for some exceptional\nreason (the Ethereum node going down or some other network connectivity issues) terminates earlier\nthan that, it will return a non-zero exit code.\n\n### Overriding pending transactions\n\nIf you want _plunger_ to try to override all pending transactions with a zero Wei ether transfer\nbut with gas cost higher than the original, run it with the `--override-with-zero-txs` argument:\n\n```bash\nbin/plunger --source parity_txqueue,jsonrpc_getblock --override-with-zero-txs 0x0101010101010101010101010101010101010101\n```\n\n_Plunger_ will send replacement transactions immediately, then it will start monitoring the\nnetwork and will not terminate until all pending transactions or their replacements get mined.\n**Due to the nature of the Ethereum network, there is no guarantee which transactions will\nactually get executed.** It is possible that some of the original stuck ones will actually\nget through. You can also get a mix of old and new ones being mined when there is more than\none transaction pending.\n\nIf for some exceptional reason (the Ethereum node going down or some other network\nconnectivity issues) _plunger_ terminates before all pending transactions from the specified\naddress get mined, it will return a non-zero exit code.\n\nThe account specified has to be unlocked for _plunger_ to be able to sign and send replacement\ntransactions; use `--eth-key` parameter to unlock the account.\n\n### Gas price\n\nGas price for overriding transactions can be specified using the `--gas-price` argument.\n\n##### Smart gas price\nPass `--smart-gas` argument for using an aggregator client which combines multiple gas price sources \nto produce a single price. The gas price for overriding transaction is the fastest gas price determined by client * 1.1.  \nNOTE: Supply API keys to avoid rate limiting and exclusion of sources which require a key.\n                                                                                                         \nIf `--gas-price` or `--smart-gas` arguments are not present, _plunger_ will use the default gas price suggested by\nthe Ethereum node it is connected to.\n\nBear in mind that the new gas price has to be at least 12.5% higher than the original one,\notherwise Parity will not even accept such a replacement transaction. If it happens, _plunger_\nwill display an error message but will still wait for the pending transactions to get mined\nas it is still possible the original one will go through. \n\n### Pending transactions discovery\n\nThe `--source` argument has to be used to specify how _plunger_ should discover pending transactions.\nTwo methods are currently supported:\n  - **JSON-RPC API** (`--source jsonrpc_getblock`) has been tested on both _Parity_ and _geth_.\n  - **Parity transaction queue** (`--source parity_txqueue`) is a custom _Parity_ RPC endpoint\n  which will not work with _geth_.\n\nBoth discovery methods can be used at the same time (`--source parity_txqueue,jsonrpc_getblock`).\n\n\n## Testing\n\n### Automated testing\n\nA unit-test harness is present for testing almost all _plunger_ features. It can be run\nwith the `./test.sh` script, preceded by installing necessary dependencies with\n`pip3 install -r requirements-dev.txt`.\n\n### Manual testing\n\nManual testing uses seth. Installation information can be found here: [https://dapp.tools/seth/](https://dapp.tools/seth/)\n\nThe following commands can be used to manually test _plunger_. The first two commands\nsend 1 Wei transfers with a pretty low gas price of 0.5 GWei, so they won't instantly\nget mined and will very likely get stuck. The third command runs _plunger_ using the same\naccount, so if everything works correctly we can see these two transactions being plunged.\n\n```\nexport ETH_FROM=0x001.......\n\nseth send --async --gas-price=500000000 --value=1 -F $ETH_FROM $ETH_FROM\nseth send --async --gas-price=500000000 --value=1 -F $ETH_FROM $ETH_FROM\n\nbin/plunger --rpc-host \u003cYOUR_RPC_HOST\u003e --source parity_txqueue --override-with-zero-txs $ETH_FROM --eth-key \u003cYOUR_CREDENTIALS\u003e\n```\n\nThe above snippet uses `seth` (see \u003chttps://github.com/dapphub/dapptools/tree/master/src/seth\u003e) for sending transactions.\n\n\n## License\n\nSee [COPYING](https://github.com/makerdao/plunger/blob/master/COPYING) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakerdao%2Fplunger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakerdao%2Fplunger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakerdao%2Fplunger/lists"}