silentpayments: add opaque data type public_data

Add data type for passing around the summed input public key (A_sum) and
the input hash tweak (input_hash). This data is passed to the scanner
before the ECDH step as two separate elements so that the scanner can
multiply b_scan * input_hash before doing ECDH.

Add functions for deserializing / serializing a public_data object to
and from a public key. When serializing a public_data object, the
input_hash is multplied into A_sum. This is so the object can be stored
as public key for wallet rescanning later, or to vend to light clients.
For the light client, a `_parse` function is added which parses the
compressed public key serialization into a `public_data` object.

Author: josibake

include/secp256k1_silentpayments.h

@@ -139,6 +139,139 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipien
     const secp256k1_pubkey *label
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
 
+/** Opaque data structure that holds silent payments public input data.
+ *
+ *  This structure does not contain secret data. Guaranteed to be 98 bytes in size. It can be safely
+ *  copied/moved. Created with `secp256k1_silentpayments_public_data_create`. Can be serialized as
+ *  a compressed public key using `secp256k1_silentpayments_public_data_serialize`. The serialization
+ *  is intended for sending the public input data to light clients. Light clients can use this
+ *  serialization with `secp256k1_silentpayments_public_data_parse`.
+ */
+typedef struct {
+    unsigned char data[98];
+} secp256k1_silentpayments_public_data;
+
+/** Compute Silent Payment public data from input public keys and transaction inputs.
+ *
+ * Given a list of n public keys A_1...A_n (one for each silent payment
+ * eligible input to spend) and a serialized outpoint_smallest, compute
+ * the corresponding input public tweak data:
+ *
+ * A_sum = A_1 + A_2 + ... + A_n
+ * input_hash = hash(outpoint_lowest || A_sum)
+ *
+ * The public keys have to be passed in via two different parameter pairs,
+ * one for regular and one for x-only public keys, in order to avoid the need
+ * of users converting to a common pubkey format before calling this function.
+ * The resulting data is can be used for scanning on the recipient side, or stored
+ * in an index for late use (e.g. wallet rescanning, vending data to light clients).
+ *
+ * If calling this function for scanning, the reciever must provide an output param
+ * for the `input_hash`. If calling this function for simply aggregating the inputs
+ * for later use, the caller can save the result with `silentpayments_public_data_serialize`.
+ *
+ *  Returns: 1 if tweak data creation was successful. 0 if an error occured.
+ *  Args:                  ctx: pointer to a context object
+ *  Out:           public_data: pointer to public_data object containing the summed public key and
+ *                              input_hash.
+ *  In:    outpoint_smallest36: serialized smallest outpoint
+ *               xonly_pubkeys: pointer to an array of pointers to taproot x-only
+ *                              public keys (can be NULL if no taproot inputs are used)
+ *             n_xonly_pubkeys: the number of taproot input public keys
+ *               plain_pubkeys: pointer to an array of pointers to non-taproot
+ *                              public keys (can be NULL if no non-taproot inputs are used)
+ *             n_plain_pubkeys: the number of non-taproot input public keys
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_public_data_create(
+    const secp256k1_context *ctx,
+    secp256k1_silentpayments_public_data *public_data,
+    const unsigned char *outpoint_smallest36,
+    const secp256k1_xonly_pubkey * const *xonly_pubkeys,
+    size_t n_xonly_pubkeys,
+    const secp256k1_pubkey * const *plain_pubkeys,
+    size_t n_plain_pubkeys
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
+
+/** Serialize a silentpayments_public_data object into a 33-byte sequence.
+ *
+ *  Returns: 1 always.
+ *
+ *  Args:       ctx: pointer to a context object.
+ *  Out:   output33: pointer to a 33-byte array to place the serialized `silentpayments_public_data` in.
+ *  In: public_data: pointer to an initialized silentpayments_public_data object.
+ */
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_public_data_serialize(
+    const secp256k1_context *ctx,
+    unsigned char *output33,
+    const secp256k1_silentpayments_public_data *public_data
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
+
+/** Parse a 33-byte sequence into a silent_payments_public_data object.
+ *
+ *  Returns: 1 if the data was able to be parsed.
+ *           0 if the sequence is invalid (e.g. does not represent a valid public key).
+ *
+ *  Args:        ctx: pointer to a context object.
+ *  Out: public_data: pointer to a silentpayments_public_data object. If 1 is returned, it is set to a
+ *                    parsed version of input33.
+ *  In:      input33: pointer to a serialized silentpayments_public_data.
+ */
+
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_public_data_parse(
+    const secp256k1_context *ctx,
+    secp256k1_silentpayments_public_data *public_data,
+    const unsigned char *input33
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
+
+/** Scan for Silent Payment transaction outputs.
+ *
+ *  Given a input public sum, an input_hash, a recipient's spend public key B_spend, and the relevant transaction
+ *  outputs, scan for outputs belong 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.
+ *
+ *  Returns: 1 if output scanning was successful. 0 if an error occured.
+ *  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 be initialized to be 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)
+ *  In:             tx_outputs: pointer to the tx's x-only public key outputs
+ *                n_tx_outputs: the number of tx_outputs being scanned
+ *                    scan_key: pointer to the recipient's scan key
+ *                 public_data: pointer to the input public key sum (optionaly, with the `input_hash`
+ *                              multiplied in, see `_recipient_compute_public_data`).
+ *      recipient_spend_pubkey: pointer to the receiver's spend pubkey
+ *                label_lookup: pointer to a callback function for looking up a label value. This fucntion
+ *                              takes a label pubkey as an argument and returns a pointer to the label tweak
+ *                              if the label exists, otherwise returns a nullptr (NULL if labels are not used)
+ *               label_context: pointer to a label context object (NULL if labels are not used)
+ */
+
+typedef const unsigned char* (*secp256k1_silentpayments_label_lookup)(const secp256k1_pubkey*, const void*);
+typedef struct {
+    secp256k1_xonly_pubkey output;
+    unsigned char tweak[32];
+    int found_with_label;
+    secp256k1_pubkey label;
+} secp256k1_silentpayments_found_output;
+
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_silentpayments_recipient_scan_outputs(
+    const secp256k1_context *ctx,
+    secp256k1_silentpayments_found_output **found_outputs,
+    size_t *n_found_outputs,
+    const secp256k1_xonly_pubkey * const *tx_outputs,
+    size_t n_tx_outputs,
+    const unsigned char *scan_key,
+    const secp256k1_silentpayments_public_data *public_data,
+    const secp256k1_pubkey *receiver_spend_pubkey,
+    const secp256k1_silentpayments_label_lookup label_lookup,
+    const void *label_context
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4)
+    SECP256K1_ARG_NONNULL(6) SECP256K1_ARG_NONNULL(7) SECP256K1_ARG_NONNULL(8);
+
 #ifdef __cplusplus
 }
 #endif

src/modules/silentpayments/main_impl.h

@@ -320,4 +320,109 @@ int secp256k1_silentpayments_recipient_create_labelled_spend_pubkey(const secp25
     return 1;
 }
 
+int secp256k1_silentpayments_recipient_public_data_create(
+    const secp256k1_context *ctx,
+    secp256k1_silentpayments_public_data *public_data,
+    const unsigned char *outpoint_smallest36,
+    const secp256k1_xonly_pubkey * const *xonly_pubkeys,
+    size_t n_xonly_pubkeys,
+    const secp256k1_pubkey * const *plain_pubkeys,
+    size_t n_plain_pubkeys
+) {
+    size_t i;
+    size_t pubkeylen = 65;
+    secp256k1_pubkey A_sum;
+    secp256k1_ge A_sum_ge, addend;
+    secp256k1_gej A_sum_gej;
+    unsigned char input_hash_local[32];
+
+    /* Sanity check inputs */
+    VERIFY_CHECK(ctx != NULL);
+    ARG_CHECK(public_data != NULL);
+    ARG_CHECK(plain_pubkeys == NULL || n_plain_pubkeys >= 1);
+    ARG_CHECK(xonly_pubkeys == NULL || n_xonly_pubkeys >= 1);
+    ARG_CHECK((plain_pubkeys != NULL) || (xonly_pubkeys != NULL));
+    ARG_CHECK((n_plain_pubkeys + n_xonly_pubkeys) >= 1);
+    ARG_CHECK(outpoint_smallest36 != NULL);
+    memset(input_hash_local, 0, 32);
+
+    /* Compute input public keys sum: A_sum = A_1 + A_2 + ... + A_n */
+    secp256k1_gej_set_infinity(&A_sum_gej);
+    for (i = 0; i < n_plain_pubkeys; i++) {
+        secp256k1_pubkey_load(ctx, &addend, plain_pubkeys[i]);
+        secp256k1_gej_add_ge_var(&A_sum_gej, &A_sum_gej, &addend, NULL);
+    }
+    for (i = 0; i < n_xonly_pubkeys; i++) {
+        secp256k1_xonly_pubkey_load(ctx, &addend, xonly_pubkeys[i]);
+        secp256k1_gej_add_ge_var(&A_sum_gej, &A_sum_gej, &addend, NULL);
+    }
+    if (secp256k1_gej_is_infinity(&A_sum_gej)) {
+        /* TODO: do we need a special error return code for this case? */
+        return 0;
+    }
+    secp256k1_ge_set_gej(&A_sum_ge, &A_sum_gej);
+
+    /* Compute input_hash = hash(outpoint_L || A_sum) */
+    secp256k1_silentpayments_calculate_input_hash(input_hash_local, outpoint_smallest36, &A_sum_ge);
+    secp256k1_pubkey_save(&A_sum, &A_sum_ge);
+    /* serialize the public_data struct */
+    public_data->data[0] = 0;
+    secp256k1_ec_pubkey_serialize(ctx, &public_data->data[1], &pubkeylen, &A_sum, SECP256K1_EC_UNCOMPRESSED);
+    memcpy(&public_data->data[1 + pubkeylen], input_hash_local, 32);
+    return 1;
+}
+
+static int secp256k1_silentpayments_recipient_public_data_load(const secp256k1_context *ctx, secp256k1_pubkey *pubkey, unsigned char *input_hash, const secp256k1_silentpayments_public_data *public_data) {
+    int combined;
+    size_t pubkeylen = 65;
+    VERIFY_CHECK(ctx != NULL);
+    ARG_CHECK(pubkey != NULL);
+    ARG_CHECK(public_data != NULL);
+
+    combined = (int)public_data->data[0];
+    ARG_CHECK(combined == 0 || combined == 1);
+    if (combined) {
+        ARG_CHECK(combined == 1 && input_hash == NULL);
+    } else {
+        ARG_CHECK(combined == 0 && input_hash != NULL);
+        memcpy(input_hash, &public_data->data[1 + pubkeylen], 32);
+    }
+    if (!secp256k1_ec_pubkey_parse(ctx, pubkey, &public_data->data[1], pubkeylen)) {
+        return 0;
+    }
+    return 1;
+}
+
+int secp256k1_silentpayments_recipient_public_data_serialize(const secp256k1_context *ctx, unsigned char *output33, const secp256k1_silentpayments_public_data *public_data) {
+    secp256k1_pubkey pubkey;
+    unsigned char input_hash[32];
+    size_t pubkeylen = 33;
+
+    ARG_CHECK(public_data->data[0] == 0);
+    if (!secp256k1_silentpayments_recipient_public_data_load(ctx, &pubkey, input_hash, public_data)) {
+        return 0;
+    }
+    if (!secp256k1_ec_pubkey_tweak_mul(ctx, &pubkey, input_hash)) {
+        return 0;
+    }
+    secp256k1_ec_pubkey_serialize(ctx, output33, &pubkeylen, &pubkey, SECP256K1_EC_COMPRESSED);
+    return 1;
+}
+
+int secp256k1_silentpayments_recipient_public_data_parse(const secp256k1_context *ctx, secp256k1_silentpayments_public_data *public_data, const unsigned char *input33) {
+    size_t inputlen = 33;
+    size_t pubkeylen = 65;
+    secp256k1_pubkey pubkey;
+
+    ARG_CHECK(public_data != NULL);
+    ARG_CHECK(input33 != NULL);
+    if (!secp256k1_ec_pubkey_parse(ctx, &pubkey, input33, inputlen)) {
+        return 0;
+    }
+    public_data->data[0] = 1;
+    secp256k1_ec_pubkey_serialize(ctx, &public_data->data[1], &pubkeylen, &pubkey, SECP256K1_EC_UNCOMPRESSED);
+    memset(&public_data->data[1 + pubkeylen], 0, 32);
+    return 1;
+}
+
 #endif