Skip to main content

Configure Fee Recipient

Configure this or lose money

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

Fee Recipient is a feature that lets you specify a priority fee recipient address on your validator client instance and beacon node.

Your fee recipient wallet address is a standard Ethereum wallet address, just like the wallet address used when sending and receiving tokens from MetaMask. Execution clients deposit 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 pay priority fees to incentivize block proposers to prioritize the inclusion of particular transactions in the blocks that they propose.

Priority fees are captured by execution clients in the execution layer [1], so validator clients need to tell execution clients where to forward the fees. This "forwarding address" is referred to as your fee recipient wallet address.

Configure fee recipient​

Your fee recipient wallet address can be configured on your validator client instance and on your beacon node. We recommend configuring it in both places. Your validator's configuration will override the beacon node configuration, while the beacon node configuration will be treated like a backup in the event that your validator configuration fails.

Configure fee recipient via flags​

Your fee recipient wallet address can be configured on both your beacon node and validator through the --suggested-fee-recipient flag:

Beacon node:

./prysm.sh beacon-chain --suggested-fee-recipient=<WALLET ADDRESS>

Validator client:

./prysm.sh validator --suggested-fee-recipient=<WALLET ADDRESS>

For example:

./prysm.sh validator --suggested-fee-recipient=0xCHANGEME012345c769F504hs287200aF50400a

If your validator is running multiple keys (for example, staking 64 ETH using two validator public keys that have been imported into a single validator client instance), all validator public keys will use the wallet address specified through the --suggested-fee-recipient flag. You can optionally associate different fee recipient wallet addresses to individual validator public keys using the JSON/YAML configuration method detailed in the following section.

Configure fee recipient via JSON/YAML (validator client only)​

You can assign different wallet addresses to each validator public key using a JSON/YAML configuration. Fee recipient address assignments specified through JSON/YAML override those configured through the --suggested-fee-recipient flag. This JSON/YAML file is called the proposer settings file — fee recipient is one of several per-validator preferences it can carry (gas limit, graffiti, and builder configuration are the others). This page covers the fee recipient fields; see Proposer settings for the complete reference, including the version 2 schema used for Gloas builder configuration.

The configuration uses the following JSON/YAML schema:

{
  "proposer_config": {
    "<VALIDATOR PUBLIC KEY>": {
      "fee_recipient": "<WALLET ADDRESS>"
    },
    "<VALIDATOR PUBLIC KEY>": {
      "fee_recipient": "<WALLET ADDRESS>"
    }
  },
  "default_config": {
    "fee_recipient": "<WALLET ADDRESS>"
  }
}

Property definitions are as follows:

  • proposer_config: An object containing key-value pairs, where member keys are validator public keys.
  • <VALIDATOR PUBLIC KEY>: A validator public key (98 characters long - not a wallet address) used as a JSON property key. Example: 0x0123456748ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a057816155ad77931185101128655c0191bd0214.
  • fee_recipient: A fee recipient wallet address. Example: 0x52FfeB84540173B15eEC5a486FdB5c769F50400a.
  • default_config: An object containing a default fee recipient wallet address. Validator public keys not specified in proposer_config will use this wallet address.

The above example 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, and will override any wallet address specified by the --suggested-fee-recipient flag.

Tell your validator to use the JSON/YAML configuration through one of the following flags:

  • proposer-settings-file: Points to a local JSON/YAML file.
  • proposer-settings-url: Points to a remote JSON/YAML configuration endpoint in URL format. 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

The rest of the proposer settings file​

The same file carries the other per-validator preferences — a gas limit, graffiti, and builder configuration — and the fields nest alongside fee_recipient:

"<VALIDATOR PUBLIC KEY>": {
  "fee_recipient": "<WALLET ADDRESS>",
  "gas_limit": "60000000",
  "graffiti": "<GRAFFITI STRING>",
  "builder": { "builders": [ { "url": "<BUILDER URL>" } ] }
}

Those fields are documented in full on the Proposer settings page, which is the reference for the whole schema:

  • gas_limit — leave it unset to follow the network's scheduled gas limit; setting it opts the key out of that schedule.
  • builder — which builders the key requests bids from, and on what terms. Read Trusting builders before setting max_execution_payment.
  • Migrating from v1 to v2 — what to do with the legacy enabled and builder-level gas_limit fields before the Gloas fork.

Frequently asked questions​

How do I know if fee recipient was properly configured?​

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

What happened to fee-recipient-config-file?​

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 as of Prysm v2.1.3.

How do I ensure that builders receive my fee recipient wallet address?​

Before the Gloas fork, builders learn your fee recipient through MEV-Boost validator registration: with --enable-builder set (or a non-empty builders list in v2 proposer settings), your validator registers periodically using the fee recipient from the flag or JSON/YAML configuration. After the Gloas fork, your fee recipient is enforced directly—builder bids that don't name your configured fee recipient are rejected before your validator uses them.

When should I set my own gas_limit, and how do I know what to set?​

Most users should not set one. When gas_limit is unset, your validator follows the network's scheduled gas limit (EIP-8261), and falls back to the chain default shipped in your Prysm release when no schedule entry is active. Etherscan's gas limit chart shows what mainnet is running today. Setting an explicit value opts the key out of the schedule — see Proposer settings for the details and the warnings Prysm logs.

Footnotes:

1. See Nodes and networksfor a quick refresher on the fundamentals of Ethereum nodes.