Add "silentpayments" module implementing BIP352 (take 4, limited to full-node scanning)

theStack commented at 12:06 pm on October 31, 2025: contributor

Description

This PR implements BIP352 with scanning limited to full-nodes. Light-client scanning is planned to be added in a separate PR in the future. The following 5 API functions are currently introduced:

Sender side [BIP description]:

secp256k1_silentpayments_sender_create_outputs: given a list of $n$ secret keys $a_1 … a_n$, a serialized outpoint, and a list of recipients (each consisting of silent payments scan pubkey and spend pubkey), create the corresponding transaction outputs (x-only public keys) for the sending transaction

Receiver side, label creation [BIP description]:

secp256k1_recipient_create_label: given a scan secret key and label integer, calculate the corresponding label_tweak and label public key
secp256k1_recipient_create_labeled_spend_pubkey: given a spend public key and a label public key, create the corresponding labeled spend public key

Receiver side, scanning [BIP description]:

secp256k1_recipient_prevouts_summary_create: given a list of $n$ public keys $A_1 … A_n$ and a serialized outpoint, create a prevouts_summary object needed for scanning
secp256k1_recipient_scan_outputs: given a prevouts_summary object, a recipients scan secret key and spend public key, and the relevant transaction outputs (x-only public keys), scan for outputs belonging to the recipients and and return the tweak(s) needed for spending the output(s). Optionally, a label_lookup callback function can be provided to also scan for labels.

Changes to the previous take

Based on the latest state of the previous PR #1698 (take 3), the following changes have been made:

rebased on master (adapting to the new unit test framework added in #1734; thanks to furszy for his mini-guide)
removed functionality that is only relevant for light clients (_prevout_summary_{parse,serialize}, __recipient_create_output_pubkeys), adapted tests and benchmark accordingly
adapted examples to have both Bob and Carol do full-node scanning, with a TODO to switch the latter to light-client scanning once available in the future
addressed various review comments, if still relevant (https://github.com/bitcoin-core/secp256k1/pull/1698#discussion_r2433803533, #1698 (review), #1698 (review), #1698 (review))

The scope reduction isn’t immediately visible in commit count (only one commit was only introducing light-client relevant functionality and could be completely removed), but the review burden compared #1698 is still significantly lower in terms of LOC, especially in the receiving commit.

Open questions / TODOs

Recent proposals of reducing the worst-case scanning time (see posts by w0xlt and jonasnick, #1698 (comment) ff.) are not taken into account yet.
Not providing prevouts_summary (de)serialization functionality yet in the API poses the risk that users try to do it anyway by treating the opaque object as “serialized”. How to cope with that? Is adding a “don’t do this” comment in API header sufficient?

build: add skeleton for new silentpayments (BIP352) module 0db22b944c

silentpayments: sending

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

5aaf3be766

silentpayments: recipient label support

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.

df0a1fe16c

silentpayments: receiving

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 in the next commit.

Add an opaque data type for passing around the prevout public key 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 the scan_key * input_hash before doing ECDH.

Finally, add test coverage for the receiving API.

4c38bafa65

silentpayments: add examples/silentpayments.c

Demonstrate sending and scanning on full nodes.

ceade4ea69

silentpayments: add benchmarks for scanning

Add a benchmark for a full transaction scan.
Only benchmarks for scanning are added as this is the most
performance critical portion of the protocol.

Co-authored-by: Sebastian Falbesoner <91535+thestack@users.noreply.github.com>

30ef0c5fe4

tests: add BIP-352 test vectors

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: Ron <4712150+macgyver13@users.noreply.github.com>
Co-authored-by: Sebastian Falbesoner <91535+thestack@users.noreply.github.com>
Co-authored-by: Tim Ruffing <1071625+real-or-random@users.noreply.github.com>

76ca66d6b4

tests: add constant time tests

Co-authored-by: Jonas Nick <2582071+jonasnick@users.noreply.github.com>
Co-authored-by: Sebastian Falbesoner <91535+thestack@users.noreply.github.com>

6cf228daa6

tests: add sha256 tag test

Test midstate tags used in silent payments.

179759ecfa

ci: enable silentpayments module 4c16ae04a7

docs: update README c11d30c25f

Add “silentpayments” module implementing BIP352 (take 4, limited to full-node scanning) #1765

Description

Changes to the previous take

Open questions / TODOs