Genesis Configuration
The Agave genesis choices used for a private development cluster, with their operational consequences.
Genesis is the initial ledger and configuration from which a Solana cluster derives its identity and starts operating. For a private cluster it is where the network becomes specific: small choices affect timing, epoch behavior, account funding, and how closely the cluster resembles mainnet.
The command below is a reference profile for a VM-oriented development cluster. Keypaths are shown as placeholders; they resolve to generated bootstrap identity, vote, stake, and faucet public keys.
For short-lived testing, a second reference profile uses the same bootstrap and faucet funding amounts, --ticks-per-slot 64, and --cluster-type development, but chooses --slots-per-epoch 4500 and --hashes-per-tick 7000. This is intended to produce short test epochs and an approximately 400-millisecond slot target; measure the deployed cluster rather than treating that target as a runtime guarantee.
| Setting | VM-oriented development profile | Short-epoch test profile |
|---|---|---|
--hashes-per-tick | sleep | 7000 |
--ticks-per-slot | 64 | 64 |
--slots-per-epoch | 432000 | 4500 |
--cluster-type | development | development |
| faucet and bootstrap funding | 1,000,000 SOL faucet; 5,000 SOL identity and stake funding | Same values |
These are deliberately different test environments. Select one complete profile and record its genesis hash; mixing individual timing flags from both does not reproduce either cluster.
Flag-by-flag rationale
| Flag | Selected value | Why it is selected |
|---|---|---|
--cluster-type | development | Marks the cluster as a development environment and makes the intent explicit. |
--hashes-per-tick | sleep | Avoids PoH speed assumptions that can be brittle on virtualized hardware. |
--ledger | dedicated ledger directory | Keeps genesis and ledger state out of the operating-system filesystem. |
--bootstrap-validator | identity, vote, and stake public keys | Defines the initial validator and separates its network identity, vote account, and stake account. |
--bootstrap-validator-lamports | 5000000000000 | Funds the bootstrap validator for a private development cluster. |
--bootstrap-validator-stake-lamports | 5000000000000 | Gives the bootstrap validator initial stake. |
--faucet-pubkey | dedicated faucet public key | Separates test-token distribution from validator identity material. |
--faucet-lamports | 1000000000000000 | Provides a usable token supply for development and testing. |
--ticks-per-slot | 64 | Establishes the cluster tick count per slot. Measure observed slot time on the deployed hardware; this flag alone does not guarantee a wall-clock slot duration. |
--slots-per-epoch | 432000 | Uses a finite, repeatable epoch length for the VM-oriented development environment. The short-epoch profile instead uses 4,500 test slots. |
| core and SPL program arguments | generated before genesis | Includes the programs the private cluster needs from its first slot. |
Build the inputs first
The command must receive public keys, not keypair files, for the bootstrap validator and faucet. Generate or restore keypairs in a protected location, then derive the public keys:
The genesis workflow also prepares core and SPL program arguments before solana-genesis runs. Those arguments are part of the network definition: record the program versions and their hashes alongside the genesis hash.
Timing: measure rather than assume
--ticks-per-slot 64 is a cluster parameter. With --hashes-per-tick sleep, the VM-oriented profile avoids requiring a host to achieve a particular PoH hash rate. The short-epoch test profile instead uses 7000 hashes per tick. Both profiles require measured slot cadence on the target hardware; neither flag combination alone guarantees a wall-clock slot duration.
After bootstrapping, take multiple samples rather than relying on one CLI response:
Compute slots advanced over the interval and keep the result with the cluster configuration. If leader slots are skipped on virtualized hardware, investigate CPU scheduling and host contention before changing genesis parameters.
Funding units
Lamport values are intentionally written as integers. One SOL equals 1,000,000,000 lamports; the faucet is initialized with 1,000,000 SOL and the bootstrap validator receives 5,000 SOL for its identity funding plus 5,000 SOL as bootstrap stake. These values are development-cluster choices, not a mainnet economic recommendation.
Choices that must be explicit
Neither reference development profile explicitly sets --inflation or --enable-warmup-epochs. Do not assume their behavior from this page: pin and document the intended behavior before creating a network that needs to match mainnet economics or epoch activation characteristics.
Before rerunning genesis
Genesis is not a routine restart operation. Recreating it changes the cluster identity and invalidates existing state. Treat a new genesis as a new network, preserve the old ledger if it may be needed for analysis, and distribute the resulting genesis hash through a trusted channel.
Post-genesis acceptance checks
Before followers join, capture:
Check that the expected genesis hash is returned, the bootstrap validator is visible, and the slot advances across repeated checks. A listening RPC port alone is not a successful bootstrap.