Configure a Fee Recipient Address (vNext)

Prysm develop branch

This guidance reflects functionality that exists only in Prysm's develop branch and may change significantly as we receive feedback from users like you. Join our Discord server to share your feedback.

Breaking changes

Breaking changes have been introduced within the develop branch. These changes introduce a new Fee Recipient and validator registration configuration schema:

The existing gaslimit property within the proposer settings file has been replaced with an optional builder object that contains the gaslimit property.
The existing suggested-fee-recipient flag must now be used with the new enable-builder flag. This allows your validator client to use the MEV Builder API.

Fee Recipient is a feature that lets you specify a priority fee recipient address on your validator client instance and beacon node. After The Merge, execution clients will begin depositing priority fees into this address whenever your validator client proposes a new block.

Background#

When users pay gas to submit transactions to the Ethereum network, they can specify a priority fee. Priority fees are like tips. End-users use priority fees to incentivize block proposers to prioritize the inclusion of particular transactions in the blocks that they propose.

Miners currently collect these priority fees. After The Merge, proof-of-work consensus will be replaced with proof-of-stake consensus. At this point, validators will collect these priority fees [1], [2].

Because priority fees are captured by execution clients in the execution layer, validator clients need to tell execution clients where to forward these priority fees. This priority fee “forwarding address” is referred to as your fee recipient address.

Configure this before The Merge

If you don't configure your fee recipient address before The Merge, your priority fee earnings will be deposited into a burn address.

Configuring Fee Recipient#

Your fee recipient address can be configured in two places: on your validator client instance and on your beacon node. Configuring fee recipient on your validator client instance lets you configure a different fee recipient address for each validator public key.

We recommend configuring it in both places, even if you only have one validator public key. Your validator client instance configuration will override the beacon node configuration, while the beacon node configuration will be treated like a backup in the event that your client instance configuration fails.

Configuring Fee Recipient on your validator client instance#

A fee recipient address can be configured on your client instance by using one of the following flags in the Prysm CLI:

Flag	Description
`suggested-fee-recipient`	Sets a default ETH address for all validator public keys. Example: `--suggested-fee-recipient=0x0123456722E6b0000012BFEBf6177F1D2e9758D9` Note: This setting is overwritten by the flags below. If you don't configure a Fee Recipient address using one of the flags below, this address will be mapped to all validator public keys.
`proposer-settings-file`	Sets the local file location for your `proposer-settings` YAML or JSON configuration. This lets you configure proposer settings like `fee_recipient` and `gas_limit` for your validator keys. This lets you override the ETH address specified by `suggested-fee-recipient` for any number of public keys. Example: `--proposer-settings-file=./proposer_settings.json`
`proposer-settings-url`	A remote `proposer-settings` configuration endpoint in URL format. This lets you override the ETH address specified by `suggested-fee-recipient` for any number of public keys. Example: `--proposer-settings-url=http://example.com/api/getProposerSettings` Note: JSON should be delivered as a JSON payload, not as a JSON file. Your client will issue a GET request and expects the response `Content-Type` header to be `application/json`.
`enable-builder`	This flag enables the periodic calling of Validator Registration API (a Builder API) while using the `suggested-fee-recipient` flag. Example: `--enable-builder` Note: this flag will not affect proposer settings file. The proposer settings can specify builder config use through its own fields.

An example invocation: ./prysm.sh validator --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9.

If you don't see any errors after issuing one of the above commands, your fee recipient address has been successfully configured.

Fee Recipient JSON Config File#

Breaking changes from 2.1.3

fee-recipient-config-file and fee-recipient-config-url flags are deprecated and have been replaced with proposer-settings-file and proposer-settings-url flags.

If you use either proposer-settings-file or proposer-settings-url to specify your fee recipient address, your YAML/JSON configuration should follow this schema:

---proposer_config:  '0x01234567155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a':    fee_recipient: '0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3'    builder:      enabled: true      gas_limit: 30000000  '0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214':    fee_recipient: '0x01234567bE214B3DaeFd350155530FCE8a85ec705'    builder:      enabled: true      gas_limit: 35000000default_config:  fee_recipient: '0x01234567c5af9B61374A128e6F85f553aF09ff89A'  builder:      enabled: true      gas_limit: 30000000

JSON example:

{  "proposer_config": {    "0x01234567155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {      "fee_recipient": "0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3",      "builder": {        "enabled": true,        "gas_limit": 30000000      }    },    "0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214": {      "fee_recipient": "0x01234567bE214B3DaeFd350155530FCE8a85ec705",      "builder": {        "enabled": false,        "gas_limit": 35000000      }    }  },  "default_config": {    "fee_recipient": "0x01234567c5af9B61374A128e6F85f553aF09ff89A"    "builder": {      "enabled": true,      "gas_limit": 30000000    }  }}

The above JSON demonstrates configuring two 1:1 mappings between validator public key:fee_recipient and a default fee_recipient. In this case, the default_config fee recipient address would apply to all validator public keys not specified in proposer_config. JSON configuration members are listed in the following table:

Member	Description
`proposer_config`	Optional. Your validator client instance’s public key. Type: Validator public key. 98 characters long hexstring. Note: Use this to map a single validator instance public key to a single fee recipient ETH address. Example: `"0x01234567155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a"`
`proposer_config.fee_recipient`	Optional. Required if validator instance public key is provided via `proposer_config`. Type: ETH address. 42 characters long hexstring. Note: Use this to map a single validator key to a single ETH fee recipient address. Example: `"0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3"`
`proposer_config.builder`	Optional. A configuration object that contains `enable` and `gas_limit` properties. Type: Object Note: Applicable only when using custom block builders.
`..builder.enabled`	Optional. Sets whether or not the validator registration is enabled or not. Type: bool Note: Applicable only when using custom block builders. Example: `true`
`..builder.gas_limit`	Optional. Sets an upper gas limit (in gwei) for block builders. Type: uint64 Note: Applicable only when using custom block builders. Block limits can only change a fixed amount per proposal - the default limit is 30M gwei. Example: `35000000`
`default_config`	Required.
`default_config.fee_recipient`	Required. Type: ETH address. 42 characters long hexstring. Note: This sets the default ETH address for all remaining validator public keys that don’t have 1:1 mapping already from the `proposer_config` member. Example: `"0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3"`
`default_config.builder`	Optional. A configuration object that contains `enable` and `gas_limit` properties. Type: Object Note: Applicable only when using custom block builders.
`..builder.enabled`	Optional. Type: bool Note: Applicable only when using custom block builders. Sets whether or not the MEV builder validator registration is enabled or not. Example: `true`
`..builder.gas_limit`	Optional. Sets a gas limit upper limit (in gwei) for block builders. Type: uint64 Note: Applicable only when using custom block builders. Block limits can only change a fixed amount per proposal - the default limit is 30M gwei. Example: `35000000`

Configuring Fee Recipient on your beacon node#

A fee recipient address can be configured on your beacon node instance by using the suggested-fee-recipient flag.

Flag	Description
`suggested-fee-recipient`	Sets a default ETH address for all validator public keys. Example: `--suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9` Note: When a fee recipient address is configured on both the validator client instance and beacon node, the validator client instance configuration will be prioritized, and the beacon node configuration will function as a fallback configuration.

Note that when configuring fee recipient on your beacon node, the beacon node will cache the fee recipient address locally.

Footnotes:

1. The Bellatrix -- Honest Validator spec contains Fee Recipient implementation details pertaining to validator clients.
2. The Bellatrix -- The Beacon Chain spec contains Fee Recipient implementation details pertaining to beacon nodes.