Skip to content

feat: Silent Payments (BIP-352) — address, descriptor and signing - #925

Draft
notTanveer wants to merge 11 commits into
selfcustody:developfrom
notTanveer:feat/silent-payments-V2
Draft

notTanveer wants to merge 11 commits into
selfcustody:developfrom
notTanveer:feat/silent-payments-V2

Conversation

@notTanveer

@notTanveer notTanveer commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

adds Silent Payments (BIP-352) as a fourth single-sig policy ("Single-sig SP"). P2TR only, marked experimental.

  • receive: shows the sp1/tsp1 address (text, QR, SD). the scan key is exported from the xpub screen behind a privacy warning. no output descriptor, SP wallets describe themselves
  • send: signs PSBTs paying SP outputs (BIP-375/376). the taproot scripts are derived while loading, so a PSBT this seed can't sign is rejected before review. review shows the sp1 address and the taproot address it lands on
  • own SP change (label 0) and self-transfers are recognised on any single-sig wallet, not just the SP policy
  • only P2PKH, P2WPKH, P2SH-P2WPKH and P2TR inputs. multisig and miniscript are refused
  • the signed PSBT is returned unfinalized on purpose. embit finalizes taproot key-path inputs, so we clear them, otherwise coordinators skip the merge of the derived scripts, ECDH shares and DLEQ proofs
  • DLEQ aux_rand comes from seed + PSBT hash + ticks, not the K210 RNG. BIP-374 binds the nonce to the statement so this is safe
  • QR output drops the BIP-376 sp_tweak fields (~70 bytes per input), SD output keeps them
  • bumps embit. datum tool adapted to bech32_decode raising Bech32DecodeError

signing warns the user to verify the sp1 address with the recipient, never the derived P2TR.

blocked on embit #145

sign flow:

sequenceDiagram
    participant U as User
    participant H as home.sign_psbt
    participant S as PSBTSigner
    participant E as embit
    U->>H: Sign > PSBT (QR or SD)
    H->>S: PSBTSigner(wallet, data)
    S->>S: validate policy, fees, input amounts
    S->>S: SP eligibility (no multisig/miniscript, P2PKH/P2WPKH/P2SH-P2WPKH/P2TR only)
    S->>E: sp_output_scripts(root)
    E-->>S: taproot script per SP output, or reject if inputs are not all ours
    H->>S: outputs()
    S-->>H: sp1 address + taproot address page per SP output
    H->>U: warnings, then review
    U->>H: Sign to QR or SD
    H->>S: sign(trim)
    S->>E: sign_with(root, aux_rand)
    E-->>S: sigs + ECDH shares + DLEQ proofs
    S->>S: scripts must match what was reviewed
    S->>S: clear final_scriptwitness/final_scriptsig
    S-->>U: unfinalized PSBT for the coordinator
Loading

@codecov

codecov Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.96049% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.56%. Comparing base (2937a29) to head (f13f76d).

Files with missing lines Patch % Lines
src/krux/pages/home_pages/home.py 50.00% 4 Missing ⚠️
src/krux/silent_payments.py 91.30% 4 Missing ⚠️
src/krux/psbt.py 98.63% 2 Missing ⚠️
Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #925      +/-   ##
===========================================
- Coverage    97.60%   97.56%   -0.05%     
===========================================
  Files           84       85       +1     
  Lines        10994    11218     +224     
===========================================
+ Hits         10731    10945     +214     
- Misses         263      273      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch from 48aeeaf to d8b3c47 Compare August 10, 2026 16:28
@qlrd

qlrd commented Aug 12, 2026 •

Copy link
Copy Markdown
Member

Thxs @notTanveer/@odudex i will do a proper check on my side and LYN.

@qlrd

qlrd commented Aug 22, 2026

Copy link
Copy Markdown
Member

all LGTM with sparrow against 2.5.3 (compiled). Tested a first time with:

git submodule update --recursive
uv sync --frozen --reinstall-package=uUR
uv run poe secp256k1-build
uv run poe secp256k1-check
uv run poe pre-commit
./krux build-release

And tested with Amigo only for now.

@jdlcdl

jdlcdl commented Aug 24, 2026 •

Copy link
Copy Markdown
Member

Wow, this is so neat!

The commonly used krux-devs' "gramps" wallet on signet now has a silent-payment tx:
6bf8cdddc2ca513ec03dd17ae520804fe520fae1c6aea140d4afdde036ebc540
...of 1m sats from gramps' native-segwit to his SP (acct#0) wallet.

Continuing with testing, another tx exists in the same wallet sending 50k sats back to gramps native-segwit and collecting the rest into a different SP address as change:
ea0cf1dbbf45528150875c9c6ad33623e3591b80c27a5b2a9a2138c8f93423f7

All working for me up to this point as-of commit 2ddb821, even though this PR is still in draft.


Problem when paying to self (is that even something one would try?)

I did provoke an error along the way, which is an odd-case (not a real use-case, or would it be de-consolidating?),
where I setup to send the original tx back to gramps w/ change and ALSO an output to gramps' very own SP address. Sparrow set it up just fine, krux pr_925 branch signed w/o errors (showing same SP addresses that Sparrow shows), but upon loading the signed PSBT back into Sparrow and expecting to be able to broadcast/update-tx, an error about invalid SP address appears in a dialog window.
pr925-SP-invalid-sp-address
I cannot share the PSBT here, but I have a copy of it saved if needed for inspection.

@qlrd

qlrd commented Aug 24, 2026

Copy link
Copy Markdown
Member

Problem when paying to self (is that even something one would try?)

had exact same error in a first try with other @notTanveer SP PR, with same context reported by you.

@notTanveer

notTanveer commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor Author

an error about invalid SP address appears in a dialog window.

this goes away once drongo#50 lands.

it's a spec issue more than a sparrow one. bip-375's text says to sort the silent
payment codes lexicographically and then by output index in ascending order if there are multiple silent payment codes with the same scan/spend keys before assigning k, but the test vectors and the
reference validator shipped in bitcoin/bips still assign k by output index, so
implementations ended up split depending on which of the two they built against.
bitcoin/bips#2207 brings the vectors
and the reference back in line with the text, and it's still open.

krux follows the text, so nothing changes on our side. drongo#50 moves sparrow to
the same order and then the two agree.

it only shows up when a tx has two or more sp outputs sharing a scan key, so paying
the same address twice, or paying yourself with sp change like in this case. with a
single sp output k is always 0 and everyone agrees.

thanks for reporting, @jdlcdl & @qlrd

@qlrd

qlrd commented Aug 28, 2026

Copy link
Copy Markdown
Member

an error about invalid SP address appears in a dialog window.

this goes away once drongo#50 lands.

it's a spec issue more than a sparrow one. bip-375's text says to sort the silent payment codes lexicographically before assigning k, but the test vectors and the reference validator shipped in bitcoin/bips still assign k by output index, so implementations ended up split depending on which of the two they built against. bitcoin/bips#2207 brings the vectors and the reference back in line with the text, and it's still open.

krux follows the text, so nothing changes on our side. drongo#50 moves sparrow to the same order and then the two agree.

it only shows up when a tx has two or more sp outputs sharing a scan key, so paying the same address twice, or paying yourself with sp change like in this case. with a single sp output k is always 0 and everyone agrees.

thanks for reporting, @jdlcdl & @qlrd

thxs for feedback @notTanveer. I will give more check on those PRs.

@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch 2 times, most recently from 7bc9fa4 to df03845 Compare August 28, 2026 13:17
@notTanveer

Copy link
Copy Markdown
Contributor Author

rebased

@jdlcdl

jdlcdl commented Aug 28, 2026 •

Copy link
Copy Markdown
Member

drongo#50 moves sparrow to the same order and then the two agree.

I confirm that with Sparrow 2.5.4 and no changes (except for your rebase) to krux solves the issue where Sparrow errored upon scanning the signed SP input paying to an external address, its own SP address and one SP change address, is resolved.

I had errors broadcasting but I suspect it is some new problem between Sparrow 2.5.4 and frigate 2.5.3. I was able to view the updated (extracted) tx and broadcast it via bitcoin-cli. Sparrow 2.5.4 had no problem identifying the new utxos while in mempool and once confirmed.

Thank you!

@qlrd qlrd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just nit/doubt. IMP htis could be less (not too much) diff

Comment thread src/krux/pages/home_pages/addresses.py Resolved
Comment thread src/krux/pages/home_pages/addresses.py Resolved
Comment thread src/krux/pages/wallet_settings.py Resolved
Comment thread tests/pages/test_wallet_settings.py Resolved
Comment thread tests/pages/test_login.py Resolved
Comment thread tests/test_wallet.py Resolved
Comment thread tests/test_wallet.py Resolved
Comment thread tests/test_wallet.py Resolved
Comment thread tests/test_wallet.py Resolved
Comment thread tests/test_wallet.py Resolved
Comment thread src/krux/pages/home_pages/addresses.py Resolved
@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch from b116bee to 0b2fda2 Compare September 1, 2026 19:56
@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch 4 times, most recently from 53bb486 to cf49505 Compare September 14, 2026 14:10
@notTanveer
notTanveer marked this pull request as ready for review September 14, 2026 14:45
@notTanveer
notTanveer marked this pull request as draft October 3, 2026 11:05
notTanveer and others added 8 commits October 16, 2026 01:59
Pulls in the embit work the Silent Payments feature depends on:

  BIP-352  silent payment address generation and scanning
  BIP-370  PSBTv2
  BIP-374  DLEQ proofs
  BIP-375  SP output derivation and PSBT fields
  BIP-376  spending from SP outputs
  BIP-392  sp() descriptor

Also carries a bech32 fix for larger payloads and secp256k1 fixes for
mutable keys in tweak functions plus ec_pubkey_tweak_mul/combine
fallbacks.

bech32_decode now raises Bech32DecodeError instead of returning a
sentinel, so the Datum Tool is adapted in the same commit: every
encoding probe against a non-bech32 payload would otherwise propagate
out of _analyze_contents rather than simply ruling that encoding out.
Catching it and treating it as "not bech32" is what the old sentinel
return meant.

Co-authored-by: odudex <odudex@proton.me>
Introduces TYPE_SILENT_PAYMENT alongside single-sig, multisig and
miniscript, wired through key derivation, the wallet model, settings and
the wallet-creation flow.

  - Key derives the BIP-352 scan and spend keys from m/352h/<coin>h/<n>h
    ("/1h/0" scan, "/0h/0" spend) and exposes sp_address() and
    sp_scan_key() for the sp() descriptor key expression.
  - The policy always uses P2TR, so script_type is forced regardless of
    what the caller passes.
  - Wallet accepts an sp() descriptor and reports the new policy.

No UI for showing or exporting the address yet; that follows.
Adds the user-facing side of the Silent Payments policy.

  - The address screen renders the sp1/tsp1 address as a Text/QR menu
    with block highlighting, so the long address can be read out in
    chunks and compared reliably.
  - The public-key screen exports the BIP-352 scan key with its
    [fingerprint/derivation] origin prefix on both the QR and the
    SD/text paths, and exports the wallet as an sp(...) descriptor
    rather than a bare key.
  - The descriptor screen accepts and displays sp() descriptors.

display_addr_highlighted() grows a bg_color argument so the highlighted
blocks can be drawn against the address screen's background.

Co-authored-by: odudex <odudex@proton.me>
Krux acts as the BIP-375 Signer: it derives the Taproot output scripts,
attaches the global ECDH shares and DLEQ proofs, and hands back an
*unfinalized* PSBT so the coordinator can verify the outputs before
finalizing. embit finalizes taproot key-path inputs on signing, so the
inputs are explicitly cleared afterwards; leaving them finalized makes
coordinators skip the merge that picks up the derived output scripts.

Eligibility and ownership are checked while loading, not after review:
a PSBT this seed cannot sign is rejected up front. Only the BIP32 half
of the ownership check runs there -- the ECDH/DLEQ work happens once,
inside sign_with().

Also:
  - P2PKH, P2SH-P2WPKH, P2WPKH and P2TR inputs are all supported.
  - DLEQ aux_rand is hedged from the seed and the PSBT rather than the
    K210 RNG. BIP-374 binds the proof nonce to the statement, so the
    near-deterministic input is safe.
  - The trimmed QR artifact keeps the SP outputs, ECDH shares and DLEQ
    proofs but drops the coordinator-authored BIP-376 sp_tweak fields,
    which would add ~70 bytes per input to the animated QR.
  - Validation is now a single point for every load path; a validation
    failure must never fall back to another encoding, which would
    re-read the PSBT with CompressMode.CLEAR_ALL and strip the SP fields.
  - Signing warns that the sp1/tsp1 address must be verified with the
    recipient, never the derived P2TR shown on-chain.

Own SP change is not recognised yet, so SP outputs classify as spends;
that follows.

Co-authored-by: odudex <odudex@proton.me>
An SP output pays a derived P2TR that nobody but the recipient can link
back to the SP address, so change sent to our own SP address would
otherwise render as a spend to a stranger.

Key.sp_detection_keys() derives the BIP-352 scan/spend keys from the
seed for *any* wallet, not only ones loaded with the Silent Payments
policy, so SP change is recognised even when the same seed was loaded
as plain single-sig. A wallet using a non-default SP account simply
fails the ownership check and the output stays a spend, which is the
safe direction.

own_sp_output_type() matches the output's scan key and then its spend
key, applying the BIP-352 label tweak when the output carries one:
label 0 is change, any other label is a self-transfer.

The keys are derived once per PSBT and cached on the signer, since
_classify_output needs them for every SP output and each derivation is
two 5-level hardened BIP32 paths.

de duplicated own_sp_output_type which was an identical copy of embit's
apply_label and check_sighash() restored.

Co-authored-by: odudex <odudex@proton.me>
Registers the new Silent Payments strings across the locale files and
the baked translation modules.

The ja-JP and zh-CN strings are worded to stay inside the glyph set the
device fonts already carry, so no font rebuild is needed: they end in an
ASCII period like the surrounding translations rather than U+3002, and
avoid characters no other translation uses. `poe missing-glyphs` reports
nothing missing, as on develop.
@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch 2 times, most recently from df84181 to 0ee9ac5 Compare October 27, 2026 10:17
chore: bump embit

- Bump vendor/embit to pick up strict SP network names, the DLEQ challenge fix and sp_output_scripts
- Derive the SP output scripts while loading the PSBT with embit's sp_output_scripts, replacing the hand-rolled ownership check
- Add a review page after each SP output with the taproot address it lands on
- Refuse to sign when a derived script differs from the one shown for review
- Add the "Taproot address:" label to all translations
- Add tests for the review page, the changed-after-review refusal and the foreign-input rejection at load
- Drop the sp() wallet descriptor and derive SP scan and spend keys from the account node
- Warn only on SP outputs that pay someone else and treat only unlabeled and label 0 outputs as own
- Clear only BIP-352 eligible inputs on sign so other signers' witnesses are kept
- Repair zero fingerprints at PSBT load for every policy, including taproot odd-y and BIP-376 spend keys
- Validate SD PSBTs on the first read and refuse the compressed fallback for SP PSBTs with foreign inputs
- Stream the PSBT into the DLEQ nonce hash and dedupe the key text view and default derivation code
- Add regression tests for odd-y taproot keys, labels, SD fallback paths and wallet settings
@notTanveer
notTanveer force-pushed the feat/silent-payments-V2 branch from 0ee9ac5 to f13f76d Compare October 28, 2026 06:06
@qlrd

qlrd commented Oct 29, 2026

Copy link
Copy Markdown
Member

Currently tested on device and working! 👯

More proper review after.

This branch has not been deployed

No deployments
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.

4 participants