silentpayments: add light client API #1912

pull theStack wants to merge 8 commits into bitcoin-core:master from theStack:silentpayments_module_lightclient_api changing 7 files +664 −116

theStack commented at 3:09 PM on August 12, 2026: contributor
This PR extends the silentpayments module with API functions for prevouts_summary (de)serialization and output public key (k=0) creation, intended to be used by tweak indexers and light clients. Note that this functionality was originally introduced in the take 3 PR (#1698), but was then later intentionally removed again in take 4 (#1765, recently merged and released), in order to reduce the scope and lower the review burden.

The following 3 API functions are added:
- secp256k1_silentpayments_recipient_prevouts_summary_serialize: given a prevouts_summary object, create the corresponding 33-bytes or 65-bytes serialization
- secp256k1_silentpayments_recipient_prevouts_summary_parse: given a 33-byte or 65-byte prevouts_summary representation, create the corresponding prevouts_summary object
- secp256k1_silentpayments_recipient_create_output_pubkeys: given a prevouts_summary object, a recipients scan secret key and a list of spend public keys, create a list of corresponding x-only output public keys (one for each spend public key, each derived with k=0).
Tests, benchmarks and the example are extended accordingly.
theStack added the label feature on Aug 14, 2026
theStack added the label needs-changelog on Aug 14, 2026
silentpayments: add API functions for `_prevouts_summary` (de)serialization
Co-authored-by: josibake <josibake@protonmail.com>
06565d0972
silentpayments: scan test vectors with all `_prevouts_summary` variants
Best reviewed with `--ignore-all-space` (or `-w` for short).
0e3518e22a

silentpayments: support creating multiple output pubkeys

This is preparatory for introducing the light client API function in the
next commit. To keep the current call-site which only creates a single
output pubkey (in `_sender_create_outputs`) as-is, a corresponding wrapper
function calls the new function with one spend pubkey.
No behaviour or API change in this commit yet.

Best reviewed with `--ignore-all-space` (or `-w` for short).

fd560b1328

silentpayments: add API function for k=0 output pubkey creation

Add function for creating k=0 outputs for multiple spend public keys.
These keys can then be checked for existance against the UTXO set/blockchain.

If a match is found, the client needs to download the full transaction and
rescan with `_scan_outputs`.

Co-authored-by: josibake <josibake@protonmail.com>

c998c83450

silentpayments: test output pubkey creation function in recipient test vectors 3c3b52da6c
silentpayments: extend example with light client scanning scenario
Co-authored-by: josibake <josibake@protonmail.com>
fa598cab4c
silentpayments: add benchmarks for k=0 output pubkey creation
TODO: also test with 65-byte sized prevout_summary serializations
8d268ce201
silentpayments: add ctime-tests for light client API 0b1cde32d5
theStack force-pushed on Aug 19, 2026
theStack commented at 6:17 PM on August 19, 2026: contributor

Rebased on master (adapting to the _eckey_pubkey_... -> _ge_... serialize/parse renames #1915) and fixed the unintentional accepting of prevouts_summary deserialization if they are in hybrid pubkey format (i.e. 65 bytes with prefix bytes 0x06 or 0x07). This will be a bit simpler and more explicit if #1918 gets in and secp256k1_ge_parse{33,65} can be used, added a TODO comment accordingly.
bitsagarob commented at 12:22 PM on September 3, 2026: none
Tested ACK 0b1cde32d56003bec3071a82b738d20314564c73

Exercised the new light client API against real chain data rather than constructed inputs: the 33-byte tweak a BlindBit Oracle v2 serves for a real 50,000 sat silent payment in mainnet block 965085, paid to a throwaway wallet whose scan key is published.
```
1. parse the 33-byte tweak the oracle serves
   ok
2. scan that transaction's one output
   found f420241ebdee9a956f88f6ea704b1e02871a64082f61489150222c3a33ee6038
   MATCHES the real 50,000 sat payment
3. round-trip: serialize the parsed summary back to 33 bytes
   in  023497fcdef5a9254be2e60e02a53bcede1e3d4ab67ed1928140a1d69438bb5678
   out 023497fcdef5a9254be2e60e02a53bcede1e3d4ab67ed1928140a1d69438bb5678
   identical
4. the 65-byte form should scan identically
   same payment found via 65-byte form
5. create_output_pubkeys, the filter-matching path, from the same tweak
   k=0 candidate f420241ebdee9a956f88f6ea704b1e02871a64082f61489150222c3a33ee6038
   equals the real output, so a filter would hit
```
Step 3: the 33-byte serialization is byte-identical to the deployed BlindBit wire format, so an index server can hand its bytes straight to _prevouts_summary_parse.

Tested with: cmake -B build -DSECP256K1_ENABLE_MODULE_SILENTPAYMENTS=ON -DSECP256K1_BUILD_BENCHMARK=ON cmake --build build -j8 && ctest --test-dir build — 223/223 passed x86-64 Linux, gcc 13.3.0. ctime_tests needs valgrind headers I don't have here, unrelated to this PR.

Contributors

theStack

bitsagarob

Labels

feature needs-changelog

Linked (view graph)

#1698 Add BIP352 module (take 3)#1765 Add "silentpayments" module implementing BIP352 (take 4, limited to full-node scanning)#1918 refactor: split `ge_parse` into explicit variants (compressed, uncompressed, uncompressed+hybrid)