A deterministic test harness for combining BIP 352 silent payments with BIP 77/78 payjoin.
A wallet that supports both features today turns one of them off when a payment request carries an
sp= silent payment address and a payjoin endpoint. Under BIP 77 and BIP 78 as written, that is the
right call. A silent payment output is derived from the sender's inputs, so when a payjoin receiver adds
an input of its own, the output the sender derived is no longer one a BIP 352 scan will find. The
receiver still holds the key, but a wallet restored from seed never finds the output.
The design this harness checks keeps both features on. The receiver re-derives every output that pays it over the final input set. For each input it adds, it attaches a BIP 375 ECDH share with a BIP 374 DLEQ proof. The sender verifies those proofs, derives the receiver's outputs itself, and accepts the proposal only if those outputs are present and pay at least what its original transaction paid. When anything fails, the sender broadcasts its original transaction, which is an ordinary silent payment.
The harness builds every transaction from the unmodified BIP 352 and BIP 374 reference code and checks what a receiver restoring from seed actually finds. It also checks what a thief holding various keys can and cannot get a sender to sign.
You need Python 3.9 or later. There is nothing to install.
python3 run_all.py
This runs, in order:
- the official BIP 352 and BIP 374 test vectors, through each BIP's own test runner;
- 109 scenarios with 542 assertions, grouped into eight modules;
- a symbolic check of the composition (19 claims).
A full run takes about four minutes, roughly one for the official vectors, one for the scenarios and
two for the symbolic check. --skip-official --skip-symbolic runs the scenarios alone. Every key,
outpoint and nonce comes from a fixed label, so every run produces the same output, and the run
rewrites vectors/*.json byte for byte.
git diff --exit-code vectors after a run is a cheap regression test.
Other options:
python3 run_all.py -v # print every assertion, not only failures
python3 run_all.py --list-mutations # the rules you can turn off
python3 run_all.py --mutate amount # turn one rule off and see which scenarios fail
python3 run_all.py --skip-official # skip the official BIP vectors
python3 run_all.py --bound 3 # three thief inputs in the symbolic check (slow)
python3 -m spj.composition_check -v # the symbolic check alone, with an example per finding
The exit status is 0 when everything passes.
Each modelled rule that the design relies on can be switched off with --mutate NAME. Switching off
any one of the 37 rules listed by --list-mutations turns at least one scenario red. For example, --mutate amount (the sender's amount check) fails S11c, and
--mutate coverage (rejecting a proposal that is missing a share) fails S26d.
| Module | Scenarios | Covers |
|---|---|---|
bip352_composition |
S1-S6 | The fallback payment; receiver inputs of each eligibility class and where they sort; receiver shares with DLEQ proofs; labels and k; other silent payment outputs in the same transaction; eligibility edge cases (NUMS script paths, annex, P2TR parity, ANYONECANPAY). |
sender_receiver_rules |
S7-S8 | A first set of sender and receiver rules in which the receiver replaces its output with an ordinary HD output. Later scenarios use these as the comparison case. |
reusable_strings |
S9-S14 | Re-deriving the replacement output instead, so a seed-only restore finds it; the sender's attempt gate; verified mode with the whole shared secret; coin tags against probing; receiver coin policy; queue stores and a public board at the directory; timing linkage. |
contact_strings |
S15-S25 | A reusable string handed to one counterparty: coin policies compared on the same event streams, the unspent check, the prevout lie and why a P2TR sender input defeats it, URI signalling, mailbox handoff, flooding, label linking, script-type matching, and an xpub alternative. |
per_input_proofs |
S26-S31 | BIP 375 per-input shares and BIP 374 proofs carried in PSBTv0 proprietary fields, what a mailbox-key thief can and cannot do, what the shares of several shown coins tell a prober together, where a sender P2TR input is required, coin selection trade-offs, full RBF, and a leaked string compared with a leaked xpub. |
sender_check_fixes |
S32 | Sender rules found missing by the symbolic check and by review, replayed on the real curve: check every proposal, count each derived script once, check witnesses against prevouts, and accept receiver inputs only of type P2TR, P2WPKH or P2SH-P2WPKH with a canonical scriptSig, since nothing signs a P2PKH scriptSig. |
burn_recovery |
S33 | What a receiver can recover if contact URIs do not require a sender P2TR input. |
contact_receivers_and_probes |
S34-S37 | A contact URI receiver that stays silent when it has no coin to add, Originals read from the mailbox that never count as a balance, the cost of probing a receiver for its coins, a separate keychain as coin source, seen inputs across all of a receiver's URIs, holding an offered coin until the payment confirms, the receiver's watch rule and its warnings, an organisation-paid contact URI with the receiver awake and asleep, queues that answer writes the same after rotation, and watching without per-item lookups. |
Some scenarios test alternatives the design considered and dropped, such as a fresh HD replacement output (S7-S8), verified mode with the whole shared secret (S11), and a per-contact coin policy (S15). They stay because later scenarios compare against them, and each title says what it tests.
The symbolic check (spj/composition_check.py) has three parts. Part 1 represents group elements as
exact integer polynomials in symbolic secrets and shows that the sender's shared secret equals the
receiver's scan secret for every input mix, then follows it through BIP 352 output and label derivation
for every k. Part 2 enumerates every proposal a modelled thief can build against the sender's rules,
for three thief profiles (mailbox key only; mailbox key plus a leaked ECDH share from the sender; mailbox
key plus the receiver's scan key), with and without a leak of the signed proposal. A thief can misdescribe
its input's prevout, its witness, or, for P2PKH and P2SH-P2WPKH, its scriptSig. Two earlier rule sets
run as regressions, so the check keeps the power to find the gaps they leave. Part 3 drops coverage,
proof verification and the contact P2TR rule one at a time and shows that a counterexample appears each
time.
The kind of string decides whether the receiver adds a coin, and there is no user setting. A one-time
URI adds one, one session at a time on a phone. A person's contact URI for an organisation that pays it,
such as a funder or employer, adds a coin from a separate keychain, never from the silent payment coins.
Shop and exchange strings add coins. A person paid repeatedly by another person, a donation page or any
public string gets a bare sp1 with no mailbox.
A contact URI receiver that has no coin to add for an Original, because it is asleep or its slot is taken, reads the Original and posts nothing, and the payer broadcasts at its reply-by time. An Original whose payment hasn't appeared after a window of at least 144 blocks makes the receiver warn and suggest checking with the contact before rotating the URI. Only an output found with the Original's own tweak is treated as a definite leak and rotates the URI at once.
The mutations nocoinsilent, coinsoff, phantom, warnonly and announced show what changes when
one of these rules is dropped.
Within the model, the harness shows that:
- the composition is algebraically correct for every input mix the symbolic check enumerates, and the real-curve derivation matches the reference code;
- under the sender rules as written, no modelled thief gets a sender to accept a proposal in which the receiver's scan finds less than the original transaction paid it, except one documented case (a one-time invoice paid by a sender with no P2TR input, where a mailbox-key thief can burn that one payment for a fee but cannot redirect it);
- coverage, proof verification and the contact P2TR rule are each necessary;
- each scenario's stated outcome holds on secp256k1 with the reference code, and switching off any modelled rule changes at least one outcome.
It does not show any of the following.
- DLEQ soundness or zero knowledge. The symbolic check treats a BIP 374 proof as sound by assumption. The real-curve scenarios call the reference prover and verifier but prove nothing about them.
- Unlinkability, or any other privacy property. Privacy scenarios are counting models with stated assumptions: candidate counts per event, Poisson arrivals, log-normal amounts, a fixed small payment history. They show the direction and rough size of an effect, not a bound.
- Anything beyond the bound. Part 2 covers one or two sender inputs over six script types and up to two
thief inputs (three with
--bound 3). Hashes are random oracles there. - Exact signature and mempool behaviour. P2WPKH signatures are modelled as BIP 143 digests rather than ECDSA. The mempool model applies BIP 125 rules 3 and 4 only, with no incremental relay fee, package rules or mining race.
- How real software behaves. The rust-payjoin sender and receiver checks, the directory and the queue stores are Python models of the cited code and designs, not the code itself. Network timing, crashes, restarts and persistence are not modelled.
run_all.py entry point
spj/core.py BIP 352/374 operations, inputs, wallets, restore scan
spj/framework.py scenario registry and the list of mutations
spj/chain_analysis.py script-type partition and payment interpretations
spj/scenarios/*.py the eight scenario modules above
spj/composition_check.py the symbolic check
spj/official.py runs the official BIP vectors
vectors/*.json recorded inputs, outputs, shares, proofs and checks per scenario
vendor/ BIP 352 and BIP 374 reference code, unmodified
Test vectors use the BIP 352 vector conventions: txids in display order, outputs as x-only hex, shares as compressed points.
The harness code is licensed under either of the MIT license (LICENSE-MIT) or the Apache License,
Version 2.0 (LICENSE-APACHE), at your option. The test vectors in vectors/ are dedicated to the public
domain under CC0 1.0 (vectors/LICENSE-CC0), so they can be copied into a BIP or another library without
a notice. The reference code under vendor/ keeps its own licenses: BSD-2-Clause for the BIP 352 and
BIP 374 reference implementations and vectors, MIT for secp256k1lab and two helper files.
vendor/README.md lists each file.
Unless you state otherwise, any contribution you submit for inclusion is dual licensed as above, and
contributions to vectors/ are dedicated under CC0 1.0, without any additional terms or conditions.