Add BIP352 module (take 3)

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,106 @@ extern "C" {
  *  any further elliptic-curve operations from the wallet.
  */
 
+
+/** The data from a single recipient address
+ *
+ *  This struct serves as an input argument to `silentpayments_sender_create_outputs`.
+ *
+ *  `index` must be set to the position (starting with 0) of this recipient in the
+ *  `recipients` array passed to `silentpayments_sender_create_outputs`. It is
+ *  used to map the returned generated outputs back to the original recipient.
+ *
+ *  Note:
+ *  The spend public key named `spend_pubkey` may have been optionally tweaked with
+ *  a label by the recipient. Whether `spend_pubkey` has actually been tagged with
+ *  a label is irrelevant for the sender. As a documentation convention in this API,
+ *  `unlabeled_spend_pubkey` is used to indicate when the unlabeled spend public must
+ *  be used.
+ */
+typedef struct secp256k1_silentpayments_recipient {
+    secp256k1_pubkey scan_pubkey;
+    secp256k1_pubkey 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. 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 or the negation of a spend key
+ *               (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)
+ *
+ *  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 `_silentpayments_recipient` object with
+ *                            index = 0.
+ *  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 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
+ *                            payment 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
+ *           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 size of taproot_seckeys array.
+ *             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 size of the plain_seckeys array.
+ */
+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