Status Node Manager API Spec (WIP)

Status Node Manager API Spec

The Status Node Manager is the back-end service for the Nimbus GUI.

The GUI app connects to the node manager through the Waku protocol. This ensures that a persistent pairing between the two can be established without any networking configuration (i.e. the user doesn't have to specify IP addresses and ports of the running Nimbus instances) and that not even metadata regarding the connection is leaked to anyone. The locally running Nimbus node can bind its REST API and metrics port to localhost and the Status node manager can make them available to the GUI through a HTTP-over-Waku transport.

This document describes the evolving REST API offered by the Status Node Manager. This API is consumed both by the Nimbus GUI and the status_node_manager command-line tool.

Common Path Parameters

Network

In endpoints of the form ../{network}/.., the network path parameter specifies the network that the operation is related to. The network parameter can be one of the following:

mainnet
holesky
sepolia
etc.

Component

In endpoints of the form ../{component}/.., the component path parameter specifies the software that the operation is related to. Some components are network-independent, while others are network-dependent. If the component is network-dependent, the network must be specified in the path as well.

Network-independent components:

host - Host machine - CPU, memory, storage, network, uptime
snm - Status Node Manager

Network-dependent components:

nimbus-el - Nimbus Eth1 client
nimbus-cl - Nimbus Eth2 client
geth - Geth client
etc.

Validator identifiers

In endpoints of the form ..validators/{validator_id}/.., the validator_id path parameter specifies the validator that the operation is related to. The validator_id is a unique identifier for the validator.

Examples:

../nimbus-cl/mainnet/..
../nimbus-cl/sepolia/..
../geth/mainnet/..
../snm/..
../host/..
../validators/0xabc123/..

Waku transport

The following endpoints are used for establishing and maintaining a Waku connection with one or more GUI clients:

POST /snm/v1/waku/pair
- Description: Used by the CLI tool to initiate a persistent connection between the node manager service and a GUI instance.
- Body parameters:
  - Pairing ID - copy/pastable text value (e.g. base64) that is generated in the GUI when the pairing process starts.
POST /snm/v1/waku/heartbeat
- Description: Endpoint for sending "heartbeat" messages to the SNM.
- Body parameters:
  - Topic - the topic to send the heartbeat message to

Validator Onboarding

The validator onboarding process involves several steps. Initially, we need to ensure that the execution and consensus layer clients are running. Then, we generate validator keys and provide them to the user. Subsequently, the user is required to sign the deposit transaction. To facilitate these steps, we need to implement the following endpoints.

Installing/removing node packages

Before any nodes can be created, we must make sure we have the right software available.

GET /snm/v1/software-events endpoint (SSE event stream).
- Description: Get notifications for status changes of ongoing installations and removals.

GET /snm/v1/software endpoint.

Description: Returns a list of all packages that can be managed by the node management service. If a given package is installed, it returns its version

Example response:

HTTP 200 OK

{
  "packages": {
    "nimbus-cl": {
      "available": "24.2.1",
      "installed": "24.1.5",
      "status": "installed"
    },
    "geth": {
      "available": "1.0.0",
      "installed": null,
      "status": "not-installed"
    }
  }
}

GET /snm/v1/software/{component} endpoint.
- Description: Returns whether the specified software package is installed and which version.
- Example response:
  - HTTP 200 OK
```
{
  "available": "24.2.1",
  "installed": "24.1.5",
  "status": "installed"
}
```

POST /snm/v1/software/{component}

Description: Installs the latest version of the specified software package.

Example response:

HTTP 202 Accepted

{
  "available": "24.2.1",
  "installed": null,
  "status": "installing"
}

HTTP 200 OK

{
  "available": "24.2.1",
  "installed": "24.2.1",
  "status": "installed"
}

DELETE /snm/v1/software/{component}
Description: Removes the specified software package.

Example responses:

HTTP 202 Accepted

{
  "available": "24.2.1",
  "installed": "24.1.5",
  "status": "removing"
}

HTTP 200 OK

{
  "available": "24.2.1",
  "installed": null,
  "status": "not-installed"
}

Creating, upgrading and restarting nodes

POST /snm/v1/networks
- Description: Requests a set of nodes to be created for connecting to a specific network (e.g. Ethereum Mainnet)
- Body parameters:
  - components: [Software] The list of software packages to use.
POST /snm/v1/{network}/update_policies
- Description: This endpoint specifies the auto-update policies for specific network connection.
POST /snm/v1/{network}/nodes/restarts
- Description: Restarting nodes may be necessary as a trouble-shooting measure by the user or in planned upgrade procedures.
- Body parameters::
  - new_version: Version Use a new version of the restarted node software after the restart.
  - zero_downtime: Bool Should the restart aim to achieve zero downtime by picking a suitable time for upgrading
  - zero_downtime_timeout: Duration Maximum time to wait before forcefully upgrading (when zero_downtime is used)

Validators setup

POST /snm/v1/{network}/validator_deposits
- Description: This endpoint generates validator keystores, deploys them according the selected network topology (e.g. on the web3signer instance, on the beacon node, on the validator client, etc) and signs the necessary deposit data messages that must be sent to the Ethereum validator deposit contract.
- Body parameters:
  - validator_count: Int The number of validators to generate.
  - withdrawal_address: String The Ethereum address to which the validator rewards will be sent.
- Example:
```
POST /snm/v1/mainnet/validator_deposits
    --data = {
      "validator_count": 10,
      "withdrawal_address": "0x00000000219ab540356cBB839Cbe05303d7705Fa"
    }
```
GET /snm/v1/{network}/validator_deposits
- Description: Returns previously generated validator deposits.
GET /snm/v1/{network}/validator_deposits/keystores
- Description: Returns previously generated validator keys.

Validator Management

For each validator the users will have the capability to manage it, examine relevant information and execute various operations.

GET /snm/v1/{network}/validators
- Description: Lists all the validators of the user for specific network ID

POST /snm/v1/{network}/validators/info

Description: Lists all the validators of the user for specific network ID and returns relevant information about them. For each validator, the following information is returned:
- information of the status of the validator ( deposit / pending / active / exited )
- information about the balance of the validator
  - Average Effectiveness
  - Current Balance
  - Validator Income
- information about the performance of the validator
  - slot information
  - blocks
  - attestations
  - slashings
Body parameters:
- validator_ids: [String] The list of validator IDs to retrieve information for. If empty, info for validators is returned.

Example request:

POST /snm/v1/mainnet/validators/info
    --data = {
      "validator_ids": ["0xabc123", "0xdef456"]
    }

Example response:

HTTP 200 OK

{
  "validators": [
    {
      "validator_id": "0xabc123",
      "status": "active",
      "balance": {
        "average_effectiveness": 95.5,
        "current_balance": 32.4,
        "validator_income": 0.75
      },
      "performance": {
        "slots_behind": 0,
        "blocks": {
          "proposed": 123,
          "missed": 4,
          "orphaned": 0,
          "scheduled": 2
        },
        "attestations": {
          "proposed": 123,
          "missed": 4
        },
        "syncs": {
          "participated": 123,
          "missed": 4,
          "orphaned": 0,
          "scheduled": 2
        },
        "slashings": [
          {
            "slashed_by": "0xdef456",
            "slot": 123456,
            "reason": "double_proposal"
          }
        ]
      }
    },
    {
      "validator_id": "0xdef456",
      "status": "pending",
      "balance": {
        "average_effectiveness": 0,
        "current_balance": 0,
        "validator_income": 0
      },
      "performance": {
        "slots_behind": 0,
        "blocks": {
          "proposed": 0,
          "missed": 0,
          "orphaned": 0,
          "scheduled": 0
        },
        "attestations": {
          "proposed": 0,
          "missed": 0
        },
        "syncs": {
          "participated": 0,
          "missed": 0,
          "orphaned": 0,
          "scheduled": 0
        },
        "slashings": []
      }
    }
  ]
}

POST /snm/v1/{network}/validators/exit
- Description: Request a voluntary exit of a validator with specific ID. Voluntary exits allow validators to permanently stop performing their duties, and eventually recover the deposit.
- Body parameters:
  - validator_ids: [String] The list of validators to exit.
GET /snm/v1/{network}/validators/migrate
- Description: Request a migration of a validator with specific ID. Returns the validator keystores and slashing protection history. Migrations allow validators to move to another validator client. This operation, stops existing client and export your slashing protection history.
- Body parameters:
  - validator_ids: [String] The list of validators to migrate.
GET /snm/v1/{network}/validators/{validator_id}/deposit
- Description: Perform a deposit top-up of a validator with specific ID. Returns a DepositData message that will be used for crafting the necessary transaction by the GUI
POST /snm/v1/{network}/validators/import
- Description: Import a validator. ( for example when migrate from another client)
-Body parameters:
- keystore: Keystore The keystore of the validator
- slash_protection_history: SlashProtectionHistory The slashing protection history of the validator

Dashboard

Device Healthcheck

The SNM should be able to monitor the health of the device that it runs on. If there is any danger it should notify the users. Additionally, the SNM should be able to monitor the health of the processes that it manages, based on the network they are part of.

GET /snm/v1/health/{component}/metrics endpoint.
- Description: Returns the metrics of the specific component in Prometheus format.
- Examples requests:
  - GET /snm/v1/health/host/metrics
  - GET /snm/v1/health/snm/metrics
  - GET /snm/v1/health/nimbus-cl/mainnet/metrics
  - GET /snm/v1/health/nimbus-cl/sepolia/metrics
GET /snm/v1/health/{component}/status endpoint.
- Description: Returns the health of the specific component.
- Example requests:
  - GET /snm/v1/health/host/status
  - GET /snm/v1/health/snm/status
  - GET /snm/v1/health/nimbus-cl/mainnet/status
  - GET /snm/v1/health/nimbus-cl/sepolia/status

Logs

The SNM should be able to provide the logs of the running services to the GUI.

GET /snm/v1/logs/{component}
- Description: Retrieves the latest logs from a specified service.
- Query parameters:
  - limit (optional): Specifies the maximum number of logs to return.
- Examples:
  - GET /snm/v1/logs/snm?limit=50
  - GET /snm/v1/logs/nimbus-cl/mainnet?limit=50
  - GET /snm/v1/logs/nimbus-cl/sepolia?limit=350
GET /snm/v1/logs/{component}/search
Description: Searches and retrieves logs based on specific criteria.
Query parameters:
- log-level: Specifies the type of logs to retrieve.
- query: Specifies the search query.
- start-time (optional): Specifies the start time for the search range.
- end-time (optional): Specifies the end time for the search range.
- limit (optional): Specifies the maximum number of logs to return.
Examples:
- GET /snm/v1/logs/snm?log-level=error&start-time=2024-04-01T00:00:00&end-time=2024-04-02T00:00:00
- GET /snm/v1/logs/nimbus-cl/mainnet?log-level=notice&query="Attestation sent"&limit=50
- GET /snm/v1/logs/nimbus-cl/sepolia?log-level=warning&query="Syncing failed"&start-time=2024-04-01T00:00:00&end-time=2024-04-02T00:00:00&limit=350

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Status Node Manager API Spec (WIP)

Status Node Manager API Spec

Common Path Parameters

Network

Component

Network-independent components:

Network-dependent components:

Validator identifiers

Examples:

Waku transport

Validator Onboarding

Installing/removing node packages

Creating, upgrading and restarting nodes

Validators setup

Validator Management

Dashboard

Device Healthcheck

Logs

Uh oh!

Clone this wiki locally