Kaspa consensus parameter overrides let developers test non-standard protocol constants from a JSON file without editing Rust source and recompiling. Rusty-kaspa pull request #751 added the feature for non-mainnet environments and made kaspad exit if an override is attempted on mainnet. It improves experimental repeatability, but invalid parameter combinations can still produce misleading or unusable test networks.

Key takeaways

• PR #751 added --override-params-file to kaspad and JSON serialization for consensus parameter structures.
• The implementation blocks overrides on Kaspa mainnet and exits during startup.
• Omitted top-level fields inherit defaults for the selected non-mainnet network.
• At the merge revision, omitted fields inside the nested crescendo object became zero, a documented temporary behavior requiring special care.
• simpa can export its active parameters, helping a developer launch kaspad against a matching simulation database.

What did rusty-kaspa PR #751 add?

Kaspanet merged rusty-kaspa pull request #751 on November 10, 2025. GitHub reports 376 additions, eight deletions, nine changed files, and three commits. The contributor stated a precise goal: change consensus constants for tests without modifying code and rebuilding.

The patch introduced a serializable OverrideParams structure, command-line handling in kaspad, merge logic that applies optional values over the selected network defaults, and a 160-line usage document. It also added --override-params-output to simpa, allowing the simulator to write the configuration needed to reproduce its database parameters elsewhere.

This is developer tooling, not a governance mechanism. A local JSON file cannot change rules accepted by independent mainnet nodes.

How do you load an override file?

Choose an isolated non-mainnet network, create a JSON document containing only the intended changes, and launch a reviewed build with the file path. The source code declared the argument with an equals requirement, so this explicit form avoids ambiguity:

kaspad --devnet --override-params-file=/path/to/overrides.json

If the file cannot be read or parsed, the merged daemon prints an error and exits. If mainnet is selected, it prints that overriding parameters on mainnet is not allowed and exits. Those fail-closed paths prevent an accidental local mainnet variant from starting through this flag.

Use a dedicated data directory and disposable keys. Never point an experiment at a production wallet directory, and never assume coins or history created on devnet or simnet have mainnet value.

Which parameters can be changed?

The merged guide lists pre-Crescendo and post-Crescendo controls across several groups:

• timing and difficulty, including target block time and difficulty-window sizes;
• GHOSTDAG and BlockDAG structure, including K, parent limits, mergeset limits, and merge depth;
• finality and pruning depths;
• transaction input, output, script-length, block-mass, and storage-mass limits;
• coinbase maturity, subsidy timing, and payload limits;
• proof-of-work testing behavior, maximum block level, and pruning-proof parameters;
• Crescendo activation and a nested set of post-Crescendo constants.

The breadth is useful for extreme-condition simulations, fork-schedule rehearsals, and regression tests. It also makes arbitrary copy-and-paste files dangerous. Changing one window or depth can violate assumptions tied to another. skip_proof_of_work is a laboratory shortcut, not a performance setting for a public network.

What is the important Crescendo nesting warning?

Top-level properties in OverrideParams are optional. When one is absent, the implementation retains the chosen network’s default. The merged documentation records a different temporary rule for the nested crescendo object: if that object is present but one of its sub-fields is omitted, the missing sub-field is set to zero instead of inheriting its network default.

That means a small-looking partial object can change far more than intended. At this revision, developers should either omit the entire crescendo object or provide and review every required sub-field. Then confirm the effective configuration through logs, generated files, or source-level tests rather than trusting the input document alone.

Because the documentation labels this behavior temporary, always check the version you run. A later release may merge nested defaults differently.

How can simpa make an experiment reproducible?

The patch added an export option to the simulation binary:

cargo run --release --bin simpa -- \
  --override-params-output overrides.json -o=/path/to/simpa/database

That file captures the parameters used to build the simulation database. The official guide then describes preparing a simnet data directory and launching kaspad --simnet with the matching override file. Treat database movement as a destructive operation: work only on disposable copies, verify paths, and follow the current documentation for the exact release.

Store the source commit, JSON checksum, command, seed, database snapshot identifier, and test assertions together. “It worked on devnet” is weak evidence unless another developer can recreate the same network and observe the same result.

What makes an override test safer?

Start with one hypothesis and the smallest parameter change that can test it. Run a control using defaults, then the override using identical software and workload. Define success and failure before observing results. Inspect startup logs, block production, peer behavior, consensus errors, pruning, memory, disk, and final state.

Keep experimental peers isolated. Nodes with different consensus constants can reject one another or build incompatible histories even if their network flag is the same. The related guide to Kaspa P2P compatibility explains why protocol compatibility deserves explicit version boundaries.

Finally, publish the exact configuration with any technical conclusion. Our coverage of the Kaspa Q&A launch shows why versioned, reproducible evidence is more durable than an answer detached from its test conditions.

What can this feature not do?

It cannot activate a mainnet rule, make an invalid parameter set safe, or prove that an extreme laboratory configuration would be deployable at network scale. The mainnet guard protects one boundary; it cannot detect every logically inconsistent value or experimental design mistake.

It also does not eliminate recompilation when the behavior under study is not exposed through OverrideParams. The public structure defines the supported surface. Developers should not invent undocumented JSON fields or infer that every compile-time constant is overrideable.

Frequently asked questions

Can I use consensus overrides on Kaspa mainnet?

No. The merged implementation explicitly blocks a mainnet launch with an override file and exits at startup.

Do missing JSON fields keep their defaults?

Top-level fields did at the merge revision. Missing fields inside a supplied crescendo object temporarily became zero, so that nested object required a complete review.

Does a devnet test prove a change is production-ready?

No. It can reproduce behavior under controlled constants. Production readiness also requires adversarial review, performance testing, compatibility analysis, specification work, and broad consensus among independent participants.

Source and verification note

This guide is grounded in merged rusty-kaspa PR #751, its code diff, and the accompanying override-params.md documentation at merge commit 8539dd4. The mainnet block, JSON behavior, parameter groups, simpa export, and nested-Crescendo warning all come from that primary source. Safety recommendations are editorial guidance, not claims that the tool validates every experiment. Check current docs before running commands.