Bonsai vs Forest storage: which format a private Besu node needs
If you are standing up or inheriting a private Hyperledger Besu network, the short answer is that Bonsai is the default world state format and Forest is for archive needs and the enterprise profile. Decide before go-live, because the format determines how much disk and memory each node needs and which historical queries it can answer. World state is the current balance, nonce, code and storage value for every account on the chain. Besu keeps it in a database organized as a trie, and the storage format controls how that trie is written to disk. *Bonsai Tries* stores the current state in a flat, compact layout and reconstructs older state on demand. *Forest of Tries*, which Besu also calls the FOREST format, stores each trie node by its hash, which keeps full history but uses significantly more memory.
The decision comes up at three points: when you build the first node, when you add a node that must match an existing profile, and when you change an existing node's configuration. Changing the format on a running node is not a simple restart. Treat it as a planned data migration and confirm the exact steps in the Besu documentation for your version. Bonsai also has a history limit. By default, Bonsai reconstructs historical state back 512 blocks, and the --bonsai-historical-block-limit option changes that window. Raising the limit does not change database size, but it does increase the work the node does to answer older state queries. If your applications, auditors or reconciliation jobs need state at arbitrary past blocks, plan for that need explicitly.
Before you choose, ask three questions. Do any consumers need state from blocks older than the Bonsai window? Does your organization's profile or reference design call for the ENTERPRISE (PRIVATE) settings, which expect Forest storage? And how much memory and disk can each node class take on, since Forest needs more memory than Bonsai? Ask your Besu team to confirm the historical limit, the disk growth profile and the memory baseline for your chosen format using a test network that reflects your transaction volume. Note that Besu advises against running an archive node with Bonsai, so a node meant for full historical access should be planned as a Forest node from the start.
Bonsai, Forest and the settings that change between them
This table compares Bonsai and Forest world state storage across archive suitability, memory use, configuration, pruning, and historical state queries. Read each row as a decision point: the default for most private nodes is Bonsai, while Forest matters when the enterprise profile or archive needs apply.
| Decision point | Bonsai (default) | Forest |
|---|---|---|
| Default status | Besu's default storage format, designed to reduce storage and increase read performance | Not the default; selected explicitly through the storage format setting |
| Archive node suitability | Besu advises against running an archive node with Bonsai | More suitable for archive nodes because it stores each trie node by hash |
| Memory use | Lower memory footprint than Forest | Uses significantly more memory than Bonsai, so confirm memory headroom before choosing it |
| Configuration setting | Set with --data-storage-format=BONSAI, or leave at default | Set with --data-storage-format=FOREST |
| Enterprise/private profile | Not the value the ENTERPRISE/PRIVATE profile expects | The profile documentation says to use --sync-mode=FULL and --data-storage-format=FOREST |
| Pruning | Historical state is reconstructed rather than pruned by a separate setting | Pruning with --pruning-enabled is no longer supported, so plan disk growth without it |
| Historical state queries | Reconstructs historical state back 512 blocks by default, adjustable with --bonsai-historical-block-limit | Keeps trie nodes by hash, so historical state is available without a reconstruction window |
| Effect of the historical block limit on disk | Changing --bonsai-historical-block-limit does not change database size | Not applicable, because the Bonsai limit setting does not apply |
| Upgrade and rollback | Database auto-upgrades on first start, and older Besu versions cannot open it, so back up before upgrading | Confirm the upgrade and rollback path for your release with the Besu release notes before changing formats |
How the format shapes disk, memory and historical queries
Bonsai and Forest store the same world state in different shapes, and that shape decides how disk and memory grow. Forest of Tries stores each trie node keyed by its hash, so every state change adds trie nodes that are kept as history, which makes it better suited to archive use. Bonsai uses a flat representation of account and storage values, which Besu's documentation describes as designed to reduce storage and increase read performance. In practice, Bonsai keeps the current state compact and reconstructs older state on demand within a limited window, while Forest keeps more of the trie structure around. Forest also uses significantly more memory than Bonsai, so a node that is comfortable on Bonsai can be under pressure on Forest with the same workload.
A historical query limit is a promise about how far back a node can answer state reads, and applications must be designed around it. Bonsai reconstructs historical state back 512 blocks by default, and the --bonsai-historical-block-limit option changes that window. Raising the limit does not change database size, but it does increase the work a node does to answer old-state queries. Any application that reads balances, storage slots or contract state at an older block, such as reconciliation, audit extracts or dispute checks, must either stay inside the window or use a node configured for the depth it needs. Confirm this with your application owners before go-live.
Disk growth, memory headroom and the right historical depth must be measured on your own hardware, not assumed from defaults. Ask the Besu team and your platform vendor for current guidance on expected state growth for your transaction volume, then run a representative load for your block time and contract mix and record database size, heap use and query latency at the historical depth you plan to offer. Plan for the Bonsai database to be upgraded in place on first start with newer releases, so the measurement should include a rollback backup. Treat the results as the basis for the storage format decision in the design phase, not as a general benchmark.
Which format fits which private network role
For general validator nodes and RPC nodes that serve applications, Bonsai is the recommended format. It is Besu's default, it is designed to reduce storage and improve read performance, and it fits the day-to-day workload of submitting transactions and answering current-state queries. The trade-off is that historical state is limited by design, so applications that ask about old balances or contract storage far in the past will not be served without extra work.
- Default fit: Bonsai is the format Besu uses unless you change it, so most private deployments start here with no extra storage flag.
- Historical reach: Bonsai reconstructs historical state back 512 blocks by default, which you can raise with
--bonsai-historical-block-limit. Raising the limit does not change database size, but it adds work at query time. - Archive caution: Besu advises against running an archive node with Bonsai, so do not reuse these nodes for deep history.
- Upgrade behavior: The Bonsai database upgrades automatically on first start, and older Besu versions cannot open the upgraded database, so take a backup before upgrading.
- Application expectations: Confirm with application owners how far back queries must reach before you accept the default limit.
Confirm with the platform owner which block limit each application needs and whether any RPC consumer reads historical state.
Archive or audit nodes exist to answer deep historical queries, such as reconstructing the state of an account or contract at an earlier block for a dispute or an examination. Forest is the format Besu documents for archive use. It stores each trie node by hash, which keeps full history available, but it uses significantly more memory than Bonsai. Forest pruning with --pruning-enabled is no longer supported, so disk growth must be planned rather than pruned away.
- Format choice: Use Forest on nodes whose purpose is complete historical state, and keep them separate from validator and RPC nodes.
- Memory cost: Expect higher memory requirements than Bonsai, so size these hosts with Forest in mind from the start.
- Disk growth: Pruning is not available for Forest, so model storage growth over the expected life of the chain and set retention expectations in writing.
- Separation of duties: Run audit nodes under their own access controls so that examination access does not reach validator keys.
- Restore testing: Include archive data in your backup and restore tests, since rebuilding a large Forest database is expensive.
Confirm with auditors which historical queries they need, how far back they go, and whether they accept reconstructing history from a node you operate.
The ENTERPRISE (PRIVATE) configuration profile sets the sync and storage values for private network operators who want a preset. Its documentation says to use --sync-mode=FULL and --data-storage-format=FOREST when you use that profile. This makes the profile a storage decision as well as a configuration choice, and it differs from the Bonsai default that most validator and RPC nodes use.
- Profile values: The profile expects
--sync-mode=FULLand--data-storage-format=FOREST, so nodes that follow it will use Forest storage. - Memory and disk: Plan hardware for Forest memory use and growth, not for Bonsai footprints, when you apply the profile.
- Mixed networks: If some nodes follow the profile and others run Bonsai, record which nodes use which format so that operators do not assume uniform behavior.
- Local overrides: Check how your own configuration file interacts with profile values, since explicit settings can change what the profile delivers.
- Version tracking: Re-check the profile values at each Besu upgrade, because preset values can change between releases.
Confirm with the platform owner whether the profile is required by your internal standard or chosen only for convenience, and record the reason for the format in the node design file.
How to configure and verify the storage format on a new node
This sequence sets the world state storage format and historical query window before the database is built, then confirms the running node uses the format and query behavior the network design requires. Each step ends with a check you can record as evidence.
Decide the storage format before first start
The network architect and node operator agree which format each node role will use. Bonsai is the default and suits most validator and full nodes. Forest suits archive needs and the ENTERPRISE/PRIVATE profile path. Record the decision per node role in the design document, because the format is chosen before the database exists. Done when every node role has a named format and a stated reason, signed off by the operator who will run it.
Confirm the node role and sync mode
The operator checks that the chosen format matches the node's job. Besu advises against running an archive node with Bonsai, so any node meant to serve full historical state must be planned as Forest. If the team uses the ENTERPRISE/PRIVATE profile, the profile documentation expects full sync and Forest storage, so the sync mode must be set to match. Confirm this against the Besu configuration profiles documentation before writing the file. Done when the role, sync mode and format agree on paper.
Set the storage format and sync mode in configuration
The operator adds the storage and sync settings to the node's TOML configuration file, which is version controlled with the rest of the node configuration. The key settings are data-storage-format and sync-mode, using the values confirmed in the previous step. Keep the same file for every restart so the format cannot change silently. Done when the configuration file is committed and a review confirms the two values match the design record.
Set the historical block limit if needed
Bonsai rebuilds historical state for 512 blocks by default. If applications need to query state further back, the operator sets bonsai-historical-block-limit to a higher value. The setting controls how far back state can be reconstructed and does not change the database size, so the disk estimate does not change with it. Document the chosen value and the reason, since the limit is a query window, not a retention promise. Done when the value is recorded and reviewed against the application query requirements.
Start the node on an empty data directory
The operator starts the node against an empty data directory on the volume planned for it. Starting on an empty directory means the database is built in the chosen format from block zero. If an existing database from another format is present, do not overwrite it silently. Move it aside, or stop and confirm the design with the network owner first. Done when the node logs show it syncing with the expected configuration and no startup errors.
Verify the storage format on the running node
The operator confirms the database on disk matches the configured format. Check the startup log for the storage format in use, and inspect the data directory layout, since Bonsai and Forest produce different structures. Also confirm the node is running the intended Besu release, because the Bonsai database auto-upgrades on first start and older versions cannot open it. Done when the logs and the data directory both show the intended format and the release is recorded in the runbook.
Test historical query behavior with defined checks
The operator runs queries for state at a block height inside the configured window and at one height just outside it. Inside the window, the node should return state. Outside the window on a Bonsai node, expect the query to fail or return no state. Record the results, the block heights used and the node version. An archive requirement that fails this test means the node must be rebuilt in Forest, so run the test before the node joins the production network. Done when both results are recorded and match the design.
Record disk and memory baselines
The operator captures disk and memory use after the node reaches the chain head and again after a sustained period of normal load. Forest uses significantly more memory than Bonsai, so a Forest node should be sized and monitored against that baseline. Use the Besu metrics endpoint, enabled with metrics-enabled, to feed Prometheus. Ask your infrastructure team to confirm the alert thresholds. Done when the baseline values are stored with the node record and alerts are configured.
What changes when you switch formats or upgrade an existing node
Switching the world state format on a node that already holds data is not a configuration tweak. Moving between Bonsai and Forest means the node has to rebuild its state database, so plan for a full resync and for disk space on the new format while the old data is still present. Estimate both from a test node in your own environment rather than from general expectations, and ask your client team or partner to document the sync duration and peak disk use they observed. Keep the old data directory until the new format has passed your checks, because it is your only fast path back.
The Besu 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. This changes rollback. If you start a Bonsai node on 26.10.0 and later need to return to an earlier release, the node will not simply run on the old binary. Take a backup of the data directory before the upgrade, store it on a separate volume, and confirm you can restore it on the previous release. Check whether the same constraint applies when you combine a format change with a version change, since the two steps can compound.
Run the change on a non-production node first, on the same Besu version, configuration and hardware class you plan to use in production. Record the sync time, disk growth, memory use under your real transaction load and the response times of the JSON-RPC calls your applications depend on. Then repeat the restore from backup as a drill. Only after both pass should you change the production nodes, one at a time, so that the network keeps its quorum and its read path while each node is out of service.
Operational and security considerations for node storage
Storage format is only one part of the decision. The data directory, the node key, the metrics you watch and the RPC endpoints you expose all shape how a Bonsai or Forest node behaves under load and during recovery. The cards below cover what to check before a node goes live.
Plan the data directory layout
The Bonsai or Forest database lives in the Besu data directory, and that directory is the largest and most time-consuming item to recover. Place it on a dedicated volume with capacity planned for growth under your chosen format, so that it can be snapshotted, resized and restored without touching the operating system. Confirm with your storage team how the volume is provisioned, expanded and monitored. Keep the data directory separate from the node key and configuration files.
Back up before every format-changing upgrade
The Besu 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. A rollback therefore depends on a backup taken before the upgrade, not on reinstalling the previous binary. Test the restore path on a non-production node so the procedure is proven before you need it. Record which Besu version created each backup.
Treat the node key as sensitive
Besu documentation states that the local node private key file is not encrypted. Restrict file permissions to the Besu service account, keep the key out of the data directory backups that leave your control, and document who can read it. Where your policy requires hardware-backed keys, the --security-module option can point Besu at a security module plugin such as the Besu HSM plugin. Confirm plugin support for your Besu version and HSM before you commit to that design.
Watch disk and memory through Prometheus
Besu exposes metrics for Prometheus with the --metrics-enabled option, and the default endpoint port is 9545. Build alerts on disk growth, free space on the data volume and memory use, since Forest needs significantly more memory than Bonsai. Compare the trend after each change of storage format or historical block limit. Confirm which metrics your monitoring stack needs and set thresholds from your own baseline rather than from vendor defaults.
Restrict access to JSON-RPC endpoints
Besu does not terminate HTTPS natively, so transport security for JSON-RPC has to come from a reverse proxy, gateway or load balancer in front of the node. Authentication is available through a username and password credentials file or through externally issued JWTs validated against a public key. Keep the RPC port off public networks, limit which interfaces listen, and confirm that the proxy in front of each node enforces TLS and the same access policy your identity team has approved.
Questions teams ask before choosing Bonsai or Forest
Which storage format does Besu use by default?
Bonsai Tries is Besu's default world state storage format. It is designed to reduce storage use and increase read performance compared with the older approach. Unless you have a specific reason to choose otherwise, a private network node starts on Bonsai. Check the storage format your Besu version uses by default in the Besu data storage formats documentation before you write your configuration, because defaults and related flags change between releases.
Can an archive node run on Bonsai?
Besu advises against running an archive node with Bonsai. Archive nodes keep historical state for every block, and that use case fits Forest better. Forest stores each trie node by its hash and is more suitable for archive nodes, but it uses significantly more memory than Bonsai. Forest pruning with the --pruning-enabled option is no longer supported, so an archive decision also means accepting full historical storage on Forest. Confirm your retention and query requirements before you choose a node role.
What drives memory and disk cost in each format?
Three factors drive the cost. The first is the storage format itself: Forest uses significantly more memory than Bonsai, and archive use grows the database over time. The second is node role, since validators, RPC nodes and archive nodes have different disk and memory profiles. The third is historical query depth. Bonsai reconstructs historical state back 512 blocks by default, adjustable with --bonsai-historical-block-limit, and that setting does not change database size, so raising it affects query reach rather than storage footprint. Benchmark your own transaction volume on a test network before sizing hardware.
Can we change the storage format after the node is running?
Changing the format means resyncing or rebuilding the node's data, so plan it as a maintenance change rather than a setting edit. Besu's Bonsai database auto-upgrades on first start, and older Besu versions cannot open an upgraded database. Take a backup of the data directory before any format or version change so you can roll back. The effort depends on chain length, node count and whether other nodes can serve the sync. Ask your team or partner to test the change on a non-production node first.
Does the ENTERPRISE profile force a storage format?
Yes, for the ENTERPRISE (PRIVATE) profile. The Besu configuration profiles documentation says to set --sync-mode=FULL and --data-storage-format=FOREST when using that profile. That choice favors archive-style history over the lower footprint of Bonsai. If your organization needs the profile's other settings but not Forest, review how profile values interact with your own configuration file before you start the node, since the two sources can conflict.
Can our own team make this decision without outside help?
Often yes, if you have engineers who can run Besu nodes, test a configuration and read release notes. The decision itself rests on four inputs: whether you need archive history, how much historical query depth applications require, your memory and disk budget, and your upgrade rhythm. Besu ships roughly monthly and the Bonsai database may auto-upgrade on start, so the team must own backup and rollback. A partner can help when the team lacks time to benchmark, document the choice for auditors, or build the test and restore procedure.
What would a partner do for the storage decision?
A partner would typically start with a written scope that covers node roles, retention and query requirements, and the target infrastructure. The work usually includes a comparison of Bonsai and Forest against those requirements, a test network to measure memory and disk behavior, configuration with the chosen format and historical block limit, backup and restore steps before any upgrade, and documentation that the operating team can maintain. Ask for these items to be named in a quote, along with who tests restores and what evidence is delivered.
Where DeployOpen helps with storage decisions on private networks
A fixed-scope engagement treats the storage format as one decision inside node design, not as a standalone setting. DeployOpen plans the choice of Bonsai or Forest for each node role in the network, then carries it through the configuration files, the sync mode and the backup and upgrade plans that depend on it. The deliverables are agreed in writing before work starts, so the storage decision, its reasoning and the settings it implies are recorded in the same document as the rest of the node design. Outcomes such as disk use or query speed depend on your hardware and workload, so the plan sets out what will be measured and how, rather than promising a figure.
To scope the work, DeployOpen needs specific inputs from your team. List each node role you intend to run (validator, RPC, archive or auditor-facing node) and the historical queries each role must answer. State your retention requirements for ledger and state data, including how far back a regulator or internal auditor may ask you to reconstruct state. Share your infrastructure details: disk types, memory per node, backup targets and the Kubernetes or virtual machine platform, if any. Also confirm which auditor requirements apply, because they determine whether historical state must be available on the node or can be obtained another way.
The plan also records which Besu version and profile values your nodes will run, since the upgrade path and the rollback steps depend on them. Because the Besu 26.10.0 release notes state that the Bonsai database auto-upgrades on first start and older versions cannot open it, the backup taken before any upgrade is part of the storage design. Confirm the current release and its requirements with the Besu releases page and your own change process before the plan is signed off.
How DeployOpen scopes and delivers Besu storage work
DeployOpen starts Bonsai vs Forest storage work with a written scope that matches each node's role to a storage format, then builds and tests the nodes inside your own infrastructure. The result is a documented configuration, a tested upgrade and rollback path, and a handover your operators can run without us.
How we scope
- Each node role is mapped to Bonsai or Forest, with the historical query needs written down first
- The written scope lists disk and memory assumptions to confirm against your own hardware and data volumes
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
- Scope names which Besu version and database upgrade behavior your team must accept before go-live
How we build
- Node configuration is built around Bonsai as the default, with any Forest nodes isolated and documented
- Historical block limit and sync settings are set per node and tested against the agreed query needs
- Backups are taken before any storage format change, so rollback to an older Besu version is possible
- Disk growth and memory use are measured under a test load in your environment before sign-off
How we hand over
- Documentation records each node's storage format, profile settings and the reason for each choice
- Runbooks cover the Bonsai auto-upgrade on first start and the backup needed before any upgrade
- Your operators walk through a restore and an upgrade rehearsal so the steps are known before production
- Handover includes a list of open items, such as settings to reconfirm after each Besu release
How we support
- Ongoing support, upgrades and monitoring of storage growth are available as a retainer
- Support reviews each new Besu release for changes to storage formats, profiles and removed options
- Storage alerts for disk and memory thresholds are set up with your existing monitoring stack
- Retainer scope and response expectations are agreed in writing, with no price list published
