Documentation Index
Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
Use this file to discover all available pages before exploring further.
Overview
BuilderBid represents a block builder’s bid in Proposer-Builder Separation (PBS). Block builders compete through MEV-Boost relays to provide the most valuable block to validators, offering payment in exchange for block inclusion rights.
import * as BuilderBid from '@voltaire/primitives/BuilderBid'
const bid = BuilderBid.from({
slot: 123456n,
parentHash: '0x...',
blockHash: '0x...',
builderPubkey: builderKey,
proposerPubkey: proposerKey,
proposerFeeRecipient: feeRecipient,
gasLimit: 30000000n,
gasUsed: 25000000n,
value: 1000000000000000000n, // 1 ETH
signature: blsSignature,
})
API
from
Creates a BuilderBid from various input types. Accepts hex strings, Uint8Arrays, and numeric types.
function from(value: BuilderBidLike): BuilderBidType
// From hex strings (common in RPC responses)
const bid = BuilderBid.from({
slot: '0x1e240',
parentHash: '0x' + '11'.repeat(32),
blockHash: '0x' + '22'.repeat(32),
builderPubkey: '0x' + '33'.repeat(48),
proposerPubkey: '0x' + '44'.repeat(48),
proposerFeeRecipient: '0x' + '55'.repeat(20),
gasLimit: '0x1c9c380',
gasUsed: '0x17d7840',
value: '0xde0b6b3a7640000',
signature: '0x' + '66'.repeat(96),
})
// From native types
const bid = BuilderBid.from({
slot: 123456n,
parentHash: new Uint8Array(32).fill(1),
blockHash: new Uint8Array(32).fill(2),
builderPubkey: new Uint8Array(48).fill(3),
proposerPubkey: new Uint8Array(48).fill(4),
proposerFeeRecipient: new Uint8Array(20).fill(5),
gasLimit: 30000000n,
gasUsed: 25000000n,
value: 1000000000000000000n,
signature: new Uint8Array(96).fill(6),
})
InvalidBuilderBidError if any field has invalid format or length.
getValue
Returns the bid value in wei.
function getValue(bid: BuilderBidType): bigint
const value = BuilderBid.getValue(bid)
console.log(`Bid: ${value} wei`)
// Bid: 1000000000000000000 wei
verify
Verifies the builder’s BLS signature on the bid. Requires a BLS verification function to be provided.
function verify(
bid: BuilderBidType,
crypto: { blsVerify: (pubkey: Uint8Array, message: Uint8Array, signature: Uint8Array) => boolean }
): boolean
import { blsVerify } from '@voltaire/crypto/bls'
const isValid = BuilderBid.verify(bid, { blsVerify })
if (!isValid) {
throw new Error('Invalid builder signature')
}
toHex
Converts a BuilderBid to hex string format for RPC compatibility. Uses snake_case field names.
function toHex(bid: BuilderBidType): BuilderBidHex
const hexBid = BuilderBid.toHex(bid)
// {
// slot: '0x1e240',
// parent_hash: '0x0101...',
// block_hash: '0x0202...',
// builder_pubkey: '0x0303...',
// proposer_pubkey: '0x0404...',
// proposer_fee_recipient: '0x0505...',
// gas_limit: '0x1c9c380',
// gas_used: '0x17d7840',
// value: '0xde0b6b3a7640000',
// signature: '0x0606...'
// }
Types
BuilderBidType
The structured builder bid object.
type BuilderBidType = {
readonly slot: SlotType // Beacon chain slot (12 sec each)
readonly parentHash: HashType // Parent block hash (32 bytes)
readonly blockHash: HashType // Proposed block hash (32 bytes)
readonly builderPubkey: Uint8Array // Builder BLS pubkey (48 bytes)
readonly proposerPubkey: Uint8Array // Proposer BLS pubkey (48 bytes)
readonly proposerFeeRecipient: AddressType // Fee recipient (20 bytes)
readonly gasLimit: Uint256Type // Block gas limit
readonly gasUsed: Uint256Type // Actual gas used
readonly value: Uint256Type // Bid value in wei
readonly signature: Uint8Array // Builder BLS signature (96 bytes)
}
BuilderBidLike
Flexible input type accepting hex strings and native types.
type BuilderBidLike = BuilderBidType | {
slot: SlotType | bigint | number | string
parentHash: HashType | string | Uint8Array
blockHash: HashType | string | Uint8Array
builderPubkey: Uint8Array | string
proposerPubkey: Uint8Array | string
proposerFeeRecipient: AddressType | string
gasLimit: Uint256Type | bigint | number | string
gasUsed: Uint256Type | bigint | number | string
value: Uint256Type | bigint | number | string
signature: Uint8Array | string
}
BuilderBidHex
RPC-compatible hex format with snake_case field names.
type BuilderBidHex = {
readonly slot: string
readonly parent_hash: string
readonly block_hash: string
readonly builder_pubkey: string
readonly proposer_pubkey: string
readonly proposer_fee_recipient: string
readonly gas_limit: string
readonly gas_used: string
readonly value: string
readonly signature: string
}
Errors
InvalidBuilderBidError
Thrown when bid construction or validation fails.
class InvalidBuilderBidError extends Error {
name: 'InvalidBuilderBidError'
details: unknown
}
- Invalid hash length (must be 32 bytes)
- Invalid BLS pubkey length (must be 48 bytes)
- Invalid signature length (must be 96 bytes)
- Invalid address length (must be 20 bytes)
- Non-object input
Field Sizes
| Field | Size | Description |
|---|
slot | 8 bytes | Beacon chain slot number |
parentHash | 32 bytes | Parent block hash |
blockHash | 32 bytes | Proposed block hash |
builderPubkey | 48 bytes | Builder BLS public key |
proposerPubkey | 48 bytes | Proposer BLS public key |
proposerFeeRecipient | 20 bytes | Ethereum address |
gasLimit | 32 bytes | Block gas limit |
gasUsed | 32 bytes | Actual gas consumed |
value | 32 bytes | Bid value in wei |
signature | 96 bytes | BLS signature |
See Also
