> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primev.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Relay Integration Guide

export const HoodiValidatorOptInRouterAddress = "0xa380ba6d6083a4Cb2a3B62b0a81Ea8727861c13e";

export const ProviderRegistryAddress_1_1_6 = "0x1C2a592950E5dAd49c0E2F3A402DCF496bdf7b67";

export const ValidatorOptInRouterProxyAddress = "0x821798d7b9d57dF7Ed7616ef9111A616aB19ed64";

export const ProviderRegistryAddressMainnet1_0_0 = "0xeb6d22309062a86fa194520344530874221ef48c";

## Overview

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

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:

<Frame>
  <img src="https://mintcdn.com/primev-24/4WGjB8DW4_T8qPTp/v1.1.0/images/mev-commit-relay.png?fit=max&auto=format&n=4WGjB8DW4_T8qPTp&q=85&s=fb395a1be6482b0334d9742ccde7a73a" alt="mev-commit relay diagram" width="1731" height="974" data-path="v1.1.0/images/mev-commit-relay.png" />
</Frame>

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

<Frame>
  <img src="https://mintcdn.com/primev-24/4WGjB8DW4_T8qPTp/v1.1.0/images/mev-commit-validator-relay.png?fit=max&auto=format&n=4WGjB8DW4_T8qPTp&q=85&s=69abd7aeac37affe39d92d8e0fbe8d31" alt="mev-commit validator relay diagram" width="1733" height="974" data-path="v1.1.0/images/mev-commit-validator-relay.png" />
</Frame>

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

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

## Quick Start

<Steps>
  <Step title="View the Example Implementation">
    * Check out this [mev-commit relay integration](https://github.com/flashbots/mev-boost-relay/pull/657)
    * Add required environment variables:

    ### Mainnet

    <CodeBlock language="bash">
      {`
            MEV_COMMIT_RPC=wss://chainrpc-wss.mev-commit.xyz
            PROVIDER_REGISTRY_ADDR=${ProviderRegistryAddressMainnet1_0_0}
            `.trim()}
    </CodeBlock>

    ### Testnet

    <CodeBlock language="bash">
      {`
            MEV_COMMIT_RPC=wss://chainrpc-wss.testnet.mev-commit.xyz
            PROVIDER_REGISTRY_ADDR=${ProviderRegistryAddress_1_1_6}
            `.trim()}
    </CodeBlock>
  </Step>

  <Step title="Test and Deploy">
    Test filtering behavior on Hoodi:

    * Register a [test builder](/v1.1.0/get-started/quickstart)
    * Submit [test bids](/bidders/best-practices#submit-bundles)
    * Verify correct block filtering
  </Step>

  <Step title="Register Your Relay">
    1. Add your relay to our [supporting relays list](/v1.1.0/get-started/validators/validator-guide#supporting-relays)
    2. Provide connection details for validators
    3. Contact the Primev team to coordinate validator outreach
  </Step>
</Steps>

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} |
| **Hoodi**   | Validator Opt In Router | {HoodiValidatorOptInRouterAddress} |

## mev-commit Chain

| Network     | Contract          | Address                               |
| ----------- | ----------------- | ------------------------------------- |
| **Mainnet** | Provider Registry | {ProviderRegistryAddressMainnet1_0_0} |
| **Testnet** | Provider Registry | {ProviderRegistryAddress_1_1_6}       |

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** | {ProviderRegistryAddress_1_1_6}       |

<AccordionGroup>
  <Accordion title="How to query the registry for registered providers">
    You can retrieve all registered providers using the following script:

    ```javascript theme={null}
    // 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);
        });
    ```
  </Accordion>

  <Accordion title="Expected Output">
    The output will contain the number of all registered keys and a list of providers with their registered BLS public keys.

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

    ...
    ```
  </Accordion>
</AccordionGroup>