Obol API (v1.2.0)
Download OpenAPI specification:Download
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.
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 |
Responses
Response samples
- 200
{- "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:
path Parameters
configHash required | string The |
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
{- "address": "0x71cb05ee1b1f506ff321da3dac38f25c0c9ce6e1",
- "enr": "enr://5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621",
- "fork_version": "0x00001020",
- "enr_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c",
- "config_signature": "0x1199fc4440aa7929905ec171ed1dad82a9f6a89891193b2b4cf45937a8cf9ece4972e02bc7e23d8b8b2e550b6430693ac6bc8c82a0509f65d0abb34d7ae0a8a81c"
}
Response samples
- 200
{- "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:
path Parameters
configHash required | string The |
Responses
Response samples
- 200
{ }
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:
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
{- "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
{- "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"
}
]
}