{"id":20433853,"url":"https://github.com/flashbots/mev-share-client-ts","last_synced_at":"2025-04-06T12:08:19.876Z","repository":{"id":142990076,"uuid":"612408902","full_name":"flashbots/mev-share-client-ts","owner":"flashbots","description":"Client library for Flashbots MEV-share Matchmaker.","archived":false,"fork":false,"pushed_at":"2024-05-08T19:13:01.000Z","size":384,"stargazers_count":124,"open_issues_count":9,"forks_count":27,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-30T11:06:42.815Z","etag":null,"topics":["flashbots","matchmaker","mev-share"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@flashbots/mev-share-client","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flashbots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-03-10T22:10:06.000Z","updated_at":"2025-03-21T12:06:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"d3cb0c86-03ec-4034-be19-2a82634736d4","html_url":"https://github.com/flashbots/mev-share-client-ts","commit_stats":null,"previous_names":["flashbots/matchmaker-ts"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-share-client-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-share-client-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-share-client-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-share-client-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flashbots","download_url":"https://codeload.github.com/flashbots/mev-share-client-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478321,"owners_count":20945266,"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":["flashbots","matchmaker","mev-share"],"created_at":"2024-11-15T08:21:49.798Z","updated_at":"2025-04-06T12:08:19.854Z","avatar_url":"https://github.com/flashbots.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flashbots MEV-Share Client\n\nClient library for MEV-Share written in Typescript.\n\nBased on [MEV-Share Spec](https://github.com/flashbots/mev-share).\n\n## quickstart\n\nInstall from npm:\n\n```sh\nyarn add @flashbots/mev-share-client\n# or\nnpm i @flashbots/mev-share-client\n```\n\nAlternatively, clone the library \u0026 build from source:\n\n```sh\ngit clone https://github.com/flashbots/mev-share-client-ts\ncd mev-share-client-ts\nyarn install \u0026\u0026 yarn build\n```\n\n```sh\n# in your project, assuming it has the same parent directory as mev-share-client-ts\nyarn add ../mev-share-client-ts\n```\n\n### use mev-share-client in your project\n\n\u003e :warning: Variables denoted in `ALL_CAPS` are placeholders; the code does not compile. [examples/](#examples) contains compilable demos.\n\nIn your project:\n\n```typescript\nimport { Wallet, JsonRpcProvider } from \"ethers\"\nimport MevShareClient, {\n    BundleParams,\n    HintPreferences,\n    IPendingBundle,\n    IPendingTransaction,\n    TransactionOptions\n} from \"@flashbots/mev-share-client\"\n\nconst provider = new JsonRpcProvider(RPC_URL)\nconst authSigner = new Wallet(FB_REPUTATION_PRIVATE_KEY, provider)\n```\n\nThe `MevShareClient` class has built-in initializers for networks supported by Flashbots.\n\n#### Connect to Ethereum Mainnet\n\n```typescript\nconst mevshare = MevShareClient.useEthereumMainnet(authSigner)\n```\n\n#### Connect to Ethereum Goerli\n\n```typescript\nconst mevshare = MevShareClient.useEthereumGoerli(authSigner)\n```\n\n#### Connect with an Ethers Provider or Chain ID\n\nNetworks supported by Flashbots have presets built-in. If it's more convenient, you can instantiate a MevShareClient using a `chainId` (or a ethers.js `Network` object, which has a `chainId` param).\n\n```typescript\nimport { JsonRpcProvider, Wallet } from \"ethers\" // ethers v6\n\n/** connects to Flashbots MEV-Share node on goerli */\nconst provider = new JsonRpcProvider(\"http://localhost:8545\", {chainId: 5, name: \"goerli\"})\nconst authSigner = new Wallet(\"0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80\")\n    .connect(provider)\n\nconst mevshare = MevShareClient.fromNetwork(authSigner, provider._network)\n\n// manually with a chainId:\nconst mevshare = MevShareClient.fromNetwork(authSigner, {chainId: 5})\n```\n\n#### Connect to a custom network\n\nTo use custom network parameters, you can instantiate a new `MevShareClient` instance directly. This example is what the client uses to connect to mainnet:\n\n```typescript\nconst mevshare = new MevShareClient(authSigner, {\n    name: \"mainnet\",\n    chainId: 1,\n    streamUrl: \"https://mev-share.flashbots.net\",\n    apiUrl: \"https://relay.flashbots.net\"\n})\n```\n\nSee `MevShareNetwork` in [src/api/interfaces](/src/api/interfaces.ts) for more details.\n\n### examples\n\n_[Source code](./src/examples/)_\n\n\u003e :information_source: Examples require a `.env` file (or that you populate your environment directly with the appropriate variables).\n\n```sh\ncd src/examples\ncp .env.example .env\nvim .env\n```\n\n#### send a tx with hints\n\nThis example sends a transaction to the Flashbots MEV-Share node on Goerli from the account specified by SENDER_PRIVATE_KEY with a hex-encoded string as calldata.\n\n```sh\nyarn example.tx\n```\n\n#### backrun a pending tx\n\nThis example watches the mev-share streaming endpoint for pending mev-share transactions and attempts to backrun them all. The example runs until a backrun has been included on-chain.\n\n```sh\nyarn example.backrun\n```\n\n#### query event history\n\nThis example queries event history, starting from the beginning, until it finds events that share transactions and logs.\n\n```sh\nyarn example.history\n```\n\n## Usage\n\nSee [src/api/interfaces.ts](src/api/interfaces.ts) for interface definitions.\n\n### `on`\n\nUse `on` to start listening for events on mev-share. The function registers the provided callback to be called when a new event is detected.\n\n```typescript\nconst handler = mevshare.on(\"transaction\", (tx: IPendingTransaction) =\u003e {\n    // handle pending tx\n})\n\n// ... before terminating program\nhandler.close()\n```\n\n### `sendTransaction`\n\nSends a private transaction to the Flashbots MEV-Share node with specified hint parameters.\n\n```typescript\nconst wallet = new Wallet(PRIVATE_KEY)\nconst tx = {\n    to: \"0xfb000000387627910184cc42fc92995913806333\",\n    value: BigInt(1e13 * 275), // price of a beer if ETH is $2000\n    data: \"0x646f637320626179626565652121\",\n    gasLimit: 42000,\n    maxFeePerGas: BigInt(1e9) * BigInt(42), // 42 gwei / gas\n    maxPriorityFeePerGas: BigInt(1e9) * BigInt(2), // 2 gwei / gas\n    chainId: 5,\n    type: 2,\n}\n\n// privacy \u0026 inclusion settings\nconst shareTxParams: TransactionOptions = {\n    hints: {\n        logs: true,\n        calldata: false,\n        functionSelector: true,\n        contractAddress: true,\n    },\n    maxBlockNumber: undefined,\n    builders: [\"flashbots\"]\n}\n\nconst signedTx = await wallet.signTransaction(tx)\nawait mevshare.sendTransaction(SIGNED_TX, shareTxParams)\n```\n\n### `sendBundle`\n\nSends a bundle; an array of transactions with parameters to specify conditions for inclusion and MEV kickbacks. Transactions are placed in the `body` parameter with wrappers to indicate whether they're a new signed transaction or a pending transaction from the event stream.\n\nSee [MEV-Share Docs](https://github.com/flashbots/mev-share/blob/main/specs/bundles/v0.1.md) for detailed descriptions of these parameters.\n\n```typescript\nconst targetBlock = 1 + await provider.getBlockNumber()\nconst bundleParams: BundleParams = {\n    inclusion: {\n        block: targetBlock,\n    },\n    body: [\n        {hash: TX_HASH_FROM_EVENT_STREAM},\n        {tx: SIGNED_TX, canRevert: false},\n    ],\n}\nawait mevshare.sendBundle(bundleParams)\n```\n\nBundles that _only_ contain signed transactions can share hints about the transactions in their bundle by setting the `privacy` parameter:\n\n```typescript\nconst targetBlock = 1 + await provider.getBlockNumber()\nconst bundleParams: BundleParams = {\n    inclusion: {\n        block: targetBlock,\n        maxBlock: targetBlock + 5, // allow bundle to land in next 5 blocks\n    },\n    body: [\n        {tx: await wallet.signTransaction(TX1), canRevert: false},\n        {tx: await wallet.signTransaction(TX2), canRevert: false},\n    ],\n    privacy: {\n        hints: {\n            txHash: true,\n            calldata: true,\n            logs: true,\n            functionSelector: true,\n            contractAddress: true,\n        },\n    }\n}\nconst backrunResult = await mevshare.sendBundle(bundleParams)\n```\n\n### `simulateBundle`\n\nSimulates a bundle. Accepts options to modify block header for simulation.\n\n```typescript\nconst bundle: BundleParams = {\n    inclusion: {\n        block: TARGET_BLOCK,\n        maxBlock: TARGET_BLOCK + 3,\n    },\n    body: [\n        {hash: \"0xTARGET_TX_HASH\"},\n        {tx: \"0xSIGNED_BACKRUN_TX\", canRevert: false}\n    ],\n    // ...\n}\n\n// ...\n// assume you sent the bundle and it didn't land, and you want to see if it would have landed in the previous block, but need the tx to think it's in the target block\n\nconst simBundleOptions: SimBundleOptions = {\n    parentBlock: TARGET_BLOCK - 1,\n    blockNumber: TARGET_BLOCK,\n    /*\n    Set any of these (block header) fields to override their respective values in the simulation context: \n    */\n    // coinbase: string,\n    // timestamp: number,\n    // gasLimit: number,\n    // baseFee: bigint,\n    // timeout: number,\n}\n\nconst simResult = await mevshare.simulateBundle(bundle, simBundleOptions)\n```\n\nThis example uses the state of `parentBlock`, but overrides the state's `blockNumber` value. Setting more fields in `SimBundleOptions` is useful when testing smart contracts which have specific criteria that must be met, like the block being a certain number, or a specific timestamp having passed.\n\n### `getEventHistoryInfo`\n\nGet information about the event history endpoint for use in [`getEventHistory`](#geteventhistory).\n\nExample:\n\n```typescript\nconst info = await mevshare.getEventHistoryInfo()\nconsole.log(info)\n```\n\nreturns something like this:\n\n```txt\n{\n  count: 56934,\n  minBlock: 9091377,\n  maxBlock: 9190024,\n  minTimestamp: 1685452445,\n  maxTimestamp: 1686943324,\n  maxLimit: 500\n}\n```\n\n### `getEventHistory`\n\nGet historical event stream data.\n\nUsing the data from our [`getEventHistoryInfo`](#geteventhistoryinfo) call, we can read events starting from the beginning. The data is paginated, so to read all of it, you'll have to make multiple calls to iterate through the it.\n\n```typescript\nconst info = await mevshare.getEventHistoryInfo()\n\n// read every event\nfor (let i = 0; i \u003c Math.ceil(info.count / info.maxLimit); i++) {\n    const events = await mevshare.getEventHistory({\n        limit: info.maxLimit,\n        offset: i * info.maxLimit,\n        blockStart: info.minBlock,\n    })\n    console.log(events)\n}\n```\n\nYou can also filter events by timestamp:\n\n```typescript\nconst events = await mevshare.getEventHistory({\n    limit: info.maxLimit,\n    offset: i * info.maxLimit,\n    timestampStart: 1686942023,\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fmev-share-client-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflashbots%2Fmev-share-client-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fmev-share-client-ts/lists"}