Cluster Definition

Propose a new Distributed Validator Cluster

Changed on Oct 28, 2026

This endpoint allows the caller to propose a distributed key generation ceremony.The caller must have accepted the latest version of Obol's terms and conditions. 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. The definition version must be v1.10.0 or later.

post/v1/definition

Request

Base URL
https://api.obol.tech
Auth
HTTP bearer

Headers

authorizationstring required

EIP712 cluster definition hash as bearer token

Request body

namestring required

uuidstring required

versionstring required

num_validatorsnumber required

thresholdnumber required

dkg_algorithm'frost' | 'keycast' | 'default' required

timestampstring required

deposit_amountsstring[] required

partial deposits.

consensus_protocol'qbft' | '' required

target_gas_limitnumber required

compoundingboolean required

Flag that enables compounding rewards for validators by using 0x02 withdrawal credentials

config_hashstring required

Example request

{
  "name": "My Obol Cluster",
  "operators": [
    {
      "address": "0x000000000000000000000000000000000000dead",
      "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
      "fork_version": "0x00001020",
      "version": "v1.8.0",
      "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
      "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
    }
  ],
  "creator": [
    {
      "address": "0x000000000000000000000000000000000000dead",
      "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
    }
  ],
  "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": [
    {
      "fee_recipient_address": "0x000000000000000000000000000000000000dead",
      "withdrawal_address": "0x000000000000000000000000000000000000dead"
    }
  ],
  "consensus_protocol": "qbft",
  "target_gas_limit": 36000000,
  "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}

Response

The cluster object

namestring required

uuidstring required

creatorCreator required

versionstring required

num_validatorsnumber required

thresholdnumber required

dkg_algorithmstring required

fork_versionstring required

config_hashstring required

config_hash is a 32 bytes SSZ hash of cluster config.

timestampstring required

validatorsValidator[] required

deposit_amountsstring[] required

Partial depoists.

definition_hashstring required

definition_hash is a 32 bytes SSZ hash of cluster config.

fee_recipient_addressstring required

Ethereum address to receive transaction fees.

withdrawal_addressstring required

Ethereum address to receive staked ether.

operatorsOperator[] required

consensus_protocolstring required