#include "../../../include/secp256k1.h"
#include "../../../include/secp256k1_extrakeys.h"
#include "../../../include/secp256k1_silentpayments.h"
#include "../../eckey.h"
#include "../../ecmult.h"
#include "../../ecmult_const.h"
#include "../../ecmult_gen.h"
#include "../../group.h"
#include "../../hash.h"
#include "../../hsort.h"

Include dependency graph for main_impl.h:

Enumerations
enum	{ LABEL_BATCH_SIZE = 8 }

Functions
static int	secp256k1_silentpayments_recipient_sort_cmp (const void pk1, const void pk2, void *ctx)
	Sort an array of Silent Payments recipients. More...

static void	secp256k1_silentpayments_recipient_sort (const secp256k1_context ctx, const secp256k1_silentpayments_recipient *recipients, size_t n_recipients)

static void	secp256k1_silentpayments_sha256_init_inputs (secp256k1_sha256 *hash)
	Set hash state to the BIP340 tagged hash midstate for "BIP0352/Inputs". More...

static int	secp256k1_silentpayments_calculate_input_hash_scalar (const secp256k1_hash_ctx hash_ctx, secp256k1_scalar input_hash_scalar, const unsigned char outpoint_smallest36, secp256k1_ge pubkey_sum)
	Callers must ensure that pubkey_sum is not the point at infinity before calling this function. More...

static void	secp256k1_silentpayments_create_shared_secret (unsigned char shared_secret33, const secp256k1_ge public_component, const secp256k1_scalar *secret_component)

static void	secp256k1_silentpayments_sha256_init_sharedsecret (secp256k1_sha256 *hash)
	Set hash state to the BIP340 tagged hash midstate for "BIP0352/SharedSecret". More...

static int	secp256k1_silentpayments_create_output_tweak (const secp256k1_context ctx, secp256k1_scalar t_k_scalar, const unsigned char *shared_secret33, uint32_t k)

static int	secp256k1_silentpayments_create_output_pubkey (const secp256k1_context ctx, secp256k1_xonly_pubkey output_xonly, const unsigned char shared_secret33, const secp256k1_pubkey spend_pubkey, uint32_t k)

int	secp256k1_silentpayments_sender_create_outputs (const secp256k1_context ctx, secp256k1_xonly_pubkey generated_outputs, const secp256k1_silentpayments_recipient recipients, size_t n_recipients, const unsigned char outpoint_smallest36, const secp256k1_keypair const keypairs, size_t n_keypairs, const unsigned char const seckeys, size_t n_seckeys)
	Create Silent Payments outputs for recipient(s). More...

static void	secp256k1_silentpayments_sha256_init_label (secp256k1_sha256 *hash)
	Set hash state to the BIP340 tagged hash midstate for "BIP0352/Label". More...

static void	secp256k1_silentpayments_label_save (secp256k1_silentpayments_label label, const secp256k1_ge ge)

static int	secp256k1_silentpayments_label_load (const secp256k1_context ctx, secp256k1_ge ge, const secp256k1_silentpayments_label *label)

int	secp256k1_silentpayments_recipient_label_parse (const secp256k1_context ctx, secp256k1_silentpayments_label label, const unsigned char *in33)
	Parse a Silent Payments label. More...

int	secp256k1_silentpayments_recipient_label_serialize (const secp256k1_context ctx, unsigned char out33, const secp256k1_silentpayments_label *label)
	Serialize a Silent Payments label. More...

int	secp256k1_silentpayments_recipient_label_create (const secp256k1_context ctx, secp256k1_silentpayments_label label, unsigned char label_tweak32, const unsigned char scan_key32, uint32_t m)
	Create Silent Payments label tweak and label. More...

int	secp256k1_silentpayments_recipient_create_labeled_spend_pubkey (const secp256k1_context ctx, secp256k1_pubkey labeled_spend_pubkey, const secp256k1_pubkey unlabeled_spend_pubkey, const secp256k1_silentpayments_label label)
	Create Silent Payments labeled spend public key. More...

int	secp256k1_silentpayments_recipient_prevouts_summary_create (const secp256k1_context ctx, secp256k1_silentpayments_prevouts_summary prevouts_summary, const unsigned char outpoint_smallest36, const secp256k1_xonly_pubkey const xonly_pubkeys, size_t n_xonly_pubkeys, const secp256k1_pubkey const *pubkeys, size_t n_pubkeys)
	An explanation of the prevouts_summary object and its usage: More...

static int	secp256k1_silentpayments_check_label_batch (secp256k1_ge label_ge, const unsigned char label_tweak, const secp256k1_gej label_candidates_gej, size_t n_batch, size_t j_start, secp256k1_silentpayments_label_lookup label_lookup, const void *label_context)

int	secp256k1_silentpayments_recipient_scan_outputs (const secp256k1_context ctx, secp256k1_silentpayments_found_output found_outputs, uint32_t n_found_outputs, const secp256k1_xonly_pubkey const tx_outputs, size_t n_tx_outputs, const unsigned char scan_key32, const secp256k1_silentpayments_prevouts_summary prevouts_summary, const secp256k1_pubkey unlabeled_spend_pubkey, secp256k1_silentpayments_label_lookup label_lookup, const void label_context)
	Scan for Silent Payments transaction outputs. More...

Variables
static const unsigned char	secp256k1_silentpayments_prevouts_summary_magic [4] = { 0xa7, 0x1c, 0xd3, 0x5e }
	magic bytes for ensuring prevouts_summary objects were initialized correctly. More...

static const unsigned char	secp256k1_silentpayments_label_magic [4] = { 0x27, 0x9d, 0x44, 0xba }

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
LABEL_BATCH_SIZE

Definition at line 571 of file main_impl.h.

Function Documentation

◆ secp256k1_silentpayments_calculate_input_hash_scalar()

static int secp256k1_silentpayments_calculate_input_hash_scalar	(	const secp256k1_hash_ctx *	hash_ctx,
		secp256k1_scalar *	input_hash_scalar,
		const unsigned char *	outpoint_smallest36,
		secp256k1_ge *	pubkey_sum
	)

static

Callers must ensure that pubkey_sum is not the point at infinity before calling this function.

Definition at line 66 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_check_label_batch()

static int secp256k1_silentpayments_check_label_batch	(	secp256k1_ge *	label_ge,
		const unsigned char **	label_tweak,
		const secp256k1_gej *	label_candidates_gej,
		size_t	n_batch,
		size_t	j_start,
		secp256k1_silentpayments_label_lookup	label_lookup,
		const void *	label_context
	)

static

Definition at line 575 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_create_output_pubkey()

static int secp256k1_silentpayments_create_output_pubkey	(	const secp256k1_context *	ctx,
		secp256k1_xonly_pubkey *	output_xonly,
		const unsigned char *	shared_secret33,
		const secp256k1_pubkey *	spend_pubkey,
		uint32_t	k
	)

static

Definition at line 151 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_create_output_tweak()

static int secp256k1_silentpayments_create_output_tweak	(	const secp256k1_context *	ctx,
		secp256k1_scalar *	t_k_scalar,
		const unsigned char *	shared_secret33,
		uint32_t	k
	)

static

Definition at line 118 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_create_shared_secret()

static void secp256k1_silentpayments_create_shared_secret	(	unsigned char *	shared_secret33,
		const secp256k1_ge *	public_component,
		const secp256k1_scalar *	secret_component
	)

static

Definition at line 88 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_label_load()

static int secp256k1_silentpayments_label_load	(	const secp256k1_context *	ctx,
		secp256k1_ge *	ge,
		const secp256k1_silentpayments_label *	label
	)

static

Definition at line 356 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_label_save()

static void secp256k1_silentpayments_label_save	(	secp256k1_silentpayments_label *	label,
		const secp256k1_ge *	ge
	)

static

Definition at line 350 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_create_labeled_spend_pubkey()

int secp256k1_silentpayments_recipient_create_labeled_spend_pubkey	(	const secp256k1_context *	ctx,
		secp256k1_pubkey *	labeled_spend_pubkey,
		const secp256k1_pubkey *	unlabeled_spend_pubkey,
		const secp256k1_silentpayments_label *	label
	)

Create Silent Payments labeled spend public key.

Given a recipient's spend public key and a label, calculate the corresponding labeled spend public key:

labeled_spend_pubkey = unlabeled_spend_pubkey + label

The result is used by the recipient to create a Silent Payments address, consisting of the serialized and concatenated scan public key and (labeled) spend public key.

Returns: 1 if labeled spend public key creation was successful. 0 if spend pubkey and label sum to zero (negligible probability for labels created according to BIP352).

Args: ctx: pointer to a context object Out: labeled_spend_pubkey: pointer to the resulting labeled spend public key In: unlabeled_spend_pubkey: pointer to the recipient's unlabeled spend public key label: pointer to the recipient's label

Definition at line 430 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_label_create()

int secp256k1_silentpayments_recipient_label_create	(	const secp256k1_context *	ctx,
		secp256k1_silentpayments_label *	label,
		unsigned char *	label_tweak32,
		const unsigned char *	scan_key32,
		uint32_t	m
	)

Create Silent Payments label tweak and label.

Given a recipient's 32 byte scan key and a label integer m, calculate the corresponding label tweak and label:

label_tweak = hash(scan_key || m)
      label = label_tweak * G

Returns: 1 if label tweak and label creation was successful. 0 if scan_key32 is invalid or the hash output label_tweak32 is not a valid scalar (negligible probability per hash evaluation).

WARNING: Creating a large number of labels may significantly degrade scanning performance in certain Silent Payments wallet implementations, such as light clients. The scanning function provided in this module, which is designed for full nodes, performs consistently even with hundreds of thousands of labels. Other implementations may not share this property or may be unable to use it due to lacking full transaction data.

To maximize wallet interoperability, it is recommended to create only the change label (m = 0) and avoid distributing labeled addresses.

Args: ctx: pointer to a context object (not secp256k1_context_static) Out: label: pointer to the resulting label label_tweak32: pointer to the 32 byte label tweak In: scan_key32: pointer to the recipient's 32 byte scan key m: integer for the m-th label (0 is used for change outputs)

Definition at line 393 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_label_parse()

int secp256k1_silentpayments_recipient_label_parse	(	const secp256k1_context *	ctx,
		secp256k1_silentpayments_label *	label,
		const unsigned char *	in33
	)

Parse a Silent Payments label.

Returns: 1 when the label could be parsed, 0 otherwise. Args: ctx: pointer to a context object Out: label: pointer to a label object In: in33: pointer to the 33-byte label to be parsed

Definition at line 362 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_label_serialize()

int secp256k1_silentpayments_recipient_label_serialize	(	const secp256k1_context *	ctx,
		unsigned char *	out33,
		const secp256k1_silentpayments_label *	label
	)

Serialize a Silent Payments label.

Returns: 1 always Args: ctx: pointer to a context object Out: out33: pointer to a 33-byte array to store the serialized label In: label: pointer to the label

Definition at line 378 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_prevouts_summary_create()

int secp256k1_silentpayments_recipient_prevouts_summary_create	(	const secp256k1_context *	ctx,
		secp256k1_silentpayments_prevouts_summary *	prevouts_summary,
		const unsigned char *	outpoint_smallest36,
		const secp256k1_xonly_pubkey const	xonly_pubkeys,
		size_t	n_xonly_pubkeys,
		const secp256k1_pubkey const	pubkeys,
		size_t	n_pubkeys
	)

An explanation of the prevouts_summary object and its usage:

Compute Silent Payments prevouts summary from prevout public keys and transaction inputs.

The prevouts_summary object contains:

[magic: 4 bytes][boolean: 1 byte][prevouts_pubkey_sum: 64 bytes][input_hash: 32 bytes]

The magic bytes are checked by functions using the prevouts_summary object to check that the prevouts_summary object was initialized correctly.

The boolean (combined) indicates whether or not the summed prevout public keys and the input_hash scalar have already been combined or are both included. The reason for keeping input_hash and the summed prevout public keys separate is so that an elliptic curve multiplication can be avoided when creating the shared secret, i.e., (recipient_scan_key * input_hash) * prevouts_pubkey_sum.

But when storing the prevouts_summary object (not supported yet), either to send to light clients or for wallet rescans, we can save 32-bytes by combining the input_hash and prevouts_pubkey_sum and saving the resulting point serialized as a compressed public key, i.e., input_hash * prevouts_pubkey_sum.

For each function:

_recipient_prevouts_summary_create always creates a prevouts_summary object with combined = false

Definition at line 488 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_scan_outputs()

int secp256k1_silentpayments_recipient_scan_outputs	(	const secp256k1_context *	ctx,
		secp256k1_silentpayments_found_output **	found_outputs,
		uint32_t *	n_found_outputs,
		const secp256k1_xonly_pubkey const	tx_outputs,
		size_t	n_tx_outputs,
		const unsigned char *	scan_key32,
		const secp256k1_silentpayments_prevouts_summary *	prevouts_summary,
		const secp256k1_pubkey *	unlabeled_spend_pubkey,
		secp256k1_silentpayments_label_lookup	label_lookup,
		const void *	label_context
	)

Scan for Silent Payments transaction outputs.

Given a prevouts_summary object, a recipient's 32 byte scan key and spend public key, and the relevant transaction outputs, scan for outputs belonging to the recipient and return the tweak(s) needed for spending the output(s). An optional label_lookup callback function and label_context can be passed if the recipient uses labels. This allows for checking if a label exists in the recipients label cache and retrieving the label tweak during scanning.

If used, the label_lookup function must return a pointer to a 32-byte label tweak if the label is found, or NULL otherwise. The returned pointer must remain valid until the next call to label_lookup or until the function returns, whichever comes first. It is not retained beyond that.

For creating the label cache, secp256k1_silentpayments_recipient_label_create and secp256k1_silentpayments_recipient_label_serialize can be used.

Note: Scanning is bounded by SECP256K1_SILENTPAYMENTS_RECIPIENT_GROUP_LIMIT and may miss outputs if a transaction contains more outputs for a single scan public key group than this limit.

Returns: 1 if output scanning was successful. 0 if the transaction is not a Silent Payments transaction, or if the arguments are invalid.

Args: ctx: pointer to a context object Out: found_outputs: pointer to an array of pointers to found output objects. The found outputs array MUST have the same length as the tx_outputs array. n_found_outputs: pointer to an integer indicating the final size of the found outputs array. This number represents the number of outputs found while scanning (0 if none are found). Can't be larger than SECP256K1_SILENTPAYMENTS_RECIPIENT_GROUP_LIMIT. In: tx_outputs: pointer to the transaction's x-only public key outputs, in their original transaction (vout) order n_tx_outputs: the size of the tx_outputs array. scan_key32: pointer to the recipient's 32 byte scan key. The scan key is valid if it passes secp256k1_ec_seckey_verify prevouts_summary: pointer to the transaction prevouts summary data (see secp256k1_silentpayments_recipient_prevouts_summary_create). unlabeled_spend_pubkey: pointer to the recipient's unlabeled spend public key label_lookup: pointer to a callback function for looking up a label value. This function takes a serialized 33-byte label as an argument and returns a pointer to the 32-byte label tweak if the label exists, otherwise returns a NULL pointer (NULL if labels are not used) label_context: pointer to a label context object (NULL if labels are not used or context is not needed)

Definition at line 603 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_sort()

static void secp256k1_silentpayments_recipient_sort	(	const secp256k1_context *	ctx,
		const secp256k1_silentpayments_recipient **	recipients,
		size_t	n_recipients
	)

static

Definition at line 42 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_recipient_sort_cmp()

static int secp256k1_silentpayments_recipient_sort_cmp	(	const void *	pk1,
		const void *	pk2,
		void *	ctx
	)

static

Sort an array of Silent Payments recipients.

This is used to group recipients by scan pubkey to ensure the correct values of k are used when creating multiple outputs for a recipient. Since heap sort is unstable, we use the recipient's index as tie-breaker to have a well-defined order, i.e. within scan pubkey groups, the spend pubkeys appear in the same order as they were passed in.

Definition at line 30 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_sender_create_outputs()

int secp256k1_silentpayments_sender_create_outputs	(	const secp256k1_context *	ctx,
		secp256k1_xonly_pubkey **	generated_outputs,
		const secp256k1_silentpayments_recipient **	recipients,
		size_t	n_recipients,
		const unsigned char *	outpoint_smallest36,
		const secp256k1_keypair const	keypairs,
		size_t	n_keypairs,
		const unsigned char const	seckeys,
		size_t	n_seckeys
	)

Create Silent Payments outputs for recipient(s).

Given a list of n secret keys a_1...a_n (one for each Silent Payments eligible input to spend), a serialized outpoint, and a list of recipients, create the taproot outputs. Inputs with conditional branches or multiple public keys are excluded from Silent Payments eligible inputs; see BIP352 for more information.

outpoint_smallest36 refers to the smallest outpoint lexicographically from the transaction inputs (both Silent Payments eligible and non-eligible inputs). This value MUST be the smallest outpoint out of all of the transaction inputs, otherwise the recipient will be unable to find the payment. Determining the smallest outpoint from the list of transaction inputs is the responsibility of the caller. It is strongly recommended that implementations ensure they are doing this correctly by using the test vectors from BIP352.

When creating more than one generated output, all of the generated outputs MUST be included in the final transaction. Dropping any of the generated outputs from the final transaction may make all or some of the outputs unfindable by the recipient.

Returns: 1 if creation of outputs was successful. 0 on failure. This is expected only with an adversarially chosen recipient spend key. Specifically, failure occurs when:

Input secret keys sum to 0 (negligible probability if at least one of the input secret keys is uniformly random and independent of all other keys)
A hash output is not a valid scalar (negligible probability per hash evaluation)
Any group (i.e. recipients sharing the same scan public key) exceeds the protocol limit SECP256K1_SILENTPAYMENTS_RECIPIENT_GROUP_LIMIT

Args: ctx: pointer to a context object (not secp256k1_context_static). Out: generated_outputs: pointer to an array of pointers to xonly public keys, one per recipient. The outputs are ordered to match the original ordering of the recipient objects, i.e., generated_outputs[0] is the generated output for the secp256k1_silentpayments_recipient object with index = 0. In: recipients: pointer to an array of pointers to Silent Payments recipients, where each recipient is a scan public key, a spend public key, and an index indicating its position in the original ordering. The recipient array will be grouped by scan public key in place (as specified in BIP0352), but generated outputs are saved in the generated_outputs array to match the original ordering (using the index field). This ensures the caller is able to match the generated outputs to the correct Silent Payments addresses. The same recipient can be passed multiple times to create multiple outputs for the same recipient. n_recipients: the size of the recipients array. outpoint_smallest36: serialized (36-byte) smallest outpoint (lexicographically) from the transaction inputs keypairs: pointer to an array of pointers to taproot keypair inputs (can be NULL if no secret keys of taproot inputs are used) n_keypairs: the size of the keypairs array. seckeys: pointer to an array of pointers to 32-byte secret keys of non-taproot inputs (can be NULL if no secret keys of non-taproot inputs are used) n_seckeys: the size of the seckeys array.

Definition at line 187 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_sha256_init_inputs()

static void secp256k1_silentpayments_sha256_init_inputs ( secp256k1_sha256 * hash )

static

Set hash state to the BIP340 tagged hash midstate for "BIP0352/Inputs".

Definition at line 57 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_sha256_init_label()

static void secp256k1_silentpayments_sha256_init_label ( secp256k1_sha256 * hash )

static

Set hash state to the BIP340 tagged hash midstate for "BIP0352/Label".

Definition at line 339 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ secp256k1_silentpayments_sha256_init_sharedsecret()

static void secp256k1_silentpayments_sha256_init_sharedsecret ( secp256k1_sha256 * hash )

static

Set hash state to the BIP340 tagged hash midstate for "BIP0352/SharedSecret".

Definition at line 110 of file main_impl.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ secp256k1_silentpayments_label_magic

const unsigned char secp256k1_silentpayments_label_magic[4] = { 0x27, 0x9d, 0x44, 0xba }

static

Definition at line 347 of file main_impl.h.

◆ secp256k1_silentpayments_prevouts_summary_magic

const unsigned char secp256k1_silentpayments_prevouts_summary_magic[4] = { 0xa7, 0x1c, 0xd3, 0x5e }

static

magic bytes for ensuring prevouts_summary objects were initialized correctly.

Definition at line 22 of file main_impl.h.

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ secp256k1_silentpayments_calculate_input_hash_scalar()

◆ secp256k1_silentpayments_check_label_batch()

◆ secp256k1_silentpayments_create_output_pubkey()

◆ secp256k1_silentpayments_create_output_tweak()

◆ secp256k1_silentpayments_create_shared_secret()

◆ secp256k1_silentpayments_label_load()

◆ secp256k1_silentpayments_label_save()

◆ secp256k1_silentpayments_recipient_create_labeled_spend_pubkey()

◆ secp256k1_silentpayments_recipient_label_create()

◆ secp256k1_silentpayments_recipient_label_parse()

◆ secp256k1_silentpayments_recipient_label_serialize()

◆ secp256k1_silentpayments_recipient_prevouts_summary_create()

◆ secp256k1_silentpayments_recipient_scan_outputs()

◆ secp256k1_silentpayments_recipient_sort()

◆ secp256k1_silentpayments_recipient_sort_cmp()

◆ secp256k1_silentpayments_sender_create_outputs()

◆ secp256k1_silentpayments_sha256_init_inputs()

◆ secp256k1_silentpayments_sha256_init_label()

◆ secp256k1_silentpayments_sha256_init_sharedsecret()

Variable Documentation

◆ secp256k1_silentpayments_label_magic

◆ secp256k1_silentpayments_prevouts_summary_magic