Skip to main content

​
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
Example: 
// 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),
})
Throws: InvalidBuilderBidError if any field has invalid format or length.

​
getValue

Returns the bid value in wei. 
function getValue(bid: BuilderBidType): bigint
Example: 
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
Example: 
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
Example: 
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
}
Common causes:
  • 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

FieldSizeDescription
slot8 bytesBeacon chain slot number
parentHash32 bytesParent block hash
blockHash32 bytesProposed block hash
builderPubkey48 bytesBuilder BLS public key
proposerPubkey48 bytesProposer BLS public key
proposerFeeRecipient20 bytesEthereum address
gasLimit32 bytesBlock gas limit
gasUsed32 bytesActual gas consumed
value32 bytesBid value in wei
signature96 bytesBLS signature

​
See Also