Skip to main content
API docs by Redocly

Obol API (v1.0.0-local)

Download OpenAPI specification:Download

Obol Labs: [email protected] URL: https://obol.tech

What is this API?

This API is for creating and managing Distributed Validators. This API works in tandem with Obol's Distributed Validator Launchpad, a dapp designed to allow people to authenticate their counterparties and agree to the terms of a Distributed Validator Cluster. This API will be made more easy for code-only interaction in the coming quarters with the release of the Obol-SDK.

Read more about Obol and how to use the launchpad on our docs site.

For enquiries:

Distributed Validators

Configuration for distributed validator key generation ceremonies.

Retrieve a Distributed Validator Cluster proposal

This endpoint allows a charon client or launchpad interface to retrieve the terms of a proposed DKG. Once all operators listed in the DKG have submitted signed approvals to the terms, this object will be ready for a cluster of operators to use as part of a DKG ceremony. If the objects in the operators array are not fully populated, these operators need to use the PUT request to upload their charon client's public key and a signature from their address to indicate their acceptance of the terms.

path Parameters
configHash
required
string

The config_hash calculated for a cluster definition.

Responses

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ]
}

Accept a proposed Distributed Validator Cluster

This endpoint is used by the operators present in the operators array of a cluster definition. These operators must submit a public key (in ENR form) to serve as their identity during the DKG, along with EIP712 signatures indicating their acceptance of the terms of this DKG.

Authorizations:
bearer
path Parameters
configHash
required
string

The config_hash calculated for a cluster definition.

header Parameters
authorization
required
string

EIP712 operator hash as bearer token

Request Body schema: application/json
address
required
string

Ethereum address of Operator.

enr
required
string
fork_version
required
string
Enum: "mainnet" "0x00000000" "goerli" "0x00001020" "gnosis" "0x00000064" "sepolia" "0x90000069" "holesky" "0x01017000"
version
required
string
enr_signature
required
string
config_signature
required
string

Responses

Request samples

Content type
application/json
{
  • "address": "0x000000000000000000000000000000000000dead",
  • "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
  • "fork_version": "0x00001020",
  • "version": "v1.8.0",
  • "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
  • "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ]
}

Retrieve a list of cluster definitions which the address belongs to.

This endpoint allows a charon client or launchpad interface to fetch a specific number of cluster definitions which the address is part of for each page.

path Parameters
address
required
string

The operator address

query Parameters
page
required
number
limit
required
number

Responses

Response samples

Content type
application/json
{
  • "cluster_definitions": [
    ],
  • "total_count": 2,
  • "total_pages": 3
}

Propose a new Distributed Validator Cluster

This endpoint allows the caller to propose a distributed key generation ceremony. The caller must specify the configuration of a Distributed Validator Cluster; such as the participating operators and the validator exit details. Operators invited to participate in this cluster must submit a public key (in ENR form) to serve as their node's identity, along with EIP712 signatures indicating their acceptance of the terms of this cluster.

Authorizations:
bearer
header Parameters
authorization
required
string

EIP712 cluster definition hash as bearer token

Request Body schema: application/json
name
required
string
required
Array of objects (OperatorDto)

operator data.

required
Array of objects (CreatorDto)

creator data.

uuid
required
string
version
required
string
num_validators
required
number >= 1
threshold
required
number >= 1
dkg_algorithm
required
string
Enum: "frost" "keycast" "default"
fork_version
required
string
Enum: "mainnet" "0x00000000" "goerli" "0x00001020" "gnosis" "0x00000064" "sepolia" "0x90000069" "holesky" "0x01017000"
timestamp
required
string
required
Array of objects (ClusterDefValidator)

validator withdrawal configuration.

deposit_amounts
required
Array of strings

partial deposits.

config_hash
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "operators": [
    ],
  • "creator": [
    ],
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}

Response samples

Content type
application/json
{
  • "name": "My Obol Cluster",
  • "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
  • "creator": { },
  • "version": "v1.8.0",
  • "num_validators": 5,
  • "threshold": 3,
  • "dkg_algorithm": "default",
  • "fork_version": "0x00001020",
  • "config_hash": "0x2204ba6c238ed2d6a8ff951d4513db993c8d6f8860468391342649bf735a87d7",
  • "timestamp": "2022-07-19T18:19:58+02:00",
  • "validators": [
    ],
  • "deposit_amounts": [
    ],
  • "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  • "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  • "withdrawal_address": "0x000000000000000000000000000000000000dead",
  • "operators": [
    ]
}

System

System related endpoints.

Redirect to the API docs

Hitting the root of the domain redirects to /docs and a swagger deployment.

Responses

Response samples

Content type
application/json
{ }

Check the API health

This endpoint reports the API and its dependencies health.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "info": {
    },
  • "error": { },
  • "details": {
    }
}

MetricsController_metrics

Responses

Response samples

Content type
application/json
"string"

Cluster Lock

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object.

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Retrieve a list of Distributed Validator Cluster Lock Objects

This endpoint is used to search for Cluster Lock Objects that match a substring of their lock_hash.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • holesky - Holesky Test Network
  • sepolia - Sepolia Test Network
  • goerli - Goerli Test Network

The network to retrieve clusters on

query Parameters
partialLockHash
required
string

A substring of the lock_hash calculated for a cluster lock.

page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 20

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a Distributed Validator Cluster Lock Object

This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it.

path Parameters
configHash
required
string

The config_hash calculated for a cluster configuration.

Responses

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Redirect to the launchpad cluster status page

This endpoint is used to redirect users to the created cluster status page after DKG is completed.

path Parameters
lockHash
required
string

The lock_hash calculated for a Distributed Validator Cluster.

Responses

Retrieve a list of Distributed Validator Clusters for which this address is an operator

This endpoint fetches a number of Distributed Validator Clusters for which the address provided is a node operator.

path Parameters
address
required
string

The operator address.

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 20

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_count": 2,
  • "total_pages": 4
}

Retrieve a list of Distributed Validator Clusters for a given network

This endpoint fetches a number of cluster lock objects for a given network.

path Parameters
network
required
string
Examples:
  • mainnet - Ethereum Mainnet
  • holesky - Holesky Test Network
  • sepolia - Sepolia Test Network
  • goerli - Goerli Test Network

The network to retrieve clusters on

query Parameters
page
required
integer
Default: 0

The page number to retrieve.

limit
required
integer
Default: 20

The number of cluster lock objects to return.

Responses

Response samples

Content type
application/json
{
  • "cluster_locks": [
    ],
  • "total_count": 2,
  • "total_pages": 4
}

Push Distributed Validator Cluster Lock Data

This endpoint saves cluster lock objects that describe the created Distributed Validator Cluster.

Request Body schema: application/json
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Response samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

Verify Distributed Validator Cluster Lock Data

This endpoint verifies cluster lock data including BLS public keys and signatures created during the DKG phase.

Request Body schema: application/json
required
object

Cluster definition data that was used in dkg to generate cluster lock.

required
Array of objects (DistributedValidatorDto)

distributed validator keys and deposit data.

signature_aggregate
required
string
lock_hash
required
string
node_signatures
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "cluster_definition": {
    },
  • "distributed_validators": [
    ],
  • "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  • "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  • "node_signatures": [
    ]
}

State

Retrieve the Validator states for a cluster

This endpoint is used to retrieve the states of all validators in a DV Cluster

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "index": "12345",
  • "status": "active_ongoing",
  • "balance": "32",
  • "0x000000000000000000000000000000": {
    }
}

Lido Exit

Retrieve Lido Distributed Validator threshold aggregated signed exit msg

This endpoint is used to retrieve lido validator exit message

Authorizations:
bearer
path Parameters
validatorPubkey
required
string

The distributed_public_key in a cluster lock.

shareIdx
required
any

Represents the cluster operatorIndex+1.

lockHash
required
any

The cluster lockHash.

Responses

Response samples

Content type
application/json
{ }

Push Lido Distributed Validator partial signed exit message

This endpoint saves partial signed exit messages.

path Parameters
lockHash
required
string

The lockHash of the cluster which the validator belongs to

Request Body schema: application/json
required
Array of objects (LidoExitBlobDto)
share_idx
required
number
signature
required
string

Responses

Request samples

Content type
application/json
{
  • "partial_exits": [
    ],
  • "share_idx": 42,
  • "signature": ""
}

Cluster Effectiveness

Retrieve a Distributed Validator Cluster Effectiveness Object

This endpoint is used to retrieve the effectiveness of a cluster by pubkey

path Parameters
lockHash
required
string

The lock_hash calculated for a cluster lock.

Responses

Response samples

Content type
application/json
{
  • "oneDay": 0,
  • "sevenDay": 0,
  • "thirtyDay": 0,
  • "all": 0
}