Relayer (API Mode)

The Relayer is a service that implements the logic for managing validator keystores, as well as signing validator operations with the Validators Manager wallet.

When the Operator Service is started in relayer mode, it will send requests to the relayer service via API calls for all operations that require interaction with the validator keystores or signing by the Validator Manager wallet: validator registrations, funding compound validators, consolidations, and withdrawals. The Relayer returns the necessary data signed by the Validators Manager.

This proves particularly useful when the Validators Manager wallet and validator keystores are managed externally from the Operator Service. In essence, the Operator communicates with the Vault contract using data and signatures provided by the Relayer.

Prerequisites

Complete the following steps before proceeding:

Required Setup Steps

1. Installation → completed
2. Validators Manager →, which is set to the wallet address of the Relayer.

Start Operator Service

To run the Operator API, use the command below:

./operator start-relayer

This command allows for direct parameter input (e.g., --data-dir) or through environment variables. A basic example of setting environment variables is as follows:

.env

CONSENSUS_ENDPOINTS=https://lighthouse
DATA_DIR=/data
DATABASE_DIR=/database
EXECUTION_ENDPOINTS=https://nethermind
NETWORK=hoodi
VAULT=0x3cc...
RELAYER_ENDPOINT=https://relayer

For additional parameter information, use the --help flag:

./operator start-relayer --help

Docker Configuration

For Docker-specific setup instructions, see Installation: Docker Setup →

How API Mode Works

The Operator never handles validator keys directly. Instead, it sends requests to your Relayer service, which:

1. Manages validator keystores internally or via external systems
2. Signs operations with the Validators Manager wallet
3. Returns signed data for the Operator to submit to the Vault contract

This architecture completely isolates key management from the Operator Service while maintaining full functionality.

Technical Implementation

All operations require an EIP-712 ↗ signature from the Validators Manager wallet. See implementation example ↗ of signing. The Relayer must sign using the same wallet address configured as Validators Manager in your Vault settings.

The Relayer must implement the following endpoints to handle different validator operations:

Validator Registration

POST /register

Request Body:

{
  "vault": "0x1234...",
  "validators_start_index": 20551,
  "amounts": [32000000000],
  "validator_type": "0x02"
}

Parameters:

• vault - Address of the vault contract to which the validators will be registered.
• validators_start_index - Validator index for the first validator in the batch.
• amounts - List of deposit amounts for each validator. Value provided in Gwei.
• validator_type - Type of validator to create. Possible values: 0x01 or 0x02

Response:

{
  "validators": [
    {
      "public_key":  "0xPubKey1",
      "deposit_signature": "0xDepositSig1",
      "amount": 32000000000,
      "exit_signature": "0xExitSig1"
    }
  ],
  "validators_manager_signature": "0xManagerSig"
}

Validator Funding

POST /fund

Request Body:

{
  "vault": "0x1234...",
  "public_keys":  ["0xPubKey1"],
  "amounts": [2000000000]
}

Parameters:

• vault - Address of the vault contract to which the validators will be funded.
• public_keys - List of public keys of validators to fund.
• amounts - List of amounts to fund into each validator. Value provided in Gwei.

Response:

{
  "validators_manager_signature": "0xManagerSig"
}

Partial and Full Validator Withdrawals

POST /withdraw

Request Body:

{
  "vault": "0x1234...",
  "public_keys":  ["0xPubKey1", "0xPubKey2"],
  "amounts": [55000000000, 0]
}

Parameters:

• vault - Address of the vault contract to which the validators will be withdrawn.
• public_keys - List of public keys of validators to withdraw from.
• amounts - List of amounts to withdraw from each validator. Value provided in Gwei.

Response:

{
  "validators_manager_signature": "0xManagerSig"
}

Validator Consolidation

POST /consolidate

Request Body:

{
  "vault": "0x1234...",
  "source_public_keys": ["0xPubKey1", "0xPubKey2"],
  "target_public_keys": ["0xPubKey3", "0xPubKey3"]
}

Parameters:

• vault - Address of the vault contract to which the validators will be consolidated.
• source_public_keys - List of public keys of validators to consolidate from.
• target_public_keys - List of public keys of validators to consolidate to.

Response:

{
  "validators_manager_signature": "0xManagerSig"
}

Relayer Info

GET /info

Response:

{
  "network": "mainnet"
}

Multiple Relayers

Multiple relayers are possible for various use-cases. You can implement your own relayer using the API specification provided above to meet your specific requirements.

Relayer Example

See demo project relayer-example ↗ - a Python-based FastAPI application that demonstrates how to implement a relayer service for Ethereum staking operations.