{"id":21531975,"url":"https://github.com/chainbound/bolt","last_synced_at":"2025-04-05T17:04:02.574Z","repository":{"id":243531543,"uuid":"790596173","full_name":"chainbound/bolt","owner":"chainbound","description":"Bolt: permissionless proposer commitments on Ethereum","archived":false,"fork":false,"pushed_at":"2025-03-10T07:53:43.000Z","size":35174,"stargazers_count":91,"open_issues_count":80,"forks_count":26,"subscribers_count":5,"default_branch":"unstable","last_synced_at":"2025-03-29T16:03:33.964Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.boltprotocol.xyz","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chainbound.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-04-23T07:08:18.000Z","updated_at":"2025-03-23T08:35:17.000Z","dependencies_parsed_at":"2024-11-07T16:35:39.899Z","dependency_job_id":"9fdfae07-ff2d-41d2-a4d2-995a4225db95","html_url":"https://github.com/chainbound/bolt","commit_stats":null,"previous_names":["chainbound/bolt"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Fbolt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Fbolt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Fbolt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainbound%2Fbolt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chainbound","download_url":"https://codeload.github.com/chainbound/bolt/tar.gz/refs/heads/unstable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369953,"owners_count":20927928,"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":[],"created_at":"2024-11-24T02:18:23.034Z","updated_at":"2025-04-05T17:04:02.555Z","avatar_url":"https://github.com/chainbound.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource srcset=\"./.github/assets/bolt-logo-wm-dark.png\" media=\"(prefers-color-scheme: dark)\"\u003e\n    \u003csource srcset=\"./.github/assets/bolt-logo-wm-light.png\" media=\"(prefers-color-scheme: light)\"\u003e\n    \u003cimg src=\"./.github/assets/bolt-logo-wm-light.png\" alt=\"BOLT\" width=\"450px\"\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Docs](https://img.shields.io/badge/Docs-7B36ED?style=for-the-badge\u0026logo=gitbook\u0026logoColor=white)][docs]\n[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge\u0026logo=twitter\u0026logoColor=white)][twitter]\n[![Discord](https://img.shields.io/badge/Discord-7289DA?style=for-the-badge\u0026logo=discord\u0026logoColor=white)][discord]\n\n\u003c/div\u003e\n\n\u003e [!IMPORTANT]\n\u003e Bolt is an implementation of permissionless proposer commitments that is fully compatible with PBS.\n\u003e In its essence, it consists in a fork of the MEV-Boost stack that allows users to request commitments\n\u003e like preconfirmations from proposers, and then adds a way for proposers to commit to transaction\n\u003e inclusion in a way that is verifiable on-chain.\n\n\u003c!-- vim-markdown-toc Marked --\u003e\n\n- [How it works](#how-it-works)\n- [Project structure](#project-structure)\n  - [Additional components](#additional-components)\n- [Kurtosis Devnet](#kurtosis-devnet)\n  - [Requirements and setup](#requirements-and-setup)\n  - [Running the devnet](#running-the-devnet)\n  - [Stopping the devnet](#stopping-the-devnet)\n- [License](#license)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## How it works\n\nThe technical flow of Bolt can be summarized in the following steps:\n\n1. Users submit transactions to an RPC endpoint that will forward them to the\n   proposer opted-in to Bolt in the beacon chain lookahead window.\n2. The proposer can accept this request and turn it into a _commitment_ relative to the\n   block that it is going to propose. This commitment acts as guarantee of inclusion of\n   the transaction in the block, also known as a _preconfirmation_.\n3. Near the time of block proposal, the proposer will share the list of committed transactions\n   with the relays that are connected to block builders. This list is called a _constraint_.\n4. Builders subscribe to proposer constraints in real time through a new relay\n   streaming endpoint to keep informed about the outstanding preconfirmations.\n5. Builders build valid blocks that adhere to all _constraints_, and append inclusion\n   proofs together with the bids to the relay for trustless verification.\n6. When it's time to propose a block, the proposer will fetch the best valid bid\n   from the relay, and verify its inclusion proofs locally before signing the header.\n7. If the constraints are respected, the proposer can propose the payload as usual\n   by sending the signed header back to the relay. If not, the proposer can self-build\n   a payload and propose it directly instead.\n\n\u003cdetails\u003e\n\u003csummary\u003eHere is a diagram illustrating the flow explained above:\u003c/summary\u003e\n\n```mermaid\nsequenceDiagram\n    participant Beacon Node as beacon node\n    participant Bolt Sidecar as bolt-sidecar\n    participant MEV-Boost as mev-boost\n    participant PBS Relay as pbs relay\n\n    Beacon Node-\u003e\u003eBolt Sidecar: /eth/v1/builder/header\n    Note over Beacon Node, Bolt Sidecar: when it's time, the proposer's beacon node will ask for an externally built payload\n\n    Bolt Sidecar-\u003e\u003eMEV-Boost: /eth/v1/builder/header\n    MEV-Boost-\u003e\u003ePBS Relay: /eth/v1/builder/header_with_proofs\n    PBS Relay-\u003e\u003eMEV-Boost: ExecutionPayloadHeader + InclusionProofs\n    MEV-Boost-\u003e\u003eBolt Sidecar: ExecutionPayloadHeader + InclusionProofs\n\n    alt Inclusion proofs sent by the relay are VALID\n        Bolt Sidecar-\u003e\u003eBeacon Node: ExecutionPayloadHeader\n        Bolt Sidecar-\u003e\u003eMEV-Boost: /eth/v1/builder/blinded-blocks\n        MEV-Boost-\u003e\u003ePBS Relay: /eth/v1/builder/blinded-blocks\n        Note over MEV-Boost, PBS Relay: the relay can now broadcast the full payload.\n    else Inclusion proofs sent by the relay are INVALID\n        PBS Relay-\u003e\u003eMEV-Boost: nil response\n        Bolt Sidecar-\u003e\u003eBeacon Node: bolt-sidecar will generate a fallback ExecutionPayload that follows all constraints committed to by the proposer.\n        Bolt Sidecar-\u003e\u003eMEV-Boost: /eth/v1/builder/blinded-blocks\n        MEV-Boost-\u003e\u003ePBS Relay: /eth/v1/builder/blinded-blocks\n        PBS Relay-\u003e\u003eBeacon Node: ExecutionPayload\n        Note over Beacon Node, Bolt Sidecar: after receiving the payload, the beacon node will broadcast it to the beacon chain p2p network.\n    end\n```\n\n\u003c/details\u003e\n\n## Project structure\n\nThis repository contains most of the necessary components of the Bolt protocol stack.\nIn particular, the core components are:\n\n- [**Bolt Sidecar**](./bolt-sidecar/): New validator software (akin to [mev-boost][fb-mev-boost])\n  that handles the receipt of preconfirmation requests from users, translates them\n  into _constraints_, and forwards them to relays. Additionally, it handles the\n  fallback logic to produce a block locally when relays send invalid inclusion proofs.\n- [**Bolt Contracts**](./bolt-contracts/): A set of smart contracts for peripheral functionality\n  such as proposer registration and permissionless dispute resolution for attributable faults.\n- [**Bolt Boost**](./bolt-boost/): A [Commit-Boost][commit-boost] module that implements the Constraints-API.\n- [**Bolt CLI**](./bolt-cli/): A CLI tool to interact with Bolt components in a safe and easy way.\n- [**Boltup**](./boltup/): Script to install the `bolt` CLI tool on any machine with a single command.\n- [**Guides**](./guides/): A set of guides and scripts for consumers and builders to learn how to use Bolt.\n- [**Scripts**](./scripts/): A collection of scripts to build and run the Kurtosis devnet locally.\n\n### Additional components\n\nBolt also relies on a few external components that are not part of this repository:\n\n- [**Ethereum Package**](https://github.com/chainbound/ethereum-package): A fork of the Kurtosis\n  Ethereum package with custom components for Bolt.\n- [**Helix Relay**](https://github.com/chainbound/helix): A fork of the [Gattaca Helix][helix] relay that\n  implements the Constraints API to proxy requests from the Bolt Sidecar to the connected builders.\n- [**Bolt Builder**](https://github.com/chainbound/bolt-builder): A fork of the [Flashbots builder][fb-builder] that\n  subscribes to new constraints from relays, builds blocks that respect them, and\n  includes the necessary proofs of inclusion in the bids submitted to relays.\n- [**Bolt MEV-Boost**](https://github.com/chainbound/bolt-mev-boost): A fork of the [Flashbots MEV-Boost][fb-mev-boost]\n  sidecar that includes new API endpoints to proxy requests from the Bolt Sidecar to the connected relays.\n\n\u003cdetails\u003e\n\u003csummary\u003eList of legacy components that are not updated to the latest version of Bolt:\u003c/summary\u003e\n\n- [**Web demo**](https://github.com/chainbound/bolt-web-demo-legacy): A simple web interface to interact\n  with the Bolt Sidecar and submit preconfirmation requests to proposers for inclusion in blocks.\n- [**MEV-Boost-Relay**](https://github.com/chainbound/bolt-mev-boost-relay): A fork of the Flashbots\n  [MEV-Boost relay][fb-relay] that includes new API endpoints to proxy requests from the Bolt Sidecar\n  to the connected builders.\n\n\u003c/details\u003e\n\n## Kurtosis Devnet\n\nWe are using a forked [Kurtosis][kurtosis] devnet stack, with custom Docker images\nfor the core components outlined above. The exact version of the Ethereum-package used\nin our devnet can be seen [here](https://github.com/chainbound/ethereum-package).\n\n### Requirements and setup\n\n8GB of RAM and a modern laptop CPU are recommended to run the devnet efficiently,\nbut it should work on most machines. Please [Open an issue][new-issue] if you encounter any problems.\n\nMake sure you have the following requirements on your machine:\n\n- [Docker engine](https://docs.docker.com/engine/install/) installed and running\n- [Just](https://github.com/casey/just) installed\n- [Kurtosis CLI](https://docs.kurtosis.com/install/) installed\n- [Foundry](https://book.getfoundry.sh/getting-started/installation) installed\n- [Rust \u0026 Cargo](https://www.rust-lang.org/tools/install) installed\n- [`cargo nextest`](https://nexte.st/)\n\n\u003e [!NOTE]\n\u003e The Kurtosis CLI version tested is `0.88.16`. Some issues may arise if you are\n\u003e using a different version.\n\u003e\n\u003e [Please make sure to install the correct version](https://docs.kurtosis.com/install-historical/).\n\nThen, clone this repository and navigate to the root directory of the project:\n\n```shell\ngit clone git@github.com:chainbound/bolt.git \u0026\u0026 cd bolt\n```\n\n### Running the devnet\n\nRunning the devnet is straightforward once you have the requirements\ninstalled. Just run the following commands in your terminal:\n\n```shell\n# build all necessary docker images locally first\njust build-local-images\n\n# spin up the kurtosis devnet on your machine\njust up\n```\n\n**Commit-Boost support**\n\nThe devnet by default will run using a fork of MEV-Boost which supports\nthe [Constraints-API](https://docs.boltprotocol.xyz/technical-docs/api/builder). Bolt also\nsupports [Commit-Boost][commit-boost] by providing a compatible MEV-Boost module\ncalled _Bolt-Boost_ that implements the Constraints-API. To use it in the devnet\nadd the appropriate `bolt_boost_image` in the `kurtosis_config.yaml` file:\n\n```yaml\n# ... the rest of the file\nmev_params:\n  # Bolt-specific images:\n  # Adding the `bolt_boost_image` will start the devnet with Bolt-Boost\n  # instead of MEV-Boost\n  bolt_boost_image: ghcr.io/chainbound/bolt-boost:v0.4.0-alpha\n  # ... the rest of the `mev_params`\n```\n\n### Stopping the devnet\n\nTo stop the devnet, run the following command:\n\n```shell\n# if you want to simply stop all running containers\njust down\n\n# if you want to remove all the data and stop the Kurtosis engine\njust clean\n```\n\n\u003e [!NOTE]\n\u003e Remember to shut down the devnet environment when you are done with it, as it\n\u003e consumes significant resources (CPU \u0026 RAM) on your machine.\n\n## License\n\nMIT. Forked repositories have their own licenses.\n\n\u003c!-- Links --\u003e\n\n[twitter]: https://twitter.com/boltprotocol_\n[discord]: https://discord.gg/pK8GgjxYQS\n[docs]: https://docs.boltprotocol.xyz/\n[new-issue]: https://github.com/chainbound/bolt/issues/new\n[fb-mev-boost]: https://github.com/flashbots/mev-boost\n[fb-relay]: https://github.com/flashbots/mev-boost-relay\n[fb-builder]: https://github.com/flashbots/builder\n[kurtosis]: https://www.kurtosis.com/\n[helix]: https://github.com/gattaca-com/helix\n[commit-boost]: https://commit-boost.github.io/commit-boost-client/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainbound%2Fbolt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainbound%2Fbolt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainbound%2Fbolt/lists"}