I'm trying to wrap my head around ranged descriptors. The docs in the bitcoin/bitcoin-repo says that a ranged descriptor can generate keys/address "in a configurable range (0-1000 by default)".


This 0-1000 range gets mentioned as a default a few times down the document, but it isn't clear if it's possible to generate keys/addresses beyond 1000, nor does there seem to be any information within the descriptor itself that allows us to look beyond 1000.

My question, stated more clearly:

  1. Is there an upper (hard) limit on the number of keys/addresses that can be generated from a ranged descriptor?
  2. Is the 1000 limit just an arbitrary number to be enforced by wallets to set a reasonable cap on the look-ahead of descriptors?

2 Answers 2


The range is determined by the context, or the caller. As far as the descriptor is concerned, there is no limit (apart from the inherent BIP32 limit of 231 keys); it defines a (practically) infinite list of scriptPubKeys.

The Bitcoin Core wallet, if used in descriptor mode, will dynamically grow the range as keys get used. The lookahead (also called gap limit) is controlled by the -keypool command-line option (or keypool= config file argument), and defaults to 1000. But if say, scriptPubKey number 337 gets used, from that point, the wallet will extend the range to 1337, and consider payments to the scriptPubKeys generated that way beyond 1000 to be its own.

That is however not the only use case for descriptors. For example, Bitcoin Core has a scantxoutset RPC which can be used to sift through the UTXO set for anything paying an output matching a certain descriptor. In that context, there is no notion of a gap limit, as it's just a single shot invocation, and the user can provide the actual range itself.


It is possible to generate as many descriptors as child of a BIP32 extended public key. That is, 2^31 of the same kind (hardened or unhardened).

1000 is just the default gap limit of the Bitcoin Core wallet.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.