|
1 | 1 | # mempool-listener |
2 | 2 | A mempool listener for contract specific transactions. |
3 | 3 |
|
| 4 | +## ⚠️ Warning |
| 5 | +This 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. |
| 6 | + |
| 7 | +## Links |
| 8 | +[GitHub Repository](https://github.com/0xfps/mempool-listener)<br> |
| 9 | +[Node Package Manager (NPM)](https://www.npmjs.com/package/mempool-listener) |
| 10 | + |
4 | 11 | ## Quick Explanation |
5 | | -Assuming we want to set up such a mempool listener for transactions that call the [`mint()`](https://sepolia.arbiscan.io/writecontract/index?m=light&v=21.10.1.1&a=0xe3Bd885d1e0e39Db79f0375AE41048057199F344&n=arbsepolia&p=#collapse2) function at [this contract address](https://sepolia.arbiscan.io/address/0xe3Bd885d1e0e39Db79f0375AE41048057199F344) on Arbitrum Sepolia, this listener will only pick up and return transactions that the data key of their transaction object starts with the function signature `0x40c10f19`. This is achieved by setting up a provider with the Arbitrum Sepolia WSS RPC, configured by the user, not by the code, and using the provider event listeners and then filtering out and returning only the [`mint()`](https://sepolia.arbiscan.io/writecontract/index?m=light&v=21.10.1.1&a=0xe3Bd885d1e0e39Db79f0375AE41048057199F344&n=arbsepolia&p=#collapse2) 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. Refer to [this article](https://www.showwcase.com/article/14647/how-to-listen-to-pending-transactions-using-ethersjs) on how this can be achieved. |
| 12 | +Assuming 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&v=21.10.1.1&a=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789&n=sepolia&p=#collapse5) function at [this contract address](https://sepolia.etherscan.io/writecontract/index?m=light&v=21.10.1.1&a=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&v=21.10.1.1&a=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789&n=sepolia&p=#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. |
| 13 | + |
| 14 | +## Collaborating |
| 15 | +If 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. |
| 16 | + |
| 17 | +## How To Use |
| 18 | +Import package from NPM. |
| 19 | +```shell |
| 20 | +npm install mempool-listener |
| 21 | +``` |
| 22 | + |
| 23 | +Import `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. |
| 24 | +```ts |
| 25 | +// TypeScript. |
| 26 | +import MempoolListener from "mempool-listener" |
| 27 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 28 | +``` |
| 29 | + |
| 30 | +```js |
| 31 | +// JavaScript. |
| 32 | +const MempoolListener = require("mempool-listener").default |
| 33 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 34 | +``` |
| 35 | + |
| 36 | +OR |
| 37 | + |
| 38 | +```js |
| 39 | +// JavaScript. |
| 40 | +const { default: MempoolListener } = require("mempool-listener") |
| 41 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 42 | +``` |
| 43 | + |
| 44 | +Configure 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. |
| 45 | + |
| 46 | +```ts |
| 47 | +// TypeScript. |
| 48 | +import { Abi } from "mempool-listener/build/types/abi-types" |
| 49 | +import { ListenerConfig } from "mempool-listener/build/types/listener-config-types" |
| 50 | + |
| 51 | +const config = { |
| 52 | + address: "0xabcdef", |
| 53 | + abi: ["Contract Abi"] as Abi, |
| 54 | + functionName: "functionName" |
| 55 | +} |
| 56 | + |
| 57 | +function executableFunc(args) { |
| 58 | + console.log(args) |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +```js |
| 63 | +// JavaScript. |
| 64 | +import { Abi } from "mempool-listener/build/types/abi-types" |
| 65 | +import { ListenerConfig } from "mempool-listener/build/types/listener-config-types" |
| 66 | + |
| 67 | +const config = { |
| 68 | + address: "0xabcdef", |
| 69 | + abi: ["Contract Abi"] as Abi, |
| 70 | + functionName: "functionName" |
| 71 | +} |
| 72 | + |
| 73 | +function executableFunc(args) { |
| 74 | + console.log(args) |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +Finally, you can start up your listener passing the `config` and `executableFunc` as arguments. |
| 79 | + |
| 80 | +```ts |
| 81 | +// TypeScript. |
| 82 | +import MempoolListener from "mempool-listener" |
| 83 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 84 | +mempoolListener.listen(config, executableFunc) |
| 85 | +``` |
| 86 | + |
| 87 | +```js |
| 88 | +// JavaScript. |
| 89 | +const MempoolListener = require("mempool-listener").default |
| 90 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 91 | +mempoolListener.listen(config, executableFunc) |
| 92 | +``` |
| 93 | + |
| 94 | +Whenever 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. |
| 95 | + |
| 96 | +You can stop the listener temporarily by calling the `stopListener` function, and, you can restart the listener by calling the `restartListener` function. |
| 97 | + |
| 98 | +```ts |
| 99 | +// TypeScript. |
| 100 | +import MempoolListener from "mempool-listener" |
| 101 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 102 | +mempoolListener.listen(config, executableFunc) |
| 103 | +mempoolListener.stopListener() |
| 104 | +mempoolListener.restartListener() |
| 105 | +``` |
| 106 | + |
| 107 | +```js |
| 108 | +// JavaScript. |
| 109 | +const MempoolListener = require("mempool-listener").default |
| 110 | +const mempoolListener = new MempoolListener("RPC or WSS URL") |
| 111 | +mempoolListener.listen(config, executableFunc) |
| 112 | +mempoolListener.stopListener() |
| 113 | +mempoolListener.restartListener() |
| 114 | +``` |
| 115 | + |
| 116 | +Trying to stop or restart an undefined listener will do nothing. |
| 117 | + |
| 118 | +## License |
| 119 | +GPL-3.0. |
0 commit comments