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, convert LevelDB data to RocksDB, move selected logical databases to configured storage volumes, 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.

⚠️

Run database maintenance offline

Before running any Toolkit command against a node database, stop the node and confirm that the process has exited. Back up the source data, run the command against the stopped data directory or a verified copy, and restart the node only after the operation completes successfully. Do not run these commands against a database that the node is still writing.

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 an offline 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 storage.balance.history.lookup = 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 db convert on x86 when you need to migrate an existing LevelDB database to RocksDB. The Toolkit does not support converting RocksDB data back to LevelDB.

⚠️

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, set storage.db.engine in config.conf (the db.engine key inside the storage { ... } block) to ROCKSDB before restarting.

Database relocation

Run this operation with java -jar Toolkit.jar db mv ... while the node is stopped.

Use when you need to:

• Place selected logical databases on different volumes (for example, move block or transactionHistoryStore to a lower-cost disk).
• 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