📘 Node Migration Playbook (Polkadot / Kusama) — DN Standard

A practical guide for safely migrating a Polkadot/Kusama node to a new server without DB corruption or app-hash divergence.

---

1. Pre-Migration Checklist

Match client version

polkadot --version

Same version must be installed on the new server.

Check current height

curl -s http://localhost:9933 -H "Content-Type: application/json" \
-d '{"id":1,"jsonrpc":"2.0","method":"chain_getHeader"}'

Ensure database type matches

RocksDB vs ParityDB must be identical.

Stop the node cleanly

sudo systemctl stop polkadot

Lock filesystem before copying

Wait 3–5 seconds until process is fully terminated:

ps aux | grep polkadot

---

2. Preparing Destination Server

Create directories

sudo mkdir -p /var/lib/polkadot
sudo chown -R polkadot:polkadot /var/lib/polkadot

Install same binary

wget https://github.com/paritytech/polkadot-sdk/releases/download/vX.Y.Z/polkadot
chmod +x polkadot && sudo mv polkadot /usr/local/bin/

Copy service file (optional)

sudo cp /etc/systemd/system/polkadot.service

---

3. DB Transfer (Safest DN Method)

On source server

Stop node → ensure no process → then run:

rsync -avz --delete \
  /var/lib/polkadot/ \
  user@NEW_SERVER:/var/lib/polkadot/

Recommended flags:

• --delete — removes junk files

• -avz — safe incremental copy

• never copy db-lock file manually

---

4. Integrity Validation Before First Start

Check DB size match

On both servers:

du -sh /var/lib/polkadot

Check last block and state root

cat /var/lib/polkadot/chains/polkadot/db/full/LOG | grep "DB flush"

or via RPC after start in safe mode (below).

---

5. First Start (Safe Mode)

Start once with debug logs:

polkadot \
  --chain=polkadot \
  --database=paritydb \
  --state-pruning=archive \
  --blocks-pruning=archive \
  -l sync=debug,afg=debug

Watch for:

✔ “Importing finalized block” ✔ no “Unexpected state root” ✔ no “Disjointed block ancestry” ✔ no DB repair triggered

If everything looks clean → stop the node.

---

6. Start with Systemd

sudo systemctl daemon-reload
sudo systemctl start polkadot
sudo systemctl status polkadot -l

---

7. Post Migration Validation

Validate height vs reference

curl -s http://localhost:9933 \
-d '{"id":1,"jsonrpc":"2.0","method":"chain_getFinalizedHead"}'

Compare with any DN reference node / telemetry.

Check app-hash consistency

curl -s http://localhost:9933 \
-d '{"jsonrpc":"2.0","id":1,"method":"chain_getBlock"}'

Compare stateRoot of latest block with a trusted node.

Check GRANDPA consistency

Look for finality logs:

journalctl -u polkadot -f | grep -i final

---

8. Common Issues & Fixes

❗ Divergent state root

Re-sync using warp sync:

polkadot --chain=polkadot --sync=warp

❗ Node stuck after migration

Usually caused by incomplete DB. Recopy directory:

rsync -avz --inplace --checksum SOURCE/ DEST/

❗ DB corruption warning on startup

Remove column cache + restart:

rm -rf /var/lib/polkadot/chains/polkadot/network

❗ Warp sync mismatch

Remove only block database and resync:

rm -rf chains/polkadot/db/full

---

9. DN-Recommended Minimal Cutover Workflow

1. Stop source node

2. rsync database to new server

3. Start node in debug mode

4. Check:

   • height matches

   • state root matches

   • finality correct

5. Enable systemd

6. Remove old node from network

This minimizes downtime and guarantees no double-import or app-hash mismatch.