Add BIP352 silentpayments module

include/secp256k1_silentpayments.h

@@ -2,6 +2,7 @@
 #define SECP256K1_SILENTPAYMENTS_H
 
 #include "secp256k1.h"
+#include "secp256k1_extrakeys.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -25,6 +26,93 @@ extern "C" {
  *  any further elliptic-curve operations from the wallet.
  */
 
+/** This struct serves as an input parameter for passing the silent payment
+ *  address data to `silentpayments_sender_create_outputs`.
+ *
+ *  The index field is for when more than one address is being sent to in
+ *  a transaction. Index is set to the position of this recipient in the
+ *  `recipients` array passed to `silentpayments_sender_create_outputs`
+ *  and used to return the generated outputs matching the original ordering.
+ *
+ *  The spend public key field is named `labeled_spend_pubkey` to indicate this
+ *  spend public key may be tweaked with an optional label. This is not relevant
+ *  for the sender and is purely a documentation convention to differentiate
+ *  between other uses of `spend_pubkey` in this API, where it is meant to refer
+ *  to the unlabeled spend public key.
+ */
+typedef struct {
+    secp256k1_pubkey scan_pubkey;
+    secp256k1_pubkey labeled_spend_pubkey;
+    size_t index;
+} secp256k1_silentpayments_recipient;
+
+/** Create Silent Payment outputs for recipient(s).
+ *
+ *  Given a list of n secret keys a_1...a_n (one for each silent payment
+ *  eligible input to spend), a serialized outpoint, and a list of recipients,
+ *  create the taproot outputs.
+ *
+ *  `outpoint_smallest` 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.
+ *
+ *  If necessary, the secret keys are negated to enforce the right y-parity.
+ *  For that reason, the secret keys have to be passed in via two different
+ *  parameter pairs, depending on whether the seckeys correspond to x-only
+ *  outputs or not.
+ *
+ *  Returns: 1 if creation of outputs was successful. 0 if an error occurred.
+ *  Args:                ctx: pointer to a context object
+ *  Out:   generated_outputs: pointer to an array of pointers to xonly pubkeys,
+ *                            one per recipient.
+ *                            The outputs here are sorted by the index value
+ *                            provided in the recipient objects.
+ *  In:           recipients: pointer to an array of pointers to silent payment
+ *                            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 sorted in place, but
+ *                            generated outputs are saved in the
+ *                            `generated_outputs` array to match the ordering
+ *                            from the index field. This ensures the caller is
+ *                            able to match the generated outputs to the
+ *                            correct silent payment addresses. The same
+ *                            recipient can be passed multiple times to create
+ *                            multiple outputs for the same recipient.
+ *              n_recipients: the number of recipients. This is equal to the
+ *                            total number of outputs to be generated as each
+ *                            recipient may passed multiple times to generate
+ *                            multiple outputs for the same recipient
+ *         outpoint_smallest: serialized (36-byte) smallest outpoint
+ *                            (lexicographically) from the transaction inputs
+ *           taproot_seckeys: pointer to an array of pointers to taproot
+ *                            keypair inputs (can be NULL if no secret keys
+ *                            of taproot inputs are used)
+ *         n_taproot_seckeys: the number of sender's taproot input secret keys
+ *             plain_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_plain_seckeys: the number of sender's non-taproot input secret
+ *                            keys
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT 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 *taproot_seckeys,
+    size_t n_taproot_seckeys,
+    const unsigned char * const *plain_seckeys,
+    size_t n_plain_seckeys
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(5);
+
 #ifdef __cplusplus
 }
 #endif