extend the gap limit only for addresses paid by a fetched transaction
What changed, and why it matters
This commit tightens when Sparrow Wallet extends the 'gap limit'—the number of empty addresses it keeps ready ahead of the last used one. Previously, merely seeing any transaction status reported for an address could push the gap forward. Now the wallet only extends the gap when a fetched transaction actually pays that address. This prevents a malicious or buggy Electrum server from tricking the wallet into generating far more addresses than necessary by reporting unrelated transaction statuses.
Users should upgrade to a Sparrow Wallet release containing this commit. Operators relying on custom Electrum servers should ensure their servers return accurate script-hash histories. Review whether prior versions could have generated excessive addresses when connected to an untrusted server.
Security signals we found
Server-supplied transaction history no longer unconditionally treated as address usage
Gap limit extension now requires cryptographic proof of payment to the address
Mitigates potential Electrum-server-driven address enumeration / DoS
Added targeted unit tests for the changed behavior
Evidence from the diff
The change is in ElectrumServer.getGapLimitSize(). Instead of taking the highest indexed WalletNode that has any history entry, it now scans from the highest index downward and picks the first node for which isPaidByFetchedTransaction() finds a matching output script in a transaction the wallet has actually downloaded. Two new unit tests verify that a status without history and a history entry for a transaction that does not pay the address do not extend the gap, while a real payment does. A silent-payments test was updated so its mock history entries reference real (mock) transactions that pay the address.
Changed components
src/main/java/com/sparrowwallet/sparrow/net/ElectrumServer.javaWallet address discovery / gap-limit logicElectrum server RPC integrationInspect captured patch +247 / −4
### src/main/java/com/sparrowwallet/sparrow/net/ElectrumServer.java
@@ -780,11 +780,36 @@ private Set<WalletNode> getAddressNodes(Wallet wallet, WalletNode purposeNode) {
}
private int getGapLimitSize(Wallet wallet, Map<WalletNode, Set<BlockTransactionHash>> nodeTransactionMap, WalletNode purposeNode) {
- int highestIndex = nodeTransactionMap.keySet().stream().filter(node -> node.getDerivation().size() > 1 && purposeNode.getKeyPurpose() == node.getKeyPurpose())
- .map(WalletNode::getIndex).max(Comparator.comparing(Integer::valueOf)).orElse(-1);
+ //Taken from the highest index down, so that only the nodes above the highest used one are checked
+ int highestIndex = nodeTransactionMap.entrySet().stream()
+ .filter(entry -> entry.getKey().getDerivation().size() > 1 && purposeNode.getKeyPurpose() == entry.getKey().getKeyPurpose())
+ .sorted(Comparator.comparingInt((Map.Entry<WalletNode, Set<BlockTransactionHash>> entry) -> entry.getKey().getIndex()).reversed())
+ .filter(entry -> isPaidByFetchedTransaction(wallet, entry.getKey(), entry.getValue()))
+ .map(entry -> entry.getKey().getIndex()).findFirst().orElse(-1);
return highestIndex + wallet.getGapLimit() + 1;
}
+ //An address is used once a transaction pays it, rather than once a status is reported for it
+ private static boolean isPaidByFetchedTransaction(Wallet wallet, WalletNode node, Set<BlockTransactionHash> references) {
+ if(references == null || references.isEmpty()) {
+ return false;
+ }
+
+ byte[] outputScript = node.getOutputScript().getProgram();
+ for(BlockTransactionHash reference : references) {
+ BlockTransaction blockTransaction = wallet.getTransactions().get(reference.getHash());
+ if(blockTransaction != null && blockTransaction.getTransaction() != null) {
+ for(TransactionOutput txOutput : blockTransaction.getTransaction().getOutputs()) {
+ if(Arrays.equals(txOutput.getScript().getProgram(), outputScript)) {
+ return true;
+ }
+ }
+ }
+ }
+
+ return false;
+ }
+
public void getReferences(Wallet wallet, Collection<WalletNode> nodes, Map<WalletNode, Set<BlockTransactionHash>> nodeTransactionMap, int startIndex) throws ServerException {
try {
Map<WalletNode, ScriptHashTx[]> nodeHashHistory = new LinkedHashMap<>(nodes.size());
### src/test/java/com/sparrowwallet/sparrow/net/GapLimitTest.java
@@ -0,0 +1,209 @@
+package com.sparrowwallet.sparrow.net;
+
+import com.google.common.net.HostAndPort;
+import com.github.arteam.simplejsonrpc.client.Transport;
+import com.sparrowwallet.drongo.KeyPurpose;
+import com.sparrowwallet.drongo.Network;
+import com.sparrowwallet.drongo.Utils;
+import com.sparrowwallet.drongo.policy.Policy;
+import com.sparrowwallet.drongo.policy.PolicyType;
+import com.sparrowwallet.drongo.protocol.Script;
+import com.sparrowwallet.drongo.protocol.ScriptType;
+import com.sparrowwallet.drongo.protocol.Sha256Hash;
+import com.sparrowwallet.drongo.protocol.Transaction;
+import com.sparrowwallet.drongo.wallet.DeterministicSeed;
+import com.sparrowwallet.drongo.wallet.Keystore;
+import com.sparrowwallet.drongo.wallet.MnemonicException;
+import com.sparrowwallet.drongo.wallet.Wallet;
+import com.sparrowwallet.drongo.wallet.WalletNode;
+import com.sparrowwallet.sparrow.SparrowWallet;
+import com.sparrowwallet.sparrow.io.Config;
+import org.junit.jupiter.api.*;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Path;
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class GapLimitTest {
+ private static final long FEE = 200L;
+ private static final int MAX_INDEX = 100;
+
+ @TempDir
+ private static Path tempHome;
+
+ private ServerType previousServerType;
+ private ElectrumServerRpc previousElectrumServerRpc;
+ private CloseableTransport previousTransport;
+ private ServerCapability previousServerCapability;
+
+ @BeforeAll
+ public static void setUpAll() {
+ System.setProperty(SparrowWallet.APP_HOME_PROPERTY, tempHome.toString());
+ }
+
+ @AfterAll
+ public static void tearDownAll() {
+ System.clearProperty(SparrowWallet.APP_HOME_PROPERTY);
+ }
+
+ @BeforeEach
+ public void setUp() {
+ Network.set(Network.TESTNET);
+ previousServerType = Config.get().getServerType();
+ Config.get().setServerType(ServerType.ELECTRUM_SERVER);
+ previousElectrumServerRpc = ElectrumServer.electrumServerRpc;
+ previousTransport = ElectrumServer.transport;
+ previousServerCapability = ElectrumServer.serverCapability;
+ ElectrumServer.transport = new UnusedTransport();
+ ElectrumServer.serverCapability = null;
+ ElectrumServer.clearPreviousServerState();
+ ElectrumServer.getSubscribedScriptHashes().clear();
+ }
+
+ @AfterEach
+ public void tearDown() {
+ Config.get().setServerType(previousServerType);
+ ElectrumServer.electrumServerRpc = previousElectrumServerRpc;
+ ElectrumServer.transport = previousTransport;
+ ElectrumServer.serverCapability = previousServerCapability;
+ ElectrumServer.clearPreviousServerState();
+ ElectrumServer.getSubscribedScriptHashes().clear();
+ Network.set(null);
+ }
+
+ @Test
+ public void statusWithoutHistoryDoesNotExtendGap() throws Exception {
+ Wallet wallet = softwareWallet();
+ ElectrumServer.electrumServerRpc = new HistoryServer(Map.of(), true);
+ refresh(wallet);
+ assertEquals(wallet.getGapLimit(), receiveChildren(wallet));
+ }
+
+ @Test
+ public void transactionNotPayingAddressDoesNotExtendGap() throws Exception {
+ Wallet wallet = softwareWallet();
+ Transaction unrelated = new Transaction();
+ unrelated.addInput(Sha256Hash.wrap(String.format("%064x", 0xc0)), 0, new Script(new byte[0]));
+ unrelated.addOutput(10_000L, softwareWallet(2).getNode(KeyPurpose.RECEIVE).getChildren().iterator().next().getAddress());
+ ElectrumServer.electrumServerRpc = new HistoryServer(Map.of(), true, unrelated);
+ refresh(wallet);
+ assertEquals(wallet.getGapLimit(), receiveChildren(wallet));
+ }
+
+ @Test
+ public void paymentExtendsGap() throws Exception {
+ Wallet wallet = softwareWallet();
+ wallet.getNode(KeyPurpose.RECEIVE).fillToIndex(wallet, 15);
+ WalletNode paid = wallet.getNode(KeyPurpose.RECEIVE).getChildren().stream().filter(node -> node.getIndex() == 15).findFirst().orElseThrow();
+ Transaction payment = new Transaction();
+ payment.addInput(Sha256Hash.wrap(String.format("%064x", 0xc1)), 0, new Script(new byte[0]));
+ payment.addOutput(10_000L, paid.getAddress());
+ ElectrumServer.electrumServerRpc = new HistoryServer(Map.of(ElectrumServer.getScriptHash(paid), payment), false);
+ refresh(wallet);
+ assertEquals(15 + wallet.getGapLimit() + 1, receiveChildren(wallet));
+ }
+
+ private static void refresh(Wallet wallet) throws ServerException {
+ assertTrue(new ElectrumServer().fetchAndCalculateHistory(wallet, null, null));
+ }
+
+ private static int receiveChildren(Wallet wallet) {
+ return wallet.getNode(KeyPurpose.RECEIVE).getChildren().size();
+ }
+
+ private static Wallet softwareWallet() throws MnemonicException {
+ return softwareWallet(1);
+ }
+
+ private static Wallet softwareWallet(int seed) throws MnemonicException {
+ Wallet wallet = new Wallet("test" + seed);
+ wallet.setPolicyType(PolicyType.SINGLE_HD);
+ wallet.setScriptType(ScriptType.P2WPKH);
+ DeterministicSeed deterministicSeed = new DeterministicSeed(Utils.hexToBytes(String.format("%032x", seed)), "", 0);
+ Keystore keystore = Keystore.fromSeed(deterministicSeed, PolicyType.SINGLE_HD, ScriptType.P2WPKH.getDefaultDerivation());
+ wallet.getKeystores().add(keystore);
+ wallet.setDefaultPolicy(Policy.getPolicy(PolicyType.SINGLE_HD, ScriptType.P2WPKH, wallet.getKeystores(), null));
+ return wallet;
+ }
+
+ /**
+ * Reports the given payments to the script hashes they pay. With reportAll, every other script hash is given a status too, with the
+ * transactions in unreferenced as its history, or none. Refuses to answer for an address past MAX_INDEX, so that a gap extended without
+ * bound fails rather than runs on.
+ */
+ private static class HistoryServer extends SimpleElectrumServerRpc {
+ private final Map<String, Transaction> payments;
+ private final boolean reportAll;
+ private final List<Transaction> unreferenced;
+
+ public HistoryServer(Map<String, Transaction> payments, boolean reportAll, Transaction... unreferenced) {
+ this.payments = payments;
+ this.reportAll = reportAll;
+ this.unreferenced = List.of(unreferenced);
+ }
+
+ private List<ScriptHashTx> getHistory(String scriptHash) {
+ if(payments.containsKey(scriptHash)) {
+ return List.of(new ScriptHashTx(0, payments.get(scriptHash).getTxId().toString(), FEE));
+ }
+
+ return reportAll ? unreferenced.stream().map(tx -> new ScriptHashTx(0, tx.getTxId().toString(), FEE)).toList() : List.of();
+ }
+
+ private void checkIndex(String path) {
+ int index = Integer.parseInt(path.substring(path.lastIndexOf('/') + 1));
+ if(index > MAX_INDEX) {
+ throw new IllegalStateException("Asked for address " + path + " beyond index " + MAX_INDEX);
+ }
+ }
+
+ @Override
+ public Map<String, String> subscribeScriptHashes(Transport transport, Wallet wallet, Map<String, String> pathScriptHashes) {
+ Map<String, String> result = new LinkedHashMap<>();
+ pathScriptHashes.forEach((path, scriptHash) -> {
+ checkIndex(path);
+ boolean reported = payments.containsKey(scriptHash) || reportAll;
+ result.put(path, reported ? Utils.bytesToHex(Sha256Hash.hash(scriptHash.getBytes())) : null);
+ });
+ return result;
+ }
+
+ @Override
+ public Map<String, ScriptHashTx[]> getScriptHashHistory(Transport transport, Wallet wallet, Map<String, String> pathScriptHashes, boolean failOnError) {
+ Map<String, ScriptHashTx[]> result = new LinkedHashMap<>();
+ pathScriptHashes.forEach((path, scriptHash) -> result.put(path, getHistory(scriptHash).toArray(new ScriptHashTx[0])));
+ return result;
+ }
+
+ @Override
+ public Map<String, String> getTransactions(Transport transport, Wallet wallet, Set<String> txids) {
+ Map<String, String> result = new LinkedHashMap<>();
+ List<Transaction> all = new ArrayList<>(payments.values());
+ all.addAll(unreferenced);
+ for(String txid : txids) {
+ Transaction transaction = all.stream().filter(tx -> tx.getTxId().toString().equals(txid)).findFirst().orElseThrow();
+ result.put(txid, Utils.bytesToHex(transaction.bitcoinSerialize()));
+ }
+ return result;
+ }
+ }
+
+ private static class UnusedTransport extends TcpTransport {
+ public UnusedTransport() {
+ super(HostAndPort.fromParts("localhost", 1));
+ }
+
+ @Override
+ public String pass(String request) {
+ throw new UnsupportedOperationException("The fake server answers without the transport");
+ }
+
+ @Override
+ public boolean isConnected() {
+ return true;
+ }
+ }
+}
### src/test/java/com/sparrowwallet/sparrow/net/SilentPaymentsBatchTest.java
@@ -34,6 +34,7 @@
import java.math.BigInteger;
import java.nio.file.Path;
import java.time.Duration;
+import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
@@ -60,6 +61,7 @@ public class SilentPaymentsBatchTest {
private ServerCapability previousServerCapability;
private final Map<String, Transaction> served = new LinkedHashMap<>();
private final Set<String> usedScriptHashes = new HashSet<>();
+ private final Map<String, String> paymentTxids = new HashMap<>();
@BeforeAll
public static void setUpAll() {
@@ -97,7 +99,8 @@ public Map<String, String> subscribeScriptHashes(Transport transport, Wallet wal
@Override
public Map<String, ScriptHashTx[]> getScriptHashHistory(Transport transport, Wallet wallet, Map<String, String> pathScriptHashes, boolean failOnError) {
Map<String, ScriptHashTx[]> result = new LinkedHashMap<>();
- pathScriptHashes.keySet().forEach(path -> result.put(path, new ScriptHashTx[0]));
+ pathScriptHashes.forEach((path, scriptHash) -> result.put(path, paymentTxids.containsKey(scriptHash)
+ ? new ScriptHashTx[] {new ScriptHashTx(0, paymentTxids.get(scriptHash), 0L)} : new ScriptHashTx[0]));
return result;
}
};
@@ -194,7 +197,13 @@ public void fetchesTheHistoryOfDeterministicNodesToTheGapLimit() {
Wallet wallet = deterministicWallet();
WalletNode receiveNode = wallet.getNode(KeyPurpose.RECEIVE);
receiveNode.fillToIndex(wallet, 1);
- usedScriptHashes.add(ElectrumServer.getScriptHash(receiveNode.getChildren().stream().filter(node -> node.getIndex() == 1).findFirst().orElseThrow()));
+ WalletNode usedNode = receiveNode.getChildren().stream().filter(node -> node.getIndex() == 1).findFirst().orElseThrow();
+ Transaction transaction = new Transaction();
+ transaction.addInput(Sha256Hash.of(new byte[] {1}), 0, new Script(new byte[0]));
+ transaction.addOutput(10000L, usedNode.getAddress());
+ served.put(transaction.getTxId().toString(), transaction);
+ usedScriptHashes.add(ElectrumServer.getScriptHash(usedNode));
+ paymentTxids.put(ElectrumServer.getScriptHash(usedNode), transaction.getTxId().toString());
assertTimeoutPreemptively(Duration.ofSeconds(10), () -> new ElectrumServer().getHistory(wallet));
assertEquals(2 + wallet.getGapLimit(), receiveNode.getChildren().size());Why this scored 51/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.