Add BIP352 module (take 3) #1698

josibake · 2025-07-10T08:53:21Z

This PR implements BIP352 - Silent payments. It is recommended to read through the BIP before reviewing this PR.

This is a continuation of the work in #1519 and only opened as a new PR due to the comment history on #1519 becoming quite long and difficult to sift through. It is recommended reviewers go through #1519 for background context, if interested.

include/secp256k1_silentpayments.h

josibake · 2025-07-14T15:04:20Z

Updated 6264c3d -> 9e85256 (2025_00 -> 2025_01, compare)

Added documentation for expectations around label_lookup pointer lifetimes (h/t @antonilol)
Update docs to accurately reflect that label_context is optional (h/t @antonilol)
Added a test case for passing a lookup callback with a null context (which required some small updates to the test label lookup function)

src/ctime_tests.c

real-or-random · 2025-07-21T14:15:58Z

Sorry, stopping CI here. We're about to make a release and need to the CI. :)

We'll restart the jobs here afterwards.

josibake · 2025-07-21T14:21:51Z

Update 9e85256 -> a4db279 (2025_01 -> 2025_02, compare)

Update the constant time tests to cover the _recipient_created_shared_secret and _recipient_created_output_pubkey functions (h/t @theStack )
Remove no longer needed TODO comments and clarify why a constant time test without a label lookup function is sufficient for _recipient_scan_outputs

josibake · 2025-07-22T10:29:47Z

Rebased on top of 0.7.0 release 🎉 a4db279 -> e35bede (2025_02 -> 2025_02_rebase, compare)

josibake · 2025-07-22T11:13:33Z

I did a deep dive on using (*arg)[size] in this PR and opened #1710 for discussion, since this is a broader topic than just this PR. The relevant changes for here and the downstream Bitcoin Core PRs are josibake@5a10880 and josibake/bitcoin@5835d98

src/modules/silentpayments/main_impl.h

josibake · 2025-07-24T12:23:16Z

Updated e35bede -> 1a84908 (2025_02_rebase -> 2025_03, compare)

Added a test case for the _recipient_create_output_pubkey corner case (h/t @theStack)
Removed the VERIFY_CHECK in favour of returning an error

src/modules/silentpayments/main_impl.h

examples/silentpayments.c

josibake · 2025-07-25T09:20:23Z

Update 1a84908 -> 2948a9b (2025_03 -> 2025_04, compare)

Fixed valgrind error in test
Update the example to use EXIT_SUCCESS/EXIT_FAILURE (h/t @theStack)
Clear shared secret variable consistently (and update comment) (h/t @theStack)
Add comment explaining why we declassify the pubkey sum (h/t @theStack)

Thanks for the thorough review, @theStack !

josibake · 2025-07-25T14:33:30Z

Update 2948a9b -> 64ecd6c (2025_04 -> 2025_05, compare)

Remove no longer needed TODO comment regarding _cmov
Remove todo comment regarding input_hash, now that this is properly specified in the BIP

cc @jonasnick and @real-or-random regarding the use of a VERIFY_CHECK in favour of returning an error, when returning an error results in an untestable branch. I'm happy with the approach here were we use a VERIFY_CHECK for input_hash and t_k to check for an overflow of the curve order. However, given this is something we've discussed a few times in the post, would be great to hear your thoughts on this and I'm happy to defer to whatever you both think is best.

This should address all of the outstanding TODOs (at least the ones we left comments for 😅 )

src/modules/silentpayments/bench_impl.h

josibake · 2025-07-28T18:06:21Z

Updated 64ecd6c -> 3c4af8f (2025_05 -> 2025_06, compare)

Updates the benchmarks per @theStack 's suggestion to have separate benchmarks for _full_scan and full_scan_with_labels
Leave a TODO comment for a follow-up to make the labels benchmark more representative of real world usage
Cleans up the benchmark arguments and formatting

theStack

In the CI commit, could add the silent payments module also to the native macOS arm64 job (as done for musig recently in #1699), e.g.

diff

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8ee13ce..f612a84 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -583,13 +583,13 @@ jobs:
       fail-fast: false
       matrix:
         env_vars:
-          - { WIDEMUL: 'int64',  RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes' }
+          - { WIDEMUL: 'int64',  RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', SILENTPAYMENTS: 'yes' }
           - { WIDEMUL: 'int128_struct', ECMULTGENPRECISION: 2, ECMULTWINDOW: 4 }
-          - { WIDEMUL: 'int128',                  ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes' }
+          - { WIDEMUL: 'int128',                  ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', SILENTPAYMENTS: 'yes' }
           - { WIDEMUL: 'int128', RECOVERY: 'yes' }
-          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes' }
-          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', CC: 'gcc' }
-          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', CPPFLAGS: '-DVERIFY' }
+          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', SILENTPAYMENTS: 'yes' }
+          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', SILENTPAYMENTS: 'yes', CC: 'gcc' }
+          - { WIDEMUL: 'int128', RECOVERY: 'yes', ECDH: 'yes', EXTRAKEYS: 'yes', SCHNORRSIG: 'yes', MUSIG: 'yes', ELLSWIFT: 'yes', SILENTPAYMENTS: 'yes', CPPFLAGS: '-DVERIFY' }
           - BUILD: 'distcheck'
 
     steps:

(untested)

examples/silentpayments.c

josibake · 2025-08-12T09:40:47Z

Updated 142f07b -> 2b57d2a (2025_11 -> 2025_12, compare)

Documentation fixes (h/t @theStack)
Added VERIFY_CHECK and more consistent ret (h/t @theStack)
Removed dead code from tests and improved legibility (h/t @theStack)

configure.ac

src/modules/silentpayments/main_impl.h

include/secp256k1_silentpayments.h

src/modules/silentpayments/tests_impl.h

src/modules/silentpayments/main_impl.h

src/modules/silentpayments/tests_impl.h

README.md

include/secp256k1_silentpayments.h

src/modules/silentpayments/main_impl.h

josibake · 2025-08-14T12:51:44Z

Updated 2b57d2a -> a428424 (2025_12 -> 2025_13, compare)

Remove extra check to make the autotools build system consistent with other modules (h/t @real-or-random )
Various wording fix-ups (h/t @real-or-random)
Use spend_pubkey to indicate a spend public key that might also have a tweak and unlabeled_spend_pubkey we mean to refer the unlabeled spend public key (vs labeled_spend_pubkey and spend_pubkey) (h/t @real-or-random )
Reword the sending API docs to avoid mentioning "sorting"

Thanks for the review @real-or-random , much prefer your wording suggestions. I pushed a version of the docs that I think helps minimise confusion about sorting, but curious to hear your thoughts as I imagine these docs will still need a bit of refining.

josibake · 2025-08-15T10:26:27Z

Updated a428424 -> 99aef92 (2025_13 -> 2025_14, compare)

Add tests for the tagged hash midstates used in silent payments (h/t @real-or-random )

The first commit moves the convenience function for verifying tagged hashes out of the musig module and is pulled in from #1725.

real-or-random · 2025-08-19T08:32:41Z

I've made my way through sending (ignoring the public header for now) and I pushed some suggestions for fixups here: master...real-or-random:secp256k1:bip352-silentpayments-module-2025-sending-fixups (and some fixups also to receiving, I hope I always picked the right commit to fixup). See commit messages for rationale. Some of these may be opinionated, so feel free to reject, disagree, or adjust.

src/modules/silentpayments/main_impl.h

real-or-random · 2025-08-20T09:41:22Z

src/modules/silentpayments/tests_impl.h

+    /* Check for malformed spend and label public keys, i.e., any single pubkey is malformed or the public
+     * keys are valid but sum up to zero.
+     */
+    {
+        secp256k1_pubkey neg_spend_pubkey = s;
+        CHECK(secp256k1_ec_pubkey_negate(CTX, &neg_spend_pubkey));
+        CHECK(secp256k1_silentpayments_recipient_create_labeled_spend_pubkey(CTX, &ls, &s, &neg_spend_pubkey) == 0);
+        memset(&l, 0, sizeof(l));
+        CHECK_ILLEGAL(CTX, secp256k1_silentpayments_recipient_create_labeled_spend_pubkey(CTX, &ls, &s, &l));
+    }
+}


This could also test with an illegal s, I think.

Move the sha256_tag_test_internal function out of the musig module into tests.c. This makes it available to other modules wishing to verify tagged hashes without needing to duplicate the function. Change the function signature to expect a const unsigned char and update the tagged hash tests to use static const unsigned char character arrays (where necessary). Add a comment for each tag. This is done as a convenience for checking the strings against the protocol specifications, where the tags are normally specified as strings. Update tests in the ellswift and schnorrsig modules to use the sha256_tag_test_internal helper function.

Add a routine for the entire sending flow which takes a set of private keys, the smallest outpoint, and list of recipients and returns a list of x-only public keys by performing the following steps: 1. Sum up the private keys 2. Calculate the input_hash 3. For each recipient group: 3a. Calculate a shared secret 3b. Create the requested number of outputs This function assumes a single sender context in that it requires the sender to have access to all of the private keys. In the future, this API may be expanded to allow for a multiple senders or for a single sender who does not have access to all private keys at any given time, but for now these modes are considered out of scope / unsafe. Internal to the library, add: 1. A function for creating shared secrets (i.e., a*B or b*A) 2. A function for generating the "SharedSecret" tagged hash 3. A function for creating a single output public key

Add function for creating a label tweak. This requires a tagged hash function for labels. This function is used by the receiver for creating labels to be used for a) creating labeled addresses and b) to populate a labels cache when scanning. Add function for creating a labeled spend pubkey. This involves taking a label tweak, turning it into a public key and adding it to the spend public key. This function is used by the receiver to create a labeled silent payment address. Add tests for the label API.

Add routine for scanning a transaction and returning the necessary spending data for any found outputs. This function works with labels via a lookup callback and requires access to the transaction outputs. Requiring access to the transaction outputs is not suitable for light clients, but light client support is enabled by exposing the `_create_shared_secret` and `_create_output_pubkey` functions in the API. This means the light client will need to manage their own scanning state, so wherever possible it is preferrable to use the `_recipient_scan_ouputs` function. Add an opaque data type for passing around the summed input public key (A_sum) and the input hash tweak (input_hash). This data is passed to the scanner before the ECDH step as two separate elements so that the scanner can multiply b_scan * input_hash before doing ECDH. Add functions for deserializing / serializing a public_data object to and from a public key. When serializing a public_data object, the input_hash is multplied into A_sum. This is so the object can be stored as public key for wallet rescanning later, or to vend to light clients. For the light client, a `_parse` function is added which parses the compressed public key serialization into a `public_data` object. Finally, add test coverage for the receiving API.

Demonstrate sending, scanning, and light client scanning.

Add a benchmark for a full transaction scan and for scanning a single output. Only benchmarks for scanning are added as this is the most performance critical portion of the protocol. Co-authored-by: Sebastian Falbesoner <[email protected]>

Add the BIP-352 test vectors. The vectors are generated with a Python script that converts the .json file from the BIP to C code: $ ./tools/tests_silentpayments_generate.py test_vectors.json > ./src/modules/silentpayments/vectors.h

Co-authored-by: Jonas Nick <[email protected]> Co-authored-by: Sebastian Falbesoner <[email protected]>

Test midstate tags used in silent payments.

josibake · 2025-08-20T10:09:32Z

Updated 99aef92 -> 2164d5c (2025_14 -> 2025_15, compare)

Primarily updates the sending commit, with a few changes to the receiving commit:

Rebased on tests: refactor tagged hash verification #1725
IWYU (h/t @real-or-random )
Improve comments regarding the scan key, i.e., stop referring to it as "secret-but-not-really" and explicitly mention what happens if the scan key is leaked (h/t @real-or-random )
Use the more precise terminology "negligible probability" (h/t @real-or-random and crypto camp, where this has been explained! 😄 )
General wording, clarity improvements for the code/comments

Thanks for the thorough review, @real-or-random ! I reviewed each fixup commit and ended up taking all of them, as I agree with the rational and much prefer the wording(s) you suggested. Also, thanks for the fixup! branch; the branch made it super simple to integrate your changes.

5153cf1 tests: refactor tagged hash tests (josibake) Pull request description: Opened in response to #1698 (comment) --- We use tagged hashes in `modules/musig`, `modules/schnorrsig`, `modules/ellswift`, and the proposed `modules/silentpayments`. In looking for inspiration on how to add tagged hash midstate verification for #1698, it seemed like a good opportunity to DRY up the code across all of the modules. I chose the convention used in the ellswift module as this seems the most idiomatic C. Since the tags are normally specified as strings in the BIPs, I also added a comment above each char array for convenience. If its deemed too invasive to refactor the existing modules in this PR, I'm happy to drop the refactor commits for the ellswift and schnorrsig modules. All I need for #1698 is the first commit which moves the utility function out of the musig module to make it available to use in the silent payments module. ACKs for top commit: real-or-random: utACK 5153cf1 assuming CI passes theStack: Code-review ACK 5153cf1 Tree-SHA512: 335ec3ee6a265e13cc379968f8fa1624534bef2389e4e21b85e6a9572ce1bd9dee4eabd2cb6d187ac974db3ab8246c2626d309ccfbee5744c30cf7560d1e261c

This was referenced Jul 10, 2025

Add BIP352 silentpayments module #1519

Closed

BIP352 tracking issue bitcoin/bitcoin#28536

Open

Silent Payments: Implement BIP352 bitcoin/bitcoin#28122

Draft

antonilol reviewed Jul 10, 2025

View reviewed changes

include/secp256k1_silentpayments.h Outdated Show resolved Hide resolved

include/secp256k1_silentpayments.h Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 6264c3d to 9e85256 Compare July 14, 2025 14:54

antonilol mentioned this pull request Jul 14, 2025

[WIP] Add bip352 silentpayments module rust-bitcoin/rust-secp256k1#721

Open

theStack reviewed Jul 21, 2025

View reviewed changes

src/ctime_tests.c Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 9e85256 to a4db279 Compare July 21, 2025 14:09

josibake force-pushed the bip352-silentpayments-module-2025 branch from a4db279 to e35bede Compare July 22, 2025 10:27

josibake mentioned this pull request Jul 22, 2025

RFC: Using unsigned char (*arg)[size] as a replacement for unsigned char *argsize for fixed length array arguments #1710

Open

real-or-random added the feature label Jul 23, 2025

theStack reviewed Jul 23, 2025

View reviewed changes

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from e35bede to 1a84908 Compare July 24, 2025 12:18

theStack reviewed Jul 24, 2025

View reviewed changes

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

examples/silentpayments.c Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 1a84908 to 2948a9b Compare July 25, 2025 09:16

josibake force-pushed the bip352-silentpayments-module-2025 branch from 2948a9b to 64ecd6c Compare July 25, 2025 14:25

jonatack mentioned this pull request Jul 25, 2025

BIP352: be explicit for the input_hash corner case bitcoin/bips#1902

Merged

theStack reviewed Jul 28, 2025

View reviewed changes

src/modules/silentpayments/bench_impl.h Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 64ecd6c to 3c4af8f Compare July 28, 2025 18:01

theStack mentioned this pull request Jul 30, 2025

Add ECDSA pubkey recovery usage example #1714

Open

theStack reviewed Jul 30, 2025

View reviewed changes

examples/silentpayments.c Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 142f07b to 2b57d2a Compare August 12, 2025 09:36

josibake mentioned this pull request Aug 12, 2025

(RFC) Have CMake generate vector.h files for test vectors #1723

Closed

real-or-random reviewed Aug 12, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

real-or-random reviewed Aug 12, 2025

View reviewed changes

include/secp256k1_silentpayments.h Outdated Show resolved Hide resolved

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

josibake force-pushed the bip352-silentpayments-module-2025 branch from 2b57d2a to a428424 Compare August 14, 2025 12:45

josibake mentioned this pull request Aug 15, 2025

tests: refactor tagged hash verification #1725

Merged

josibake force-pushed the bip352-silentpayments-module-2025 branch from a428424 to 99aef92 Compare August 15, 2025 10:21

real-or-random reviewed Aug 19, 2025

View reviewed changes

src/modules/silentpayments/main_impl.h Outdated Show resolved Hide resolved

real-or-random mentioned this pull request Aug 20, 2025

docs: Clarify that callback can be called more than once #1727

Open

real-or-random reviewed Aug 20, 2025

View reviewed changes

josibake and others added 12 commits August 20, 2025 10:51

build: add skeleton for new silentpayments (BIP352) module

72acb93

silentpayments: add examples/silentpayments.c

e18be7d

Demonstrate sending, scanning, and light client scanning.

silentpayments: add benchmarks for scanning

1f26c1f

Add a benchmark for a full transaction scan and for scanning a single output. Only benchmarks for scanning are added as this is the most performance critical portion of the protocol. Co-authored-by: Sebastian Falbesoner <[email protected]>

tests: add BIP-352 test vectors

724b985

Add the BIP-352 test vectors. The vectors are generated with a Python script that converts the .json file from the BIP to C code: $ ./tools/tests_silentpayments_generate.py test_vectors.json > ./src/modules/silentpayments/vectors.h

tests: add constant time tests

f8816b5

Co-authored-by: Jonas Nick <[email protected]> Co-authored-by: Sebastian Falbesoner <[email protected]>

tests: add sha256 tag test

15d594c

Test midstate tags used in silent payments.

ci: enable silentpayments module

42f2595

docs: update README

2164d5c

josibake force-pushed the bip352-silentpayments-module-2025 branch from 99aef92 to 2164d5c Compare August 20, 2025 09:59

Add BIP352 module (take 3) #1698

Are you sure you want to change the base?

Add BIP352 module (take 3) #1698

Uh oh!

Conversation

josibake commented Jul 10, 2025

Uh oh!

Uh oh!

Uh oh!

josibake commented Jul 14, 2025

Uh oh!

Uh oh!

real-or-random commented Jul 21, 2025

Uh oh!

josibake commented Jul 21, 2025

Uh oh!

josibake commented Jul 22, 2025

Uh oh!

josibake commented Jul 22, 2025

Uh oh!

Uh oh!

josibake commented Jul 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josibake commented Jul 25, 2025

Uh oh!

josibake commented Jul 25, 2025

Uh oh!

Uh oh!

josibake commented Jul 28, 2025

Uh oh!

theStack left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

josibake commented Aug 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josibake commented Aug 14, 2025

Uh oh!

josibake commented Aug 15, 2025

Uh oh!

real-or-random commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

real-or-random Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

josibake commented Aug 20, 2025

Uh oh!

Uh oh!

real-or-random commented Aug 19, 2025 •

edited

Loading