fix: use derivation indexes, not record counts, for new and discovered addresses (#3762)
What changed, and why it matters
This commit fixes a bug in Cake Wallet's Bitcoin address handling. Previously, the wallet chose new receive/change addresses by counting how many address records existed, rather than by checking the actual derivation index. On some Bitcoin address types (P2PKH, P2SH, P2TR), this count could include legacy-derivation records, causing the wallet to skip ahead and create address 'holes' (for example, jumping from index 21 to 44). A wallet restored from seed would not scan those skipped indexes, so any funds sent to them could appear missing after restore. The fix makes new addresses use the lowest unused derivation index and makes address discovery continue from the highest used index, with added unit tests.
Review and merge the fix; ensure the new unit tests pass. Users who generated Bitcoin receive/change addresses on affected P2PKH/P2SH/P2TR pages before this fix should be advised to verify balances after restoring from seed, and to consider sweeping any funds sent to skipped indexes if they can identify them.
Security signals we found
Address gap/derivation index mismatch could cause funds to be missed on wallet restore
Fix replaces list-length/count-based indexing with derivation-index-based logic
Legacy derivation records could inflate counts and create unscanned address holes
Discovery gap check now uses addressRecord.index instead of list index
New unit tests added for index helpers and address generation/discovery
Evidence from the diff
The patch changes ElectrumWalletBase and ElectrumWalletAddresses to use derivation indexes instead of list lengths/positions. New helpers nextIndexOf(branch) and firstFreeIndex(takenIndexes) are introduced. generateNewAddress and getChangeAddress now compute the lowest free standard-chain index, treating legacy records as taken only when the legacy derivation produces the same keys. Address discovery now starts after the highest index on the branch, and gap-limit checks compare addressRecord.index rather than list position. Unit tests cover contiguous branches, branches with holes, duplicated indexes, and legacy-same-chain cases.
Changed components
cw_bitcoin/lib/electrum_wallet.dartcw_bitcoin/lib/electrum_wallet_addresses.dartcw_bitcoin/test/address_index_test.dartInspect captured patch +438 / −20
### cw_bitcoin/lib/electrum_wallet.dart
@@ -2990,8 +2990,8 @@ abstract class ElectrumWalletBase
historiesWithDetails.addAll(result.transactions);
final matchedAddresses = branchFor(addressRecord);
- final isUsedAddressAboveGap = matchedAddresses.indexOf(addressRecord) >=
- matchedAddresses.length -
+ final isUsedAddressAboveGap = addressRecord.index >=
+ nextIndexOf(matchedAddresses) -
(addressRecord.isHidden
? ElectrumWalletAddressesBase.defaultChangeAddressesCount
: ElectrumWalletAddressesBase.defaultReceiveAddressesCount);
@@ -3483,7 +3483,7 @@ abstract class ElectrumWalletBase
final highestUsedIndex = _highestUsedIndex(currentBranch);
final shouldDiscover =
- highestUsedIndex >= 0 && highestUsedIndex >= currentBranch.length - gapLimit;
+ highestUsedIndex >= 0 && highestUsedIndex >= nextIndexOf(currentBranch) - gapLimit;
if (!shouldDiscover) return;
@@ -3533,9 +3533,11 @@ abstract class ElectrumWalletBase
.toList()
..sort((a, b) => a.index.compareTo(b.index));
+ /// The derivation index of the highest used address, -1 when none is used.
+ /// [addresses] must be sorted by index, as [getAddressBranchByType] returns them.
int _highestUsedIndex(List<BitcoinAddressRecord> addresses) {
for (int i = addresses.length - 1; i >= 0; i--) {
- if (addresses[i].isUsed) return i;
+ if (addresses[i].isUsed) return addresses[i].index;
}
return -1;
}
### cw_bitcoin/lib/electrum_wallet_addresses.dart
@@ -58,6 +58,21 @@ const List<BitcoinAddressType> DOGECOIN_ADDRESS_TYPES = [
const List<BitcoinAddressType> EXTRA_ACCOUNT_ADDRESS_TYPES = [SegwitAddresType.p2wpkh];
+/// The index after the highest one on [branch] (0 when it's empty): where discovery continues.
+/// Counting the records instead falls short when lower indexes are missing, and runs ahead when an
+/// index appears twice.
+int nextIndexOf(Iterable<BaseBitcoinAddressRecord> branch) =>
+ branch.fold(-1, (int highest, record) => max(highest, record.index)) + 1;
+
+/// The lowest index not in [takenIndexes]: where a new address goes, so a branch grows without gaps.
+int firstFreeIndex(Set<int> takenIndexes) {
+ var index = 0;
+ while (takenIndexes.contains(index)) {
+ index++;
+ }
+ return index;
+}
+
abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
ElectrumWalletAddressesBase(
WalletInfo walletInfo, {
@@ -445,16 +460,15 @@ abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
updateChangeAddresses();
if (changeAddresses.isEmpty) {
- final accountChangeCount = _addresses
- .where((addressRecord) =>
- _isCurrentAccountAddress(addressRecord) &&
- addressRecord.isHidden &&
- addressRecord.type == addressPageType)
- .length;
+ final takenIndexes = _takenStandardIndexes(
+ isHidden: true,
+ type: addressPageType,
+ accountIndex: currentAccountIndex,
+ );
final newAddresses = await _createNewAddresses(
gap,
- startIndex: accountChangeCount,
+ startIndex: firstFreeIndex(takenIndexes),
isHidden: true,
type: addressPageType,
accountIndex: currentAccountIndex,
@@ -551,13 +565,9 @@ abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
final accountIndex = walletInfo.type == WalletType.bitcoin ? currentAccountIndex : 0;
- final newAddressIndex = addressesByReceiveType.fold(
- 0,
- (int acc, addressRecord) => addressRecord is BitcoinAddressRecord &&
- addressRecord.accountIndex == accountIndex &&
- addressRecord.isHidden == false
- ? acc + 1
- : acc);
+ final newAddressIndex = firstFreeIndex(
+ _takenStandardIndexes(isHidden: false, type: addressPageType, accountIndex: accountIndex),
+ );
final hd = _hdForAddressGeneration(
isHidden: false,
@@ -823,7 +833,7 @@ abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
}) async {
final newAddresses = await _createNewAddresses(
gap,
- startIndex: addressList.length,
+ startIndex: nextIndexOf(addressList),
isHidden: isHidden,
isLegacyDerivation: isLegacyDerivation,
type: type,
@@ -859,7 +869,7 @@ abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
}) async {
final newAddresses = await _createNewAddresses(
gap,
- startIndex: addressList.length,
+ startIndex: nextIndexOf(addressList),
isHidden: isHidden,
type: type,
isLegacyDerivation: isLegacyDerivation,
@@ -1184,6 +1194,42 @@ abstract class ElectrumWalletAddressesBase extends WalletAddresses with Store {
return hd;
}
+ /// The indexes taken on the standard [type] chain of [accountIndex]: its own records, and the
+ /// legacy ones too when the legacy derivation has the same keys, since then they are the same
+ /// addresses.
+ Set<int> _takenStandardIndexes({
+ required bool isHidden,
+ required BitcoinAddressType type,
+ required int accountIndex,
+ }) {
+ var legacyIsSameChain = false;
+ try {
+ final standard = _hdForAddressGeneration(
+ isHidden: isHidden,
+ type: type,
+ isLegacyDerivation: false,
+ accountIndex: accountIndex,
+ );
+ final legacy = _hdForAddressGeneration(
+ isHidden: isHidden,
+ type: type,
+ isLegacyDerivation: true,
+ accountIndex: accountIndex,
+ );
+ legacyIsSameChain = standard.publicKey.toHex() == legacy.publicKey.toHex() &&
+ standard.chainCode.toHex() == legacy.chainCode.toHex();
+ } on UnsupportedAddressTypeForAccountException catch (_) {}
+
+ return {
+ for (final record in _addresses)
+ if (record.isHidden == isHidden &&
+ record.type == type &&
+ (walletInfo.type != WalletType.bitcoin || record.accountIndex == accountIndex) &&
+ (!record.isLegacyDerivation || legacyIsSameChain))
+ record.index,
+ };
+ }
+
@action
Future<void> setLightningAddress(String walletName, {String newAddress = ""}) async {
if (lightningWallet == null) return;
### cw_bitcoin/test/address_index_test.dart
@@ -0,0 +1,370 @@
+import "package:bitcoin_base/bitcoin_base.dart";
+import "package:blockchain_utils/blockchain_utils.dart";
+import "package:cw_bitcoin/bitcoin_address_record.dart";
+import "package:cw_bitcoin/bitcoin_wallet_addresses.dart";
+import "package:cw_bitcoin/electrum_wallet_addresses.dart";
+import "package:cw_bitcoin/payjoin/manager.dart";
+import "package:cw_bitcoin/utils.dart";
+import "package:cw_core/db/sqlite.dart";
+import "package:cw_core/wallet_info.dart";
+import "package:cw_core/wallet_type.dart";
+import "package:flutter_test/flutter_test.dart";
+import "package:sqflite_common_ffi/sqflite_ffi.dart";
+
+final Bip32Slip10Secp256k1 _master =
+ Bip32Slip10Secp256k1.fromSeed(List<int>.generate(64, (i) => i));
+
+Bip32Slip10Secp256k1 _hd(String path) => _master.derivePath(path) as Bip32Slip10Secp256k1;
+
+final Bip32Slip10Secp256k1 _p2wpkhReceiveHd = _hd("m/84'/0'/0'/0");
+final Bip32Slip10Secp256k1 _p2wpkhChangeHd = _hd("m/84'/0'/0'/1");
+final Bip32Slip10Secp256k1 _p2pkhReceiveHd = _hd("m/44'/0'/0'/0");
+final Bip32Slip10Secp256k1 _p2pkhChangeHd = _hd("m/44'/0'/0'/1");
+final Bip32Slip10Secp256k1 _legacyReceiveHd = _hd("m/0'/0");
+final Bip32Slip10Secp256k1 _legacyChangeHd = _hd("m/0'/1");
+
+BitcoinAddressRecord _record(
+ int index, {
+ BitcoinAddressType type = SegwitAddresType.p2wpkh,
+ bool isHidden = false,
+ bool isLegacyDerivation = false,
+ bool isUsed = false,
+ int accountIndex = 0,
+}) {
+ final Bip32Slip10Secp256k1 hd = _hd(
+ "m/1'/${type == P2pkhAddressType.p2pkh ? 44 : 84}'/$accountIndex'"
+ "/${isLegacyDerivation ? 1 : 0}'/${isHidden ? 1 : 0}",
+ );
+ final String address = type == P2pkhAddressType.p2pkh
+ ? generateP2PKHAddress(hd: hd, index: index, network: BitcoinNetwork.mainnet)
+ : generateP2WPKHAddress(hd: hd, index: index, network: BitcoinNetwork.mainnet);
+
+ return BitcoinAddressRecord(
+ address,
+ index: index,
+ type: type,
+ isHidden: isHidden,
+ isLegacyDerivation: isLegacyDerivation,
+ isUsed: isUsed,
+ accountIndex: accountIndex,
+ network: BitcoinNetwork.mainnet,
+ );
+}
+
+List<BitcoinAddressRecord> _range(
+ int start,
+ int end, {
+ BitcoinAddressType type = SegwitAddresType.p2wpkh,
+ bool isHidden = false,
+ bool isLegacyDerivation = false,
+ bool isUsed = false,
+ int accountIndex = 0,
+}) =>
+ [
+ for (int i = start; i < end; i++)
+ _record(
+ i,
+ type: type,
+ isHidden: isHidden,
+ isLegacyDerivation: isLegacyDerivation,
+ isUsed: isUsed,
+ accountIndex: accountIndex,
+ ),
+ ];
+
+class _NoPayjoin implements PayjoinManager {
+ @override
+ dynamic noSuchMethod(Invocation invocation) => throw UnimplementedError();
+}
+
+class _Addresses extends BitcoinWalletAddresses {
+ _Addresses(
+ super.walletInfo, {
+ required List<BitcoinAddressRecord> records,
+ required Bip32Slip10Secp256k1 legacyReceiveHd,
+ required Bip32Slip10Secp256k1 legacyChangeHd,
+ }) : super(
+ mainHdByTypeAndAccount: {
+ 0: {
+ SegwitAddresType.p2wpkh: _p2wpkhReceiveHd,
+ P2pkhAddressType.p2pkh: _p2pkhReceiveHd,
+ },
+ },
+ sideHdByTypeAndAccount: {
+ 0: {
+ SegwitAddresType.p2wpkh: _p2wpkhChangeHd,
+ P2pkhAddressType.p2pkh: _p2pkhChangeHd,
+ },
+ },
+ accountIndexes: [0],
+ currentAccountIndex: 0,
+ legacyMainHd: legacyReceiveHd,
+ legacySideHd: legacyChangeHd,
+ network: BitcoinNetwork.mainnet,
+ isHardwareWallet: false,
+ payjoinManager: _NoPayjoin(),
+ initialAddresses: records,
+ );
+
+ @override
+ Future<void> saveAddressesInBox() async {}
+}
+
+Future<_Addresses> _addresses(
+ List<BitcoinAddressRecord> records, {
+ BitcoinAddressType addressPageType = SegwitAddresType.p2wpkh,
+ bool legacyIsSameChain = false,
+}) async {
+ final WalletInfo walletInfo = WalletInfo.external(
+ id: "address_index_test",
+ name: "address_index_test",
+ type: WalletType.bitcoin,
+ isRecovery: false,
+ restoreHeight: 0,
+ date: DateTime(2026),
+ dirPath: "",
+ path: "",
+ address: "",
+ )..addressPageType = addressPageType.toString();
+
+ final _Addresses addresses = _Addresses(
+ walletInfo,
+ records: records,
+ legacyReceiveHd: legacyIsSameChain ? _p2wpkhReceiveHd : _legacyReceiveHd,
+ legacyChangeHd: legacyIsSameChain ? _p2wpkhChangeHd : _legacyChangeHd,
+ );
+ await walletInfo.getManualAddresses();
+ return addresses;
+}
+
+List<int> _indexes(Iterable<BaseBitcoinAddressRecord> records) =>
+ records.map((record) => record.index).toList();
+
+void main() {
+ setUpAll(() async {
+ sqfliteFfiInit();
+ db = await databaseFactoryFfi.openDatabase(inMemoryDatabasePath);
+ await db!.execute(
+ "CREATE TABLE IF NOT EXISTS walletInfoAddress "
+ "(walletInfoAddressId INTEGER PRIMARY KEY, walletInfoId INTEGER, type INTEGER, "
+ "address TEXT)",
+ );
+ });
+
+ group("nextIndexOf", () {
+ test("is 0 for an empty branch", () {
+ expect(nextIndexOf(<BitcoinAddressRecord>[]), 0);
+ });
+
+ test("is the length for a contiguous branch", () {
+ expect(nextIndexOf(_range(0, 22)), 22);
+ });
+
+ test("continues after the highest index when lower indexes are missing", () {
+ expect(nextIndexOf([..._range(0, 22), _record(44)]), 45);
+ });
+
+ test("is not pushed ahead by a duplicated index", () {
+ expect(nextIndexOf([..._range(0, 3), _record(2, isLegacyDerivation: true)]), 3);
+ });
+
+ test("does not depend on the order of the records", () {
+ expect(nextIndexOf([_record(7), _record(2), _record(5)]), 8);
+ });
+ });
+
+ group("firstFreeIndex", () {
+ test("is 0 when nothing is taken", () {
+ expect(firstFreeIndex(<int>{}), 0);
+ });
+
+ test("is the next index for a contiguous set", () {
+ expect(firstFreeIndex({0, 1, 2}), 3);
+ });
+
+ test("fills the lowest hole", () {
+ expect(firstFreeIndex({0, 1, 2, 4, 44}), 3);
+ });
+
+ test("is 0 when index 0 is missing", () {
+ expect(firstFreeIndex({1, 2, 3}), 0);
+ });
+ });
+
+ group("generateNewAddress", () {
+ test("ignores legacy records that derive different keys", () async {
+ final _Addresses addresses = await _addresses(
+ [
+ ..._range(0, 22, type: P2pkhAddressType.p2pkh),
+ ..._range(0, 22, type: P2pkhAddressType.p2pkh, isLegacyDerivation: true),
+ ],
+ addressPageType: P2pkhAddressType.p2pkh,
+ );
+
+ final BaseBitcoinAddressRecord address = addresses.generateNewAddress();
+
+ expect(address.index, 22);
+ expect(
+ address.address,
+ generateP2PKHAddress(hd: _p2pkhReceiveHd, index: 22, network: BitcoinNetwork.mainnet),
+ );
+ });
+
+ test("counts legacy records that derive the same keys", () async {
+ final _Addresses addresses = await _addresses(
+ [
+ ..._range(0, 3),
+ ..._range(0, 5, isLegacyDerivation: true),
+ ],
+ legacyIsSameChain: true,
+ );
+
+ expect(addresses.generateNewAddress().index, 5);
+ });
+
+ test("fills a hole left on the branch", () async {
+ final _Addresses addresses = await _addresses([..._range(0, 22), _record(44)]);
+
+ expect(addresses.generateNewAddress().index, 22);
+ await Future<void>.delayed(Duration.zero);
+ expect(addresses.generateNewAddress().index, 23);
+ });
+
+ test("ignores change records and other address types", () async {
+ final _Addresses addresses = await _addresses([
+ ..._range(0, 2),
+ ..._range(0, 10, isHidden: true),
+ ..._range(0, 10, type: P2pkhAddressType.p2pkh),
+ ]);
+
+ expect(addresses.generateNewAddress().index, 2);
+ });
+
+ test("ignores records of other accounts", () async {
+ final _Addresses addresses = await _addresses([
+ ..._range(0, 2),
+ ..._range(0, 10, accountIndex: 1),
+ ]);
+
+ expect(addresses.generateNewAddress().index, 2);
+ });
+
+ test("starts at 0 on an empty branch", () async {
+ final _Addresses addresses = await _addresses(<BitcoinAddressRecord>[]);
+
+ expect(addresses.generateNewAddress().index, 0);
+ });
+ });
+
+ group("getChangeAddress", () {
+ test("creates new change addresses from the lowest free index", () async {
+ final _Addresses addresses = await _addresses([
+ ..._range(0, 30),
+ ..._range(0, 3, isHidden: true, isUsed: true),
+ _record(5, isHidden: true, isUsed: true),
+ ]);
+
+ final BitcoinAddressRecord address = await addresses.getChangeAddress();
+
+ expect(address.index, 3);
+ expect(address.isHidden, isTrue);
+ expect(
+ address.address,
+ generateP2WPKHAddress(hd: _p2wpkhChangeHd, index: 3, network: BitcoinNetwork.mainnet),
+ );
+ });
+ });
+
+ group("discoverAddressesBatch", () {
+ test("starts at 0 on an empty branch", () async {
+ final _Addresses addresses = await _addresses(<BitcoinAddressRecord>[]);
+
+ final List<BitcoinAddressRecord> discovered = await addresses.discoverAddressesBatch(
+ <BitcoinAddressRecord>[],
+ false,
+ (_) async => <String>{},
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(discovered), List<int>.generate(20, (i) => i));
+ });
+
+ test("continues at the length of a contiguous branch", () async {
+ final List<BitcoinAddressRecord> branch = _range(0, 22);
+ final _Addresses addresses = await _addresses(branch);
+
+ final List<BitcoinAddressRecord> discovered = await addresses.discoverAddressesBatch(
+ branch,
+ false,
+ (_) async => <String>{},
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(discovered), List<int>.generate(20, (i) => 22 + i));
+ });
+
+ test("continues after the highest index of a branch with a hole", () async {
+ final List<BitcoinAddressRecord> branch = [..._range(0, 22), _record(44)];
+ final _Addresses addresses = await _addresses(branch);
+
+ final List<BitcoinAddressRecord> discovered = await addresses.discoverAddressesBatch(
+ branch,
+ false,
+ (_) async => <String>{},
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(discovered), List<int>.generate(20, (i) => 45 + i));
+ });
+
+ test("keeps going from the highest index while the gap has a used address", () async {
+ final List<BitcoinAddressRecord> branch = [..._range(0, 22), _record(44)];
+ final _Addresses addresses = await _addresses(branch);
+ final String usedAddress =
+ generateP2WPKHAddress(hd: _p2wpkhReceiveHd, index: 50, network: BitcoinNetwork.mainnet);
+
+ final List<BitcoinAddressRecord> discovered = await addresses.discoverAddressesBatch(
+ branch,
+ false,
+ (_) async => {usedAddress},
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(discovered), List<int>.generate(40, (i) => 45 + i));
+ });
+
+ test("continues after the highest change index", () async {
+ final List<BitcoinAddressRecord> branch = [
+ ..._range(0, 3, isHidden: true),
+ _record(9, isHidden: true),
+ ];
+ final _Addresses addresses = await _addresses(branch);
+
+ final List<BitcoinAddressRecord> discovered = await addresses.discoverAddressesBatch(
+ branch,
+ true,
+ (_) async => <String>{},
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(discovered), List<int>.generate(20, (i) => 10 + i));
+ expect(discovered.every((record) => record.isHidden), isTrue);
+ });
+ });
+
+ group("discoverAddresses", () {
+ test("continues after the highest index of a branch with a hole", () async {
+ final List<BitcoinAddressRecord> branch = [..._range(0, 22), _record(44)];
+ final _Addresses addresses = await _addresses(branch);
+
+ await addresses.discoverAddresses(
+ branch,
+ false,
+ (_) async => null,
+ isLegacyDerivation: false,
+ );
+
+ expect(_indexes(branch.skip(23)), List<int>.generate(20, (i) => 45 + i));
+ });
+ });
+}Why this scored 64/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.