Skip to main content

Configure a Fee Recipient Address

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.

Merge Testnet Users

If you're running on a Merge Testnet, use Prysm v2.1.3-rc.4 with the vNext Fee Recipient guidance, as some options have changed.


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. We recommend configuring it in both places. 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 overrides the two config options below. If you set this, the config options will be ignored.
fee-recipient-config-fileSets the local file location for the fee recipient JSON configuration.

Example: --fee-recipient-config-file=./fee_recipient_config.json

fee-recipient-config-urlSets a URL for a remote fee recipient JSON configuration.

Example: --fee-recipient-config-url=http://example.com/api/getFeeRecipient

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#

If you use either fee-recipient-config-file or fee-recipent-config-url to specify your fee recipient address, your JSON configuration should follow this schema:

{  "proposer_config": {    "0x01234567155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {      "fee_recipient": "0x012345670FCE8a85ec7055A5F8b2bE214B3DaeFd3"    },    "0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214": {      "fee_recipient": "0x01234567bE214B3DaeFd350155530FCE8a85ec705"    }  },  "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"

default_configRequired.
default_config.fee_recipientRequired.

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"

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.