{"id":41504242,"url":"https://github.com/primev/primev-builder","last_synced_at":"2026-01-23T19:14:21.422Z","repository":{"id":166135119,"uuid":"637976854","full_name":"primev/primev-builder","owner":"primev","description":"builder-boost enabled Flashbots Builder (reference implementation)","archived":false,"fork":false,"pushed_at":"2023-08-30T23:03:09.000Z","size":163901,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-20T14:32:43.771Z","etag":null,"topics":["blockbuilder","ethereum","flashbots","geth","geth-node","mev","protocol"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-08T20:20:16.000Z","updated_at":"2024-10-27T04:12:19.000Z","dependencies_parsed_at":"2024-05-20T23:30:11.243Z","dependency_job_id":null,"html_url":"https://github.com/primev/primev-builder","commit_stats":null,"previous_names":["primev/primev-builder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/primev/primev-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primev%2Fprimev-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primev%2Fprimev-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primev%2Fprimev-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primev%2Fprimev-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primev","download_url":"https://codeload.github.com/primev/primev-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primev%2Fprimev-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28698455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T17:25:48.045Z","status":"ssl_error","status_checked_at":"2026-01-23T17:25:47.153Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["blockbuilder","ethereum","flashbots","geth","geth-node","mev","protocol"],"created_at":"2026-01-23T19:14:20.535Z","updated_at":"2026-01-23T19:14:21.414Z","avatar_url":"https://github.com/primev.png","language":"Go","readme":"[geth readme](README.original.md)\n\n# Primev Block Builder\n\nThis project implements the Primev blockbuilder, based on Flashbots' fork of go-ethereum (geth). This version accepts a new cli flag for a Primev endpoint. When a block is built it will send it to the configured address.\n\nBig shoutout to flashbots for paving the way of PBS/mev research and setting standards that others can openly build on. Below info follows flashbots' open source builder docs:\n\nSee also: https://docs.flashbots.net/flashbots-mev-boost/block-builders\n\nRun on your favorite network, including Mainnet, Goerli, Sepolia and local devnet. Instructions for running a pos local devnet can be found [here](https://github.com/avalonche/eth-pos-devnet).\n\nYou will need to run a modified beacon node that sends a custom rpc call to trigger block building. You can use the modified [prysm fork](https://github.com/flashbots/prysm) for this.\n\nTest with [mev-boost](https://github.com/flashbots/mev-boost) and [mev-boost test cli](https://github.com/flashbots/mev-boost/tree/main/cmd/test-cli).\n\nBuilding `geth` requires both a Go (version 1.19 or later) and a C compiler. You can install\nthem using your favourite package manager. Once the dependencies are installed, run\n\n## How it works\n\n* Builder sends each block template to the new local relay introduced in the Primev version to send the payload the the builder-boost instance (see [builder-boost](https://github.com/primevprotocol/builder-boost)\n* Builder polls relay for the proposer registrations for the next epoch when block building is triggered\n* If both local relay and remote relay are enabled, local relay will overwrite remote relay data. This is only meant for the testnets!\n\n## Primev Builder modifications present in this repo\n### Overview\nBuilder will consistently spin up lightweight go-routines to POST new templates.\n![boost img](https://github.com/primevprotocol/primev-builder/assets/13987321/d203dbd6-3dc9-4c4e-bf96-2e39073b7330)\n\n## Quickstart (5 mins)\n1. Clone the repository\n2. Build the instance and add the flag -builder.remote_primev_endpoint \u003cyour-builder-boost-url\u003e --builder.primev_token \u003cyour-selected-private-token\u003e\n\n## Advanced instructions (optional - self customize)\n### **General Overview of Changes Needed**\n\nThe idea behind the builder changes is to enable a new local “relay” to publish blocks to, in a very similar fashion to how blocks are sent to relays like flashbots, blocknative, or agnostic today.\n\nBelow is a more detailed perspective of the standard flow in the Flashbots builder. We add a command of **`go SubmitBlockPrimev(\u0026blockData)`** in the SubmitBlock section.\n\nGeth instances have the concept of an IRelay. You simply need to add a **`SubmitBlockPrimev`** to such a relay that is in use and configure any necessary configurations via modifications similar to this commit: **https://github.com/primevprotocol/builder-reference-primev/commit/9f160e8934fef1aadd21e095c432db41538b93af**\n\n## **Step by Step Walkthrough**\n\n## **Step 1. Registering the Builder Boost environment variables**\n\n### Step 1a. Primev Endpoint\n\nYou can view the entire commit for this section below.\n\n**[Commit: 9f160e8934fef1aadd21e095c432db41538b93af](https://github.com/primevprotocol/builder-reference-primev/commit/9f160e8934fef1aadd21e095c432db41538b93af)**\n\nBy the end of this, you can build Geth, and you will see the following output:\n\n```\nbashCopy code\n**WARN [timestamp] Remote Primev Endpoint is not Set, payloads will not be sent to Primev Network**\n\n```\n\nIf you set the correct environment variable **`BUILDER_REMOTE_PRIMEV_ENDPOINT`** or pass in the flag **`builder.remote_primev_endpoint`** while running Geth, you'll see the following successful message:\n\n```\nbashCopy code\n**INFO [timestamp] Remote Primev Endpoint is Set, payloads will be sent to Primev Network endpoint=\u003cYour builder boost URL\u003e**\n\n```\n\n### Step 1b. Primev auth Token\nThe **primev auth token** is used to authorize and authenticate the builder instance. This is to ensure only your builders can post payloads to Boost.\n\nThe following link showcases the necessary modifications to set up the Primev Auth Token:\n\n**[Commit: d9b8addd1fdeea8c841a43ff7653e7c9345e7e0d](https://github.com/primevprotocol/primev-builder/commit/d9b8addd1fdeea8c841a43ff7653e7c9345e7e0d)**\n\nWe will describe below in Step 3 how to submit the request. Ensure you make the modification to add the **`X-Builder-Token: \u003cprimev-token\u003e`** header to the POST request that is made to Boost.\n\n## **Step 2. Updating the Relay Interface to Support Block Submission to Primev/Builder Boost**\n\nIn this commit, we simply add all the required function details to support updating the Relay interface to publish to Builder Boost.\n\n**[Commit: 6d8ae9aae17a1b966ac0f682ba9843bd8746dc4f](https://github.com/primevprotocol/builder-reference-primev/commit/6d8ae9aae17a1b966ac0f682ba9843bd8746dc4f)**\n\n## **Step 2a. Update interface needs for Unit Tests**\n\nFollow the commit to add a stub for the **`testRelay`** to ensure it adheres to the new interface.\n\n**[Commit: 122e82ee6072ff2cda94ed8e75fdd861befccd19](https://github.com/primevprotocol/builder-reference-primev/commit/122e82ee6072ff2cda94ed8e75fdd861befccd19)**\n\n## **Step 3. Start Submitting Blocks to Builder Boost**\n\nFinally we submit the block details via a go-routine to ensure we don't block for the response:\n\n**[Commit: 04d81efdf499ada3cee303316665edf0d5945a27](https://github.com/primevprotocol/builder-reference-primev/commit/04d81efdf499ada3cee303316665edf0d5945a27)**\n\nVoila, your builder is now a bleeding edge builder that can share hints! Not some off the shelf stock builder 😉\n\n------\n\nBelow are the rest of builder instructions from the vanilla Flashbots builder:\n\n## Limitations\n\n* Does not accept external blocks\n* Does not have payload cache, only the latest block is available\n\n# Usage\n\nConfigure geth for your network, it will become the block builder.\n\nBuilder-related options:\n```\n$ geth --help\n\n   BUILDER\n\n    --builder                      (default: false)\n          Enable the builder\n\n    --builder.beacon_endpoints value (default: \"http://127.0.0.1:5052\")\n          Comma separated list of beacon endpoints to connect to for beacon chain data\n          [$BUILDER_BEACON_ENDPOINTS]\n\n    --builder.bellatrix_fork_version value (default: \"0x02000000\")\n          Bellatrix fork version. [$BUILDER_BELLATRIX_FORK_VERSION]\n\n    --builder.dry-run              (default: false)\n          Builder only validates blocks without submission to the relay\n\n    --builder.genesis_fork_version value (default: \"0x00000000\")\n          Gensis fork version. [$BUILDER_GENESIS_FORK_VERSION]\n\n    --builder.genesis_validators_root value (default: \"0x0000000000000000000000000000000000000000000000000000000000000000\")\n          Genesis validators root of the network. [$BUILDER_GENESIS_VALIDATORS_ROOT]\n\n    --builder.ignore_late_payload_attributes (default: false)\n          Builder will ignore all but the first payload attributes. Use if your CL sends\n          non-canonical head updates.\n\n    --builder.listen_addr value    (default: \":28545\")\n          Listening address for builder endpoint [$BUILDER_LISTEN_ADDR]\n\n    --builder.local_relay          (default: false)\n          Enable the local relay\n\n    --builder.no_bundle_fetcher    (default: false)\n          Disable the bundle fetcher\n\n    --builder.relay_secret_key value (default: \"0x2fc12ae741f29701f8e30f5de6350766c020cb80768a0ff01e6838ffd2431e11\")\n          Builder local relay API key used for signing headers [$BUILDER_RELAY_SECRET_KEY]\n\n    --builder.remote_relay_endpoint value\n          Relay endpoint to connect to for validator registration data, if not provided\n          will expose validator registration locally [$BUILDER_REMOTE_RELAY_ENDPOINT]\n\n    --builder.secondary_remote_relay_endpoints value\n          Comma separated relay endpoints to connect to for validator registration data\n          missing from the primary remote relay, and to push blocks for registrations\n          missing from or matching the primary [$BUILDER_SECONDARY_REMOTE_RELAY_ENDPOINTS]\n\n    --builder.seconds_in_slot value (default: 12)\n          Set the number of seconds in a slot in the local relay\n\n    --builder.secret_key value     (default: \"0x2fc12ae741f29701f8e30f5de6350766c020cb80768a0ff01e6838ffd2431e11\")\n          Builder key used for signing blocks [$BUILDER_SECRET_KEY]\n\n    --builder.slots_in_epoch value (default: 32)\n          Set the number of slots in an epoch in the local relay\n\n    --builder.validation_blacklist value\n          Path to file containing blacklisted addresses, json-encoded list of strings\n\n    --builder.validator_checks     (default: false)\n          Enable the validator checks\n\n    MINER\n\n    --miner.algotype value         (default: \"mev-geth\")\n          Block building algorithm to use [=mev-geth] (mev-geth, greedy)\n\n    --miner.blocklist value\n          flashbots - Path to JSON file with list of blocked addresses. Miner will ignore\n          txs that touch mentioned addresses.\n\n    --miner.extradata value\n          Block extra data set by the miner (default = client version)\n\n   METRICS\n\n   --metrics.builder value          (default: false)\n            Enable builder metrics collection and reporting\n```\n\nEnvironment variables:\n```\nBUILDER_TX_SIGNING_KEY - private key of the builder used to sign payment transaction, must be the same as the coinbase address\n```\n\n## Metrics\n\nTo enable metrics on the builder you will need to enable metrics with the flags `--metrics --metrics.addr 127.0.0.1 --metrics.builder` which will run\na metrics server serving at `127.0.0.1:6060/debug/metrics`. This will record performance metrics such as block profit and block building times.\nThe full list of metrics can be found in `miner/metrics.go`.\n\nSee the [metrics docs](https://geth.ethereum.org/docs/monitoring/metrics) for geth for more documentation.\n\n## Blacklisting addresses\n\nIf you want to reject transactions interacting with certain addresses, save the addresses in json file with an array of strings. Deciding whether to use such a list, as well as maintaining it, is your own responsibility.\n\n- for block building, use `--miner.blocklist`\n- for validation, use `--builder.validation_blacklist`\n\n--\n\n## Details of the implementation\n\nThere are two parts of the builder.\n\n1. `./builder` responsible for communicating with the relay\n2. `./miner` responsible for producing blocks\n\n### `builder` module\n\nMain logic of the builder is in the `builder.go` file.\n\nBuilder is driven by the consensus client SSE events that sends payload attribute events, triggering the `OnPayloadAttribute` call.\nAfter requesting additional validator data from the relay builder starts building job with `runBuildingJob`.\nBuilding job continuously makes a request to the `miner` with the correct parameters and submits produced block.\n\n* Builder retries build block requests every second on average.\n* If the job is running but a new one is submitted for a different slot we cancel previous job.\n* All jobs have 12s deadline.\n* If new request is submitted for the same slot as before but with different parameters, we run these jobs in parallel.\n  It is possible to receive multiple requests from CL for the same slot but for different parent blocks if there is a possibility\n  of a missed block.\n* All submissions to the relay are rate limited at 2 req/s\n* Only blocks that have more profit than the previous best submissions for the particular job are submitted.\n\nAdditional features of the builder:\n* Builder can submit data about build blocks to the database. It stores block data, included bundles, and all considered bundles.\n  Implemented in `flashbotsextra.IDatabaseService`.\n* It's possible to run local relay in the same process\n* It can validate blocks instead of submitting them to the relay. (see `--builder.dry-run`)\n\n### `miner` module\n\nMiner is responsible for block creation. Request from the `builder` is routed to the `worker.go` where\n`generateWork` does the job of creating a block.\n\n* Coinbase of the block is set to the address of the block proposer, fee recipient of the validator receives its eth\n  in the last tx in the block.\n* We reserve gas for the proposer payment using `proposerTxPrepare` and commit proposer payment after txs are added with\n  `proposerTxCommit`. We do it in a way so all fees received by the block builder are sent to the fee recipient.\n* Transaction insertion is done in `fillTransactionsAlgoWorker` \\ `fillTransactions`. Depending on the algorithm selected.\n  Algo worker (greedy) inserts bundles whenever they belong in the block by effective gas price but default method inserts bundles on top of the block.\n  (see `--miner.algo`)\n* Worker is also responsible for simulating bundles. Bundles are simulated in parallel and results are cached for the particular parent block.\n* `algo_greedy.go` implements logic of the block building. Bundles and transactions are sorted in the order of effective gas price then\n  we try to insert everything into to block until gas limit is reached. Failing bundles are reverted during the insertion but txs are not.\n* Builder can filter transactions touching a particular set of addresses.\n  If a bundle or transaction touches one of the addresses it is skipped. (see `--miner.blocklist` flag)\n\n## Bundle Movement\n\nThere are two ways bundles are moved to builders\n\n1. via API -`sendBundle`\n2. via Database - `flashbotsextra.IDatabaseService`\n\n### `fetcher` service\n* Fetcher service is part of `flashbotsextra.IDatabaseService` which is responsible for fetching the bundles from db and pushing into mev bundles queue which will be processed by builder.\n* Fetcher is a background process which fetches high priority and low priority bundles from db.\n* Fetcher fetches `500` high priority bundles on every head change, and `100` low priority bundles in the interval of every `2 seconds`.\n\n## Block builder diagram\n\n![block builder diagram](docs/builder/builder-diagram.png \"Block builder diagram\")\n\n---\n\n# Security\n\nIf you find a security vulnerability in this project or any other initiative\nrelated to proposer/builder separation in Ethereum, please let us know sending\nan email to security@flashbots.net.\n\n---\n\n# License\n\nThe code in this project is free software under the [LGPL License](COPYING.LESSER).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimev%2Fprimev-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimev%2Fprimev-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimev%2Fprimev-builder/lists"}