descriptors: document the feature set and the known divergences

Two READMEs written for someone judging what this library does and how it
differs from the implementations they may know.

descriptors/README.md lists the supported script and key expressions and
the API, the expressions that are deliberately not implemented (combo(),
raw(), addr(), musig(), rawtr(), sp()) with the reason for each, the
absent features that a reader would otherwise assume (no policy compiler,
no descriptor inference, no signing, no PSBT), a table of the behavioral
divergences from Bitcoin Core c4fbd3c7211 and rust-miniscript v13 with the
relevant Core line numbers, and the handful of behaviors that surprise:
the P2WSH plan witness omitting the witness script, key validity being
checked at derivation rather than at parse time, hardened steps needing an
xprv, and the network being a parameter of derivation rather than of the
descriptor.

descriptors/miniscript/README.md does the same for the engine: the
fragment set, a table of the three script contexts with the limits each
enforces, what it cannot do (no compiler, no script decoding, keys are
opaque), and the divergences that matter - Parse being sane by default,
the 10,000-byte Tapscript limit being what the builder can emit, the
Legacy context being a rust concept that Core does not have, and the two
places where the analysis deliberately differs from rust.

Author: guggero

descriptors/README.md

@@ -0,0 +1,98 @@
+# descriptors
+
+Output script descriptors as specified in BIP380 through BIP389: parse a
+descriptor, derive its addresses and scripts, estimate its spending weight, lift
+it to a semantic policy, and plan and complete a spend.
+
+The miniscript engine lives in [`miniscript/`](miniscript/README.md), which has
+its own notes.
+
+## What is supported
+
+**Script expressions**: `pk()`, `pkh()`, `wpkh()`, `sh()`, `wsh()`, `tr()` with
+an arbitrary script tree, `multi()`, `sortedmulti()`, and miniscript expressions
+(in `wsh()`, in `tr()` leaves, and in `sh()`, see the divergences below). Each
+is accepted only in the positions its BIP allows, so `sh(sh(…))`,
+`wsh(wsh(…))`, `wsh(wpkh(…))` and `tr()` outside the top level are rejected at
+parse time.
+
+**Key expressions**: hex public keys (33-byte compressed, 65-byte uncompressed,
+32-byte x-only in `tr()`), WIF private keys, `xpub`/`xprv` with derivation
+paths, `[fingerprint/path]` key origins, hardened steps, `/*` and `/*h`
+wildcards, and BIP389 `<a;b;…>` multipath elements. Which serialization is valid
+where follows BIP380 to BIP386: uncompressed keys in the pre-segwit positions
+only, x-only inside `tr()` only.
+
+**API**: `NewDescriptor`, `String` (with checksum), `Keys`, `DescType`,
+`MultipathLen`, `AddressAt`, `ScriptCodeAt`, `MaxWeightToSatisfy`, `Lift`, and
+`PlanAt` returning a `Plan` with `SatisfactionWeight`, `ScriptSigSize`,
+`WitnessSize` and `Satisfy`.
+
+## What is not supported
+
+| Expression | BIP | Why |
+|------------|-----|-----|
+| `combo()` | 384 | Stands for two or four output scripts; the API is one script per descriptor |
+| `raw()`, `addr()` | 385 | No keys and no satisfaction, so most of the API is meaningless for them |
+| `musig()` | 390 | Needs BIP327 key aggregation and BIP328 derivation |
+| `rawtr()`, `sp()` | - | Not implemented |
+
+Also absent, by design: no policy-to-miniscript compiler (rust-miniscript has
+one), no descriptor inference from an existing script (Core's
+`InferDescriptor`), no signing, and no PSBT integration - `Plan.Satisfy` takes
+finished signatures and returns raw witness and scriptSig bytes.
+
+## Divergences from Bitcoin Core and rust-miniscript
+
+Checked against Bitcoin Core `c4fbd3c7211` and rust-miniscript v13.
+
+| Behavior | Here | Core | rust |
+|----------|------|------|------|
+| Bare `multi()` above 3 keys | rejected | rejected (`descriptor.cpp:2419`) | accepted |
+| Miniscript inside `sh()` | accepted, compressed keys only | rejected entirely (`descriptor.cpp:2682`) | accepted, also with uncompressed keys |
+| `tr()` leaf other than `pk()`, e.g. `pkh()` | accepted | accepted | accepted |
+| `sh()` redeem script over 520 bytes | rejected | rejected (`descriptor.cpp:2427`) | rejected |
+| Plan scriptSig size for P2SH | counts the redeem script | n/a | excludes it, unlike its own `max_weight_to_satisfy` |
+
+The `tr()` leaf row is a divergence from the *letter of BIP386*, not from the
+implementations: BIP386 says only `pk()` may appear in a tree expression, but
+BIP379 and BIP387 postdate it and allow any miniscript fragment plus
+`multi_a()`/`sortedmulti_a()`. Editorial fixes for that and for four other BIP
+text issues found while implementing this are in
+`code-ingest/bip-text-issues-2026-08-05.md`, with the full reasoning for each
+divergence in `code-ingest/implementation-divergences-2026-08-05.md`.
+
+## Behavior worth knowing
+
+- **A P2WSH plan's witness omits the witness script.** `Plan.Satisfy` returns
+  the satisfaction elements only, and `WitnessSize` matches that, so a caller
+  building a transaction has to append the witness script itself. A legacy P2SH
+  scriptSig, by contrast, does include its redeem script, and a taproot
+  script-path witness includes the leaf script and control block. The P2WSH case
+  follows the reference this package was ported against; rust-miniscript
+  includes the witness script.
+- **Key validity is checked at derivation, not at parse time.** A hex key of the
+  right length that is not a point on the curve parses, and `AddressAt` is where
+  it fails. Core rejects it at parse time.
+- **A hardened step needs the private extended key.** `pkh(xpub…/0h/*)` is a
+  valid descriptor, but deriving from it fails; the same descriptor with an
+  `xprv` derives. This matches BIP380, where such an expression is valid.
+- **The network is a parameter of derivation, not of the descriptor.**
+  `AddressAt` takes the chain parameters, and the network bytes of an extended
+  key or a WIF key are ignored.
+- **The parsed miniscript must be sane**, i.e. non-malleable, signature-bound
+  and inside every resource limit of its context. See the miniscript README.
+- **A descriptor is bounded**: nesting depth, tap tree depth (128, BIP341),
+  multisig key counts and script sizes are all limited at parse time, so an
+  untrusted descriptor cannot exhaust memory, stack or CPU.
+
+## Testing
+
+Besides unit tests, the package is checked against three external references:
+the BIP test vectors of BIP380 to BIP389 (`testdata/bip_vectors.json`, run by
+`TestBIPVectors`, which also pins down what is unsupported), a
+rust-miniscript-generated corpus of descriptors with their addresses, script
+codes, weights, lifted policies and plans (`testdata/descriptors_from_rust.tsv`),
+and reference derivations from the descriptors-go implementation
+(`testdata/derivation.json`). `FuzzNewDescriptor` fuzzes the parser and the
+derivation paths.

descriptors/miniscript/README.md

@@ -0,0 +1,87 @@
+# miniscript
+
+Miniscript as specified in BIP379: parse an expression, analyze it, build its
+script, and produce a non-malleable satisfaction. Used by the
+[`descriptors`](../README.md) package, but usable on its own.
+
+## What is supported
+
+**Every BIP379 fragment and wrapper**, plus `multi_a()` (BIP387) and
+`sortedmulti_a()` (BIP387), including the syntactic sugar (`pk`, `pkh`, `and_n`,
+`t:`, `l:`, `u:`).
+
+**Three script contexts**, which decide the allowed fragments, the key
+serialization and the resource limits:
+
+| Context | Keys | Multisig | Script size | Ops | Other limits |
+|---------|------|----------|-------------|-----|--------------|
+| `P2WSH` | 33-byte compressed | `multi`, ≤ 20 keys | ≤ 3600 | ≤ 201 | ≤ 100 witness elements, ≤ 1000 stack elements |
+| `P2TR` | 32-byte x-only | `multi_a`/`sortedmulti_a`, ≤ 999 keys | ≤ 10000 | - | ≤ 1000 stack elements |
+| `Legacy` | 33-byte compressed | `multi`, ≤ 20 keys | ≤ 520 | ≤ 201 | ≤ 1650 byte scriptSig, no `or_i`, no `d:` |
+
+**Analysis**: the correctness type system (`B`/`V`/`K`/`W` plus the
+`zondumsfe` properties), malleability, timelock mixing, script size, op count,
+witness element count, execution stack peak and satisfaction size - the whole
+static analysis BIP379 describes.
+
+**API**: `Parse`, `ParseInsane`, and on the resulting `AST`: `Script`,
+`Satisfy`, `Keys`, `ApplyVars`, `Clone`, `Lift`, `DrawTree`, `IsSane`,
+`IsValidTopLevel`, `ScriptLen`, `MaxSatisfactionSize`,
+`MaxSatisfactionWitnessElements`.
+
+## What is not supported
+
+- **No compiler.** A policy cannot be compiled to miniscript; only the reverse
+  (`Lift`). rust-miniscript has a compiler behind a feature flag.
+- **No script decoding.** A miniscript cannot be recovered from raw script bytes,
+  which both Core and rust can do.
+- **Keys are opaque.** A key argument is an identifier until `ApplyVars`
+  substitutes bytes for it, and only its length is checked; whether it is a
+  valid curve point is the caller's business.
+
+## Divergences worth knowing
+
+- **`Parse` is sane by default.** It rejects expressions that are malleable,
+  need no signature, are not a valid top level, mix timelock kinds, or exceed a
+  resource limit - the same set rust-miniscript's `from_str` enforces through
+  `Ctx::SANE`. `ParseInsane` runs the analysis without those checks, for
+  inspecting an expression that is known not to be sane.
+- **The Tapscript script size limit is 10000 bytes**, not the block weight.
+  Tapscript imposes no script size limit of its own, but the script builder
+  cannot emit more, so the parse-time limit is what can actually be built rather
+  than a limit that would let an expression parse and never compile.
+- **The `Legacy` context is a rust concept.** Core does not accept miniscript
+  inside `sh()` at all (`descriptor.cpp:2682` in Core `c4fbd3c7211`). Where the
+  context exists here, it mirrors rust's: `or_i` and `d:` are rejected because
+  an `OP_IF` argument is not required to be minimally encoded outside segwit, so
+  a third party could malleate the branch selector. Unlike rust's, it takes
+  compressed keys only.
+- **The execution stack model differs from rust in three fragments.** For
+  `thresh`, `or_d` and `multi`, this package computes the true peak: rust's
+  value is an order-dependent conservative estimate for `thresh`, and one
+  respectively two elements short of the peak for `or_d` (the `OP_IFDUP` of a
+  satisfied first branch) and `multi` (the `<k>` and `<n>` around its keys). The
+  differential test records the difference. Every other computed property
+  matches rust exactly.
+- **The witness size of `d:` is one byte larger than rust's.** rust-miniscript
+  counts the `<1>` selector element that a `d:` satisfaction pushes as a single
+  witness byte, inconsistently with its own `or_i`, which counts the identical
+  element as two: its length prefix plus the byte itself. This package counts
+  two, so that a fee estimate covers the witness its satisfier really produces.
+- **Malleability propagation differs in one corner.** The satisfaction type has
+  no equivalent of rust's "impossible versus unavailable" distinction, so the
+  malleable flag of a non-sane threshold branch without a signature can differ.
+  Sane expressions are unaffected, and no satisfaction this produces is invalid.
+
+## Testing
+
+The package is checked against rust-miniscript by differential tests over about
+8,200 expressions per context: every computed property
+(`testdata/props_from_rust*.tsv`) and the byte-exact script encoding
+(`testdata/scripts_from_rust*.tsv`), plus parse agreement over roughly 13,700
+expressions. The corpora from rust's own test suite (`testdata/*.txt`) cover
+valid, invalid, malleable and timelock-conflicting expressions with their
+expected types. `execute_test.go` and `tap_test.go` run real spends through the
+btcd script engine, and `FuzzParse` fuzzes the parser and every downstream pass.
+See [`testdata/README.md`](testdata/README.md) for how the corpora were
+generated; they have since been contributed upstream as BIP379's test vectors.