Builder Integration

This document outlines the key aspects of integrating with TitanRelay, a high-performance MEV-Boost relay. It supports standard APIs with a few enhancements for improved functionality and performance.

Get Validators

We've added a "preferences" field to validator submissions, enabling relay-level PEPC (Protocol Enforced Proposer Commitments). Currently, we support two preferences:

1. filtering: The relay supports both filtering and non-filtering proposers under a single URL. Filtering is now per-proposer instead of per-relay.

2. trusted_builders: When signing up for optimistic relaying, you'll receive a BuilderID (e.g., "Titan"). Proposers can specify to only accept blocks from certain builders.

struct ValidatorPreferences {
    /// A string indicating which filtering policy to use ("regional" or "global").
    filtering: String,
    /// An optional list of BuilderIDs. If this is set, the relay will only accept
    /// submissions from builders whose public keys are linked to the IDs in this list.
    /// This allows for limiting submissions to a trusted set of builders.
    trusted_builders: Option<Vec<String>>,
}

struct BuilderGetValidatorsResponse {
    slot: u64,
    validator_index: usize,
    entry: SignedValidatorRegistration,
    preferences: ValidatorPreferences,
}

Optimistic Relaying

Optimistic V1

We support standard optimistic v1 relaying with up to 64 ETH collateral. See the Optimistic Relaying page for more details.

Optimistic V2

This endpoint is now deprecated

We support OptimisticV2 submissions. If enabled for v1, you can submit to our v2 endpoints. OptimisticV2 decouples the lightweight header from the heavier payload, allowing for faster processing. See the original proposal here.

To send a block submission with OptimisticV2, you will need to call these two new endpoints:

1. relay/v1/builder/headers: Contains the header and signed bid trace.

2. relay/v1/builder/blocks_optimistic_v2: The submission struct is identical to the block submitted with the current relay/v1/builder/blocks endpoint.

struct HeaderSubmission {
    bid_trace: BidTrace,
    execution_payload_header: ExecutionPayloadHeader,
    blobs_bundle: BlobsBundle,
}

struct SignedHeaderSubmission {
    message: HeaderSubmissionDeneb,
    signature: BlsSignature,
}

We recommend submitting v2 alongside normal block submissions for extra redundancy and because v2 is still in the testing phase. We often over-demote so it’s best if you use separate pubkeys to mitigate the impact of incorrect demotions.

Alongside changing the submission endpoints, you must also manually track your collateral to guarantee it covers the block value and ensure a valid full block is received within 2 seconds of a valid header submission to avoid demotion.

Optimistic V3

Optimistic v3 submissions are enabled at relay/v3/builder/headers

struct HeaderSubmissionV3 {
    url: Vec<u8>,
    tx_count: u32,
    submission: SignedHeaderSubmission,
}

Where SignedHeaderSubmission is the same as for V2. When submitting a header you need to ensure that the corresponding payload is available at [url]/get_payload_v3 . The relay may send a request for the payload via a ssz-encoded SignedGetPayloadV3 request:

struct GetPayloadV3 {
    /// Hash of the block header from the `SignedHeaderSubmission`.
    block_hash: B256,
    /// Timestamp (in milliseconds) when the relay made this request.
    request_ts_millis: u64,
    /// Relay's public key
    relay_pubkey: BlsPublicKey,
}


struct SignedGetPayloadV3 {
    message: GetPayloadV3,
    signature: BlsSignature,
}

The builder is expected to timely return the corresponding SignedBidSubmission , failure to do so may result in a missed slot and collateral slashing. Collateral requirements are the same as for V2 submissions.

Read more about v3 here.

Block deltas

To optimise bandwidth utilisation we support sending dehydrated payloads for V1 submissions. A builder may submit transactions and blobs only once per slot. Subsequent submissions within the same slot can reference those orders by their hash or proof, and the relay will rehydrate the payload using a local cache.

struct DehydratedBidSubmissionElectra {
    message: BidTrace,
    execution_payload: ExecutionPayload,
    blobs_bundle: DehydratedBlobs,
    execution_requests: ExecutionRequests,
    signature: BlsSignature,
}

struct DehydratedBlobs {
    /// List of proofs to re-hydrate the BlobsBundle
    proofs: Vec<KzgProof>,
    new_items: Vec<BlobItem>,
}

struct BlobItem {
    proof: KzgProof,
    commitment: KzgCommitment,
    blob: Blob,
}

The transaction hashes are directly reusing the transaction field in the ExecutionPayload. To enable block deltas make sure to add a x-hydrate header to the submission.

You can refer to the full rehydration logic here.

Submission Headers

• Content-Encoding : optional, supported values: gzip, zstd . Default is no compression

• Content-Type : optional, supported value: application/octet-stream for SSZ encoding. Default is json encoding

• x-api-key : optional, if present and matching with an optimistic pubkey, signature verification will be skipped

• x-hydrate: optional, if present enables block deltas submissions

• x-sequence : optional, if present the relay will reject lower sequence numbers received for the same slot / pubkey

Websocket TopBid Stream

We provide a websocket stream at the endpoint builder/top_bid that sends real-time updates whenever a new top bid is received by the relay. Each time a new best bid is processed, a message containing the updated bid information will be pushed to connected clients. Authentication for this stream is done using an x-api-key header.

The structure of the TopBidUpdate message is as follows:

struct TopBidUpdate {
    timestamp: u64,
    slot: u64,
    block_number: u64,
    block_hash: B256,
    parent_hash: B256,
    builder_pubkey: BlsPublicKey,
    fee_recipient: Address,
    value: U256,
}

To access the TopBid stream, builders must meet three criteria:

• Build ≥ 0.10% of all MevBoost blocks (weekly rolling basis)

• Submit ≥ 90% of blocks built

• Supply ≥ 0.1 ETH as optimistic collateral

Relay Locations

• NV: us-east-1

• FR: eu-central-1

• TK: ap-northeast-1