fetch a script hash again when a reorg replaces the block of a payment found by a history fetch still in progress
What changed, and why it matters
This commit fixes a corner case in Sparrow Wallet where a blockchain reorganization (a 'reorg') could leave the wallet showing a payment as confirmed when the block it was confirmed in has been replaced. The bug occurs when the reorg happens while the wallet is still fetching history. After the fix, Sparrow detects this situation and re-fetches the affected address/script hash so the payment is re-verified against the new chain. In the worst case, a user might rely on an incorrect balance or transaction confirmation state, but the fix is defensive and the window for the issue is narrow.
Review and merge the patch. Run the new unit tests and consider additional integration tests around reorg scenarios. Users should upgrade to a release containing this fix, especially if relying on confirmation state for time-sensitive decisions. No immediate emergency response is indicated because exploitation requires a blockchain reorg and a narrow timing window.
Security signals we found
Blockchain reorg handling bug in wallet history synchronization
Potential stale/incorrect transaction confirmation state
Defensive fix with added unit tests for regression coverage
No explicit CVE, advisory, or security disclosure referenced
Evidence from the diff
The patch modifies ElectrumServer.fetchAndCalculateWalletHistory to detect when a reorg is reconciled while a history fetch pass is in flight. It records reorgCount before the pass and compares it after. If a new reorg occurred during the pass, it calls invalidateWalletScriptHashesForReorg(wallet, lastReorgForkHeight) and posts RequestWalletRefreshEvent. This handles the case where the wallet had no outputs above the fork at the time of invalidation, so the earlier invalidation logic did nothing. It also adjusts the logic that clears transaction outputs for nodes with no retrieved status, so nodes invalidated during the pass are not incorrectly cleared. Two unit tests simulate a reorg between proof verification and output installation, verifying the node is re-fetched and the payment is re-proven at height 0 (unconfirmed/mempool) after the reorg.
Changed components
src/main/java/com/sparrowwallet/sparrow/net/ElectrumServer.javaWallet history synchronization and reorg invalidation logicInspect captured patch +123 / −2
### src/main/java/com/sparrowwallet/sparrow/net/ElectrumServer.java
@@ -512,11 +512,18 @@ private boolean fetchAndCalculateWalletHistory(Wallet wallet, List<Wallet> filte
//Taken before the fetch, so an invalidation arriving while this pass runs can be told from one the pass is acting on
Set<String> invalidatedBeforeFetch = Set.copyOf(reorgInvalidatedScriptHashes);
+ int reorgsBeforeFetch = reorgCount;
Map<String, String> previousScriptHashes = getCalculatedScriptHashes(wallet);
Map<WalletNode, Set<BlockTransactionHash>> nodeTransactionMap = (nodes == null ? getHistory(wallet) : getHistory(wallet, nodes));
getReferencedTransactions(wallet, nodeTransactionMap);
calculateNodeHistory(wallet, nodeTransactionMap);
+ //A reorg reconciled while this pass was in flight was invalidated against the outputs the wallet held at the time, which do not include
+ //a payment this pass has just found above the fork. The wallet may have had nothing above it then, and so not have refreshed at all
+ if(reorgCount != reorgsBeforeFetch && invalidateWalletScriptHashesForReorg(wallet, lastReorgForkHeight)) {
+ EventManager.get().post(new RequestWalletRefreshEvent(wallet));
+ }
+
//A node invalidated by a reorg has no retrieved status left to compare against, so it must not count as changed history below
Set<String> invalidatedScriptHashes = Set.copyOf(reorgInvalidatedScriptHashes);
@@ -561,11 +568,13 @@ private boolean fetchAndCalculateWalletHistory(Wallet wallet, List<Wallet> filte
reorgInvalidatedScriptHashes.removeAll(invalidatedBeforeFetch.stream().filter(walletScriptHashes::contains).collect(Collectors.toSet()));
}
- //Clear transaction outputs for nodes that have no history - this is useful when a transaction is replaced in the mempool
+ //Clear transaction outputs for nodes that have no history - this is useful when a transaction is replaced in the mempool. A node a reorg
+ //invalidated during this pass has no status because it was invalidated, not because it has no history, and is left for the refresh
if(nodes != null) {
for(WalletNode node : nodes) {
String scriptHash = getScriptHash(node);
- if(retrievedScriptHashes.get(scriptHash) == null && !node.getTransactionOutputs().isEmpty()) {
+ if(retrievedScriptHashes.get(scriptHash) == null && !node.getTransactionOutputs().isEmpty()
+ && (invalidatedBeforeFetch.contains(scriptHash) || !invalidatedScriptHashes.contains(scriptHash))) {
log.debug("Clearing transaction history for " + node);
node.getTransactionOutputs().clear();
}
### src/test/java/com/sparrowwallet/sparrow/net/TransactionProofTest.java
@@ -26,6 +26,7 @@
import com.sparrowwallet.sparrow.ChainTip;
import com.sparrowwallet.sparrow.EventManager;
import com.sparrowwallet.sparrow.SparrowWallet;
+import com.sparrowwallet.sparrow.event.RequestWalletRefreshEvent;
import com.sparrowwallet.sparrow.event.TransactionProofsFailedEvent;
import com.sparrowwallet.sparrow.event.TransactionProofsRefusedEvent;
import com.sparrowwallet.sparrow.event.WalletNodeHistoryChangedEvent;
@@ -1020,6 +1021,106 @@ public void clearsAnInvalidationTheRefreshItTriggeredHasActedOn() throws Excepti
assertFalse(ElectrumServer.reorgInvalidatedScriptHashes.contains(scriptHash), "and the exemption lasts for exactly that one fetch");
}
+ /**
+ * A reorg reconciled after a pass has proven a payment new to the wallet, but before the pass has given its node the outputs, finds nothing of the
+ * wallet's above the fork, so the wallet neither invalidates the node nor refreshes. The pass does both once the outputs are in, and the refresh
+ * proves the payment again against the block that replaced the one it was proven in.
+ */
+ @Test
+ public void invalidatesANodeGivenOutputsAboveAForkReconciledDuringThePass() throws Exception {
+ Wallet wallet = testWallet();
+ WalletNode node = wallet.getNode(KeyPurpose.RECEIVE).getChildren().iterator().next();
+ String scriptHash = ElectrumServer.getScriptHash(node);
+ Transaction payment = newConfirmedPayment(wallet, node);
+
+ assertTrue(reorganisingBeforeOutputs().fetchAndCalculateHistory(wallet, null, null));
+
+ assertNull(ElectrumServer.retrievedScriptHashes.get(scriptHash), "the node must be fetched again");
+ assertTrue(ElectrumServer.reorgInvalidatedScriptHashes.contains(scriptHash));
+ assertEquals(1, listener.getRefreshRequests());
+
+ new ElectrumServer().fetchAndCalculateHistory(wallet, null, null);
+
+ assertEquals(0, wallet.getWalletTransaction(payment.getTxId()).getHeight());
+ assertEquals(0, node.getTransactionOutputs().iterator().next().getHeight());
+ }
+
+ /**
+ * A payment usually arrives on a fetch of the one node its status changed on. Invalidated during that pass, the node has no status left, which
+ * is not the server reporting it has no history: its outputs stay for the refresh rather than being cleared until it runs.
+ */
+ @Test
+ public void keepsTheOutputsOfANodeInvalidatedDuringAPassOfThatNode() throws Exception {
+ Wallet wallet = testWallet();
+ WalletNode node = wallet.getNode(KeyPurpose.RECEIVE).getChildren().iterator().next();
+ String scriptHash = ElectrumServer.getScriptHash(node);
+ Transaction payment = newConfirmedPayment(wallet, node);
+
+ assertTrue(reorganisingBeforeOutputs().fetchAndCalculateHistory(wallet, null, Set.of(node)));
+
+ assertEquals(1, node.getTransactionOutputs().size());
+ assertEquals(payment.getTxId(), node.getTransactionOutputs().iterator().next().getHash());
+ assertNull(ElectrumServer.retrievedScriptHashes.get(scriptHash));
+ assertTrue(ElectrumServer.reorgInvalidatedScriptHashes.contains(scriptHash));
+ assertEquals(1, listener.getRefreshRequests());
+
+ new ElectrumServer().fetchAndCalculateHistory(wallet, null, null);
+
+ assertEquals(0, wallet.getWalletTransaction(payment.getTxId()).getHeight());
+ assertEquals(0, node.getTransactionOutputs().iterator().next().getHeight());
+ }
+
+ /**
+ * A payment to the node the wallet does not yet hold, confirmed in a chain whose block at the proven height includes it, so its proof
+ * reconstructs until that block is replaced.
+ */
+ private Transaction newConfirmedPayment(Wallet wallet, WalletNode node) throws Exception {
+ Transaction payment = new Transaction();
+ payment.addInput(Sha256Hash.ZERO_HASH, 0, new Script(new byte[0]));
+ payment.addOutput(10000L, wallet.getAddress(node));
+
+ blockTransactions = List.of(payment, transaction(1), transaction(2), transaction(3));
+ chain = mineChain(Network.REGTEST.getGenesisHeader(), CHAIN_LENGTH, merkleRoot(txids(blockTransactions)));
+ ElectrumServer.getHeaderStore().truncate(0);
+ seedStore(chain, CHAIN_LENGTH - 1);
+ server = new FakeProofServer(chain);
+ ElectrumServer.electrumServerRpc = server;
+ server.serveTransaction(payment);
+ server.serveProof(payment, PROVEN_HEIGHT, 0);
+ ScriptHashTx confirmed = new ScriptHashTx(PROVEN_HEIGHT, payment.getTxId().toString(), null);
+ server.serveHistory(node.getDerivationPath(), confirmed);
+ server.serveScriptHashStatus(ElectrumServer.getScriptHash(node), ElectrumServer.getScriptHashStatus(List.of(confirmed)));
+
+ return payment;
+ }
+
+ /**
+ * A server whose pass has the store reorganised above the payment's block after its proof is verified and before node outputs are installed,
+ * the wallet's own invalidation running in between as it does on the application thread.
+ */
+ private ElectrumServer reorganisingBeforeOutputs() {
+ return new ElectrumServer() {
+ @Override
+ public void calculateNodeHistory(Wallet calculatingWallet, Map<WalletNode, Set<BlockTransactionHash>> nodeTransactionMap) {
+ try {
+ HeaderStore store = ElectrumServer.getHeaderStore();
+ store.truncate(PROVEN_HEIGHT - 1);
+ BlockHeader previous = chain.get(PROVEN_HEIGHT - 2);
+ for(int height = PROVEN_HEIGHT; height < CHAIN_LENGTH; height++) {
+ previous = mineHeader(previous, Sha256Hash.ZERO_HASH, CHAIN_TIME + 100 + height);
+ store.append(previous);
+ }
+ } catch(Exception e) {
+ throw new IllegalStateException(e);
+ }
+ ElectrumServer.lastReorgForkHeight = PROVEN_HEIGHT - 1;
+ ElectrumServer.reorgCount++;
+ assertFalse(ElectrumServer.invalidateScriptHashesForReorg(calculatingWallet, PROVEN_HEIGHT - 1), "the wallet holds nothing above the fork yet");
+ super.calculateNodeHistory(calculatingWallet, nodeTransactionMap);
+ }
+ };
+ }
+
/**
* A reorg reaches the wallets that are open when the store is rewound. One opened afterwards, in the same session or a later one, still holds what
* the replaced block proved at a height the server reports unchanged, so its node is never fetched and the stored height never looked at. The
@@ -1106,6 +1207,7 @@ public void doesNotReproveAStoredHeightWhoseBlockTheStoreHolds() throws Exceptio
assertEquals(Integer.MAX_VALUE, ElectrumServer.lastReorgForkHeight);
assertEquals(PROVEN_HEIGHT, wallet.getWalletTransaction(transaction.getTxId()).getHeight());
assertEquals(PROVEN_HEIGHT, node.getTransactionOutputs().iterator().next().getHeight());
+ assertEquals(0, listener.getRefreshRequests());
}
/**
@@ -1566,6 +1668,12 @@ public static class ProofListener {
private Wallet reportedWallet;
private int failedEvents;
private int refusedEvents;
+ private int refreshRequests;
+
+ @Subscribe
+ public void requestWalletRefresh(RequestWalletRefreshEvent event) {
+ refreshRequests++;
+ }
@Subscribe
public void transactionProofsFailed(TransactionProofsFailedEvent event) {
@@ -1601,6 +1709,10 @@ public int getRefusedEvents() {
return refusedEvents;
}
+ public int getRefreshRequests() {
+ return refreshRequests;
+ }
+
public boolean isEmpty() {
return failedEvents == 0 && refusedEvents == 0;
}Why this scored 57/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.