Designing the genesis file for a private Hyperledger Besu network starts before the first node boots
Designing the genesis file is the first hard-to-reverse decision when a consortium or regulated product stands up a private Hyperledger Besu network. Besu is an open source Ethereum execution client written in Java and licensed under Apache 2.0, and it supports private, permissioned networks using proof-of-authority consensus, either QBFT or IBFT 2.0, for enterprise and consortium environments. Every node reads the same genesis file at startup, and the values in it set the consensus rules, the initial validator set, the gas limit, the elliptic curve and any preallocated accounts or contracts. Once blocks exist, changing those values is not a configuration edit. It is a chain-level change that every operator must coordinate, so the file deserves the same scrutiny as a contract or a control design.
A design review of the genesis file is worth scheduling before any node is provisioned, and again whenever the consortium adds a member, changes its consensus choice or plans a new network. Reviewers should confirm the consensus section matches the protocol the members have agreed, that the initial validators listed in extraData are the organizations and keys that will actually operate them, and that the gas limit and per-transaction gas cap fit the workloads planned for the tokenization or settlement application. They should also confirm that every member will use the same ecCurve, because all nodes must share one curve. Ask the team which Besu release will run the network, and check its build requirements against the current Besu releases page before fixing the file.
Genesis settings and when each choice fits
This table compares the main genesis decisions for a private Besu network by what each one controls, when it fits, and how hard it is to change once the chain runs. Read it before drafting the genesis file, because several rows describe settings that a running network cannot easily reset.
| Genesis setting | What it decides | When it fits | Hard to change later |
|---|---|---|---|
| Consensus section (QBFT) | Which consensus protocol the chain runs and the parameters it uses, such as block period and epoch length | Any new permissioned network that will use proof-of-authority consensus, where QBFT is the protocol in scope | Epoch length should not be changed on a running network, because doing so after genesis can produce illegal blocks |
| Initial validators in extraData | The starting validator set, encoded as RLP with vanity data, validator addresses and seals | When the validator owners are known before go-live and each organization has agreed its operators | Replacing validators is possible through validator management, but the starting list must be encoded correctly before the first block |
| gasLimit | The block gas limit that every node applies from the first block | When transaction volume and contract sizes are estimated during design, with room for growth | Changing it later requires a planned transition, so confirm the current procedure in the Besu docs before go-live |
| alloc (accounts and contracts) | Preallocated balances, account code and initial storage written into the chain at genesis | When pre-deployed contracts, funded operator accounts or reference contracts must exist from block zero | Contract code and storage at genesis become permanent state, so a bug in preloaded code cannot be patched by editing the file |
| ecCurve (secp256k1 or secp256r1) | The elliptic curve used for signatures across the whole network | secp256k1 for Ethereum-compatible tooling and keys; secp256r1 where the organization requires that curve. Confirm tooling support first | All nodes must use the same curve, so it cannot be mixed within one network and must be settled before any node joins |
| Milestone block numbers | The block heights at which protocol rules activate, such as later hard-fork features | When the network will follow a planned upgrade schedule that all operators agree on in advance | Activation heights are fixed in the file, so every node must carry the same schedule, and late changes need coordinated upgrades |
How to build and review the genesis file step by step
This sequence takes a genesis file from governance agreement to a verified, identical file on every node before any network goes live. Each step closes with a check so that disagreements surface on a dev network, not after launch.
Agree governance and the validator set
Before anyone edits JSON, the organizations in the network agree who operates validators, who approves changes to the genesis file, and which accounts and contracts will be preallocated. Each organization confirms its validator node identities and the ownership of each key. The output is a signed decision record that lists the validator addresses, the change approvers and the rule for adding or removing validators later. You know this step is done when every organization has signed off on the same list, and nobody holds a version that differs from it.
Generate QBFT extraData from the validator list
Using the agreed validator addresses, generate the extraData value with the Besu command besu rlp encode --type=QBFT_EXTRA_DATA. The encoded value holds 32 bytes of vanity data, the initial validator list, and empty vote, round and seal fields for the genesis block. Keep the input list in source control next to the command so the result can be reproduced. The check is to decode the output, or inspect it against the agreed list, and confirm that every validator address appears exactly once and in the expected form.
Define alloc entries for accounts and contracts
Add the alloc section entries for preallocated accounts, with their balances, and for any contracts that must exist at genesis. Each contract entry needs an address, bytecode and storage key value pairs, so the bytecode should be compiled from reviewed source and checked against the artifact your developers deploy. Record the source revision and a hash of each bytecode value. Confirm the result by reading the alloc entries back and comparing each bytecode hash with the hash of the reviewed artifact.
Set ecCurve and epochLength consistently
Set the ecCurve value in the genesis config to the curve your organizations have chosen, from the options Besu supports, and confirm that every node will read the same value. Also fix the epochLength in the QBFT section before genesis, because Besu does not recommend changing it on a running network, where a change can produce illegal blocks. Review these two values with the security team, since they cannot be corrected later without a new chain. The check is a written note recording each value and the approver who accepted it.
Review the complete file as a group
Run a joint review in which each organization reads the full genesis file against the decision record from the first step. Reviewers check the consensus section, the extraData decoding, the gas limit, the chain identifier, every alloc entry and any milestone block settings. Changes found during review are made to the source inputs, not by editing the JSON by hand, and the file is regenerated. Done means the reviewers have approved one specific version, identified by its SHA-256 hash.
Test-start a dev network from the same file
Start a dev network using the exact approved genesis file, with the same Besu version each organization plans to run, and confirm that the validators produce blocks and that a test transaction settles. Check the startup logs for warnings about the genesis configuration and confirm the expected validators are sealing. Do this before any production node is started, because the results show problems that document review may miss. Keep the logs with the approved hash as evidence.
Confirm every node reports the same genesis
On each production node, before it joins the network, compute the hash of the genesis file it will use and compare it with the approved hash. Then query each node for its genesis block hash over JSON-RPC and confirm that all nodes return the same value. Any mismatch stops the launch, because nodes with different genesis blocks cannot form one chain. Record the hashes and the time of the check in the change log so the state of the network can be verified later.
Store the approved file under change control
Commit the approved genesis file, its generation inputs, the decision record and the test logs to a version-controlled repository with restricted write access. Attach a signed approval from each organization to the release tag. The stored file becomes the reference for every future node, audit and upgrade review. Confirm the repository copy matches the hash recorded in the previous step. Any later change to the genesis of a live network needs a new decision, because it cannot be applied by editing this file.
Security risks in genesis design and how to reduce them
The genesis file is read by every node and fixes the chain's starting state, so a mistake in it is shared by every organization on the network. The five risks below share one root cause: the genesis file is treated as a one-time setup artifact rather than a controlled, reviewed document that outlives the launch.
Unowned preallocated balances
The alloc section can credit accounts with a starting balance before the first block. If no one can say which organization or person controls each address, those funds have no clear owner when a key is lost or an employee leaves. Before launch, map every preallocated address to a named owner, record how that owner's key is held, and confirm that the list matches the agreed business plan for the network.
Unreviewed contract bytecode in alloc
Contracts placed in the alloc section are deployed at genesis, and their bytecode, storage and address are fixed in the file. Nobody can patch them later without a network-wide change. Treat each contract as release code: obtain the source, rebuild the bytecode with the same compiler settings, compare it with the alloc entry, and have a second engineer review the storage values before the genesis file is signed off.
Mismatched elliptic curves
Every node must use the same elliptic curve, which is set with ecCurve in the genesis config. Besu supports secp256k1 and secp256r1. If one organization builds its genesis with a different curve, its nodes cannot join the network as intended. Agree the curve in the governance documents before the genesis file is drafted, and have each participant confirm the value in its own copy before the first start.
Unencrypted node key files
The local node private key file is not encrypted in Besu. Key files often sit in the same repository, shared drive or deployment bundle as the genesis workflow, so a copy of that bundle can expose node identities. Store key files with restricted filesystem permissions and keep them out of artifacts that get shared. Where hardware-backed storage is required, the security module plugin and HSM options are covered in separate guidance.
Genesis files outside source control
When the genesis file is edited on one engineer's workstation, drift between organizations is hard to detect and impossible to audit. Keep the approved genesis file, its generated extraData and the record of who approved each change in version control, with review required before merge. Compare the hash of the file each node runs against the approved copy, so a silent local edit shows up before it affects block validation.
Who decides what when several organizations share one genesis
The network sponsor usually coordinates the consortium and decides what the shared network is for. In most arrangements this role sets the boundaries that every other party must accept, including the consensus protocol, the initial validator set and the rules for changing either. No governance structure is standard here, so the questions below are a starting agenda rather than a template.
- Consensus and chain identity: Confirm the
chainId, the QBFT consensus section and theepochlengthvalue, and who may propose changes to them. - Initial validator set: Agree which organizations hold validator seats at genesis and how the
extraDatavalidator list is generated and verified by each member. - Preallocated accounts and contracts: Agree which accounts receive balances and which contracts appear in the
allocsection, and who approved each entry. - Change rights: Ask who can authorize a new genesis or a milestone block, and whether a member can veto that change.
Check that the agreed genesis file is stored under version control with a signed record of each member's approval.
Each consortium member's platform team must confirm that the genesis file works on its own infrastructure. Every node in the network must use the same elliptic curve, set with ecCurve, so a member that standardizes on a different curve cannot join without changing the shared file. Each team should also check that the gas settings and milestone blocks match what its nodes and tooling expect.
- Curve choice: Confirm the
ecCurvevalue (secp256k1 or secp256r1) against the key tooling and HSM support each member plans to use. - Gas limit: Check the block
gasLimitagainst node sizing and the transaction workload the member expects to submit. - Milestone blocks: Confirm which fork activation blocks are set and that the member's Besu version supports them.
- Validator keys: Confirm that each validator address in
extraDatamaps to a key the member controls and can back up.
Ask each team for a written sign-off that its test nodes started from the same genesis file hash.
Security and compliance reviewers look at what the genesis file commits the network to and how the keys and contracts in it can be traced. They do not need to write the genesis file, but they should be able to see every parameter that affects trust, access and cryptographic strength. DeployOpen prepares evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors and certification bodies make those decisions.
- Cryptographic choices: Review the curve decision and whether it matches the organization's approved cryptography list.
- Preallocated balances and contracts: Ask for a list of every
allocentry with its owner, purpose and the bytecode source. - Validator ownership: Confirm which validator addresses map to which organization and how their keys are protected.
- Change record: Ask for the history of genesis changes, including who approved them and the reasons.
Request a copy of the genesis file with a reproducible hash and the review notes that accompany it.
The audit and legal function needs to know who was entitled to approve the shared genesis, what each party agreed to, and whether the record can be produced later. Since the genesis file is hard to change once blocks exist, its approval history carries weight long after go-live. Legal teams should confirm that the agreement among members covers the genesis parameters, not only the operating model.
- Approval authority: Confirm which signatories approved the genesis and whether their authority was documented.
- Scope of obligations: Check whether the agreement says who bears responsibility if a validator or preallocated account is misconfigured.
- Retention: Confirm where the signed genesis, the review notes and the hash records will be kept and for how long.
- Dispute path: Agree how a member raises an objection to a genesis parameter before the network starts.
Ask counsel to review the agreed questions list against the consortium agreement before the file is finalized.
Genesis limits to confirm in your own environment
A genesis file sets assumptions that every node and every later release must honor. The items below are the points to check against the Besu docs for your chosen version and against your own test network before the file is frozen. Several of them connect: the release you run, the consensus and curve you pick, and how you change the chain once it holds data.
Which genesis fields can change
Confirm, for the Besu version you plan to run, which genesis settings can be altered through a documented transition and which are fixed for the life of the chain. Treat the QBFT extraData, the curve and the initial alloc as fields to verify with the consensus and curve documentation rather than assume. Record the answer in the design review so that a later change is planned as a transition, not discovered during an incident.
JDK 25 for the chosen release
The Besu 26.6.0 release notes state that Besu requires JDK 25 to build and run. Confirm that the release you select, and every release you expect to adopt during the chain's life, runs on the JDK your operations team supports. A genesis that you cannot start on your standard runtime image blocks the whole network, so test the exact JDK build in the dev cluster.
Monthly release cadence and genesis reviews
Besu uses calendar version numbers and ships roughly monthly, so a genesis reviewed once can sit next to several releases within a single quarter. Make the genesis review a standing step in your upgrade process: each candidate release is checked against the current genesis file and its transition settings before it reaches validators. Ask who owns that review and how long a release may wait in the queue.
Consensus and curve interoperability
Confirm that the QBFT consensus section and the ecCurve you choose meet the needs of every party that will connect. All nodes must share one curve, and a mismatch stops peers from agreeing on the chain. If an outside system, wallet or signing service expects a particular curve, verify that before the genesis is fixed, because switching later is not a routine operation.
Genesis changes once the chain holds data
Once blocks exist, a change to the genesis file is no longer a file edit. Confirm with the Besu docs which changes are handled through milestone blocks and transitions, and which would require a new chain with state migrated by you. Agree in writing who approves such a change, how the old chain is preserved, and how nodes that missed a transition are recovered.
Genesis file questions buyers ask before hiring help
What drives the effort of designing a Besu genesis file?
The effort follows the number of decisions that must be settled before the first block, and how many organizations must agree to them. The consensus section, the initial validator set in extraData, the gas limit, preallocated accounts and contracts, the elliptic curve and any milestone blocks each need a decision and a record of why it was made. Effort rises when several organizations hold different views on validator ownership, when custom contracts must be preallocated and verified, or when the team has not yet decided which upgrades the network will follow. Effort falls when the parameters are already agreed and the work is limited to producing and checking the file. Ask any partner to break the estimate into these decision areas so you can see where the time goes.
Can an internal team design a Besu genesis file alone?
Yes, a capable internal team can write and validate a genesis file using the Besu documentation, provided it has engineers who understand QBFT, the extraData encoding and how the chain will be upgraded. The file itself is short, but the risk sits in the choices it fixes permanently. Teams that do this alone usually benefit from a written design record, a second reviewer who was not involved in drafting, and a rehearsal on a throwaway network before anything goes to a shared environment. Confirm internally who will own the file after handover, who approves changes, and whether anyone has run a QBFT network before. An outside review can cover the gaps without taking over the decisions.
What does a partner need from our side before starting?
A partner needs the decisions and the people who can make them. Expect to provide a list of participating organizations and their roles, the intended validator count and who will run each validator, the target block time and gas policy, the cryptographic curve requirement from your security team, any contracts or balances that must exist at genesis, and the upgrade policy your organization accepts. You should also provide the hosting constraints, such as cloud accounts, data centers or air-gapped networks, and the key management approach. Without these inputs, a partner can only draft options. Ask for a written list of open decisions at the start, with an owner and a due date for each.
How long does the genesis design review take?
The review length depends on governance and scope rather than on the file's size. A single-organization network with settled parameters can move quickly, while a consortium where each member must approve the validator set, the curve, the gas limit and the preallocations will need time for each organization's internal approvals. Scope also matters: custom preallocated contracts require bytecode review and storage checks, and each additional contract adds work. Ask a partner to tie the schedule to named review gates, such as parameter sign-off, a dry run on a test network and final approval, so that any delay is visible and attributable to a specific decision.
What does a fixed-scope quote for genesis design cover?
A fixed-scope quote is based on a written scope that names the decisions, the deliverables and the acceptance steps before work starts. For genesis design, a reasonable scope lists the parameters to be decided, the genesis file and its generation steps, the extraData creation process, the review of preallocated accounts and contracts, a test network run, and a design record that explains each choice. It should also state what is excluded, such as node deployment, permissioning policy or ongoing validator management. Ask the partner to show how changes requested during the review are priced, and which items would reopen the scope. DeployOpen does not publish prices, so the quote will follow from the agreed scope.
Can we change the genesis file after the network goes live?
Not in the usual sense. A genesis file defines the first block, so changing it after go-live means starting a new chain or moving to a different network with a new history. Besu also advises against changing epochLength on a running network, because doing so after genesis can produce illegal blocks. Some parameters can be changed later through supported mechanisms, such as QBFT validator management or gas limit transitions, and those paths are documented separately. Before go-live, confirm with your engineers which values are fixed for the life of the chain and which can be changed through a documented transition, and record that list in the design.
How does the genesis design affect later Besu upgrades?
The genesis file sets the starting rules that every later Besu release must honor on your chain. Besu ships calendar releases, and the release notes for recent versions include removals and behavior changes, so the parameters you choose at genesis, including the consensus type and any milestone blocks, determine which upgrade steps are possible. For example, the 26.4.0 release removed Clique consensus, so a network that began on Clique cannot simply continue with a current release. Ask your engineers to test each planned Besu version against a copy of the genesis configuration and to keep the file under source control so every operator starts from the same content.
Planning for changes after the chain is live
Some genesis-level choices cannot be edited on a running chain. The chain ID, the consensus section, the curve set in ecCurve, the preallocated accounts and the initial validators in extraData are all fixed at genesis, so a change to any of them usually means a planned transition or a new chain. Before go-live, decide which of these values you could live with for years and which you would expect to revisit. Record that list in the design document so the team knows which future changes need a transition plan and which need a new network. Besu's own documentation warns against changing epochlength on a running network, because doing so after genesis can produce illegal blocks, so treat that setting as fixed unless the QBFT docs say otherwise for your version.
Behavior around the chain can also change between Besu releases, even when the genesis is untouched. The Besu 26.4.0 release removed Clique consensus, so Besu can no longer start or produce blocks on a pure Clique network. A genesis file that still declares Clique would not give you a working node after that upgrade. The 26.10.0 release notes state that the Bonsai database auto-upgrades on first start and that older Besu versions cannot open an upgraded database, so a backup taken before the upgrade is the only rollback path. Check the release notes for every version between your current and target release, not only the latest one, and confirm the planned upgrade with the vendor or in your own environment before you schedule it.
Keep the genesis file, node configuration and permissions files under version control, with each change reviewed and tagged to the Besu version it was tested against. Then rehearse every upgrade in a dev cluster built from the same genesis and configuration as production, including a restore from the pre-upgrade backup. Ask whether your rehearsal covers a node that starts from an upgraded database, a rollback to the previous client version and a validator set change. The rehearsal result should answer one question: can the team return the network to a known state within the window your consortium has agreed. If the answer is unclear, the genesis decisions should be revisited before the chain holds production value.
How DeployOpen scopes and delivers genesis design for Besu
DeployOpen approaches the genesis file for a private Besu network as a written design decision, made before any node starts. We plan the consensus section, initial validators, gas limit, preallocated accounts and milestone blocks together, then document the values so every operator in the network can reproduce them.
How we scope
- Engagements are fixed-scope, with the genesis parameters, consensus choice and network participants agreed in writing first
- The written scope lists each genesis section we will decide, including extraData, alloc entries and the elliptic curve
- We confirm which organizations will run validators and nodes, since each must start from the identical genesis file
- Ongoing support, upgrades and continuous testing are available as retainers after handover
How we build
- We generate the QBFT extraData with the Besu encoding tool and record the validator list it contains
- We draft the genesis file in version control and review each value against the chosen Besu release
- We test the file on a non-production network, starting every node from the same genesis and checking that blocks are produced
- We review preallocated contract code and storage entries against the source and build records we are given
How we hand over
- You receive the final genesis file, a record of every non-default value and the reason behind it
- The handover notes state which parameters are fixed at genesis and which changes need a planned network transition
- We document the extraData generation steps so your team can regenerate and verify the value independently
- Runbooks cover how new nodes are started from the approved file and how the file is stored and shared
How we support
- We review any proposed genesis change with you before it reaches a running network, since some values cannot be altered later
- Support can cover the Besu upgrades that affect genesis-related settings, planned with your other operators
- We confirm with you and the Besu documentation which settings remain changeable after launch
- Retainers can include periodic checks that every node still reports the same genesis hash
