Running as API service

The Operator API facilitates the initiation of validator registrations via API calls, proving particularly useful in environments such as DVT or 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. The operator API provides access to several key endpoints:

• GET /validators - retrieves a list of validators eligible for registration based on the assets available in the vault.

• POST /validators - allows for the submission of exit signatures for the validators identified in the previous step.

Prerequisite

Before proceeding, ensure the following prerequisites are completed:

1. Install Operator Service

2. Generate a hot wallet or upload an existing one. Refer to the Prepare Operator Service section for more details.

3. Update deposit data file to the Vault

Running operator API

To run the Operator API, use the command below:

./operator start-api

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

API_PORT=8000
CONSENSUS_ENDPOINTS=https://lighthouse
DATA_DIR=/data
DATABASE_DIR=/database
EXECUTION_ENDPOINTS=https://nethermind
NETWORK=holesky
VAULT=0x3cc...

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

./operator start-api --help

Docker Usage Notes

When operating within Docker, it's necessary to specify the --data-dir variable, such as --data-dir=/data to avoid the error:

Directory '/nonexistent/.stakewise' does not exist.

Ensure the data-dir is mapped to a directory on the host.

Additionally, include --api-host=0.0.0.0 and map the API port (default 8000) to the host port. 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.

Example workflow

1. Retrieving Validators Eligible for Registration

An external service performs a GET request on the /validators endpoint. If the vault has sufficient assets for registration, this endpoint will respond with entries consisting of public_key and index. The quantity of these entries matches the number of validators eligible for registration. For instance, with 65 ETH in the vault, it will yield two entries, such as:

[
  {
    "public_key": "0x123..",
    "index": 12345
  }
]

Should the deposit data file linked with the operator lack sufficient public keys, the endpoint will return all available public keys. For instance, if there are 96 ETH in the vault but the deposit data file only contains two available public keys, the response will include two entries.

2. Submitting validator registrations

An external service generates exit signatures based on the entries from step 1 and then executes a POST request on the /validators endpoint, specifying the public_key and exit_signature for each validator like so:

[
  {
    "public_key": "0x123..",
    "exit_signature": "0x456..."
  }
]

• The sequence of entries in the POST request must align with the order in the response from step 1. For instance, if the GET request returns three entries but the POST request is only made for the last two, it will fail. However, the request will be successful if it's made solely for the first entry.

• The operator verifies the exit signatures to ensure they match the correct validator indexes, fork version, etc. If the POST request does not pass validation, a 400 error code is returned; a 200 code is returned for successful validation.

• Upon acceptance of the request, the subsequent GET response will be empty, signaling that the operator has commenced the validator registration task. Should this task fail, the GET request will once again list the validators eligible for registration.