Cluster Definition

Last updated 1 month ago

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.obol.tech//v1/definition/operator/{address}?page=1&limit=1'

200

500

{
  "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
}

A list of cluster definitions which the operator is part of

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.obol.tech//v1/definition/{configHash}'

200

404

500

{
  "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
}

The cluster object

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: 0x00001020Available options:

versionstringrequiredExample: v1.8.0

enr_signaturestringrequiredExample:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

config_signaturestringrequiredExample:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.obol.tech//v1/definition/{configHash}' \
  --header 'Authorization: Bearer JWT' \
  --header 'authorization: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "0x000000000000000000000000000000000000dead",
    "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
    "fork_version": "0x00001020",
    "version": "v1.8.0",
    "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
    "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
  }'

200

400

401

404

409

500

{
  "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
}

The cluster object

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

operatorsobject[] · min: 3required

operator data.

creatorobject[]required

creator data.

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

versionstringrequiredExample: v1.8.0

num_validatorsnumber · min: 1requiredExample: 5

thresholdnumber · min: 1requiredExample: 3

dkg_algorithmstring · enumrequiredExample: defaultAvailable options:

fork_versionstring · enumrequiredExample: 0x00001020Available options:

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

validatorsobject[]required

validator withdrawal configuration.

deposit_amountsstring[]required

partial deposits.

consensus_protocolstringrequiredExample: qbft

target_gas_limitnumber · min: 1requiredExample: 36000000

compoundingbooleanrequired

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

config_hashstringrequiredExample: 0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.obol.tech//v1/definition' \
  --header 'Authorization: Bearer JWT' \
  --header 'authorization: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "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"
  }'

201

400

401

409

500

{
  "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
}

The cluster object

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

Retrieve a Distributed Validator Cluster proposal

Accept a proposed Distributed Validator Cluster

Propose a new Distributed Validator Cluster

Show child attributes

Show child attributes

Show child attributes