> ## 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.

# BuilderBid

> Block builder bids for Proposer-Builder Separation (PBS) and MEV-Boost

## 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.

```typescript theme={null}
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.

```typescript theme={null}
function from(value: BuilderBidLike): BuilderBidType
```

**Example:**

```typescript theme={null}
// 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.

```typescript theme={null}
function getValue(bid: BuilderBidType): bigint
```

**Example:**

```typescript theme={null}
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.

```typescript theme={null}
function verify(
  bid: BuilderBidType,
  crypto: { blsVerify: (pubkey: Uint8Array, message: Uint8Array, signature: Uint8Array) => boolean }
): boolean
```

**Example:**

```typescript theme={null}
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.

```typescript theme={null}
function toHex(bid: BuilderBidType): BuilderBidHex
```

**Example:**

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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

| 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

* [MEV-Boost Documentation](https://boost.flashbots.net/)
* [Proposer-Builder Separation](https://ethereum.org/en/roadmap/pbs/)
* [BLS12-381](/crypto/bls12381) - BLS signature cryptography
* [Slot](/primitives/slot) - Beacon chain slot type