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:

We also 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. builder/headers: Contains the header and signed bid trace.

2. builder/blocks_optimistic_v2: The submission struct is identical to the block submitted with the current 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.

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:

pub struct TopBidUpdate {
    timestamp: u64,
    slot: u64,
    block_number: u64,
    block_hash: Hash32,
    parent_hash: Hash32,
    builder_pubkey: BlsPublicKey,
    fee_recipient: ExecutionAddress,
    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

• SG: ap-southeast-1

Testing

We have a full production cluster running on the Holesky testnet. holesky.titanrelay.xyz