OBobol
Cluster Lock

Retrieve a Distributed Validator Cluster Lock Object

Changed on

This endpoint is used to retrieve a cluster lock object by the hash of the configuration used to create it. Several cluster locks can share a config_hash (for example when the DKG is run again with the same configuration); this endpoint returns the most recently created one, so the answer only changes when another lock is posted for the config_hash. Its is_current / superseded_by fields say whether it is the lock Obol monitoring sees running (an older lock whose Charon nodes report more recently can be current instead). Use GET /lock/{lockHash} to retrieve a specific lock. Responses may be cached for a short time.

get/v1/lock/configHash/{configHash}

Request

  • Base URL
    https://api.obol.tech
  • Auth
    none declared

Path parameters

configHashstring required

The config_hash calculated for a cluster configuration.

Response

The most recently created cluster lock for this config_hash

distributed_validatorsDistributedValidator[] required
signature_aggregatestring required
lock_hashstring required
node_signaturesstring[] required
definition_storedboolean required

true: cluster_definition is the exact definition this lock was created with (covered by lock_hash). false: this lock was stored without its exact cluster definition; lock_hash cannot be re-verified until the lock file is posted again.

is_currentboolean required

true: this is the current lock for its validators and config_hash. Several locks can share validator keys or a config_hash (re-split or DKG re-run); the current one is the lock whose Charon nodes reported most recently to Obol monitoring, or, when none of them has reported, the most recently created. It can change when another lock is posted for the same keys or when a sibling starts or stops reporting. GET /lock/configHash/{configHash} does not use this rule: it returns the most recently created lock, which can be is_current false.

superseded_bystring nullable required

lock_hash of the current lock that shares validator keys or the config_hash with this one, when this lock is not current; null when it is current.

Example response

{
  "cluster_definition": {
    "name": "My Obol Cluster",
    "uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
    "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",
    "deposit_amounts": [
      "8000000000",
      "16000000000",
      "8000000000"
    ],
    "definition_hash": "0xb656f5a4a5537b5817d6bcf735d043f17f5aff568b1a7ec9102a9f687bd4510c",
    "fee_recipient_address": "0x000000000000000000000000000000000000dead",
    "withdrawal_address": "0x000000000000000000000000000000000000dead",
    "consensus_protocol": "qbft",
    "target_gas_limit": 36000000,
    "compounding": true
  },
  "signature_aggregate": "0x85650c30ec29a3703934bf50a28da102975deda77e758579ea3dfe4136abf752",
  "lock_hash": "0xd2880980169ee4a0000f23feb8fad9a6c70f38312956fe67aa89e118f5b0e048",
  "definition_stored": true,
  "is_current": true
}

Changes

  • c545dd14c211Revision changes
    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

  • ffbd09536a1aRevision changes
    • info

      added the non-success response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status