READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

20,601 bytes · SHA-256 70b073de4d41c4ce… · View upstream ↗

1#ifndef SECP256K1_SILENTPAYMENTS_H
2#define SECP256K1_SILENTPAYMENTS_H
3
4#include <stdint.h>
5#include "secp256k1.h"
6#include "secp256k1_extrakeys.h"
7
8#ifdef __cplusplus
9extern "C" {
10#endif
11
12/** This module provides an implementation for Silent Payments, as specified in
13 *  BIP352. This particularly involves the creation of input tweak data by
14 *  summing up secret or public keys and the derivation of a shared secret using
15 *  Elliptic Curve Diffie-Hellman. Combined are either:
16 *    - spender's secret keys and recipient's public key (a * B, sender side)
17 *    - spender's public keys and recipient's secret key (A * b, recipient side)
18 *  With this result, the necessary key material for ultimately creating/scanning
19 *  or spending Silent Payments outputs can be determined.
20 *
21 *  Note that this module is _not_ a full implementation of BIP352, as it
22 *  inherently doesn't deal with higher-level concepts like addresses, output
23 *  script types or transactions. The intent is to provide a module for
24 *  abstracting away the elliptic-curve operations required for the protocol. For
25 *  any wallet software already using libsecp256k1, this API should provide all
26 *  the functions needed for a Silent Payments implementation without requiring
27 *  any further elliptic-curve operations from the wallet.
28 */
29
30/* Maximum number of Silent Payments recipients per group (i.e.
31 * recipients sharing the same scan public key) as per BIP-352 */
32#define SECP256K1_SILENTPAYMENTS_RECIPIENT_GROUP_LIMIT 2323
33
34/** The data from a single recipient address
35 *
36 *  This struct serves as an input argument to `silentpayments_sender_create_outputs`.
37 *
38 *  `index` must be set to the position (starting with 0) of this recipient in the
39 *  `recipients` array passed to `silentpayments_sender_create_outputs`. It is
40 *  used to map the returned generated outputs back to the original recipient.
41 *
42 *  Note:
43 *  The spend public key named `spend_pubkey` may have been optionally tweaked with
44 *  a label by the recipient. Whether `spend_pubkey` has actually been tagged with
45 *  a label is irrelevant for the sender. As a documentation convention in this API,
46 *  `unlabeled_spend_pubkey` is used to indicate when the unlabeled spend public key
47 *  must be used.
48 */
49typedef struct secp256k1_silentpayments_recipient {
50    secp256k1_pubkey scan_pubkey;
51    secp256k1_pubkey spend_pubkey;
52    size_t index;
53} secp256k1_silentpayments_recipient;
54
55/** Create Silent Payments outputs for recipient(s).
56 *
57 *  Given a list of n secret keys a_1...a_n (one for each Silent Payments
58 *  eligible input to spend), a serialized outpoint, and a list of recipients,
59 *  create the taproot outputs. Inputs with conditional branches or multiple
60 *  public keys are excluded from Silent Payments eligible inputs; see BIP352
61 *  for more information.
62 *
63 *  `outpoint_smallest36` refers to the smallest outpoint lexicographically
64 *  from the transaction inputs (both Silent Payments eligible and non-eligible
65 *  inputs). This value MUST be the smallest outpoint out of all of the
66 *  transaction inputs, otherwise the recipient will be unable to find the
67 *  payment. Determining the smallest outpoint from the list of transaction
68 *  inputs is the responsibility of the caller. It is strongly recommended
69 *  that implementations ensure they are doing this correctly by using the
70 *  test vectors from BIP352.
71 *
72 *  When creating more than one generated output, all of the generated outputs
73 *  MUST be included in the final transaction. Dropping any of the generated
74 *  outputs from the final transaction may make all or some of the outputs
75 *  unfindable by the recipient.
76 *
77 *  Returns: 1 if creation of outputs was successful.
78 *           0 on failure, i.e., when one of the following occurs:
79 *             - The size of any group (i.e. recipients sharing the same scan public key)
80 *               exceeds the protocol limit SECP256K1_SILENTPAYMENTS_RECIPIENT_GROUP_LIMIT.
81 *             - The sum of all input secret keys is 0.
82 *               (This occurs only with negligible probability if at least one of the
83 *               input secret keys is uniformly random and independent of all other keys.)
84 *             - An invalid output public key is created. (This can only happen for an
85 *               adversarially chosen recipient spend public key.)
86 *
87 *  Args:                ctx: pointer to a context object
88 *                            (not secp256k1_context_static).
89 *  Out:   generated_outputs: pointer to an array of pointers to xonly public keys,
90 *                            one per recipient.
91 *                            The outputs are ordered to match the original
92 *                            ordering of the recipient objects, i.e.,
93 *                            `generated_outputs[0]` is the generated output
94 *                            for the `secp256k1_silentpayments_recipient` object
95 *                            with index = 0.
96 *  In:           recipients: pointer to an array of pointers to Silent Payments
97 *                            recipients, where each recipient is a scan public
98 *                            key, a spend public key, and an index indicating
99 *                            its position in the original ordering. This function
100 *                            may reorder the pointers to the recipient objects
101 *                            within the array, i.e., after the call (including on
102 *                            failure), the index fields of the recipient objects
103 *                            may no longer correspond to the positions in the
104 *                            array. Multiple recipient objects with the same scan
105 *                            public key and/or same spend public key can be passed
106 *                            if they carry different indices.
107 *              n_recipients: the size of the recipients array.
108 *       outpoint_smallest36: serialized (36-byte) smallest outpoint
109 *                            (lexicographically) from the transaction inputs
110 *                  keypairs: pointer to an array of pointers to taproot
111 *                            keypair inputs (can be NULL if no secret keys
112 *                            of taproot inputs are used)
113 *                n_keypairs: the size of the keypairs array.
114 *                   seckeys: pointer to an array of pointers to 32-byte
115 *                            secret keys of non-taproot inputs (can be NULL
116 *                            if no secret keys of non-taproot inputs are
117 *                            used)
118 *                 n_seckeys: the size of the seckeys array.
119 */
120SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_sender_create_outputs(
121    const secp256k1_context *ctx,
122    secp256k1_xonly_pubkey **generated_outputs,
123    const secp256k1_silentpayments_recipient **recipients,
124    size_t n_recipients,
125    const unsigned char *outpoint_smallest36,
126    const secp256k1_keypair * const *keypairs,
127    size_t n_keypairs,
128    const unsigned char * const *seckeys,
129    size_t n_seckeys
130) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(5);
131
132/** Opaque data structure that holds a Silent Payments label.
133 *
134 *  Guaranteed to be 68 bytes in size. Serialized and parsed with
135 *  `secp256k1_silentpayments_recipient_label_serialize` and
136 *  `secp256k1_silentpayments_recipient_label_parse`.
137 */
138typedef struct secp256k1_silentpayments_label {
139    unsigned char data[68];
140} secp256k1_silentpayments_label;
141
142/** Parse a Silent Payments label.
143 *
144 *  Returns: 1 when the label could be parsed, 0 otherwise.
145 *  Args:    ctx: pointer to a context object
146 *  Out:   label: pointer to a label object
147 *  In:     in33: pointer to the 33-byte label to be parsed
148 */
149SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_label_parse(
150    const secp256k1_context *ctx,
151    secp256k1_silentpayments_label *label,
152    const unsigned char *in33
153) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
154
155/** Serialize a Silent Payments label
156 *
157 *  Returns: 1 always
158 *  Args:    ctx: pointer to a context object
159 *  Out:   out33: pointer to a 33-byte array to store the serialized label
160 *  In:    label: pointer to the label
161 */
162SECP256K1_API int secp256k1_silentpayments_recipient_label_serialize(
163    const secp256k1_context *ctx,
164    unsigned char *out33,
165    const secp256k1_silentpayments_label *label
166) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
167
168/** Create Silent Payments label tweak and label.
169 *
170 *  Given a recipient's 32 byte scan key and a label integer m, calculate the
171 *  corresponding label tweak and label:
172 *
173 *      label_tweak = hash(scan_key || m)
174 *            label = label_tweak * G
175 *
176 *  Returns: 1 if label tweak and label creation was successful.
177 *           0 if scan_key32 is invalid or the hash output label_tweak32 is
178 *             not a valid scalar (negligible probability per hash evaluation).
179 *
180 * WARNING: Creating a large number of labels may significantly degrade
181 * scanning performance in certain Silent Payments wallet implementations,
182 * such as light clients. The scanning function provided in this module,
183 * which is designed for full nodes, performs consistently even with hundreds
184 * of thousands of labels. Other implementations may not share this property
185 * or may be unable to use it due to lacking full transaction data.
186 *
187 * To maximize wallet interoperability, it is recommended to create only
188 * the change label (m = 0) and avoid distributing labeled addresses.
189 *
190 *  Args:                ctx: pointer to a context object
191 *                            (not secp256k1_context_static)
192 *  Out:               label: pointer to the resulting label
193 *             label_tweak32: pointer to the 32 byte label tweak
194 *  In:           scan_key32: pointer to the recipient's 32 byte scan key
195 *                         m: integer for the m-th label (0 is used for change outputs)
196 */
197SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_label_create(
198    const secp256k1_context *ctx,
199    secp256k1_silentpayments_label *label,
200    unsigned char *label_tweak32,
201    const unsigned char *scan_key32,
202    uint32_t m
203) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
204
205/** Create Silent Payments labeled spend public key.
206 *
207 *  Given a recipient's spend public key and a label, calculate the
208 *  corresponding labeled spend public key:
209 *
210 *      labeled_spend_pubkey = unlabeled_spend_pubkey + label
211 *
212 *  The result is used by the recipient to create a Silent Payments address,
213 *  consisting of the serialized and concatenated scan public key and
214 *  (labeled) spend public key.
215 *
216 *  Returns: 1 if labeled spend public key creation was successful.
217 *           0 if spend pubkey and label sum to zero (negligible probability for
218 *             labels created according to BIP352).
219 *
220 *  Args:                    ctx: pointer to a context object
221 *  Out:    labeled_spend_pubkey: pointer to the resulting labeled spend public key
222 *  In:   unlabeled_spend_pubkey: pointer to the recipient's unlabeled spend public key
223 *                         label: pointer to the recipient's label
224 */
225SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_create_labeled_spend_pubkey(
226    const secp256k1_context *ctx,
227    secp256k1_pubkey *labeled_spend_pubkey,
228    const secp256k1_pubkey *unlabeled_spend_pubkey,
229    const secp256k1_silentpayments_label *label
230) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
231
232/** Opaque data structure that holds Silent Payments prevouts summary data.
233 *
234 *  The exact representation of data inside is implementation defined and not
235 *  guaranteed to be portable between different platforms or versions. It is
236 *  however guaranteed to be 101 bytes in size, and can be safely copied/moved.
237 *  This structure does not contain secret data. It can be created with
238 *  `secp256k1_silentpayments_recipient_prevouts_summary_create`.
239 */
240typedef struct secp256k1_silentpayments_prevouts_summary {
241    unsigned char data[101];
242} secp256k1_silentpayments_prevouts_summary;
243
244/** Compute Silent Payments prevouts summary from prevout public keys and transaction
245 *  inputs.
246 *
247 *  Given a list of n public keys A_1...A_n (one for each Silent Payments
248 *  eligible input to spend) and a serialized outpoint_smallest36, create a
249 *  `prevouts_summary` object. This object summarizes the prevout data from the
250 *  transaction inputs needed for scanning.

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.