Descriptor syntax for hash preimages

# · jaonoctus · #1 · 04 Oct 2026, 08:45 UTC

Summary

Descriptors can carry private keys (pk(WIF/xprv)) and return them with listdescriptors private=true, but there is no equivalent for the secrets of miniscript hash fragments. I’d like to discuss adding a private form, e.g. sha256(preimage(HEX)), and the same for hash256, ripemd160 and hash160, possibly as a new BIP extending BIP 379.

Motivation

I ran into this while solving the TABConf / Michael Tidwell CTB challenge, where spending required providing a hash preimage. I expected it to work like pk(WIF/xprv): put the secret in the descriptor, import it, and let the wallet build and sign the transaction.

Instead, there is currently no way to give a preimage to Bitcoin Core’s wallet:

the descriptor only accepts the digest;
no RPC adds preimages to a PSBT;
the only path is inserting PSBT_IN_SHA256 (or the other hash fields) with an external tool before walletprocesspsbt/finalizepsbt can complete the witness.

Why preimages are closer to keys than to signatures

#24114 suggests descriptors could eventually replace most of SignatureData, “everything except signatures/preimages”. Signatures commit to a specific transaction, so they can never be part of a descriptor. A preimage does not: once generated (or given to you ahead of time), it is a long-lived secret that depends only on the script. That is exactly what a private key is.

	Keys	Hashes
Public	`pk(PUBKEY)`	`sha256(DIGEST)`
Private	`pk(WIF/xprv)`	(none right now)

In @sipa’s words from the same issue:

if we keep adding exceptions, perhaps the philosophy is wrong.

“Descriptors may carry private keys but not preimages” looks like one of those exceptions.

Sketch/Draft:

Syntax. sha256(preimage(HEX)), hash256(preimage(HEX)), ripemd160(preimage(HEX)), hash160(preimage(HEX)).
Exactly 32 bytes. All four fragments compile to OP_SIZE 32 OP_EQUALVERIFY <HASHOP> <digest> OP_EQUAL, so a valid preimage is always 32 bytes, even for ripemd160/hash160. Any other length would be unsatisfiable and should be rejected by the parser.
Explicit marker required. For sha256/hash256, preimage and digest are both 32 bytes, so raw hex is ambiguous by construction. Keys avoid this because WIF/xprv have their own encodings.
Serialization. The public string prints the digest; the private string (private=true) prints the preimage form. Descriptors inferred from scripts produce the digest form, just as they never contain private keys.
Wallet/signing (Bitcoin Core). Today the miniscript satisfier looks up preimages only in SignatureData, populated from PSBT fields. Preimages from a descriptor would be stored and encrypted alongside keys, exposed through the SigningProvider, and used by the satisfier in addition to SignatureData.
Safety. A revealed preimage is public, but sane miniscript already requires a signature on every satisfaction path (the s property), so a preimage alone never spends. The preimage form is a secret like a WIF and should be handled the same way (backups, encryption, never in the public string).

This does not replace the PSBT path: preimages learned at spend time (e.g. from a counterparty in an HTLC) still belong in PSBT fields. It only covers preimages known when the descriptor is created.

Open questions

Marker syntax: preimage(HEX) nested inside the fragment, a prefix, or something else?
Scope: an amendment to BIP 379, or a separate BIP like other descriptor extensions?
Complementary RPC: independently of descriptors, should Core get an RPC to add hash preimages to a PSBT, for the learned-at-spend-time case?
Signers/hardware wallets: would devices that accept miniscript descriptors want to handle preimage secrets, or should this be software-wallet only?
Deterministic preimages: is there interest in deriving preimages from key material (similar to how Lightning derives secrets), or is a literal preimage enough for a first step?

# · Ferdinando Ametrano · #2 · 27 Oct 2026, 17:39 UTC

A literal preimage stops being secret once one output is spent through its hash branch, and in a ranged descriptor every other output shares that branch.

Hash fragments take a digest, not a key expression, so sha256(preimage(HEX)) gives the same digest at every index of a /* descriptor. After one spend through the hash path, the preimage is on chain. The s property still keeps the other outputs safe, since each needs a signature, but their hash condition no longer adds anything. A private key is different: spending does not reveal it. So “a secret like a WIF” holds only until the first spend. Your question on deterministic preimages may be the answer: a preimage derived per index from key material gives each output its own digest. A first step with literal preimages could state the limit.

The private and public strings will have different checksums, as with keys. The BIP should say so, since this is new for a hash fragment.

btclib-wallet, a library I maintain, has no preimage(HEX) syntax yet, but its parser already gives the expected script for the digest form of all four fragments. I can add the private form and compute test vectors: each private descriptor must give the same script as the one written with the digest, and its public string must print that digest.