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 →
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 →

Operator-Relayer Flow

The Operator requests signatures from the Relayer for three main operations:

Registration

Trigger: When sufficient balance (32 ETH) is detected

Process:

1. Operator requests validator data from Relayer
2. Relayer responds with signed data package
3. Operator submits registration to Vault contract

Required data:

• Validator public key, deposit signature, amount
• Validator exit signature
• Validators Manager signature

Exit Signature Details

The Relayer should use the validator index passed in the request. The Operator passes the start validator index - increment this for each validator except the first one.

Funding

Trigger: When funding existing compound validators (0x02)

Process:

1. Operator calls /fund endpoint
2. Relayer responds with signatures
3. Operator executes funding transaction

Required data:

• Vault address
• Public keys of validators to fund
• Amounts to deposit (in Gwei)

Withdrawals

Trigger: For partial or full validator withdrawals

Process:

1. Operator calls /withdraw endpoint
2. Relayer responds with authorization signature
3. Operator submits withdrawal transaction

Required data:

• Vault address
• Public keys of validators to withdraw from
• Amounts to withdraw (in Gwei)

Technical Implementation

The Validators Manager signature uses EIP-712 ↗. See implementation example ↗. The signer address must be the Validators Manager configured in Vault settings.

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

Validator Registration

POST /validators

Request Body:

{
  "vault": "0x1234...",
  "validators_start_index": int,
  "amounts": int[],
  "validator_type": "ValidatorType"
}

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": "string",
      "deposit_signature": "string",
      "amount": int,
      "exit_signature": "string"
    }
  ],
  "validators_manager_signature": "string"
}

Validator Funding

POST /fund

Request Body:

{
  "vault": "0x1234...",
  "public_keys": ["string"],
  "amounts": [int]
}

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": [
    {
      "public_key": "string",
      "deposit_signature": "string",
      "amount": int
    }
  ],
  "validators_manager_signature": "string"
}

Partial and Full Validator Withdrawals

POST /withdraw

Request Body:

{
  "vault": "0x1234...",
  "public_keys": ["string"],
  "amounts": [int]
}

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. If the amount is 0, the Operator requests a full withdrawal. Otherwise, the value must be provided in Gwei.

Response:

{
  "validators_manager_signature": "string"
}

Validator Consolidation

POST /consolidate

Request Body:

{
  "vault": "0x1234...",
  "source_public_keys": ["string"],
  "target_public_keys": ["string"]
}

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": "string"
}

Relayer Info

GET /info

Response:

{
  "network": "string"
}

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.