Relay Integration Guide

Overview

Enabling mev-commit on your relay is simple and requires minimal changes to your existing setup.

This guide explains how to integrate your relay with mev-commit. Your relay will check if the current slot’s validator has opted into mev-commit:

If they haven’t opted in, your relay works normally:

If they have opted in, your relay only accepts blocks from mev-commit builders:

To implement this, your relay needs to track two things:

Provider Registry: Lists opted-in builders and their BLS keys
Validator Registry: Shows which validators have opted into mev-commit

Quick Start

View the Example Implementation

Check out this mev-commit relay integration
Add required environment variables:

Mainnet

MEV_COMMIT_RPC=wss://chainrpc-wss.mev-commit.xyz
PROVIDER_REGISTRY_ADDR=ProviderRegistryAddressMainnet1_0_0

Testnet

MEV_COMMIT_RPC=wss://chainrpc-wss.testnet.mev-commit.xyz
PROVIDER_REGISTRY_ADDR=ProviderRegistryAddress0_7_0

Test and Deploy

Test filtering behavior on Holesky:

Register a test builder
Submit test bids
Verify correct block filtering

Add your relay to our supporting relays list
Provide connection details for validators
Contact the Primev team to coordinate validator outreach

You have now successfully integrated your relay with mev-commit.

Implementation Details

What Contracts to Monitor

To track which validators have opted into mev-commit, you’ll want to monitor the following contracts:

Ethereum L1

Network	Contract	Address
Mainnet	Validator Opt In Router	ValidatorOptInRouterProxyAddress
Holesky	Validator Opt In Router	ValidatorOptInRouterAddress

mev-commit Chain

Network	Contract	Address
Mainnet	Provider Registry	ProviderRegistryAddressMainnet1_0_0
Testnet	Provider Registry	ProviderRegistryAddress0_7_0

By monitoring these contracts, you can determine which validators and providers have opted into mev-commit and ensure compliance with the protocol.

How to Query the Provider Registry

The mev-commit provider registry contract maintains the list of authorized providers such as block builders. You can query this contract to validate builder addresses. Contract Details:

Network	Address
mev-commit chain mainnet	ProviderRegistryAddressMainnet1_0_0
mev-commit chain testnet	ProviderRegistryAddress0_7_0

How to query the registry for registered providers

You can retrieve all registered providers using the following script:

// Import the ethers library
const ethers = require("ethers");

// Define the provider using the RPC URL
const provider = new ethers.JsonRpcProvider("https://chainrpc.mev-commit.xyz/");

// Define the contract address and ABI
const providerRegistryAddress = "0xb772Add4718E5BD6Fe57Fb486A6f7f008E52167E";
const abi = [
    "event ProviderRegistered(address indexed provider, uint256 stakedAmount)",
    "function isProviderValid(address provider) public view",
    "function getBLSKeys(address provider) external view returns (bytes[])"
];

// Create a new contract instance
const contract = new ethers.Contract(providerRegistryAddress, abi, provider);

// Function to retrieve BLS keys grouped by valid provider address
async function getRegisteredProviders() {
    const filter = contract.filters.ProviderRegistered();
    const events = await contract.queryFilter(filter);
    let totalKeys = 0;

    const providerMap = {};

    for (const event of events) {
        const providerAddress = event.args.provider;

        try {
            //This will fail if the provider isn't valid
            await contract.isProviderValid(providerAddress);

            const blsKeys = await contract.getBLSKeys(providerAddress);

            // Convert each key to hex string for any future usage
            providerMap[providerAddress] = blsKeys.map(key => ethers.hexlify(key));
            totalKeys += blsKeys.length
        } catch (error) {
            // Skip invalid providers or failed fetches
        }
    }

    console.log("Total registered keys: ", totalKeys);
    return providerMap;
}

// Run and log providers with their BLS keys
getRegisteredProviders()
    .then(providerMap => {
    console.log("Valid providers and their BLS keys:");
        for (const [address, blsKeys] of Object.entries(providerMap)) {
            console.log(`\nProvider: ${address}`);
            blsKeys.forEach((key, index) => {
            console.log(`  Key ${index + 1}: ${key}`);
            });
        }
    })
    .catch(error => {
        console.error("Error fetching providers:", error);
    });

Expected Output

The output will contain the number of all registered keys and a list of providers with their registered BLS public keys.

Total registered keys:  23
Valid providers and their BLS keys:

Provider: 0x...
  Key 1: 0x...

Provider: 0x...
  Key 1: 0x...

Provider: 0x...
  Key 1: 0x...
  Key 2: 0x...
  Key 3: 0x...

...

Get Started

Concepts

Developers

Overview

Quick Start

Mainnet

Testnet

Implementation Details

What Contracts to Monitor

Ethereum L1

mev-commit Chain

How to Query the Provider Registry

Get Started

Concepts

Developers

​Overview

​Quick Start

​Mainnet

​Testnet

​Implementation Details

​What Contracts to Monitor

​Ethereum L1

​mev-commit Chain

​How to Query the Provider Registry

Overview

Quick Start

Mainnet

Testnet

Implementation Details

What Contracts to Monitor

Ethereum L1

mev-commit Chain

How to Query the Provider Registry