Upgrade Guide

Treat a Tidecoin Core upgrade as an operational change: read the release notes, back up wallets, stop the node cleanly, replace binaries, restart, and verify chain, wallet, RPC, and service health before re-enabling dependent systems.

This page is the upgrade runbook. It is not the release-note archive; see Release Notes for version-specific changes.

Pre-upgrade checklist

Check	Required action
Release notes reviewed	Look for wallet format, chainstate, RPC, config, and activation changes.
Wallet backups current	Use `backupwallet` for every wallet with funds.
Service config captured	Preserve `tidecoin.conf`, systemd/container config, and firewall rules.
Current version recorded	Save `tidecoind -version` and package/build metadata.
Current chain state recorded	Save `getblockchaininfo` output.
Rollback plan written	Know whether downgrade is supported before you need it.
Dependent services paused	Exchanges and indexers should pause writes during upgrade.

Do not rely on a filesystem copy of a live wallet as the backup. Use Backups.

Standard upgrade

Announce or schedule maintenance for services that depend on the node.
Back up wallets.
Stop the node cleanly:


tidecoin-cli stop

Wait for the process to exit.
Replace binaries or install the new package.
Start the node.
Check logs and RPC:


tidecoin-cli getblockchaininfo
tidecoin-cli getnetworkinfo
tidecoin-cli listwallets

Verify dependent systems: explorers, exchange deposit monitors, monitoring, ZMQ subscribers, and wallets.

Post-upgrade validation

Area	Check
Chain	Expected network, height advancing, no unexpected warnings.
Peers	Peer count and network activity normal.
Wallets	Expected wallets loaded and balances visible after any rescan.
RPC	Service users can call their whitelisted commands.
Indexes	`txindex`, block filter, and coinstats indexes catch up if enabled.
ZMQ/REST	Subscribers and REST clients reconnect.
Logs	No repeated startup, database, wallet, or validation errors.

Keep the old binary available until the new version is verified, but do not downgrade blindly after wallet or chainstate migrations.

Wallet and chainstate compatibility

Wallet and chainstate formats can change across releases. The safe rule is:

Change type	Operator response
Wallet format change	Back up before upgrade; do not downgrade unless release notes say it is safe.
Chainstate format change	Expect first startup to migrate or require rebuild.
Index format change	Indexes may rebuild.
RPC behavior change	Update integration clients and whitelists.
Activation-rule change	Check Activation Status and release notes.

If startup reports unsupported chainstate or replay errors, stop and follow Reindex & Recovery.

Downgrade policy

Downgrades are not guaranteed. A downgrade is only safe when the release notes for both versions say the wallet, chainstate, and config state remain compatible.

Before attempting a downgrade:

Stop the node.
Preserve current logs.
Confirm wallet backups exist from before the upgrade.
Confirm the older binary supports the current wallet and chainstate formats.
Start on a copied datadir first if possible.

When in doubt, restore from backup or resync node data rather than forcing an older binary onto migrated state.

Exchange and infrastructure nodes

For exchange, pool, and explorer nodes:

Step	Reason
Pause deposit crediting	Avoid crediting from a node in transition.
Pause withdrawals if wallet changes are expected	Avoid signing during maintenance.
Upgrade secondary node first	Preserve an independent comparison point.
Compare best block hash across nodes	Detect fleet split or lag.
Resume services after confirmation window	Ensure reorg and indexer state is stable.

Source of truth

Topic	Source
Version-specific changes	`../tidecoin/doc/release-notes.md`, Release Notes
Wallet backup and restore	Backups
Recovery actions	Reindex & Recovery
Activation state	Activation Status

See also: Install a Node, Backups, Monitoring.