Skip to main content

Relayer (API Mode)

The Relayer is a service that provides validator credentials and signatures via API calls. The Operator Service requests this complete validator data package via API calls, and the Relayer returns it signed by the validators manager.

The Operator API facilitates validator operations via API calls, including validator registrations, funding compound validators, consolidations, and withdrawals. This proves particularly useful when validator keys are managed externally from the Operator Service.

In this framework, validator credentials and signatures are provided by the Relayer service, which can generate keys internally or integrate with external key management systems.

In essence, the Operator communicates with the Vault contract using credentials and signatures provided by the Relayer service.

Prerequisites​

Complete the following steps before proceeding:

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

start-relayer Command​

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

Operator-Relayer Flow​

The Operator requests validator credentials and signatures from the Relayer for three main operations: validator registration, funding compound validators, and withdrawals.

When the Operator detects sufficient balance (32 ETH) for validator operations, it requests the necessary data from the Relayer service. The Relayer responds with:

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

The Operator then uses this data to execute the validator operation on the Vault contract.

To produce the exit signature, the Relayer should use the validator index passed in the request. The Operator passes the start validator index. You should increment this index for each validator except the first one.

Once the Operator receives registration data, it requests Oracles approvals and submits the registration to the Vault contract.

The Validators Manager signature is an EIP-712 ↗ signature. See EIP-712 message structure in vault contract ↗. The signer address must be the Validators Manager configured in Vault settings.

API Endpoints​

The Relayer provides several endpoints to handle different validator operations:

Register New Validators​

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

Fund Compounding Validators​

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

Get Signature for Withdraw Funds from Validators Transaction​

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. Value provided in Gwei

Response:

{
  "validators_manager_signature": "string"
}

Get Signature for Consolidate Validators Transaction​

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

Fetch Info About Relayer​

GET /info

Response:

{
  "network": "string"
}
IconMultiple 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.

IconRelayer Example

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

Last updated on