Skip to main content

Relayer (API Mode)

The Operator API facilitates the initiation of validator registrations via API calls, proving particularly useful in cases where the operator independently oversees the creation and storage of validator keys.

Within this framework, keystores are generated and preserved externally from the operator. Similarly, exit signatures are produced outside the operator.

In essence, the operator acts as an intermediary for communication with the Vault contract.

Prerequisites​

Complete the following steps before proceeding:

IconRequired Setup Steps
  1. Installation ↗
  2. Validator Keys ↗

Running Operator API​

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-api --help
IconDocker Usage Notes

When operating within Docker, it's necessary to specify the --data-dir variable, such as --data-dir=/data. Ensure the data-dir is mapped to a directory on the host.

The database-dir should also be mapped to a host directory or Docker volume, with write permissions enabled for the directory linked to database-dir. Setting up permissions is not required if using volumes.

Relayer API​

IconInfo

Relayer API is supported since Operator release v2.0.0

Operator-Relayer Flow​

The Operator Service continuously monitors Vault balance changes. When 32 ETH becomes available, the following process occurs:

Step 1: Balance Detection

  • Operator detects sufficient balance (32 ETH) in the Vault
  • Operator predicts the next validator index for registration

Step 2: Data Request

  • Operator sends a request to the Relayer service
  • Request includes validator start index and batch size information

Step 3: Registration Data Provision The Relayer must provide comprehensive validator registration data:

IconRegistration Data Requirements
  • Validator public key - The public key for the validator
  • Deposit signature - Signature for the deposit transaction
  • Deposit amount - Amount being deposited (typically 32 ETH)
  • Validator exit signature - Pre-signed exit signature for the validator
  • Validators manager signature - Authorization signature from validators manager

Step 4: Signature Generation

  • Exit Signature: Relayer uses the validator index from the request. For batch operations, increment the index for each validator (except the first)
  • Manager Signature: Must be an EIP-712 ↗ signature following the message structure defined in the Vault contract ↗. The signer address must match the validators manager configured in Vault settings.

Step 5: Registration Completion

  • Operator receives registration data from Relayer
  • Operator requests approval from Oracles ↗ network
  • Upon approval, Operator submits the registration transaction to the Vault contract

Request format:​

POST /validators

{
  "vault": "0x1234...",
  "validators_start_index": int,
  "validators_batch_size": int,
  "validators_total": int
}
IconRequest Parameters
  • validators_start_index - validator index for the first validator in the batch
  • validators_batch_size - number of validators in current batch. Maximum batch size is determined by protocol config, currently 10.
  • validators_total - hint for Relayer. Does not affect Relayer response. Relayer may use this value to allocate larger portions of validators in background. validators_total should be more than or equal to validators_batch_size.

Response format:​

{
  "validators": [
    {
      "public_key": "string",
      "deposit_signature": "string",
      "amount_gwei": int,
      "exit_signature": "string"
    }
  ],
  "validators_manager_signature": "string"
}

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

IconRelayer Example

See demo project relayer-example ↗ - a Python-based FastAPI application that demonstrates how to implement a relayer service for Ethereum staking operations. The relayer acts as an intermediary between validators and the StakeWise operator service, handling validator credential generation and management.

You may use it as a starting point for your own Relayer.

Last updated on