{"id":14958580,"url":"https://github.com/0xfps/mempool-listener","last_synced_at":"2025-05-02T13:30:25.207Z","repository":{"id":253822217,"uuid":"843333067","full_name":"0xfps/mempool-listener","owner":"0xfps","description":"A mempool listener for contract specific transactions.","archived":false,"fork":false,"pushed_at":"2024-08-19T18:59:39.000Z","size":81,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-04-07T02:08:32.550Z","etag":null,"topics":["blockchain","ethereum","evm","listener","mempool","smart-contract"],"latest_commit_sha":null,"homepage":"https://github.com/0xfps/mempool-listener","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xfps.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":"2024-08-16T09:32:16.000Z","updated_at":"2025-03-17T13:07:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"393da393-8a43-48b7-ac80-306d404181ac","html_url":"https://github.com/0xfps/mempool-listener","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"ee0f5a37eec9d84d99081e68b2f6d0cb1224853d"},"previous_names":["0xfps/mempool-listener"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfps%2Fmempool-listener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfps%2Fmempool-listener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfps%2Fmempool-listener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfps%2Fmempool-listener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xfps","download_url":"https://codeload.github.com/0xfps/mempool-listener/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252045995,"owners_count":21685932,"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":["blockchain","ethereum","evm","listener","mempool","smart-contract"],"created_at":"2024-09-24T13:17:26.825Z","updated_at":"2025-05-02T13:30:24.788Z","avatar_url":"https://github.com/0xfps.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mempool-listener\nA mempool listener for contract specific transactions.\n\n## ⚠️ Warning\nThis implementation is for educational purposes and not for production use. The tests carried out with this listener were all done on testnet networks and uses specific RPC endpoints that support the `eth_newPendingTransaction` API. It is nice to note that not all RPC or WSS endpoints support this API.\n\n## Links\n[GitHub Repository](https://github.com/0xfps/mempool-listener)\u003cbr\u003e\n[Node Package Manager (NPM)](https://www.npmjs.com/package/mempool-listener)\n\n## Quick Explanation\nAssuming we want to set up such a mempool listener for transactions that were sent due to a call on the [`handleOps()`](https://sepolia.etherscan.io/writecontract/index?m=light\u0026v=21.10.1.1\u0026a=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789\u0026n=sepolia\u0026p=#collapse5) function at [this contract address](https://sepolia.etherscan.io/writecontract/index?m=light\u0026v=21.10.1.1\u0026a=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789) on Ethereum Sepolia, this listener will only pick up transactions that the data key of their transaction object starts with the function signature `0x1fad948c` and call a set `executableFunction` the listener has been configured with. This is achieved by setting up a provider with a user chosen Ethereum Sepolia WSS or RPC endpoint, and using the provider's event listeners, filter out and work with only the [`handleOps()`](https://sepolia.etherscan.io/writecontract/index?m=light\u0026v=21.10.1.1\u0026a=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789\u0026n=sepolia\u0026p=#collapse5) transactions sent to that contract address that are in the mempool. We can use the ABI for the configured transaction to be listened for to try to extract the values sent as arguments to the transaction and we can try to do stuff with that in the `executableFunction` as the user desires. Refer to [this article](https://www.showwcase.com/article/14647/how-to-listen-to-pending-transactions-using-ethersjs) on how this can be achieved.\n\n## Collaborating\nIf you happen to use this package, and run into some bug, or have some ideas on how I can improve the functionalities, please reach out by opening an [issue](https://github.com/0xfps/mempool-listener/issues). You can also fix it yourself and make a pull request. Thanks, and I appreciate your use of this package.\n\n## How To Use\nImport package from NPM.\n```shell\nnpm install mempool-listener\n```\n\nImport `MempoolListener` into your code file and initialize it with your chosen RPC or WSS endpoint URL. Your RPC or WSS URL should support the [`eth_newPendingTransaction`](https://etclabscore.github.io/core-geth/JSON-RPC-API/modules/eth/#eth_newpendingtransactions) API.\n```ts\n// TypeScript.\nimport MempoolListener from \"mempool-listener\"\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\n```\n\n```js\n// JavaScript.\nconst MempoolListener = require(\"mempool-listener\").default\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\n```\n\nOR\n\n```js\n// JavaScript.\nconst { default: MempoolListener } = require(\"mempool-listener\")\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\n```\n\nConfigure the ABI of the contract, the contract address and function name to listen to. Also, configure your executable function, in this case called `executableFunc`. This is the function that gets called whenever a transaction that matches the `functionName` is picked up by the listener. `executableFunc` **MUST** have one parameter, `args` that is an object containing the arguments in the picked up pending transaction, the value sent to the call, and the gas price paid for the transaction.\n\n```ts\n// TypeScript.\nimport { Abi } from \"mempool-listener/build/types/abi-types\"\nimport { ListenerConfig } from \"mempool-listener/build/types/listener-config-types\"\n\nconst config = {\n    address: \"0xabcdef\",\n    abi: [\"Contract Abi\"] as Abi,\n    functionName: \"functionName\"\n}\n\nfunction executableFunc(args) {\n    console.log(args)\n}\n```\n\n```js\n// JavaScript.\nconst config = {\n    address: \"0xabcdef\",\n    abi: [\"Contract Abi\"],\n    functionName: \"functionName\"\n}\n\nfunction executableFunc(args) {\n    console.log(args)\n}\n```\n\nFinally, you can start up your listener passing the `config` and `executableFunc` as arguments.\n\n```ts\n// TypeScript.\nimport MempoolListener from \"mempool-listener\"\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\nmempoolListener.listen(config, executableFunc)\n```\n\n```js\n// JavaScript.\nconst MempoolListener = require(\"mempool-listener\").default\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\nmempoolListener.listen(config, executableFunc)\n```\n\nWhenever a pending transaction is picked up, it checks for the first four bytes of the `data` key in the transaction data and tries to match it with the selector of the function name you passed in your config. If these two selectors match, the `executableFunc` is called.\n\nYou can stop the listener temporarily by calling the `stopListener` function, and, you can restart the listener by calling the `restartListener` function.\n\n```ts\n// TypeScript.\nimport MempoolListener from \"mempool-listener\"\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\nmempoolListener.listen(config, executableFunc)\nmempoolListener.stopListener()\nmempoolListener.restartListener()\n```\n\n```js\n// JavaScript.\nconst MempoolListener = require(\"mempool-listener\").default\nconst mempoolListener = new MempoolListener(\"RPC or WSS URL\")\nmempoolListener.listen(config, executableFunc)\nmempoolListener.stopListener()\nmempoolListener.restartListener()\n```\n\nTrying to stop or restart an undefined listener will do nothing.\n\n## License\nGPL-3.0.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xfps%2Fmempool-listener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xfps%2Fmempool-listener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xfps%2Fmempool-listener/lists"}