Network upgrades

A change to NULL's consensus rules activates at a block height fixed in advance and shipped in a release. There is no signalling or voting. This page explains how activation works and what node operators, exchanges and pools need to do.

How activation works

Every rule set has a 32-bit branch id. Each network starts on its genesis branch (0x4d41494e on mainnet) and carries a schedule of (height, branch) pairs. At any height, the rules in force are those of the last upgrade at or below that height, or the genesis branch if none.

The branch id is not stored in blocks or transactions. Instead every transaction signature commits to it, so a transaction is valid under exactly one rule set:

• After an upgrade, transactions signed for the old rules are invalid in new blocks, and the reverse. Neither side of a split can replay the other's transactions.
• Mainnet and the test network have different genesis branches, so a test network transaction is never valid on mainnet.
• A transaction's id does not include the branch. The same txid keeps its identity; only its validity changes.
• Block and transaction versions do not change, and transactions keep the same shape on every branch.

Nothing else changes at an activation height unless the release says so.

Check the schedule on your node

getblockchaininfo reports the branch in force and the one that will apply to the next block:

curl -s -H "Authorization: Bearer $(cat ~/.local/share/null/main/chain/rpc.token)" \
  -d '{"jsonrpc":"2.0","method":"getblockchaininfo","id":1}' \
  http://127.0.0.1:18446/

When a release announces an upgrade

A release that schedules an upgrade says so in its release notes, with the activation height. It ships well before that height.

1. Upgrade before the activation height. Install the release as described in Run a node. A node that has not upgraded by the activation height is left on its own chain.
2. Expect a resync. Adding an upgrade to the schedule changes the rules the chain database was built under, so the new release refuses the old database. Delete the chain directory the node names and let it resync from peers. Plan the time this takes.
3. Keep your wallets. Wallet files are not affected; wallets rescan from the node after it resyncs.
4. Watch pending payments around the height. The mempool empties when the block before the activation height is applied, and afterwards accepts only transactions signed for the new branch. A wallet rebuilds a pending payment after activation. Exchanges and pools should not count on a transaction broadcast just before the height and should re-check payout status after it.
5. Check after activation. getblockchaininfo should show the new branch, and your node's height should match the explorer.

A node that did not upgrade

A node on the old release keeps validating under the old branch past the activation height. It rejects the first block signed for the new branch as having invalid signatures, bans the peer that sent it, and stays on the old chain. This is a hard fork, visible in its logs as rejected blocks and banned peers, with a tip that stops matching the explorer. Upgrade it as soon as you notice.

Late upgrades and downgrades

The chain database records a digest of the rules it was built under: the consensus parameters, the genesis branch, the upgrade schedule, the circuit's verifying key and a revision number for changes in how blocks are validated. A binary whose digest differs refuses to open the database and names the directory to delete:

the chain in <dir> was built under different consensus rules, for example by an older version; delete that directory and restart to resync

This covers two cases:

• Upgrading late. If you install the new release after your node followed the old chain past the activation height, the blocks it applied under the old rules are not trusted. Delete the chain directory and resync.
• Downgrading. An older binary refuses a database built by a newer one for the same reason.

There is no in-place rewind: the fix is always to delete the chain directory and resync from peers. A database built by a release from before the digest existed is also refused. Mempool contents are not saved across restarts, so they need no migration.

How upgrades are shipped

Developers pick a new branch id, gate the rule change on it while keeping the old rule for every earlier height, add the (height, branch) entry to the network's schedule with tests on both sides of the height, and publish the release well before activation.

What upgrades do not do

• No miner signalling or voting. Activation is by height only.
• No version bits in block headers.
• No branch check between peers. Peers compare genesis hashes when they connect; a peer on the other side of a fork is found and banned when it sends an invalid block.