Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 110 additions & 1 deletion bip-0379.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,7 +405,116 @@ paths hit any of the limits.

## Test Vectors

TBD
### Conventions

Text files have one vector per line, no comments. `*.txt` is space separated,
`*.tsv` tab separated. Expressions contain no whitespace. A key argument is a letter
`A`..`Z` standing for the public key of the secret key `0x00…01` … `0x00…1a`,
serialized compressed in P2WSH and x-only in Tapscript. The limit vectors need more
distinct keys than that and write `K` followed by the secret key in decimal instead
(`K1`, `K2`, …). Hash arguments are literal hex. A type string is the basic type
(`B`/`V`/`K`/`W`) plus its properties (`zondumsfe`) in arbitrary order, so compare
sorted. Files with a `_tap` suffix are Tapscript (`multi_a`, x-only, Schnorr), the
others P2WSH.

### Files

| File | Lines | Line format | Asserts |
|------|-------|-------------|---------|
| `valid_from_alloy.txt` | 5,896 | `<expr> <type>` | parses, is a valid top level, has that type |
| `valid_8f1e8_from_alloy.txt` | 3,492 | same | same, corpus of an earlier upstream revision |
| `malleable_from_alloy.txt` | 7,024 | same | parses, has that type, but has no `m` property, i.e. is not sane |
| `conflict_from_alloy.txt` | 1,773 | same | parses and has that type; combines height- and time-based `after()`, on one spending path in 1,586 lines (not sane) and on alternative `andor` branches in the other 187 (sane) |
| `edge_cases.txt` | 42 | `<expr>` | a hand-written file: `thresh` at `k=1`/`k=n`, `multi` with 1 and 20 keys, all four hash fragments, the timelock boundaries (`499999999`/`500000000`, `4194304`/`4194305`), and the sugar forms |
| `invalid.txt` | 5,574 | `<expr>` | must be rejected (mostly type-check failures) |
| `opcodes.txt` | 18,185 | `<expr> <type> <ops>` | as above, plus the op count of a satisfaction, see `op_count` below |
| `limits.txt`, `limits_tap.txt` | 8, 2 | `<expr> <limit> <verdict>` | hand-written files: each resource limit at its boundary, `limit` being one of `ops`, `script_size`, `witness_elements` and `stack`. A `within` expression is sane; an `over` expression exceeds that limit by one and must be rejected, by the parser or by the sanity checks |
| `props_from_rust[_tap].tsv` | 8,198 + header | `expr script_size op_count sat_witness_elements exec_stack mixed_timelocks non_malleable requires_sig sat_size` | the static analysis, with the columns described below. A two-field row ending in `PARSE_ERR` must be rejected (1,470 of them in the Tapscript file, from the `multi`→`multi_a` substitution) |
| `scripts_from_rust[_tap].tsv` | 8,198 | `<expr>\t<script hex>` | the translation table byte for byte, incl. `v:` collapsing into the `VERIFY` opcode and minimal number encoding. `ERR` = no encoding in that context |
| `redeem.json` | 46 cases | JSON | optional satisfaction vectors: `{miniscript, valid, can_sign_N, …}` plus an `identifiers` map of keys, preimages and hashes |

### Resource Columns

This document specifies the resource limits, but not how to count the quantities
they bound, and implementations count them differently. The resource columns of
`props_from_rust[_tap].tsv` and `opcodes.txt` count them as rust-miniscript does:

* `script_size`: the size of the script in bytes, which the translation table
determines, so it does not depend on the implementation.
* `op_count` (`<ops>` in `opcodes.txt`): the non-push opcodes of the script plus the
keys of every `CHECKMULTISIG` a satisfaction executes, i.e. the quantity the 201-op
limit bounds. Tapscript has no op limit, so there the column has no meaning; it
counts a `multi_a` as no ops at all.
* `sat_witness_elements`: the number of witness elements of a satisfaction, plus one
in both contexts. The 100-element limit of P2WSH applies to this column minus one.
* `sat_size`: the size in bytes of a satisfaction, each element including its length
prefix, without the element count. Signatures are assumed to be 73 bytes for ECDSA
and 66 bytes for Schnorr, each including its length prefix.
* `exec_stack`: rust-miniscript's estimate of how many elements the script pushes
above its witness. It is not the exact peak: for a `thresh` it depends on the
order of the sub expressions, and for `or_d` and `multi` it falls short.

`op_count`, `sat_witness_elements` and `sat_size` are the maximum over every
satisfaction the fragment rules allow, including malleable ones, such as the
dissatisfaction of a hash fragment with a 32-byte value that is not the preimage.
Bitcoin Core counts only non-malleable satisfactions, which never dissatisfy a hash
fragment, and does not count the witness script as a witness element. An
implementation that counts like Core reproduces every other column, but differs on
`sat_witness_elements` in every row that has a satisfaction, and on roughly one in
ten op counts and one in five `sat_size` values.

The limits themselves do not depend on how these quantities are counted, as this
document says what each of them includes: `limits[_tap].txt` puts each limit at its
boundary, with expressions that contain no hash fragment.

### Execution

There is a Golang based minimal harness available that executes all test vectors against
the [Go implementation](https://github.com/btcsuite/btcd/pull/2568). It compares every
column of every file except `exec_stack`, as the Go implementation computes the exact
peak instead, and the Tapscript `op_count`. The `mixed_timelocks`, `non_malleable` and
`requires_sig` columns are compared through the sanity checks, which must reject an
expression that any of them disqualifies.

With at least `Go 1.25.0` installed, they can be run with:

```shell
$ cd bip-0379
$ go run main.go
```

### Provenance

The `*.txt` corpora, except the limit vectors, come from rust-miniscript's
`src/miniscript/ms_tests.rs` at `698b97f`. The `*.tsv` tables were extracted from
the same, unmodified commit by a program that prints what the crate computes for
each expression, and cross-checked against an
[independent Go implementation](https://github.com/btcsuite/btcd/pull/2568).

`redeem.json` comes from the Go implementation's end-to-end spend tests.

`limits[_tap].txt` were written for this document, and their verdicts checked
against Bitcoin Core, rust-miniscript and the Go implementation. rust-miniscript
counts the witness script towards the 100-element limit, so it rejects the
`within` vector of that limit.

## Gaps

The generated static-analysis corpora are dominated by `multi`, `sha256`, `after`,
`andor` and `or_d`; `older()`, `ripemd160()`, `hash256()`, `hash160()` and `and_n()` occur
only in the 42 hand-written lines, never in composition.

The following cases are still missing from the static-analysis corpora:

1. `older()` alongside `after()` in the positions `after()` appears in, since
the two differ in the relative/absolute timelock analysis, and the generated
corpora only ever use `after()`.
2. The 1,000 stack element limit in P2WSH, and in Tapscript a `multi_a` at that
limit, which needs a script of 33 KB that not every implementation accepts.
3. The four timelock-mixing combinations of the BIP's own wording (absolute
height with absolute time, relative height with relative time, and the two
legal mixes), which `conflict_from_alloy.txt` covers only for `after()`.


## Backwards Compatibility

Expand Down
Loading
Loading