diff --git a/apis/fee_recipient.yaml b/apis/fee_recipient.yaml new file mode 100644 index 0000000..3c605ce --- /dev/null +++ b/apis/fee_recipient.yaml @@ -0,0 +1,78 @@ +get: + operationId: ListFeeRecipient + summary: List Fee Recipient. + description: | + List the validator public key to eth address mapping for fee recipient feature on a specific public key. + The validator public key will return with the default fee recipient address if a specific one was not found. + + WARNING: The fee_recipient is not used on Phase0 or Altair networks. + security: + - bearerAuth: [] + tags: + - Fee Recipient + parameters: + - in: path + name: pubkey + schema: + $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey" + required: true + responses: + "200": + description: success response + content: + application/json: + schema: + title: ListFeeRecipientResponse + type: object + required: [data] + properties: + data: + $ref: "../keymanager-oapi.yaml#/components/schemas/FeeRecipient" + "401": + $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized" + "403": + $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden" + "404": + $ref: "../keymanager-oapi.yaml#/components/responses/NotFound" + "500": + $ref: "../keymanager-oapi.yaml#/components/responses/InternalError" + +post: + operationId: SetFeeRecipient + summary: Set Fee Recipient. + description: | + Sets the validator client fee recipient mapping which will then update the beacon node. + Existing mappings for the same validator public key will be overwritten. + Specific Public keys not mapped will continue to use the default address for fee recipient in accordance to the startup of the validator client and beacon node. + Cannot specify default fee recipient address through API. + + WARNING: The fee_recipient is not used on Phase0 or Altair networks. + security: + - bearerAuth: [] + tags: + - Fee Recipient + parameters: + - in: path + name: pubkey + schema: + $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey" + required: true + requestBody: + content: + application/json: + schema: + $ref: '../keymanager-oapi.yaml#/components/schemas/EthAddress' + required: true + responses: + "202": + description: successfully updated + "400": + $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest" + "401": + $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized" + "403": + $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden" + "404": + $ref: "../keymanager-oapi.yaml#/components/responses/NotFound" + "500": + $ref: "../keymanager-oapi.yaml#/components/responses/InternalError" \ No newline at end of file diff --git a/flows/client-specific/README.md b/flows/client-specific/README.md deleted file mode 100644 index 9a7f523..0000000 --- a/flows/client-specific/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Prysm Specific Flows -Prysm (https://github.com/prysmaticlabs/prysm) at the time of writing is one of the consensus layer clients implementing the Keymanager APIs. -There are some Prysm specific quirks that this document would like to make users aware of. - -### Prysm Default Validator API Address -`http://127.0.0.1:7500/` - -Prysm by default runs on the above address when running with `--web` flag. please look at our documentation [here](https://docs.prylabs.network/docs/prysm-usage/web-interface) for more information. Prysm includes its own native UI implementation as well. - - -## prysm version 2.0.7 - -1. Authentication: Prysm requires a bearer token for using the validator APIs, this token is also used for Prysm's native UI. For more information on where to find this token please look at the Prysm Docs. - -4. CORS: Prysm has CORS protection with ports 3000 (typically REACT), 7500, and 4200 (typically Angular). Please use the appropriate Prysm flag to enable other ports. Please look at the Prysm Docs for more information. - -3. Prysm Wallet & keymanager Type: Prysm uses something called a Prysm wallet (not related to hardware wallet) to manage the validator keys inside the Prysm client. All users of Prysm must create a wallet with a specific keymanager type in order to import or delete validator keys. The following errors will be thrown if requirements are not met: -- invalid wallet: either the wallet itself is corrupted, missing, or unable to be opened. -- invalid keymanager type: the keymanager type when creating the wallet isn't usable with the keymanager APIs. Only the `local` keymanager type is allowed to be used for Keymanager APIs referring to the type where users are storing the validators in their local Prysm instance instead of using a remote signer. -- validator service cannot get keymanager: The Keymanager API is called too soon after wallet creation. -4. API middleware and Internal RPC: Prysm doesn't natively use REST and uses gRPC internally instead for APIs, that means Prysm is translating HTTP REST calls into RPC calls and vice versa. This can cause certain types of issues that although unintended, can happen. -- Error code or error message unexpected: because our RPC codes are translated to HTTP errors there may be unexpected response codes in which case please report to the Prysm Team -- Golang primitives default values: Golang (the programming language Prysm is written in) will default certain primatives by default (`string` as `""` instead of `null`, `boolean` as `false` instead of `null`, etc) we try to account for as many as we can with tests but please let the team know if Prysm behaves differently from other clients. \ No newline at end of file diff --git a/keymanager-oapi.yaml b/keymanager-oapi.yaml index 1f90dba..bbe6895 100644 --- a/keymanager-oapi.yaml +++ b/keymanager-oapi.yaml @@ -31,6 +31,8 @@ servers: default: "https://public-mainnet-node.ethereum.org" tags: + - name: Fee Recipient + description: Set of endpoints for management of fee recipient. - name: Local Key Manager description: Set of endpoints for key management of local keys. - name: Remote Key Manager @@ -41,6 +43,8 @@ paths: $ref: './apis/local_keystores.yaml' /eth/v1/remotekeys: $ref: './apis/remote_keystores.yaml' + /eth/v1/validator/{pubkey}/feerecipient: + $ref: './apis/fee_recipient.yaml' components: securitySchemes: @@ -52,8 +56,12 @@ components: schemas: Pubkey: $ref: './types/public_key.yaml' + EthAddress: + $ref: './types/eth_address.yaml' Keystore: $ref: './types/keystore.yaml' + FeeRecipient: + $ref: './types/fee_recipient.yaml' SignerDefinition: $ref: './types/signer_definition.yaml' ImportRemoteSignerDefinition: @@ -70,21 +78,24 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorResponse" - Unauthorized: description: "Unauthorized, no token is found" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" - Forbidden: description: "Forbidden, a token is found but is invalid" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" - + NotFound: + description: "Path not found" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" InternalError: description: | Internal server error. The server encountered an unexpected error indicative of diff --git a/types/eth_address.yaml b/types/eth_address.yaml new file mode 100644 index 0000000..9e98749 --- /dev/null +++ b/types/eth_address.yaml @@ -0,0 +1,4 @@ +type: string +description: "An address on the execution (Ethereum 1) network." +example: "0xabcf8e0d4e9587369b2301d0790347320302cc09" +pattern: "^0x[a-fA-F0-9]{40}$" \ No newline at end of file diff --git a/types/fee_recipient.yaml b/types/fee_recipient.yaml new file mode 100644 index 0000000..d72c0b9 --- /dev/null +++ b/types/fee_recipient.yaml @@ -0,0 +1,7 @@ +type: object +required: [pubkey,ethaddress] +properties: + pubkey: + $ref: './public_key.yaml' + ethaddress: + $ref: './eth_address.yaml' \ No newline at end of file