Gap Limit

Anna uses a wallet, an app or device for receiving and sending bitcoin. She created many receiving addresses in advance, the details someone needs to send her a payment, but never used some of them. After restoring her wallet, some payments are missing. Imagine a search with a limit of 20: address index 0 has history, the following indices 1–20 do not, and index 21 received a payment. An index is simply an address’s position in the sequence; numbering starts at zero. The scan stops after the empty run, before index 21, and misses that payment. If a used address appeared within the searched run, the gap counter would restart. The limit therefore does not mean that the entire wallet can have at most twenty addresses. [1] [6]

What does unused mean here? It does not mean an address with no money on it right now. Anna may have received a payment and later spent it all. Its balance is then zero, but its transaction history remains, so the address still counts as used during discovery. BIP 44 therefore works with history, not just the current balance. Treating every empty address as never used could stop recovery too early. Even a receipt spent long ago is useful when checking a restored wallet. [1]

BIP 44 is a standard describing how accounts and addresses are organised in a hierarchical wallet, which arranges keys and addresses in a tree with different branches. Its Address gap limit rule sets a boundary of 20 for discovery on the external receiving branch, the sequence of addresses intended to receive payments. Software should warn when generating an address beyond that boundary. This is a recovery convention, not a consensus rule determining whether the network accepts a transaction. Other wallets may use different settings or discovery procedures. Nor does this rule recommend reusing the same receiving address indefinitely. [1]

The original wallet may know addresses generated far ahead in the sequence. When restoring from a backup of the keys alone, the new software may not know how far you previously went. Electrum explicitly warns about this in its documentation: addresses beyond Gap Limit may not be found automatically during ordinary recovery. It describes increasing the limit or deriving further addresses until the used position is reached. The appropriate settings depend on the particular software and wallet type. The FAQ’s default of 20 refers to Electrum 2.0; it is not a universal value for all current wallets. [2]

Think of a wallet as an organised tree. Accounts separate groups of funds, and each account can contain different address branches. Under BIP 44, change=0 identifies the receiving branch and change=1 the branch for your own change, the amount that remains with the sender after a payment. Account discovery begins with account 0 and checks its external branch. If it finds history, it continues to the next account; the first account without history stops account discovery. The standard therefore says not to create a new account if the preceding one has no history. A gap in one address branch and a skipped empty account are different problems. Raising one limit does not, by itself, determine which further accounts the software will search. [1]

BIP 32 describes deterministic key derivation: the same starting data and the same path produce the same keys. A Derivation Path is the route through this tree; together with the script type, meaning the spending rules, it determines which addresses the wallet tracks. The correct Seed Phrase, your backup words, is therefore only part of the information needed for correct recovery. With BIP 39, an optional passphrase also contributes to the calculation of the seed, the starting secret for deriving keys. The passphrase is additional secret text, distinct from the application password. A different passphrase leads to a different wallet; raising Gap Limit does not correct it. A private key is a secret numerical value that a wallet uses to create a digital signature authorizing a spend. For advanced readers, an xpub is an extended public key used to derive further public keys. It helps track addresses and payments but cannot, by itself, authorize spending. It cannot, by itself, cross a hardened derivation step, which requires the parent private key. Searching further cannot supply that missing capability. [4] [5] [6]

Bitcoin Core 29.0 exposes importdescriptors through RPC, the node’s programming interface. A descriptor describes how keys form spending conditions and the addresses to watch. The range parameter sets the index range to derive; it is not a rule for stopping after an unused gap. For an active descriptor, next_index sets the next index used to generate addresses. timestamp instead sets how far back to look for transactions. The value now is intended for outputs known never to have been used; it does not replace recovery of older payments. The documentation also includes blocks up to two hours before the earliest timestamp among the imported descriptors and the Mempool, the local collection of unconfirmed transactions. Even a correctly derived address may therefore be absent from the wallet’s overview if the relevant period was not searched. [3]

Back to Anna. If she has a known receiving address or payment record from the original wallet, she can check whether the new wallet actually found it. Compare receipts already spent as well as the final balance. A longer scan may discover overlooked history, but takes time and more queries; when using a remote server, it can reveal more related addresses to that server. Searching alone neither transfers funds nor changes the blockchain. If the history still does not match, check the backup information, account, path, address type and availability of historical data rather than only raising the limit further. Finding one address does not prove that the entire recovery is complete. [1] [2] [4]