Cluster Definition

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

get

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

addressstringRequired

The operator address

Query parameters

pagenumberRequired

limitnumberRequired

Responses

200

A list of cluster definitions which the operator is part of

application/json

Responseany of

500

An unknown error occurred

get

GET //v1/definition/operator/{address} HTTP/1.1
Host: api.obol.tech
Accept: */*

{
  "cluster_definitions": [
    {
      "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": [
        "8000000000",
        "16000000000",
        "8000000000"
      ],
      "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
      "fee_recipient_address": "0x000000000000000000000000000000000000dead",
      "withdrawal_address": "0x000000000000000000000000000000000000dead",
      "operators": [
        {}
      ],
      "consensus_protocol": "qbft",
      "target_gas_limit": 36000000,
      "compounding": true
    }
  ],
  "total_count": 2,
  "total_pages": 3
}

Retrieve a Distributed Validator Cluster proposal

get

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

configHashstringRequired

The config_hash calculated for a cluster definition.

Responses

200

The cluster object

application/json

Responseany of

404

Cluster definition not found

500

An unknown error occurred

get

GET //v1/definition/{configHash} HTTP/1.1
Host: api.obol.tech
Accept: */*

{
  "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": [
    "8000000000",
    "16000000000",
    "8000000000"
  ],
  "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  "withdrawal_address": "0x000000000000000000000000000000000000dead",
  "operators": [
    {}
  ],
  "consensus_protocol": "qbft",
  "target_gas_limit": 36000000,
  "compounding": true
}

Accept a proposed Distributed Validator Cluster

put

This endpoint is used by the operators present in the operators array of a cluster definition. The operator must have accepted the latest version of Obol's terms and conditions. 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

Path parameters

configHashstringRequired

The config_hash calculated for a cluster definition.

Header parameters

authorizationstringRequired

EIP712 operator hash as bearer token

Body

addressstringRequired

Ethereum address of Operator.

Example: 0x000000000000000000000000000000000000dead

enrstringRequiredExample: enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621

fork_versionstring · enumRequiredExample: 0x00001020Possible values:

versionstringRequiredExample: v1.8.0

enr_signaturestringRequiredExample:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

config_signaturestringRequiredExample:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

Responses

200

The cluster object

application/json

Responseany of

400

Invalid payload data

401

Authorization header is missing or incorrect

404

Data not found

409

Duplicate entry

500

An unknown error occurred

put

PUT //v1/definition/{configHash} HTTP/1.1
Host: api.obol.tech
Authorization: Bearer JWT
authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 487

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

{
  "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": [
    "8000000000",
    "16000000000",
    "8000000000"
  ],
  "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  "withdrawal_address": "0x000000000000000000000000000000000000dead",
  "operators": [
    {}
  ],
  "consensus_protocol": "qbft",
  "target_gas_limit": 36000000,
  "compounding": true
}

Propose a new Distributed Validator Cluster

post

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.

Authorizations

Header parameters

authorizationstringRequired

EIP712 cluster definition hash as bearer token

Body

namestringRequiredExample: My Obol Cluster

uuidstringRequiredExample: 0194FDC2-FA2F-FCC0-41D3-FF12045B73C8

versionstringRequiredExample: v1.8.0

num_validatorsnumber · min: 1RequiredExample: 5

thresholdnumber · min: 1RequiredExample: 3

dkg_algorithmstring · enumRequiredExample: defaultPossible values:

fork_versionstring · enumRequiredExample: 0x00001020Possible values:

timestampstringRequiredExample: 2022-07-19T18:19:58+02:00

deposit_amountsstring[]Required

partial deposits.

consensus_protocolstring · enumRequiredExample: qbftPossible values:

target_gas_limitnumber · min: 1RequiredExample: 36000000

compoundingbooleanRequired

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

config_hashstringRequiredExample: 0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c

Responses

201

The cluster object

application/json

Responseany of

400

Invalid definition data

401

Authorization header is missing or incorrect

409

Duplicate entry

500

An unknown error occurred

post

POST //v1/definition HTTP/1.1
Host: api.obol.tech
Authorization: Bearer JWT
authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 1280

{
  "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"
    }
  ],
  "deposit_amounts": [
    "text"
  ],
  "consensus_protocol": "qbft",
  "target_gas_limit": 36000000,
  "compounding": true,
  "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}

{
  "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": [
    "8000000000",
    "16000000000",
    "8000000000"
  ],
  "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
  "fee_recipient_address": "0x000000000000000000000000000000000000dead",
  "withdrawal_address": "0x000000000000000000000000000000000000dead",
  "operators": [
    {}
  ],
  "consensus_protocol": "qbft",
  "target_gas_limit": 36000000,
  "compounding": true
}