Wallet descriptors: reconcile derivation ranges before balances
A watch-only wallet balance describes outputs the wallet can recognize under its imported information and scanning history. It does not automatically describe every address a business ever derived, and it does not establish that the observer can spend the outputs. Reconcile the descriptor’s coverage before interpreting a balance discrepancy.
The research object is a coverage specification: script type, public derivation information, branch, index interval and historical start point. The procedure can be documented without publishing a real extended public key or importing anything into a live wallet.
Inspect the descriptor’s role
The Bitcoin Core 30.0 importdescriptors reference describes range, next_index, timestamp and internal fields. Read those argument definitions together: an index-generation setting, a scanning start time and a change classification are different controls.
Record whether the supplied information describes one fixed script or a ranged family. For a family, preserve the derivation path and branch relationship privately, alongside a sanitized public identifier. Receiving and change branches can require separate coverage records. Importing one does not demonstrate that the other was examined.
Use fictional labels such as Receiving-R and Change-C in a shared memo. An extended public key can expose linked address history even when it cannot sign transactions. There is no analytical need to put a real one into a public worked example.
A hypothetical range reconciliation
Assume a fictional organization has provided authorized public derivation information for two branches. The current study has verified receiving indices 0–99 and change indices 0–49, including both stated endpoints. At the selected cutoff, recognized unspent outputs total 3 BTC and 1 BTC respectively.
| Coverage component | Verified index interval | Unspent amount found |
|---|---|---|
| Receiving-R | 0–99 | 3 BTC |
| Change-C | 0–49 | 1 BTC |
| Original covered set | Both intervals | 4 BTC |
| Later receiving observation | Index 120 | 0.5 BTC |
| Expanded known covered set | Original set plus index 120 | 4.5 BTC |
The original arithmetic is 3 + 1 = 4. Adding the newly verified output gives 4 + 0.5 = 4.5 BTC. No coin was created by the research correction. The observation set expanded.
Index 120 lies outside the original receiving interval. Its omission does not prove that the node miscomputed the imported set. The first task is to compare the wallet’s recognized scripts with the organization’s actual derivation scope, rather than treating every mismatch as a blockchain inconsistency.
Do not call 4.5 the exhaustive organization-wide total. Other branches or higher indices remain outside this example’s evidence. A finite search can establish a quantity inside its verified set without establishing a useful upper bound on all undisclosed derivations.
Range, next index and history are separate
An index used for generating the next address is not a certificate that all earlier or later addresses have been scanned. Record generation state separately from the explicit imported range and completed scan. A display that says next index 121 does not by itself prove the historical treatment of every index through 120.
Also distinguish an upper range setting from observed use. Extending a range to include index 200 creates more candidates to inspect; it does not mean the organization actually used every intervening address. Preserve identified outputs rather than multiplying an average balance by the number of candidate scripts.
The RPC documentation’s timestamp field controls where rescanning begins. Its special now value can bypass historical scanning. Therefore a descriptor with the correct public derivation and index range can still produce an incomplete historical view if the scan starts too late.
Boundary case: the script was covered but the time was not
In a separate hypothetical case, receiving index 20 has an unspent 0.25 BTC output created before the imported scan start. The range includes 20, but the study has not established that its earlier creation was inspected. This is a time-coverage gap rather than a range-coverage gap.
Correcting the index interval alone would not necessarily repair it. Verify the scan’s starting block or timestamp, completion status and the node’s ability to supply the required history. If an earlier scan later finds the output, label it recovered historical evidence, not a new deposit on the recovery date.
An empty scan result is not automatically zero when scanning was interrupted or required history was unavailable. Keep successful coverage intervals and failures so that another researcher can distinguish no matches from no completed observation.
Control and identity need their own evidence
A descriptor can recognize a locking condition without supplying the signatures needed to satisfy it. Mark watch-only recognition, known policy and demonstrated signing control separately. Do not perform a real spend merely to make the research table look complete.
Likewise, receiving derivation information through a document does not prove the named organization owns every recognized output. Retain the authenticated statement’s scope and date. A custodian may supply a monitoring view covering assets with several beneficial owners; recognition and attribution remain different questions.
When two imported records recognize the same output, deduplicate the inventory by outpoint while retaining both recognition relationships. Receiving and change labels do not turn one output into two assets. Investigate a label conflict separately rather than deleting one source’s history.
A bounded coverage checklist
| Action | Save | Failure treatment |
|---|---|---|
| Confirm network and script type | Private descriptor identity and sanitized memo label | Resolve incompatible or ambiguous scripts |
| List all declared branches | Receiving/change purpose and derivation relationship | Keep missing branches unknown |
| Fix index intervals | Explicit lower and upper bounds | Do not infer completeness from next_index |
| Verify historical coverage | Scan start, completion and available blocks | Separate incomplete scan from zero matches |
| Reconcile outputs | Distinct outpoints and values at one cutoff | Remove duplicate recognition, preserve later discoveries |
| State control scope | Watch-only status and attribution evidence | Avoid claiming spendability or organization-wide completeness |
Release the balance with its coverage sentence: these specified branches, index intervals and historical observations contain these verified unspent outputs at this cutoff. Reopen the study when a declared branch changes, a higher used index appears, the historical start is corrected or the attribution statement is superseded. A coverage correction should improve the record without rewriting the time at which the underlying coins arrived.
FAQ
Does possessing an extended public key let the researcher spend bitcoin?
Not by itself. Public derivation and output recognition are different from the private authorization required by the relevant locking conditions.
Can a finite empty range prove the wallet has no other outputs?
No. It concerns that script set and completed history. Other branches, indices or historical gaps remain separate questions.