Warning:
this component has no documented requirements. A new requirements page should be created and linked to this component.
|
Contents |
The builder consumes consensus events emitted by the HotShot Event Stream and also handles HTTP requests from external clients.
These are emitted by the HotShot consensus protocol. Each event is associated with a view number, for which the builder maintains a centralized record (called the ”global state”) that tracks what has been received.
Transactions Represents new transactions submitted to the public mempool.
DA Proposal Provides data availability information for a block.
Quorum Proposal Represents a block proposal that needs to be supported by a quorum of nodes.
Decide Signifies that a view has been finalized by HotShot.
Clients interact with the builder through HTTP APIs. The endpoints allow clients to submit transactions, query metadata, and fetch blocks constructed by the builder.
POST /submittxn Submit a transaction directly to the builder’s private mempool.
POST /submitbatch Submit a list of transactions directly to the builder’s private mempool.
GET /availableblocks Lists all block candidates for a given parent block and view.
GET /claimblock Returns the full block data for a specific hash.
GET /claimheaderinput Returns the header for a specific block.
GET /builderaddress Returns the public key identifying the builder.
Each view has a lifecycle tracked by the builder. Internally, builder states are indexed by view number and VID commitment. There are also storages for in-progress DA and quorum proposals, indexed by view number and builder commitment. Multiple proposals for the same view is allowed, as long as they correspond to different VID and builder commitments. See Builder State Refactor for additional consideration about builder states.
Initialization The builder receives either a quorum or a DA proposal from HotShot. It records the proposal in a builder state associated with the view number.
Collection When both types of proposals are available for the same view number, the builder considers this view ”ready for construction.”
Update A new builder state is spawned for the next view, using the current view as its parent. This makes it possible for the builder to construct a candidate block that extends the existing chain state to avoid double-inclusion or missing transactions, but the builder does not actually construct the block at this stage. Instead, the child state begins collecting transactions and waits until a client queries the available block candidates to perform the construction.
Finalization When a finalized leaf is received, the builder marks that view as completed and prunes old state information.
Note that the view number itself advances according to HotShot consensus. Each new proposal or finalized leaf refers to a specific view, and the builder does not advance views independently–it only reacts to what HotShot emits.
When both quorum and DA proposals exist for a view, the builder enters the block building process.
Constuct a candidate block from available transactions.
Produce block header and payload.
Make the block data available through HTTP APIs.
Currently, each builder state handles its own decision-making and spawns new builder states based on received quorum and DA proposals. This approach may introduce redundancy and complexity.
To avoid the potential issues above and improve consistency and scalability, we implemented a refactor to handle the builder state spawning in a clearer and less error-prone way by a centralized state coordinator. It indexes both proposals and builder states by view number and builder commitment, and is responsible for tracking the active builder states and deciding which state should be extended to spawn a new state.
Note that this refactor has not been integrated into the codebase.