Skip to content

Silent payments: BIP-352 addresses and BIP-375 sending - #556

Open
kkdao wants to merge 11 commits into
ElementsProject:masterfrom
kkdao:feat/silent-payments
Open

kkdao wants to merge 11 commits into
ElementsProject:masterfrom
kkdao:feat/silent-payments

Conversation

@kkdao

@kkdao kkdao commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

The goal is end to end silent payments on Jade, retail and DIY: show the
device's own sp1 address, sign a send to an sp1 address (BIP-375 with the
BIP-374 proof) and spend a received silent payment (BIP-376). Jade does its
PSBT handling through libwally, so this comes first. This PR covers addresses,
proofs and sending; BIP-376 spending comes next.

Commits, each with its own tests:

  1. addr: Add BIP-352 silent payment addresses. Encode and decode sp/tsp
    addresses (bech32m, up to 1023 characters). Decoding accepts versions 1
    to 30 and keeps their first 66 bytes, rejects version 31, and rejects a
    version 0 address with extra data, as BIP-352 requires. Tested against
    every recipient in the BIP-352 vectors.
  2. psbt: Parse BIP-375 silent payment outputs. PSBT_OUT_SP_V0_INFO and
    PSBT_OUT_SP_V0_LABEL are parsed, validated and serialized for v2 and
    rejected in v0. A v2 output may leave out PSBT_OUT_SCRIPT only when it
    has a silent payment code. A label without a code is refused both when
    parsing and when writing. No transaction can be built (so no signing or
    extraction) while any silent payment script is missing, and a PSBT with a
    code cannot be converted to v0. The BIP-373 output field 0x08 inside the new
    range stays an unknown field.
  3. psbt: Identify silent payment PSBTs by their codes. The unique id uses
    a zero byte and the silent payment code in place of the script, as
    BIP-375 defines, so it does not change once a signer fills the scripts
    in. Combine takes a computed script from whichever side has it, and
    still refuses two different computed scripts.
  4. crypto: Add BIP-374 DLEQ proof generation. wally_dleq_proof_generate()
    and wally_dleq_proof_verify(), defaulting to the secp256k1 generator.
    Generation multiplies the private key and nonce through secp256k1's
    constant time ECDH routine (secp256k1_ec_pubkey_tweak_mul is variable
    time, so it is only used on public values in verification), and the
    nonce is reduced modulo n in constant time. Tested against every case
    in the BIP-374 vectors.
  5. psbt: Parse BIP-375 ECDH shares and DLEQ proofs. Global 0x07/0x08 and
    input 0x1d/0x1e, keyed by scan key, in new sp_ecdh_shares and
    sp_dleq_proofs maps on wally_psbt and wally_psbt_input (this changes the
    struct layout). v2 only; kept as unknowns in PSETs. The BIP-373 MuSig2
    input fields 0x1a-0x1c inside the new range stay unknown fields.
  6. psbt: Compute BIP-375 silent payment scripts.
    wally_psbt_compute_sp_scripts() finds the eligible inputs and their keys
    (BIP-352: P2TR unless its internal key is NUMS H, P2WPKH, P2SH-P2WPKH,
    P2PKH; uncompressed keys are skipped; segwit v2+ inputs fail), also for
    finalized inputs, verifies every DLEQ proof present for an eligible input
    or the whole transaction, derives each script with the BIP-375 ordering,
    up to the BIP-352 limit of 2323 per scan key, sets missing scripts, checks
    present ones, and clears the modifiable flags. It changes nothing if any
    step fails. Parsing also rejects a PSBT whose silent payment
    script is set while inputs or outputs are still modifiable.
  7. psbt: Add BIP-375 ECDH shares from input keys.
    wally_psbt_add_sp_ecdh_shares() takes one private key per input and adds
    a global share per scan key when the keys cover every eligible input, or
    per-input shares otherwise. Secret multiplications are constant time.
  8. psbt: Sign with SIGHASH_ALL for silent payments. With silent payment
    outputs present, signing and the signature hash use SIGHASH_ALL, also
    for taproot when no sighash is given, and any other sighash is refused.
  9. psbt: Verify silent payment scripts before signing. Every call that makes
    a signature, and wally_psbt_extract(), verifies each silent payment
    script, so a coordinator cannot pre-fill one paying its own key. A PSBT
    that is not v2 but has a code fails these checks.
  10. psbt: Require proven prevouts to sign ECDSA. An ECDSA signature does not
    commit to the other inputs' prevout scripts, so a co-signer's false witness
    utxo could change the key sum and strand the payment. With silent payment
    outputs, signing or hashing a non-taproot input requires a non-witness utxo
    on every input. Taproot signatures commit to all prevout scripts, so witness
    utxos stay enough for them. This is stricter than BIP-375, whose vectors
    only supply witness utxos, so those vectors compute but do not sign here.
  11. psbt: Bind silent payment signing to the PSBT. A signature over something
    else would make those checks worthless. With silent payment outputs,
    wally_psbt_get_input_signature_hash() verifies the scripts and refuses any
    transaction but the one the PSBT describes,
    wally_psbt_sign_input_bip32() refuses any hash but that transaction's, and
    the signing cache is not used.

The deliberate differences from the BIP-375 reference validator all come from
one rule: leaving an input out of the key sum, or using the wrong key for it,
gives a script the receiver cannot find, so a coordinator must not be able to
cause that. An eligible input's public key must hash to its P2WPKH, P2PKH or
P2SH-P2WPKH prevout script, and a P2SH redeem script must hash to its prevout;
the validator takes the first BIP32 derivation key unchecked. A finalized input
is only skipped if its data really spends the prevout. A NUMS internal key,
from the field or a control block, must match the output key; the validator
trusts the field. A non-witness utxo must match the input and agree with any
witness utxo.

What a malicious coordinator controls, and what happens if it lies: an output
script (verified against its code before any signature or extraction); a
silent payment code (not checkable here: a signer must show it to the user);
an ECDH share or proof (verified against the input keys); an input's key, final
data or NUMS claim (must match its prevout, as above); the sighash and
modifiable flags (refused unless BIP-375 allows them); a non-witness utxo
(checked against the input); a witness utxo (required to be backed by a
non-witness utxo on every input before a non-taproot signature); the PSBT
version (a code cannot be converted to v0, and a v0 PSBT with a code from loose
parsing signs nothing); a caller's transaction or hash, should a coordinator
supply either (refused unless it matches the PSBT).

A signer still has to show the user each output, as the library cannot judge
these: an output with no code is a plain output; an added output sharing the
recipient's scan key takes k=0 and can leave the recipient's output unfindable;
PSBT_OUT_SP_V0_LABEL is not checked; wally_psbt_add_sp_ecdh_shares() multiplies
any scan key it is given by the input keys, so call it only after approval; and
a pre-filled garbage signature makes wally_psbt_sign() return without signing.

Each attack test runs the public signing calls and asserts no signature comes
out, and fails with its fix removed.

New public struct members: sp_ecdh_shares and sp_dleq_proofs on wally_psbt and
wally_psbt_input, which changes the struct layout. The output fields live in the
existing psbt_fields map, with get/set/clear accessors for the silent payment
code.

This touches the same PSBT files as draft #535 (Tapscript and MuSig2), and a
trial merge conflicts in eight files. It is not the same work: the BIP-373
MuSig2 fields stay unknown fields here, and #535 parses them. I am happy to do
the rebase if this lands second.

The official vectors' P2WPKH prevout scripts do not commit to their keys, so the
tests correct those scripts first; output scripts depend only on the keys and
outpoints, so the expected scripts are unchanged. I plan to raise this with the
vector authors.

Test vectors are pinned: BIP-375 from bitcoin/bips a34f044b (vectors 1.1.1, BIP
0.1.3) and BIP-374 from bitcoin/bips afaa8566. The BIP-352 vectors are read from
the bundled secp256k1-zkp silentpayments module.

Tests run every BIP-375 vector (bitcoin/bips a34f044b): each finalizable
vector's scripts are recomputed from its shares, and again from its input
private keys as both one global share and per-input shares; every invalid
vector is rejected by parsing or by computing. All 28 BIP-352 sending
vectors also run through both functions, built as finalized PSBTs: malleated
P2PKH, uncompressed keys, invalid P2SH, NUMS inputs, keys summing to zero and
K_max. Further tests cover inputs crafted to be left out of the key sum, P2SH
redeem script checks, both taproot key parities, clone and combine of the new
maps, and the signing rules below.

I also fuzzed parsing, wally_psbt_get_id, clone, combine, both new functions,
signing, signature hashes, extraction, address decoding and the DLEQ code, seeded
with the official vectors: 20 minutes and about 8 million inputs under ASan, UBSan
and LeakSanitizer (with alignment checks off, for an unaligned read in ccan sha256
this PR does not touch), and 10 minutes and about 7 million inputs under
MemorySanitizer (built with memset, as it cannot see explicit_bzero). The harness
also aborts if signing or extraction succeeds on a PSBT whose scripts do not verify,
or if an ECDSA signature is added without every prevout proven. Neither run found
anything in this code. The harness is not part of this PR; I can add it to fuzz/ if
you want it.

Cross-checked against an independent implementation: PSBTs signed by
wally_psbt_add_sp_ecdh_shares() and wally_psbt_compute_sp_scripts() pass
the BIP-375 verifier in kiss-bdk (Rust, BDK and bdk-sp), which I use as
the coordinator for DIY signers, on 14 of the 16 finalizable vectors. The
other two hit simplifications in that verifier (k order for differently
labelled codes under one scan key, and NUMS inputs); in both, libwally
produces the official vectors' scripts.

Testing: make check and every Python test file pass on the final commit, and each
commit passes its own tests. The .gitlab-ci.yml amalgamation, no-elements, CMake,
MinGW, scan-build, gcc ASan/UBSan and valgrind lanes all pass in every matrix
configuration on the final commit, run locally with the same commands on Debian
trixie (GCC 14, clang 19), on arm64 rather than your x86 image. GCC on arm64 needed
-flax-vector-conversions -fsigned-char for scrypt and ccan base64 code this PR does
not touch. The valgrind lanes ran the C tests and the changed Python test files. I
did not run the Java, wheel, npm or release jobs.

Known and left for later:

  • BIP-376 (spending received silent payments) comes next. PSBT_IN_SP_TWEAK is
    0x20, so it also widens the input field bitset, which tops out at 31 today.
  • wally_psbt_to_bytes still writes a PSBT whose silent payment script was set by
    hand while the modifiable flags were on; parsing then rejects it.
    wally_psbt_compute_sp_scripts never produces one.
  • When the modifiable flags are zero, wally omits PSBT_GLOBAL_TX_MODIFIABLE, as
    BIP-370 allows; the BIP-375 reference validator expects the field.
  • wally_psbt_get_id still zeroes the locktime by default, as it did before,
    rather than using the BIP-370 computed one.

Older problems, not from this work, that I can fix separately:

  • Parsing with WALLY_PSBT_PARSE_FLAG_LOOSE leaks memory when a v2 PSBT also
    carries a v0 global transaction.
  • Parsing the bytes psbt\xff\x00 with WALLY_PSBT_PARSE_FLAG_LOOSE and then
    calling wally_psbt_set_version(psbt, 0, 2) dereferences NULL in psbt_v0_to_v2.
  • Outside silent payments, the signing cache is not tied to a transaction, so
    reusing it across different transactions gives a stale hash.

@jgriffiths

Copy link
Copy Markdown
Contributor

Hi @kkdao great stuff!

I am focused on getting the Jade 1.0.42 release out, once that is done I will look to add the descriptor work this relies on and this change after that.

In the meantime I am working on a wally 1.6.1 branch with minor fixes which I hope to release soon (a few days to a week). The branch is here: https://github.com/ElementsProject/libwally-core/tree/post_1_6_0_updates - if you'd like to fix the older problems you mentioned, targeting that branch, that would be great if possible. Thanks!

@kkdao kkdao mentioned this pull request Nov 11, 2026
kkdao added 11 commits November 12, 2026 17:24
A silent payment address is bech32m with an sp or tsp prefix, a
version, and the receiver's scan and spend public keys. It may be up
to 1023 characters, so it cannot use the 90 character segwit address
code.

Add wally_addr_silent_payment_from_bytes(), which writes a version 0
address, and wally_addr_silent_payment_to_bytes(), which returns the
two keys. As BIP-352 requires, decoding accepts versions 1 to 30 and
keeps only their first 66 bytes, rejects version 31, and rejects a
version 0 address carrying extra data. Both keys must be valid
points. The tests use every recipient in the BIP-352 vectors.
A BIP-375 output to a silent payment address carries the receiver's
scan and spend public keys in PSBT_OUT_SP_V0_INFO, with an optional
PSBT_OUT_SP_V0_LABEL used to verify change. Its PSBT_OUT_SCRIPT is
left out until a signer computes it from the inputs' private keys.

Parse, validate and serialize both fields for PSBTv2, and reject them
in v0, including when converting a PSBT with a code to v0. Allow a v2
output without a script only when it has a silent payment code, and
reject a label without one. A transaction cannot be built while any
silent payment script is missing, so signing and extraction fail until
the signer has filled them in. Add accessors for the silent payment
code.

The BIP-373 MuSig2 output field 0x08 sits inside the new range and
is still kept as an unknown field. Tests use the BIP-375 vectors
from bitcoin/bips commit a34f044b.
BIP-375 computes a PSBT's unique id with each silent payment output's
script replaced by a zero byte and its silent payment code, so the id
is the same before and after a signer computes the scripts. Without
this, a PSBT with an unresolved output had no id at all, and combine,
which compares ids, refused it.

Build the id that way, and let combine take a computed script from
either side when the other side does not have it yet. Two different
computed scripts for the same output still fail to combine.
A BIP-375 signer that computes a silent payment ECDH share also
publishes a BIP-374 proof that the share came from the inputs' own
private keys, so anyone holding the input public keys can check a
share before relying on the output script derived from it.

Add wally_dleq_proof_generate() and wally_dleq_proof_verify(). The
generator defaults to the secp256k1 one, as silent payments use.
Generation multiplies the private key and nonce through the constant
time ECDH routine and reduces the nonce modulo the group order in
constant time; verification only handles public values. Tests run
every case in the BIP-374 vectors from bitcoin/bips commit afaa8566.
BIP-375 signers publish an ECDH share and a BIP-374 proof for each
silent payment scan key, either once for all inputs (global fields
0x07 and 0x08) or per input (fields 0x1d and 0x1e). Until now these
were kept as unknown fields with no validation.

Parse, validate, serialize and combine them for PSBTv2, reject them
in v0, and leave them unknown in PSETs. They are keyed by scan key, so
they get new sp_ecdh_shares and sp_dleq_proofs maps on the PSBT and
its inputs, which changes the layout of both structs. The BIP-373
MuSig2 input fields inside the new range stay unknown fields.
A silent payment output's script depends on the ECDH shares of the
transaction's eligible inputs, so a signer or coordinator has to
derive it rather than read it from the PSBT.

Add wally_psbt_compute_sp_scripts(). It finds the eligible inputs and
their keys under the BIP-352 rules, verifies every DLEQ proof present
for an eligible input or the whole transaction, derives each script
in the BIP-375 order, sets missing scripts, checks present ones and
clears the modifiable flags. It changes nothing if any step fails.

An eligible input's key must hash to its prevout script, and a P2SH
redeem script must hash to its prevout. A key that is not the one
actually spent makes the payment unfindable by its receiver. The
BIP-375 reference validator does not check this and its vectors' P2WPKH
prevouts do not commit to their keys, so the tests correct those
prevouts first; output scripts depend only on keys and outpoints.

Parsing now also rejects a PSBT whose silent payment script is set
while its inputs or outputs are still modifiable, as BIP-375 requires.
A signer holding the private keys of a transaction's inputs writes the
ECDH shares and DLEQ proofs that wally_psbt_compute_sp_scripts() reads.

Add wally_psbt_add_sp_ecdh_shares(). It takes one private key per input
and adds one share per scan key when the keys cover every eligible
input, or a share per held input otherwise. A taproot key is accepted
with either parity, and a key that does not match its input is refused.
Secret multiplications go through secp256k1's constant time ECDH.

Tests rebuild every finalizable BIP-375 vector's scripts from its input
keys both ways, and cover eligibility, parity, clone and combine.
Silent payment scripts are derived from the position of each code, so
a signature that does not commit to every output could let them be
moved or dropped. BIP-375 therefore allows only SIGHASH_ALL.

With silent payment outputs present, signing and the signature hash
now use SIGHASH_ALL, also for taproot when no sighash is given, and any
other sighash is refused, as it is by wally_psbt_compute_sp_scripts().
A silent payment output's script is only trustworthy once derived from
its code. A coordinator can pre-fill it with a script paying its own
key, and wally_psbt_sign() signed that, as only a missing script was
refused. wally_psbt_compute_sp_scripts() caught this, but nothing made
a signer call it.

Verify every silent payment script, unchanged, in each call that makes
a signature and in wally_psbt_extract(), which BIP-375 requires of an
extractor and which callers use to build the transaction they hash.
A PSBT that is not v2 but has a code, which loose parsing can produce,
fails these checks rather than skipping them.
wally_psbt_get_input_signature_hash() takes a caller's transaction and
does not verify, so its documentation says a caller signing the hash
itself must call wally_psbt_compute_sp_scripts() first.
An input's prevout script decides whether it counts towards a silent
payment's key sum. A witness utxo cannot be checked, and an ECDSA
signature does not commit to the prevout scripts of the other inputs.
A co-signer could claim its real P2WPKH input is a P2WSH: the signer
would derive an output without that key, and the signature stays valid
for the real transaction, whose receiver cannot find the payment.

With silent payment outputs, refuse to sign or hash a non-taproot input
unless a non-witness utxo proves the prevout of every input. A taproot
signature commits to all of the prevout scripts, so a false one only
makes it invalid, and witness utxos stay enough for it.
Checking a PSBT does not protect a signature over something else.
wally_psbt_get_input_signature_hash() takes a caller's transaction and
wally_psbt_sign_input_bip32() takes a caller's hash, so a transaction
paying an attacker could be hashed and signed while the unchanged PSBT
still verified. The signing cache could also supply parts of such a
transaction to wally_psbt_sign().

With silent payment outputs, the hash call now verifies the scripts and
refuses any transaction other than the one the PSBT describes, the
input signing call refuses any hash but that transaction's, and the
cache is not used. A caller no longer has to remember to verify first.
@kkdao
kkdao force-pushed the feat/silent-payments branch from 363627d to 24fd744 Compare November 12, 2026 08:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants