> For the complete documentation index, see [llms.txt](https://docs.espressosys.com/network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.espressosys.com/network/developer/operators/running-a-builder.md). # Run a Builder ### **Overview** Participants creating blocks for Espresso must run a builder, a piece of software which tracks the state of [HotShot consensus](/network/network/networks.md#protocol-documentation) so that it is able to and propose blocks at the correct time. The builder functions to create a block filled with transactions, drawing from transactions accessible in Espresso's public mempool as well as its own private mempool. Espresso provides a simple builder implementation, which participants can run out-of-the-box or build their own software on top of. This document describes how to run the basic builder software. For comprehensive guidance on the design of an Espresso builder, it is recommended to refer to the [`hotshot-builder-core`](https://github.com/EspressoSystems/hotshot-builder-core) repository. Furthermore, to gain insight into the process of enabling builder services for Espresso network, pertinent information can be found at [`espresso-builder`](https://github.com/EspressoSystems/espresso-network/tree/main/crates/builder). For access to the most recent builder Docker images, please visit [here](https://github.com/EspressoSystems/espresso-network/pkgs/container/espresso-network%2Fbuilder). ### Usage ```bash # Clone the espresso-network repository git clone https://github.com/EspressoSystems/espresso-network # Build the executable in release mode cargo build --release # Run a builder natively target/release/permissionless-builder [options] # To understand more about the available builder options target/release/permissionless-builder -h # Run a node with the builder docker image docker run -it \ [-e ENV=VALUE...] \ ghcr.io/espressosystems/espresso-network/builder:main ``` For a quick start, we recommend referring to the `espresso-network` [docker-compose](https://github.com/EspressoSystems/espresso-network/blob/main/docker-compose.yaml) file, and looking particularly at [`permissionless-builder`](https://github.com/EspressoSystems/espresso-network/blob/ea5e1c143820719535661e9bfaf037f16432c398/docker-compose.yaml#L674-L699). ### Parameters & options
Environment variableCLI flagDescription
ESPRESSO_SEQUENCER_HOTSHOT_EVENT_STREAMING_API_URL--hotshot-event-streaming-urlURL of hotshot events API running on Espresso DA committee node. A builder will subscribe to this server to receive hotshot events. (e.g. http://localhost:8081)
ESPRESSO_BUILDER_ETH_MNEMONIC--eth-mnemonicMnemonic phrase for builder account (e.g. "test test test test test test test test test test test junk")
ESPRESSO_BUILDER_ETH_ACCOUNT_INDEX--eth-account-indexIndex of a funded account. Note: This account must be funded in Espresso, meaning ETH must be bridged from the L1
ESPRESSO_BUILDER_L1_PROVIDER--l1-provider-urlA Url builder will use for RPC communication with L1 (e.g. http://demo-l1-network:8545)
ESPRESSO_SEQUENCER_STATE_PEERS--state-peersPeer nodes use to fetch missing state
ESPRESSO_SEQUENCER_CHAIN_ID--chain-idUnique identifier for an instance of the sequencer network
ESPRESSO_SEQUENCER_MAX_BLOCK_SIZE--max-block-sizeMaximum allowed size (in bytes) for a block
ESPRESSO_SEQUENCER_BASE_FEE--base-feeMinimum fee in WEI per byte of payload
ESPRESSO_BUILDER_SERVER_PORT--portPort to run builder server on through which sequencer node can query builder provided APIs (e.g 41003)
ESPRESSO_BUILDER_BOOTSTRAPPED_VIEW--view-numberBootstrapping View number (e.g. 0)
ESPRESSO_BUILDER_CHANNEL_CAPACITY--channel-capacityThe most outstanding hotshot events a builder wants at a point in time (e.g. 1024)
ESPRESSO_BUILDER_WEBSERVER_RESPONSE_TIMEOUT_DURATION--max-api-timeout-duratioThe amount of time a builder can wait before timing out a request to the API (e.g 1s)
ESPRESSO_BUILDER_BUFFER_VIEW_NUM_COUNT--buffer-view-num-countThe number of views to buffer before a builder garbage collects its state (e.g. 15)
## Hardware requirements Hardware requirements are subject to change as new features are added, but for now we recommend the following: * **Memory**: 4-8 GB * **CPU:** 2-4 Cores --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.espressosys.com/network/developer/operators/running-a-builder.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.