|
| 1 | +# Kaspa Crescendo Hardfork Node Setup Guide |
| 2 | + |
| 3 | +Kaspa is about to take a significant leap with the **Crescendo Hardfork**, as detailed in [KIP14](https://github.com/kaspanet/kips/blob/master/kip-0014.md), transitioning from 1 to 10 blocks per second. The hardfork is scheduled to activate on mainnet at DAA Score `110,165,000` which is roughly `2025-05-05 1500 UTC`. |
| 4 | + |
| 5 | +## Recommended Hardware Specifications |
| 6 | + |
| 7 | +- **Minimum**: |
| 8 | + - 8 CPU cores |
| 9 | + - 16 GB RAM |
| 10 | + - 256 GB SSD |
| 11 | + - 5 MB/s (or ~40 Mbit/s) network bandwidth |
| 12 | + |
| 13 | +- **Preferred for Higher Performance**: |
| 14 | + - 12–16 CPU cores |
| 15 | + - 32 GB RAM |
| 16 | + - 512 GB SSD |
| 17 | + - Higher network bandwidth for robust peer support |
| 18 | + |
| 19 | +While the minimum specs suffice to sync and maintain a TN10 node with the accelerated 10 bps, increasing CPU cores, RAM, storage, and bandwidth allows your node to serve as a stronger focal point on the network. This leads to faster initial block download (IBD) for peers syncing from your node and provides more leeway for future storage growth and optimization. |
| 20 | + |
| 21 | +If you are a pool operator, it is _strongly recommended_ that you pick specs that are closer to the preferred specifications above. |
| 22 | + |
| 23 | +## Running Your Node |
| 24 | + |
| 25 | +1. **Obtain Kaspa v1.0.0 binaries** |
| 26 | + Download and extract the official [1.0.0 release](https://github.com/kaspanet/rusty-kaspa/releases/tag/v1.0.0), or build from the `master` branch by following the instructions in the project README. |
| 27 | + |
| 28 | +2. **Launch the Node** |
| 29 | + ``` |
| 30 | + kaspad --utxoindex |
| 31 | + ``` |
| 32 | +
|
| 33 | + *(If running from source code:)* |
| 34 | + ``` |
| 35 | + cargo run --bin kaspad --release -- --utxoindex |
| 36 | + ``` |
| 37 | +
|
| 38 | + To run on testnet, simply add `--testnet` at the end. For example: |
| 39 | +
|
| 40 | + ``` |
| 41 | + kaspad --utxoindex --testnet |
| 42 | + ``` |
| 43 | +
|
| 44 | +Leave this process running. Closing it will stop your node. If you have other flags that you use for your current node, you may continue to use those. |
| 45 | +
|
| 46 | +- **Advanced Command-Line Options**: |
| 47 | + - `--disable-upnp` if you don't want your node to be automatically publicly connectable (if your router supports UPnP). Recommended for pools and exchanges. |
| 48 | + - `--rpclisten=0.0.0.0` to listen for RPC connections on all network interfaces (public RPC). Use `--rpclisten=127.0.0.1` if you are running your pool/exchange software on the same machine |
| 49 | + - `--rpclisten-borsh` for local borsh RPC access from the `kaspa-cli` binary. |
| 50 | + - `--unsaferpc` for allowing P2P peer query and management via RPC (recommended to use only if **not** exposing RPC publicly). |
| 51 | + - `--perf-metrics --loglevel=info,kaspad_lib::daemon=debug,kaspa_mining::monitor=debug` for detailed performance logs. |
| 52 | + - `--loglevel=kaspa_grpc_server=warn` for suppressing most RPC connect/disconnect log reports. |
| 53 | + - `--ram-scale=3.0` for increasing cache size threefold (relevant for utilizing large RAM; can be set between 0.1 and 10). |
| 54 | +
|
| 55 | +## Mining and Preparation for Crescendo |
| 56 | +
|
| 57 | +Crescendo introduces a new field in transactions, `mass`, which needs to be preserved from the template that you get from `GetBlockTemplate` and passed back when you submit your mined block via `SubmitBlock`. |
| 58 | +
|
| 59 | +Ensure your pool/stratum is updated to preserve this field in the transactions by updating your GRPC proto files. Then, ensure that your pool software properly sends back the `mass` for each transaction in the block. |
| 60 | +
|
| 61 | +### Updating your Pool/Stratum to work in Cresendo |
| 62 | +
|
| 63 | +#### Updating GRPC proto |
| 64 | +
|
| 65 | +Make sure that you get the updated `message.proto` and `rpc.proto` from the rusty-kaspa repo at https://github.com/kaspanet/rusty-kaspa/tree/master/rpc/grpc/core/proto |
| 66 | +
|
| 67 | +#### Using the golang Kaspad repo as an SDK |
| 68 | +
|
| 69 | +If you use the golang Kaspad repo as an SDK, a new tag [v0.12.20](https://github.com/kaspanet/kaspad/releases/tag/v0.12.20) has been made which contains the changes you would need to get your pool/stratum updated. Update your dependency on the old repo to that tag. |
| 70 | +
|
| 71 | +### What happens if I don't update my pool/stratum? |
| 72 | +
|
| 73 | +Before Crescendo activates, you will see the following warning in your node when you submit blocks: |
| 74 | +
|
| 75 | +``` |
| 76 | +The RPC submitted block {block_has} contains a transaction {tx_hash} with mass = 0 while it should have been strictly positive. |
| 77 | +This indicates that the RPC conversion flow used by the miner does not preserve the mass values received from GetBlockTemplate. |
| 78 | +You must upgrade your miner flow to propagate the mass field correctly prior to the Crescendo hardfork activation. |
| 79 | +Failure to do so will result in your blocks being considered invalid when Crescendo activates. |
| 80 | +``` |
| 81 | +
|
| 82 | +Double check that your proto files are updated and that you are able to submit blocks with transactions without triggering this warning. |
| 83 | +
|
| 84 | +After Crescendo activates, if you still have not updated, the blocks that you submit will be considered invalid. |
0 commit comments