zpub-check

zpub-check finds whether a native SegWit address is derived from an extended public key within an explicit range. It performs every derivation locally and does not need Bitcoin Core, a blockchain database, or network access.

It is intended for ranges far beyond normal wallet gap limits, such as 200,000 receive and change addresses.

• Keep extended public keys private. They reveal the complete transaction history of every address derived from them.
• The tool never makes network requests.
• A match proves that the address occurs under one of the branches and indices searched. A non-match does not rule out another account, branch, script type, or index outside the requested range.
• zpub and vpub inputs are interpreted as native SegWit P2WPKH keys. xpub and tpub are also accepted and interpreted as P2WPKH for convenience.
• The supplied extended public key should normally be account-level, for example m/84'/0'/0'. Paths reported by the tool are relative to that key.

Install Nix with flakes enabled, plus direnv and nix-direnv. Then run:

direnv allow
make check

Use make help to list the supported commands. The normal workflow is:

make fmt
make check
make release
make nix-build

make coverage runs the complete test suite and rejects source-line coverage below 100%.

Search the inclusive range 0..=199999 on both receive and change branches:

make run ARGS='\
  --zpub zpub... \
  --address bc1q... \
  --end 199999'

Run the optimized binary directly for large searches:

make release
./target/release/zpub-check \
  --zpub zpub... \
  --address bc1q... \
  --branch both \
  --start 0 \
  --end 199999

Limit parallelism and request machine-readable output:

./target/release/zpub-check \
  --zpub zpub... \
  --address bc1q... \
  --branch receive \
  --start 100000 \
  --end 299999 \
  --jobs 4 \
  --format json

Branches are standard non-hardened children relative to the supplied key:

The end index is inclusive and cannot exceed 2147483647, the largest non-hardened BIP32 child index. Exit status is 0 for a match, 1 for no match, and 2 for invalid input or another error.

$ zpub-check --zpub zpub... --address bc1q... --end 200000
MATCH address=bc1q... branch=change index=193842 path=1/193842

make run ARGS='--help'