v0.15.8 — testnet recovery release (teranode-cli rewindblockchain)

[oskarszoon]

v0.15.8 — testnet recovery release (teranode-cli rewindblockchain)

Released: 2026-07-27
GitHub: https://github.com/bsv-blockchain/teranode/releases/tag/v0.15.8
Container: ghcr.io/bsv-blockchain/teranode:v0.15.8

Upgrade priority

Required for any testnet operator whose node was wedged by the pre-v0.15.7 OP_RETURN spend bug (Discussion #1344). Everyone else on v0.15.x is fine to stay on v0.15.7 — v0.15.8 does not change the validation pipeline, it only ships the recovery tool.

Mainnet operators: v0.15.8 is safe to deploy but not required.

The recovery path

The pre-v0.15.7 bug caused a bare OP_RETURN output to be dropped from the UTXO set at store time; when a later block later spent it, the block cannot validate and the node loops on it forever. v0.15.7 fixed store-time behaviour but did not un-drop rows already lost. v0.15.8 ships teranode-cli rewindblockchain, which rewinds the local blockchain past the bad block so the node re-syncs those blocks fresh with the fix in effect.

Recovering a wedged testnet node (docker / teranode-quickstart)

The rewind is destructive and refuses to run against a live node. The steps below stop everything except the blockchain container, run the rewind inside it, then bring the rest back.

1. Force the FSM into IDLE while the node is still on the old version

docker exec blockchain teranode-cli setfsmstate --fsmstate idle

If the node is stuck mid-CATCHINGBLOCKS (which is common for the wedge scenario), transition through running first:

docker exec blockchain teranode-cli setfsmstate --fsmstate running \
  && docker exec blockchain teranode-cli setfsmstate --fsmstate idle

2. Update the image tag to v0.15.8

Edit docker-compose.yml (or your compose override) so every teranode service references ghcr.io/bsv-blockchain/teranode:v0.15.8, then:

docker compose pull

3. Stop every teranode service except blockchain

docker compose stop asset propagation validator subtreevalidator \
  blockvalidation blockassembly blockpersister utxopersister p2p \
  legacy

(Adjust the service names to match your compose file — the goal is: everything down except blockchain.)

4. Recreate the blockchain container on v0.15.8

docker compose up -d blockchain

Wait a few seconds for it to come healthy, then confirm the FSM is still IDLE:

docker exec blockchain teranode-cli getfsmstate

5. Run the rewind inside the blockchain container

docker exec -it blockchain teranode-cli rewindblockchain --target-height 1749330 --verify

1749330 is a known-safe testnet height BEFORE the wedge block. --verify runs post-rewind consistency checks.

Type y when prompted. The tool logs each phase (preflight, unmined, blocks, finalize, verify) and exits with a summary.

6. Bring the rest of the stack back up and return the FSM to running

docker compose up -d
docker exec blockchain teranode-cli setfsmstate --fsmstate running

The node will now sync forward from the rewound height. With the v0.15.7 store-time fix in effect, the block that previously wedged it will validate cleanly.

Kubernetes / EKS operators

The same recovery pattern applies (set FSM to IDLE, scale everything except blockchain to zero, exec into the blockchain pod to run teranode-cli rewindblockchain, scale back, set FSM to running), but the exact commands depend on how your cluster is provisioned. Reach out in #teranode-support with your setup details before running rewind on a k8s deployment — mistakes on the wrong pod are hard to undo.

What changed

• feat(teranode-cli): register rewindblockchain subcommand (backport feat(teranode-cli): register rewindblockchain subcommand (#1341) #1345 / Ship rewindblockchain: not a teranode-cli subcommand, not in the image, no docs — repair tool unreachable on a deployed node #1341) — makes the destructive-rewind recovery tool available as a teranode-cli subcommand with all flags, prompt handling, and a positional-argument guard.
• fix(rewindblockchain): never move BlockPersisterHeight forward on rewind (backport fix(rewindblockchain): never move BlockPersisterHeight forward on rewind (#1340) #1342 / rewindblockchain: resetBlockPersisterHeight moves the persister forward when it is behind the rewind target, silently skipping persistence #1340) — clamps state[BlockPersisterHeight] against the blocks-table ground truth so the rewind tool cannot accidentally fast-forward the persister and drive irreversible blob deletion.
• fix(rewindblockchain): open the subtree store with the node's hashPrefix (backport fix(rewindblockchain): open the subtree store with the node's hashPrefix (#1351) #1352 / rewindblockchain: subtree store opened without WithHashPrefix — every subtree read misses, Phase 2 cannot rewind any file:// deployment #1351) — reads ?hashPrefix= from the subtree store URL and passes it into NewStore, so the rewind tool shares the node's exact blob path layout and its Del calls actually match what the node wrote.

Known issues

None new.

Full changelog