Node maintenance toolkit

📘

Prerequisites

• Deploy a node
• Database snapshots

The Toolkit is a bundle of database-maintenance utilities shipped alongside FullNode.jar. It lets you reshape a node's on-disk state without rebuilding from genesis: prune to a Lite Fullnode snapshot, copy data between volumes, switch storage engines, partition a single database into pieces, or apply LevelDB startup tuning.

Each utility is invoked as a sub-command of Toolkit.jar. Run with -h for the full option list of any sub-command.

Available utilities

For step-by-step CLI usage of each utility — flags, examples, and edge cases — see the Toolkit User Guide.

When to use each utility

Lite Fullnode pruning

Use when you need to:

• Generate a Lite Fullnode snapshot from a running Fullnode database (so you can deploy a new Lite Fullnode without re-syncing).
• Re-prune an existing Lite Fullnode to reclaim disk space — recommended on a periodic cadence (monthly is common) since a Lite Fullnode accumulates data at the same rate as a Fullnode after startup.

java -jar Toolkit.jar db lite -o split -t snapshot -fn /path/to/output-directory -ds /path/to/snapshot

GreatVoyage-v4.8.2 adds --exclude-historical-balance, which excludes balance-trace and account-trace when generating a snapshot to reduce its size:

java -jar Toolkit.jar db lite -o split -t snapshot \
  -fn /path/to/output-directory -ds /path/to/snapshot \
  --exclude-historical-balance

This option only has an effect when the source Fullnode has run with historyBalanceLookup = true. After these databases are excluded, the resulting Lite Fullnode cannot reliably serve historical balance queries, and a later merge does not restore the excluded data. Do not enable this option if you need historical balance queries through getBlockBalance or getAccountBalance.

See Lite Fullnode for what gets included in the snapshot and how the 65,536-block window is chosen.

Keystore management

Before GreatVoyage-v4.8.2, FullNode.jar --keystore-factory opened an interactive keystore manager whose main operations were GenKeystore and ImportPrivateKey. Starting with GreatVoyage-v4.8.2, these functions are integrated into Toolkit.jar: GenKeystore corresponds to keystore new, and ImportPrivateKey corresponds to keystore import. The Toolkit also adds keystore list and keystore update. --keystore-factory remains available for compatibility, but displays a deprecation warning and is planned for removal in a future release. Use the Toolkit.jar keystore command group for new operations and gradually update scripts or workflows that depend on the legacy entry point.

Basic usage:

java -jar Toolkit.jar keystore new
java -jar Toolkit.jar keystore import
java -jar Toolkit.jar keystore list
java -jar Toolkit.jar keystore update <address>

The default keystore directory is Wallet under the current working directory; use --keystore-dir to select another directory. keystore new and keystore import can read a password from --password-file. For keystore update, that file must contain the current password on the first line and the new password on the second line. keystore import can also read a private key from --key-file. Apply strict file permissions to files containing passwords or private keys, never commit them to a repository, and securely remove them after use.

⚠️

keystore list validation scope

keystore list only reads the address declared in each file; it does not decrypt the keystore or verify that the address matches the private key. Do not trust keystore files from unknown sources. The address-to-private-key relationship is validated only when the keystore is decrypted and loaded.

Data copy

Use when you need to:

• Move a node's database to faster storage without restarting from genesis.
• Restore a backup onto a fresh machine.
• Stage a node alongside a running one (then promote by swapping directories).

The Toolkit's copy implementation handles LevelDB / RocksDB internals correctly and is significantly faster than cp -r on large datasets.

Data conversion (LevelDB ↔ RocksDB)

Use when you need to switch storage engines on an existing node — for example, migrating to RocksDB for better random-read performance or to LevelDB for compatibility with a snapshot mirror that only publishes one engine.

⚠️

Safe database conversion

Always run conversion on a stopped node and against a copy of the original database. Engine conversion is not in-place.

After conversion, update db.engine in config.conf to match the new engine before restarting.

Database partitioning

Use when you need to:

• Spread a database across multiple volumes (e.g., separate hot data from cold data).
• Reduce I/O contention on a single disk.
• Match a specific filesystem or RAID layout for performance.

For the partition layout file format and shard placement, see the Toolkit User Guide.

LevelDB startup optimization

Use when:

• You restart the node frequently (development / staging).
• You're seeing long startup times caused by LevelDB compaction or recovery passes.

The optimization tool pre-organizes LevelDB metadata so the engine starts faster on the next launch.

Related resources

• Toolkit User Guide — Authoritative CLI reference with examples
• Database snapshots — Pre-built snapshots from public mirrors
• Lite Fullnode — When to choose a Lite Fullnode over a Fullnode
• Deploy a node — End-to-end deployment workflow