Skip to main content

Configure Fee Recipient

caution

This feature is currently in public preview and may change significantly as we receive feedback from users like you. Join our Discord server to share your feedback.

See Fee Recipient - vNext to review documentation supporting the vNext implementation of this feature.

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:

FlagDescription
suggested-fee-recipientSets 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-fileSets 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-urlA 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.

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'    gas_limit: 35000000  '0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214':    fee_recipient: '0x01234567bE214B3DaeFd350155530FCE8a85ec705'    gas_limit: 35000000default_config:  fee_recipient: '0x01234567c5af9B61374A128e6F85f553aF09ff89A'  gas_limit: 30000000

JSON example:

{  "proposer_config": {    "0x01234567155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {      "fee_recipient": "0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3",      "gas_limit": 35000000    },    "0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214": {      "fee_recipient": "0x01234567bE214B3DaeFd350155530FCE8a85ec705",      "gas_limit": 35000000    }  },  "default_config": {    "fee_recipient": "0x01234567c5af9B61374A128e6F85f553aF09ff89A"  }}

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:


MemberDescription
proposer_configOptional. 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_recipientOptional. 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.gas_limitOptional. 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
default_configRequired.
default_config.fee_recipientRequired. Sets a default fee recipient ETH address.

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.gas_limitOptional. Sets a gas limit goal (in gwei) for block builders to target.

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.

FlagDescription
suggested-fee-recipientSets 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.