Obol API (v1.2.0)

Download OpenAPI specification:Download

Obol Labs: support@obol.tech URL: https://obol.tech

What is this API?

This API is for creating and managing Distributed Validators. This API works in tandem with Obol's Distributed Validator Launchpad, a dapp designed to allow people to authenticate their counterparties and agree to the terms of a Distributed Validator Cluster. This API will be made more easy for code-only interaction in the coming quarters with the release of the Obol-SDK.

Read more about Obol and how to use the launchpad on our docs site.

Distributed Validators

Configuration for distributed validator key generation ceremonies.

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 signed the terms of the cluster, 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

configHash

required

string

The config_hash calculated for a cluster definition.

Responses

Response samples

200

Content type

application/json

{"name": "My Obol Cluster",
"uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
"creator": {"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
},
"version": "v1.2.0",
"num_validators": 5,
"threshold": 3,
"fee_recipient_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"withdrawal_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"dkg_algorithm": "default",
"fork_version": "0x00001020",
"config_hash": "0x3940294920aaabbbccccddddeeeffff33224",
"timestamp": "2022-07-19T18:19:58+02:00",
"operators": [{"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
"fork_version": "0x00001020",
"enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}
]
}

Accept a proposed Distributed Validator Cluster

This endpoint is used by the operators present in the operators array of a cluster definition. 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:

bearer

path Parameters

configHash

required

string

The config_hash calculated for a cluster definition.

header Parameters

authorization

required

string

EIP712 operator hash as bearer token

Request Body schema: application/json

address required	string
enr required	string
fork_version required	string
enr_signature required	string
config_signature required	string

Responses

Request samples

Payload

Content type

application/json

{"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
"fork_version": "0x00001020",
"enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}

Response samples

200

Content type

application/json

{"name": "My Obol Cluster",
"uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
"creator": {"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
},
"version": "v1.2.0",
"num_validators": 5,
"threshold": 3,
"fee_recipient_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"withdrawal_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"dkg_algorithm": "default",
"fork_version": "0x00001020",
"config_hash": "0x3940294920aaabbbccccddddeeeffff33224",
"timestamp": "2022-07-19T18:19:58+02:00",
"operators": [{"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
"fork_version": "0x00001020",
"enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}
]
}

Delete a Distributed Validator Cluster proposal

This endpoint allows the caller to delete an unwanted DKG ceremony proposal.

Authorizations:

bearer

path Parameters

configHash

required

string

The config_hash calculated for a cluster definition.

Responses

Response samples

200

Content type

application/json

{ }

Propose a new Distributed Validator Cluster

This endpoint allows the caller to propose a distributed key generation ceremony. 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:

bearer

header Parameters

authorization

required

string

EIP712 cluster definition hash as bearer token

Request Body schema: application/json

name required	string
required	Array of objects (ClusterDefOperator)
required	object (ClusterDefCreator)
uuid required	string
version required	string
num_validators required	number >= 1
threshold required	number >= 1
fee_recipient_address required	string
withdrawal_address required	string
dkg_algorithm required	string
fork_version required	string
timestamp required	string
config_hash required	string

Responses

Request samples

Payload

Content type

application/json

{"name": "My Obol Cluster",
"operators": [{"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1"
}
],
"creator": {"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1"
},
"uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
"version": "v1.2.0",
"num_validators": 5,
"threshold": 3,
"fee_recipient_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"withdrawal_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"dkg_algorithm": "default",
"fork_version": "0x00001020",
"timestamp": "2022-07-19T18:19:58+02:00",
"config_hash": "0x29b0223beea5f4f74391f445d15afd4294040374f6924b98cbf8713f8d962d7c"
}

Response samples

201

Content type

application/json

{"name": "My Obol Cluster",
"uuid": "0194FDC2-FA2F-FCC0-41D3-FF12045B73C8",
"creator": {"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
},
"version": "v1.2.0",
"num_validators": 5,
"threshold": 3,
"fee_recipient_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"withdrawal_address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
"dkg_algorithm": "default",
"fork_version": "0x00001020",
"config_hash": "0x3940294920aaabbbccccddddeeeffff33224",
"timestamp": "2022-07-19T18:19:58+02:00",
"operators": [{"address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1"
}
]
}

System

System related endpoints.

Redirect to the API docs

Hitting the root of the domain redirects to /docs and a swagger deployment.

Responses

Response samples

200

Content type

application/json

{ }

Check the API health

This endpoint reports the API and its dependencies health.

Responses

Response samples

200
503

Content type

application/json

{"status": "ok",
"info": {"database": {"status": "up"
}
},
"error": { },
"details": {"database": {"status": "up"
}
}
}