OptionalcandidatesOptional: every unverified contract this handler could own at one HD
index — pure derivation, no I/O, no metadata. discoverRange probes
these scripts and the look-ahead band subscribes to them, so the two
cannot cover different sets.
boarding omits it: its probe is an on-chain address lookup, and that
keeps it out of the band (deposits are watched on their own channel).
OptionaldiscoverOptional: answer for a whole scan window in one batched round-trip.
The scanner prefers it over per-index discoverAt calls when present,
which is what keeps a 10-index window to 1-2 indexer requests instead
of one per index. Handlers whose source is inherently per-address (e.g.
boarding, on Esplora) implement only discoverAt.
All-or-nothing per call. Either resolve with a map covering every requested index (empty array = confirmed miss), or reject — a handler whose inner chunk fails partway must discard the partial results and reject, because a missing index would otherwise read as "no funds here" and let restore close its gap window on a failed request. The scanner enforces this rather than trusting it: an incomplete map is treated as a rejection, making the whole requested range indeterminate (hits present in it are still persisted) and truncating the scan at the range's first index. Indices that were not requested are ignored.
Optional capability a ContractHandler implements to participate in
wallet.restore()'s gap-limit scan. The scanner owns the index loop and the gap counter; the handler answers "do I own a contract anchored to the pubkey/descriptor at this index?" — checked against the indexer / explorer / (for swaps) the handler's own source. The handler MAY batch/cache internally across calls.