Deprecate prior and add /validator/config endpoint #87
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,3 +2,4 @@ | |
| .DS_Store | ||
| deploy | ||
| node_modules | ||
| dictionary.dic | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,251 @@ | ||
| get: | ||
| operationId: getValidatorConfig | ||
| summary: Get Validator Config. | ||
| description: | | ||
| Returns the block-production preferences of the requested keys, or of all keys known to the | ||
| server when `pubkeys` is not given. | ||
|
|
||
| Each configured key returns its complete document, exactly as it was submitted. A key the | ||
| server knows but has no document for returns an empty object; its effective preferences are | ||
| the read-only `default_config` included in the response, taken whole (documents are | ||
| all-or-nothing, so nothing is merged per field). Keys the server does not know are omitted | ||
| from the response entirely. | ||
| security: | ||
| - bearerAuth: [] | ||
| tags: | ||
| - Validator Config | ||
| parameters: | ||
| - in: query | ||
| name: pubkeys | ||
| required: false | ||
| description: | | ||
| Restrict the response to the given public keys. Keys the server does not know are omitted | ||
| from the response. When not given, the response covers all keys known to the server. | ||
| style: form | ||
| explode: false | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey" | ||
| responses: | ||
| "200": | ||
| description: Success response | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: GetValidatorConfigResponse | ||
| type: object | ||
| required: [data] | ||
| properties: | ||
| data: | ||
| type: object | ||
| required: [configs] | ||
| properties: | ||
| default_config: | ||
| allOf: | ||
| - $ref: "../keymanager-oapi.yaml#/components/schemas/ValidatorConfig" | ||
| - description: | | ||
| The defaults the client applies to keys with no configured document. | ||
| Read-only through this API. When present, `default_config` is itself a | ||
| complete document. When absent, keys without a document follow the | ||
| client's built-in defaults. | ||
| configs: | ||
| type: object | ||
| description: | | ||
| Mapping of validator public key (hex encoded with 0x prefix) to its configured | ||
| `ValidatorConfig` document. Keys with no per-key configuration map to an empty | ||
| object. | ||
| additionalProperties: | ||
| $ref: "../keymanager-oapi.yaml#/components/schemas/ValidatorConfig" | ||
| example: | ||
| data: | ||
| default_config: | ||
| fee_recipient: "0x8943545177806ED17B9F23F0a21ee5948eCaa776" | ||
| target_gas_limit: "30000000" | ||
| graffiti: "example graffiti" | ||
| builder: | ||
| enabled: true | ||
| builders: | ||
| - url: "https://builder-a.example.com" | ||
| auth_data: "0x68747470733a2f2f6275696c6465722d612e6578616d706c652e636f6d" | ||
| max_execution_payment: "0" | ||
| min_bid: "0" | ||
| builder_boost_factor: "100" | ||
| - url: "https://builder-b.example.com" | ||
| auth_data: "0x68747470733a2f2f6275696c6465722d622e6578616d706c652e636f6d" | ||
| max_execution_payment: "0" | ||
| min_bid: "0" | ||
| builder_boost_factor: "100" | ||
| configs: | ||
| "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": | ||
| fee_recipient: "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3" | ||
| target_gas_limit: "45000000" | ||
| graffiti: "example graffiti" | ||
| builder: | ||
| enabled: true | ||
| builders: | ||
| - url: "https://builder-a.example.com" | ||
| auth_data: "0x1234567890abcdef" | ||
| pubkey: "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a" | ||
| max_execution_payment: "250000000" | ||
| min_bid: "10000000" | ||
| builder_boost_factor: "100" | ||
| - url: "https://builder-a.example.com" | ||
| auth_data: "0xdeadbeef" | ||
| max_execution_payment: "0" | ||
| min_bid: "0" | ||
| builder_boost_factor: "100" | ||
| "0xa99a76ed7796f7be22d5b7e85deeb7c5677e88e511e0b337618f8c4eb61349b4bf2d153f649f7b53359fe8b94a38e44c": | ||
| fee_recipient: "0x8943545177806ED17B9F23F0a21ee5948eCaa776" | ||
| target_gas_limit: "30000000" | ||
| graffiti: "" | ||
| builder: | ||
| enabled: false | ||
| "0xb0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7": {} | ||
| "400": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest" | ||
| "401": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized" | ||
| "403": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden" | ||
| "500": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/InternalError" | ||
|
|
||
| post: | ||
| operationId: setValidatorConfig | ||
| summary: Set Validator Config. | ||
| description: | | ||
| Sets the block-production preferences of one or more keys. Each submitted document replaces | ||
| the key's entire configuration; the server MUST NOT merge it with previously stored values. | ||
| Submit either a complete document (`fee_recipient`, `target_gas_limit`, `graffiti`, and a | ||
| fully resolved `builder`) or an empty one (`{}`), which clears the key so it follows the | ||
| client's defaults again (there is no separate delete operation). Anything in between fails | ||
| that key with a per-key `error` status. | ||
|
|
||
| Keys NOT present in `request.configs` are left untouched: only submitted keys are affected, so | ||
| a large key set may be split across multiple requests. Servers SHOULD accept request bodies | ||
| large enough to cover their full key set in one request (thousand-key batches are expected). | ||
|
|
||
| A configuration may be set for a key the server does not yet manage. The server SHOULD store it | ||
| (pre-provisioning) so it takes effect when the key is later added; a server that does not | ||
| pre-provision returns `not_found`. | ||
|
|
||
| Atomicity is per key, NOT per batch: each key's document takes effect fully or not at all, but | ||
| the batch is not transactional across keys. Keys that validate successfully are applied even | ||
| when other keys in the same request fail, and each key's outcome is reported in the per-key | ||
| response status. | ||
|
|
||
| Servers MUST validate the syntax of every submitted field (types, formats, patterns). A | ||
| `builders` list containing two entries with the same (`url`, `auth_data`) pair, compared as | ||
| the decoded `auth_data` bytes, is invalid; the server MUST NOT silently drop the duplicate. | ||
| Any such failure rejects that key's entire document with a per-key `error` status: no part of | ||
| it is applied. | ||
| Unrecognized fields are ignored for forward compatibility, consistent with the rest of the | ||
| keymanager API. In particular, `default_config` is read-only and cannot be written through this | ||
| API. | ||
| security: | ||
| - bearerAuth: [] | ||
| tags: | ||
| - Validator Config | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: SetValidatorConfigRequest | ||
| type: object | ||
| required: [configs] | ||
| properties: | ||
| configs: | ||
| type: object | ||
| description: | | ||
| Mapping of validator public key (hex encoded with 0x prefix) to the full | ||
| `ValidatorConfig` document to set for that key, or `{}` to clear it. Keyed by | ||
| public key rather than validator index so configurations can be pre-provisioned | ||
| for keys that are not yet active. | ||
| additionalProperties: | ||
| $ref: "../keymanager-oapi.yaml#/components/schemas/ValidatorConfig" | ||
| example: | ||
| configs: | ||
| "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": | ||
| fee_recipient: "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3" | ||
| target_gas_limit: "45000000" | ||
| graffiti: "example graffiti" | ||
| builder: | ||
| enabled: true | ||
| builders: | ||
| - url: "https://builder-a.example.com" | ||
| auth_data: "0x68747470733a2f2f6275696c6465722d612e6578616d706c652e636f6d" | ||
| max_execution_payment: "250000000" | ||
| min_bid: "10000000" | ||
| builder_boost_factor: "100" | ||
| "0xa99a76ed7796f7be22d5b7e85deeb7c5677e88e511e0b337618f8c4eb61349b4bf2d153f649f7b53359fe8b94a38e44c": | ||
| fee_recipient: "0x8943545177806ED17B9F23F0a21ee5948eCaa776" | ||
| target_gas_limit: "30000000" | ||
| graffiti: "" | ||
| builder: | ||
| enabled: true | ||
| builders: | ||
| - url: "https://builder-b.example.com" | ||
| auth_data: "0xdeadbeef" | ||
| max_execution_payment: "0" | ||
| min_bid: "0" | ||
| builder_boost_factor: "100" | ||
| - url: "https://builder-b.example.com" | ||
| auth_data: "0xDEADBEEF" | ||
| max_execution_payment: "0" | ||
| min_bid: "0" | ||
| builder_boost_factor: "100" | ||
| "0xb0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7": {} | ||
| responses: | ||
| "200": | ||
| description: Success response | ||
| content: | ||
| application/json: | ||
| schema: | ||
| title: SetValidatorConfigResponse | ||
| type: object | ||
| required: [data] | ||
| properties: | ||
| data: | ||
| type: object | ||
| description: Status of each key in `request.configs`, keyed by the same public keys. | ||
| additionalProperties: | ||
| type: object | ||
| required: [status] | ||
| properties: | ||
| status: | ||
| type: string | ||
| description: | | ||
| - set: the document was validated and applied. A complete document is | ||
| stored (pre-provisioned if the key is not yet managed, taking effect | ||
| when it is added); `{}` clears the key's configuration. | ||
| - not_found: the server neither manages this key nor supports | ||
| pre-provisioning, so nothing was stored | ||
| - error: the document failed validation or could not be applied; no change | ||
|
Collaborator
There was a problem hiding this comment. what should we do for unknown fields, silently accept ( client specific) or error here?
Author
There was a problem hiding this comment. removed |
||
| was made for this key | ||
| enum: | ||
| - set | ||
| - not_found | ||
| - error | ||
| example: set | ||
| message: | ||
| type: string | ||
| description: error message if status == error | ||
| example: | ||
| data: | ||
| "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": | ||
| status: set | ||
| "0xa99a76ed7796f7be22d5b7e85deeb7c5677e88e511e0b337618f8c4eb61349b4bf2d153f649f7b53359fe8b94a38e44c": | ||
| status: error | ||
| message: "builder.builders[1] duplicates the (url, auth_data) pair of builder.builders[0]" | ||
| "0xb0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7": | ||
| status: set | ||
| "400": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest" | ||
| "401": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized" | ||
| "403": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden" | ||
| "500": | ||
| $ref: "../keymanager-oapi.yaml#/components/responses/InternalError" | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we note specifics on not accepting duplicate urls just like we did on ethereum/beacon-APIs#630 ? or any other specifics
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i'm in the process of specifying that we MUST accept duplicate urls as long as the each per-key, there are no duplicate (url, auth_data) pairs