|
| 1 | +--- |
| 2 | +title: Ethers Provider - Flashbot-bundle |
| 3 | +--- |
| 4 | + |
| 5 | +Contains the `FlashbotsBundleProvider` ethers.js provider to provide high-level access to `eth_sendBundle` rpc endpoint on [mev-relay](https://github.com/flashbots/mev-relay-js). |
| 6 | + |
| 7 | +Flashbots-enabled relays and miners expose two new jsonrpc endpoint: `eth_sendBundle` and `eth_callBundle`. Since these are brand-new, non-standard endpoints, ethers.js and other libraries do not natively support these requests (like `getTransactionCount`). In order to interact with these endpoints, you will also need access to another full-featured (non-Flashbots) endpoint for nonce-calculation, gas estimation, and transaction status. |
| 8 | + |
| 9 | +This library is not a fully functional ethers.js implementation, just a simple provider class, designed to interact with your existing ethers.js v5 module. |
| 10 | + |
| 11 | +You can pass in a generic ethers.js provider to the Flashbots provider in the constructor: |
| 12 | + |
| 13 | +```ts |
| 14 | +const NETWORK_INFO = { chainId: 1, ensAddress: '', name: 'mainnet' } |
| 15 | +// Standard json rpc provider directly from ethers.js |
| 16 | +const provider = new providers.JsonRpcProvider({ url: ETHEREUM_RPC_URL }, NETWORK_INFO) |
| 17 | +// `authSigner` is an Ethereum private key that does NOT store funds and is NOT your bot's primary key. |
| 18 | +// This is an identifying key for signing payloads to establish reputation and whitelisting |
| 19 | +const authSigner = new Wallet('0x0000000000000000000000000000000000000000000000000000000000000000') |
| 20 | +// flashbots provider requires passing in a standard provider |
| 21 | +const flashbotsProvider = await FlashbotsBundleProvider.create(provider, authSigner) |
| 22 | +``` |
| 23 | + |
| 24 | +The flashbotsProvider provides the sendBundle function: |
| 25 | + |
| 26 | +```ts |
| 27 | +flashbotsProvider.sendBundle(bundledTransactions: Array<FlashbotsBundleTransaction | FlashbotsBundleRawTransaction>, targetBlockNumber: number) |
| 28 | + => Promise<FlashbotsTransactionResponse> |
| 29 | +``` |
| 30 | + |
| 31 | +and simulate function: |
| 32 | + |
| 33 | +```ts |
| 34 | +flashbotsProvider.simulate( |
| 35 | + signedBundledTransactions: Array<string>, |
| 36 | + blockTag: BlockTag, |
| 37 | + stateBlockTag?: BlockTag, |
| 38 | + blockTimestamp?: number) |
| 39 | + => Promise<SimulationResponse> |
| 40 | +``` |
| 41 | + |
| 42 | +## Example |
| 43 | + |
| 44 | +```ts |
| 45 | +// Using the map below ships two different bundles, targeting the next two blocks |
| 46 | +const blockNumber = await provider.getBlockNumber() |
| 47 | +const minTimestamp = (await provider.getBlock(blockNumber)).timestamp |
| 48 | +const maxTimestamp = minTimestamp + 120 |
| 49 | +const bundlePromises = [blockNumber + 1, blockNumber + 2].map((targetBlockNumber) => |
| 50 | + flashbotsProvider.sendBundle( |
| 51 | + [ |
| 52 | + { |
| 53 | + signedTransaction: SIGNED_ORACLE_UPDATE_FROM_PENDING_POOL // serialized signed transaction hex |
| 54 | + }, |
| 55 | + { |
| 56 | + signer: wallet, // ethers signer |
| 57 | + transaction: transaction // ethers populated transaction object |
| 58 | + } |
| 59 | + ], |
| 60 | + targetBlockNumber, // block number at which this bundle is valid |
| 61 | + { |
| 62 | + minTimestamp, // optional minimum timestamp at which this bundle is valid (inclusive) |
| 63 | + maxTimestamp // optional maximum timestamp at which this bundle is valid (inclusive) |
| 64 | + } |
| 65 | + ) |
| 66 | +) |
| 67 | +``` |
| 68 | + |
| 69 | +## bundledTransactions |
| 70 | + |
| 71 | +A Flashbots bundle consists of one or more transactions in strict order to be relayed to the miner directly. While the miner requires signed transactions, `sendBundle()` can receive a mix of pre-signed transaction and `TransactionRequest` + `Signer` (wallet) objects. |
| 72 | + |
| 73 | +These bundles can pay the miner either via gas fees _OR_ via `block.coinbase.transfer(minerReward)`. |
| 74 | + |
| 75 | +## targetBlockNumber |
| 76 | + |
| 77 | +The only block number for which the bundle is to be considered valid. If you would like more than one block to be targeted, submit multiple rpc calls targeting each specific block. This value should be higher than the value of getBlockNumber(). Submitting a bundle with a target block number of the current block, or earlier, is a no-op. |
| 78 | + |
| 79 | +## FlashbotsTransactionResponse |
| 80 | + |
| 81 | +A high-level object which contains metadata available at transaction submission time, as well as the following functions which can wait, track, and simulate the bundle's behavior. |
| 82 | + |
| 83 | +- receipts() - Returns promise of an array of transaction receipts corresponding to the transaction hashes that were relayed as part of the bundle. Will not wait for block to be mined; could return incomplete information |
| 84 | +- wait() - Returns a promise which will wait for target block number to be reched _OR_ one of the transactions to become invalid due to nonce-issues (including, but not limited to, one of the transactions from you bundle being included too early). Returns the wait resolution as a status enum |
| 85 | +- simulate() - Returns a promise of the transaction simulation, once the proper block height has been reached. Use this function to troubleshoot failing bundles and verify miner profitability |
| 86 | + |
| 87 | +## How to run demo.ts |
| 88 | + |
| 89 | +Included is a simple demo of how to construct the FlashbotsProvider with auth signer authentication and submit a [non-functional] bundle. This will not yield any mev, but could serve as a sample initialization to help integrate into your own functional searcher. |
0 commit comments