Setting the Besu block gas limit and transaction gas cap before go-live
The consortium or private network team that fixes gas settings before launch needs to decide two numbers early. The block gasLimit caps the total gas that all transactions in one block can consume, and the per-transaction cap, set through the QBFT pertxgaslimit option, caps how much gas any single transaction may request. Together they decide how large a transaction can be, how many transactions fit in a block, and how much work each validator must do before the next block arrives.
The genesis gasLimit bounds everything else. A positive pertxgaslimit value must not exceed it, and Besu validates this at startup, so a mismatch stops the node rather than failing later. When pertxgaslimit is omitted, Besu applies the EIP-7825 default of 16777216. Setting it to 0 disables the cap entirely. Teams should confirm which behavior they want in writing before go-live, because the default is not the same as having no limit at all.
Teams should tune these values rather than accept defaults when their workloads include large contract deployments, batch settlement transactions or heavy onchain computation, or when their validators are modest hardware and block time matters more than transaction size. The Besu free gas guide suggests choosing a gasLimit close to what validators can process within the configured block time when on-time blocks matter more than large transactions. Confirm validator throughput with your own measurements on the hardware you will run before picking a number.
Which gas decisions the network team must make
Gas settings in a private Besu network are not one switch. They set how much work fits in a block, how large a single transaction may be, and what applications can expect, so the decisions below need to be made together before genesis is written.
Block gas limit in genesis
The gasLimit in the genesis file caps total gas per block and is set when the chain starts. Besu's free gas guidance suggests a value near what validators can process within the configured block time when on-time blocks matter more than large transactions. Confirm the value with a load test on your validator hardware before go-live, since changing it later requires a planned transition.
Per-transaction gas cap
The QBFT pertxgaslimit option limits how much gas one transaction may use. If it is omitted, the EIP-7825 default of 16777216 applies, 0 disables the cap, and a positive value must not exceed the genesis gasLimit. Decide whether the cap should protect block production from oversized transactions or whether your applications need more headroom.
Expected transaction sizes
Measure the gas each application call consumes, including contract deployments and batch operations, before choosing either limit. A tokenization or settlement workflow that bundles many transfers into one call needs a different ceiling than simple payments. Ask each application team for worst-case gas figures and test them against the chosen cap.
On-time blocks or large transactions
A higher gas limit lets validators include bigger transactions, but each block takes longer to execute and propagate. If settlement finality depends on blocks arriving on schedule, favor a lower limit that validators comfortably process within the block time. If some workloads need large transactions, accept longer blocks and test the trade-off under load.
Hardware headroom across validators
Every validator must process the same blocks, so the slowest validator sets the practical limit. Confirm CPU, memory and disk capacity on each validator and RPC node, and measure execution time with Prometheus metrics on realistic transaction mixes. Re-test whenever hardware, Besu version or block time changes.
Change path and governance
Both values can be changed on a running QBFT network with a transitions entry at a future block, but all nodes must be stopped and restarted. Agree who approves a change, how the new block number is chosen, and how each organization in a consortium confirms its node config matches. Write the procedure down before the first production block.
Gas limit and cap options and when each fits
This table compares the four ways to set the per-transaction gas cap and block gas limit on a private QBFT network: keep the default, set a lower positive value, disable the cap, or tune the block gas limit to validator throughput. Read each row for the fit, the trade-off and what your team must verify before choosing it. The main takeaway is that the cap is a network-wide setting that must stay within the genesis gas limit, so decide it before go-live.
| Option | Fit | Trade-off | What to verify |
|---|---|---|---|
| Keep the EIP-7825 default cap | Networks that want Ethereum-aligned transaction limits and no custom tuning | Large transactions above the default are rejected, which may block some contract deployments or batch operations | Confirm your largest expected transaction fits the default and that no tooling sets a higher gas limit |
| Set a positive pertxgaslimit below the genesis gasLimit | Networks that want a stricter ceiling than the default while keeping a cap in place | A value set too close to the block limit can make large transactions hard to fit in a block; the value must not exceed the genesis gasLimit | Confirm the value is at or below the genesis gasLimit (Besu validates this at startup) and test your heaviest transactions against it |
| Set pertxgaslimit to 0 to disable the cap | Networks where the operator controls all submitted transactions and needs no per-transaction ceiling | Any transaction can request up to the block gas limit, so one transaction may consume a large share of a block and crowd out others | Confirm all submitting applications are trusted, rate and fee policies are in place, and the block gasLimit is sized for your validators |
| Free gas style gasLimit tuned to validator throughput | Networks where blocks arriving on time matters more than large transactions, such as settlement workloads with predictable transaction sizes | A lower gasLimit limits how much work each block carries, so bursts of activity wait longer or are dropped from the next block | Measure how much work your validators process within the configured block time in a test cluster before setting the gasLimit |
| Changing the cap on a running network | Networks that start with one cap and later need a different value | Requires a transitions entry at a future block and a stop and restart of all nodes, so it is a coordinated change | Agree the activation block with all operators, confirm every node runs the same configuration and rehearse the change in a non-production network |
How to configure gas limits in a QBFT genesis and verify them
This sequence turns the gas decisions into tested genesis and consensus settings, with a check at each stage so the chosen block gas limit and per-transaction cap are proven before the network carries real workloads.
Gather transaction size requirements from application owners
Ask each application owner for the largest transactions their contracts will send, including contract deployments, batch settlement calls and any bulk writes, and how often those transactions occur. Application owners and the network team own this step together. It is done when every workload has a documented estimate of gas per transaction and a stated maximum, so the team can compare those figures against the block gas limit you plan to set. Ask whether any use case needs large transactions and whether blocks must arrive on time more than large transactions must fit, since Besu's free gas guidance treats that trade-off as the main decision.
Set the genesis gas limit and block time
Choose the gasLimit in the genesis file and confirm the block period in the QBFT consensus section, since both determine how much work validators must process per block. The network architect makes this change and records the reasoning next to the file. Besu's free gas documentation suggests a gas limit near what validators can process within the configured block time when on-time blocks matter more than large transactions. Done when the genesis file parses, the gasLimit value is written as a hex value, and a written note links the value to the sizing evidence from the previous step. Confirm the exact field names and value formats against the QBFT documentation for your Besu version.
Set the QBFT per-transaction gas cap
In the QBFT section of the genesis file, set pertxgaslimit to the cap you want. If the key is omitted, Besu applies the EIP-7825 default of 16777216. A value of 0 disables the cap, and a positive value must not exceed the genesis gasLimit. The network architect makes this choice with the application owners, who confirm that the largest expected transaction fits within the cap. Done when the chosen value is written explicitly in the file, so the decision is visible in review rather than left to the default, and the team has noted whether the cap is the default, a custom positive value or disabled.
Confirm Besu validates the cap at startup
Start a single validator on a throwaway copy of the genesis file with the chosen values, then deliberately test a pertxgaslimit larger than the genesis gasLimit in a second copy. The platform engineer runs both starts and reads the logs. Besu validates a positive cap against the genesis gasLimit at startup, so the oversized copy should fail to start while the valid copy should run. Done when the valid configuration starts cleanly and the invalid one is rejected with a clear error, which proves the check works in the version you will run. Repeat this check after any version upgrade.
Run load tests on a dev network sized like production
Build a development network with the same consensus settings, validator count, node roles and hardware class as production, then submit transactions at the sizes and rates the application owners described. The test team measures whether blocks arrive within the configured block time, how full blocks get, and whether large transactions are accepted or rejected at the cap. Done when the results show the chosen gas limit and cap handle the expected peak load, and any transaction that exceeds the cap is rejected in the way the application team expects. If the dev network is smaller than production, the results only partly predict production, so record that limit in the test report.
Record the chosen values under source control
Commit the final genesis file, the node configuration and a short decision record to the repository that holds your network configuration. The network owner approves the change through the normal review process. Record the gas limit, pertxgaslimit value, block time, the tests that justified them and the Besu version used. Done when the repository holds a tagged version of these files, the team can rebuild the genesis from the repository, and the decision record names the test results that support each value. Note that changing either value later on an existing QBFT network requires a transitions entry at a future block and a stop and restart of all nodes, so this record is the baseline for any future change.
How to change the transaction cap on a running QBFT network
On an existing QBFT network, the per-transaction gas cap can be changed by adding a transitions entry that sets a new pertxgaslimit at a future block. The change is not a live setting. All nodes must be stopped and restarted as part of the rollout, so every operator needs the same transitions block in its configuration before the target block is reached. Plan the change as a coordinated maintenance event, not as a configuration tweak on one node.
The target block is a shared decision. Every validator must agree on the block number, confirm the current chain height, and confirm that its node will be restarted with the updated file before that height is reached. If one operator restarts late or with a stale file, its node can disagree with the rest of the validator set at the transition. Agree the window, the rollback contact and the person who verifies the new value on each node in writing before anyone edits a file. The Besu QBFT documentation sets out the transition syntax and should be the reference your change record cites.
The genesis gasLimit cannot be changed this way. The transitions mechanism covers the per-transaction cap, while the block gas limit is set in the genesis file that every node loaded at first start. Raising or lowering the block limit on a live chain is a separate decision with its own effect on block size and validator load, and it should be planned together with the genesis and upgrade decisions covered elsewhere on this page. Confirm with your Besu version which fields are accepted in transitions before you write the change, and test the entry on a development network first.
Operational risks when gas settings are wrong
Gas settings touch every node, every application and every operator at once, so a mistake rarely stays local. The risks below connect block gas limit, the per-transaction cap and the transition process, and each one names a check to run before go-live and before any change.
Oversized transactions slow validators
A block gas limit set high lets very large transactions into a block, and every validator must execute them within the configured block time. Check the gasLimit against what your validator hardware can process in that block time, using measurements from your own test network rather than assumptions. The free gas guide ties a sensible limit to that processing capacity, so treat it as the starting test.
Caps that reject legitimate calls
A per-transaction cap set too low causes application calls that run fine on a development chain to fail in production, often with errors that look like application bugs. Contract teams should measure gas use for their heaviest functions, including deployments, before fixing the cap. Confirm the cap with the application owners and document the figure they agreed to.
Inconsistent settings across operators
When operators in a consortium set different values in their genesis or node configuration, nodes can disagree about which transactions are valid, which blocks to accept and when to stop producing. Keep the genesis and the pertxgaslimit under version control, and have every operator confirm the same file hash before the network starts.
Missed restarts during a transition
A change to the per-transaction cap made through a transitions entry takes effect only after all nodes are stopped and restarted. An operator who skips a node leaves that node enforcing the old rule while others enforce the new one. Build a restart checklist that lists every validator and RPC node, and confirm each node reports the expected configuration after restart.
Loss of visibility into gas use
Without block and transaction metrics in Prometheus, teams cannot see whether blocks approach the gasLimit or whether transactions are being rejected for gas reasons. Enable metrics with --metrics-enabled, set dashboards for block gas use and transaction outcomes, and set alerts before the network carries production traffic so that a bad setting shows up early.
Questions buyers ask about gas limit work on Besu
What does a gas limit review cost and what drives the price?
The price depends on the written scope, not on a standard rate. The main cost components are the time spent profiling real transaction types, building and running load tests against your validator hardware, and coordinating any transition with each organization that runs a node. Costs rise when the network has many contract types with very different gas profiles, when validators are spread across several organizations, or when the change must be rehearsed in a non-production cluster first. Costs fall when transaction data already exists and the change window is defined. Ask for a quote that separates profiling, testing, transition planning and post-change verification, and states which parts recur. A gas review is usually one-time, while any later re-tuning is a new scope.
How long does a gas limit review take?
Duration is set by how many transaction types you must profile, how many validators must be tested, and how many organizations must agree on the transition block. A single-organization network with a small set of known contracts usually moves faster than a consortium where each member runs its own nodes and approves changes through its own change process. Lead time for hardware, test environments and change windows often matters more than the analysis itself. DeployOpen fixes the timeline in the written scope before work starts, so ask for the milestones, the dependencies on your teams and the approval steps that sit outside the engagement.
What must our team provide before a gas review starts?
The team needs to supply the inputs that determine the result. Typically that includes a sample or export of real transaction profiles with their gas use, the hardware and configured block time of every validator, the current genesis gasLimit and any QBFT transitions already in place, and the list of applications and organizations that submit transactions. You will also need a named owner for each validator, access to a non-production network for load tests, and change windows agreed with every party that must restart nodes. Missing transaction data is the most common reason a review stalls, so confirm what your team can export before you ask for a quote.
Can our internal team set the gas limit without outside help?
Yes, an experienced Besu operations team can change gasLimit and pertxgaslimit on its own network, provided it can measure transaction gas use, test the result under realistic load and coordinate restarts. The harder part is usually the analysis and the coordination. Teams often underestimate the effect of a larger gas limit on validator block processing, and they overlook that a per-transaction cap cannot exceed the genesis gasLimit. Consider an outside review if the team has not profiled its workload, if the network has several operators, or if a failed change would stop a production service. Your team can keep ownership of execution while the review checks the numbers.
What risks come with changing the gas limit on a live network?
The main risks are blocks that validators cannot process within the configured block time, transactions that are rejected or stuck because they exceed the per-transaction cap, and nodes that fail to restart with a configuration that no longer matches their peers. Changing the per-transaction cap on an existing QBFT network requires a transitions entry at a future block, and every node must be stopped and restarted with the change. Operators that miss the window can fork away from the rest of the network. A rehearsed plan, a rollback path and a clear go or no-go decision from every operator reduce these risks.
How do we request a fixed-scope quote for gas limit work?
Send a short written brief that names the network, the Besu version in use, the consensus protocol, the number of validators and organizations, and the transaction types you need profiled. State the outcome you want, such as a gas limit and per-transaction cap with tested evidence, and list what you can provide from the section above. Ask for the scope, deliverables, assumptions, your responsibilities, the timeline and the exclusions in writing. A fixed-scope quote follows from that written scope, so the more precise the brief, the more precise the quote.
Does a gas review also cover compliance evidence for auditors?
A gas review produces engineering evidence: the chosen values, the profiling data, the load test results, the transition record and the rollback plan. That evidence can support a compliance assessment, but DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations. Ask your assessor early which records they expect for configuration changes, and confirm that the change process in your organization will retain them.
How to confirm gas settings hold in production
Start with Besu's own metrics, not with the transaction failures users report. Run each node with the --metrics-enabled option so it exposes metrics for Prometheus, which listens on the default endpoint port 9545 unless you change it. Scrape every validator and RPC node, not only one, because a cap that is correct on one node and different on another will show up as inconsistent block production. Besu's documentation also describes a sample Grafana dashboard you can import as a starting point. Confirm the metric names and dashboard panels against the version you run, since they change between releases, and check the Besu metrics documentation before you write alerts against them.
Track three things together. First, block fullness: how much of the gasLimit each block uses over a rolling window. Blocks that are consistently near the limit mean demand is pressing on the ceiling, and the gasLimit or the per-transaction cap may need to rise. Second, block timing: whether blocks arrive at the configured block time, because a gasLimit set too high for validator hardware can slow block production, and that shows up as late blocks before it shows up as failures. Third, transaction rejections in the node logs and in the responses your applications receive, separated by cause. A transaction rejected for exceeding the per-transaction cap is a different signal from one rejected because it cannot fit in the remaining block space, and each points to a different change.
Set a baseline before go-live and review it after the first weeks of real traffic, then set alerts on sustained changes rather than single blocks. Record the values the network runs with, including the genesis gasLimit and the pertxgaslimit value, in the same change record as the genesis file. Any change to either setting should trigger a fresh baseline, because the transition steps described above change the rules at a future block and your dashboards must show the switch. Ask your monitoring team to confirm which rejection messages their logging pipeline captures, since an unparsed rejection looks like a healthy network until a user complains.
How DeployOpen works on this
DeployOpen scopes the block gas limit and per-transaction gas cap as part of the network design, before genesis is written, and then delivers the configuration as a documented, tested change. Engagements are fixed-scope, with the gas settings, test plan and transition steps agreed in writing before work starts.
How we scope
- Document the expected transaction mix, including contract deployments and large batch transactions, against the block time you plan to run.
- Agree in writing whether the genesis gasLimit and pertxgaslimit are set for a new network or changed on an existing one.
- Confirm the block time, validator hardware and monitoring thresholds that the gas settings must fit within.
How we build
- Write the genesis and node configuration files under source control, with the gas values reviewed alongside consensus settings.
- Test the chosen gas limits on a dev cluster with representative transactions, including ones near the per-transaction cap.
- Prepare a transitions entry for a future block when the cap must change, and rehearse the stop and restart sequence on all nodes.
How we hand over
- Deliver a runbook that records each gas value, why it was chosen, and the Besu version it was tested against.
- Provide validation evidence showing startup checks passed and sample transactions behaved as expected on each node.
- Walk operators through how to read block fullness metrics and when to revisit the gas limit.
How we support
- Offer ongoing support and upgrade work as a retainer, covering gas settings through each Besu release.
- Re-check gas assumptions when the application's transaction profile or validator hardware changes.
- Plan any future gas cap change as a scheduled transition, with a rollback and communication plan for every operator.
