Definition

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.

get

/v1/definition/{configHash}

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

The cluster object

Accept a proposed Distributed Validator Cluster

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.

put

/v1/definition/{configHash}

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

enrstringrequired

Example: enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621

versionstringrequired

Example: v1.8.0

enr_signaturestringrequired

Example:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

config_signaturestringrequired

Example:

0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c

fork_versionstring · enumrequired

Example: 0x00001020

Options: mainnet, 0x00000000, goerli, 0x00001020, gnosis, 0x00000064, sepolia, 0x90000069, holesky, 0x01017000

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",
    "version": "v1.8.0",
    "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
    "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
    "fork_version": "0x00001020"
  }'

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

The cluster object

Propose a new Distributed Validator Cluster

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.

post

/v1/definition

Authorizations

Header parameters

authorizationstringrequired

EIP712 cluster definition hash as bearer token

Body

namestringrequired

Example: My Obol Cluster

uuidstringrequired

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

versionstringrequired

Example: v1.8.0

num_validatorsnumber · min: 1required

Example: 5

thresholdnumber · min: 1required

Example: 3

timestampstringrequired

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

config_hashstringrequired

Example: 0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c

dkg_algorithmstring · enumrequired

Example: default

Options: frost, keycast, default

fork_versionstring · enumrequired

Example: 0x00001020

Options: mainnet, 0x00000000, goerli, 0x00001020, gnosis, 0x00000064, sepolia, 0x90000069, holesky, 0x01017000

operatorsobject[]required

creatorobject[]required

validatorsobject[]required

deposit_amountsstring[]required

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",
    "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
    "version": "v1.8.0",
    "num_validators": 5,
    "threshold": 3,
    "timestamp": "2022-07-19T18:19:58+02:00",
    "config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c",
    "dkg_algorithm": "default",
    "fork_version": "0x00001020",
    "operators": [
      {
        "address": "0x000000000000000000000000000000000000dead",
        "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
        "version": "v1.8.0",
        "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
        "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
        "fork_version": "0x00001020"
      }
    ],
    "creator": [
      {
        "address": "0x000000000000000000000000000000000000dead",
        "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
      }
    ],
    "validators": [
      {
        "fee_recipient_address": "0x000000000000000000000000000000000000dead",
        "withdrawal_address": "0x000000000000000000000000000000000000dead"
      }
    ],
    "deposit_amounts": [
      "text"
    ]
  }'

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

The cluster object