SDKAPI
Edit

Cluster Definition

Retrieve a Distributed Validator Cluster proposal

get
/v1/definition/{configHash}

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
get
/v1/definition/{configHash}
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
/v1/definition/{configHash}

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
put
/v1/definition/{configHash}
PUT /v1/definition/{configHash} HTTP/1.1
Host: api.obol.tech
Authorization: Bearer YOUR_SECRET_TOKEN
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
}

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

get
/v1/definition/operator/{address}

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
get
/v1/definition/operator/{address}
GET /v1/definition/operator/{address}?page=1&limit=1 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
}

Propose a new Distributed Validator Cluster

post
/v1/definition

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
post
/v1/definition
POST /v1/definition HTTP/1.1
Host: api.obol.tech
Authorization: Bearer YOUR_SECRET_TOKEN
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
}
PreviousMetricsNextCluster Lock

Last updated

Was this helpful?