batch: Add create and destroy APIs

This commit adds the _batch_create and _batch_destroy APIs.

Relevant Links:
1. _batch_scratch_size allocation formula is taken from bench ecmult:
https://github.com/bitcoin-core/secp256k1/blob/694ce8fb2d1fd8a3d641d7c33705691d41a2a860/src/bench_ecmult.c#L312.
2. aux_rand16 param in _batch_create enables synthetic randomness for
randomizer generation: sipa/bips#204.

Author: siv2r

include/secp256k1_batch.h

@@ -18,6 +18,51 @@ extern "C" {
  *     (https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki).
  */
 
+/** Opaque data structure that holds information required for the batch verification.
+ *
+ *  The purpose of this structure is to store elliptic curve points, their scalar
+ *  coefficients, and scalar coefficient of generator point participating in Multi-Scalar
+ *  Point Multiplication computation, which is done by `secp256k1_ecmult_strauss_batch_internal`
+ */
+typedef struct secp256k1_batch_struct secp256k1_batch;
+
+/** Create a secp256k1 batch object object (in dynamically allocated memory).
+ *
+ *  This function uses malloc to allocate memory. It is guaranteed that malloc is
+ *  called at most twice for every call of this function.
+ *
+ *  Returns: a newly created batch object.
+ *  Args:        ctx: an existing `secp256k1_context` object. Not to be confused
+ *                    with the batch object object that this function creates.
+ *  In:    max_terms: Max number of (scalar, curve point) pairs that the batch
+ *                    object can store.
+ *                    1. `batch_add_schnorrsig`         - adds two scalar-point pairs to the batch
+ *                    2. `batch_add_xonpub_tweak_check` - adds one scalar-point pair to the batch
+ *                    Hence, for adding n schnorrsigs and m tweak checks, `max_terms`
+ *                    should be set to 2*n + m.
+ *        aux_rand16: 16 bytes of fresh randomness. While recommended to provide
+ *                    this, it is only supplemental to security and can be NULL. A
+ *                    NULL argument is treated the same as an all-zero one.
+ */
+SECP256K1_API secp256k1_batch* secp256k1_batch_create(
+    const secp256k1_context* ctx,
+    size_t max_terms,
+    const unsigned char *aux_rand16
+) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
+
+/** Destroy a secp256k1 batch object (created in dynamically allocated memory).
+ *
+ *  The batch object's pointer may not be used afterwards.
+ *
+ *  Args:       ctx: a secp256k1 context object.
+ *            batch: an existing batch object to destroy, constructed
+ *                   using `secp256k1_batch_create`
+ */
+SECP256K1_API void secp256k1_batch_destroy(
+    const secp256k1_context* ctx,
+    secp256k1_batch* batch
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
+
 #ifdef __cplusplus
 }
 #endif

src/modules/batch/main_impl.h

@@ -3,4 +3,139 @@
 
 #include "include/secp256k1_batch.h"
 
+/** Opaque data structure that holds information required for the batch verification.
+ *
+ *  Members:
+ *       data: scratch space object that contains points (_gej) and their
+ *             respective scalars. To be used in Multi-Scalar Multiplication
+ *             algorithms such as Strauss and Pippenger.
+ *    scalars: pointer to scalars allocated on the scratch space.
+ *     points: pointer to points allocated on the scratch space.
+ *       sc_g: scalar corresponding to the generator point (G) in Multi-Scalar
+ *             Multiplication equation.
+ *     sha256: contains hash of all the inputs (schnorrsig/tweaks) present in
+ *             the batch object, expect the first input. Used for generating a random secp256k1_scalar
+ *             for each term added by secp256k1_batch_add_*.
+ *     sha256: contains hash of all inputs (except the first one) present in the batch.
+ *             `secp256k1_batch_add_` APIs use these for randomizing the scalar (i.e., multiplying
+ *             it with a newly generated scalar) before adding it to the batch.
+ *        len: number of scalar-point pairs present in the batch.
+ *   capacity: max number of scalar-point pairs that the batch can hold.
+ *     result: tells whether the given set of inputs (schnorrsigs or tweak checks) is valid
+ *             or invalid. 1 = valid and 0 = invalid. By default, this is set to 1
+ *             during batch object creation (i.e., `secp256k1_batch_create`).
+ *
+ *  The following struct name is typdef as secp256k1_batch (in include/secp256k1_batch.h).
+ */
+struct secp256k1_batch_struct{
+    secp256k1_scratch *data;
+    secp256k1_scalar *scalars;
+    secp256k1_gej *points;
+    secp256k1_scalar sc_g;
+    secp256k1_sha256 sha256;
+    size_t len;
+    size_t capacity;
+    int result;
+};
+
+static size_t secp256k1_batch_scratch_size(int max_terms) {
+    size_t ret = secp256k1_strauss_scratch_size(max_terms) + STRAUSS_SCRATCH_OBJECTS*16;
+    VERIFY_CHECK(ret != 0);
+
+    return ret;
+}
+
+/** Allocates space for `batch->capacity` number of scalars and points on batch
+ *  object's scratch space */
+static int secp256k1_batch_scratch_alloc(const secp256k1_callback* error_callback, secp256k1_batch* batch) {
+    size_t checkpoint = secp256k1_scratch_checkpoint(error_callback, batch->data);
+    size_t count = batch->capacity;
+
+    VERIFY_CHECK(count > 0);
+
+    batch->scalars = (secp256k1_scalar*)secp256k1_scratch_alloc(error_callback, batch->data, count*sizeof(secp256k1_scalar));
+    batch->points = (secp256k1_gej*)secp256k1_scratch_alloc(error_callback, batch->data, count*sizeof(secp256k1_gej));
+
+    /* If scalar or point allocation fails, restore scratch space to previous state */
+    if (batch->scalars == NULL || batch->points == NULL) {
+        secp256k1_scratch_apply_checkpoint(error_callback, batch->data, checkpoint);
+        return 0;
+    }
+
+    return 1;
+}
+
+/* Initializes SHA256 with fixed midstate. This midstate was computed by applying
+ * SHA256 to SHA256("BIP0340/batch")||SHA256("BIP0340/batch"). */
+static void secp256k1_batch_sha256_tagged(secp256k1_sha256 *sha) {
+    secp256k1_sha256_initialize(sha);
+    sha->s[0] = 0x79e3e0d2ul;
+    sha->s[1] = 0x12284f32ul;
+    sha->s[2] = 0xd7d89e1cul;
+    sha->s[3] = 0x6491ea9aul;
+    sha->s[4] = 0xad823b2ful;
+    sha->s[5] = 0xfacfe0b6ul;
+    sha->s[6] = 0x342b78baul;
+    sha->s[7] = 0x12ece87cul;
+
+    sha->bytes = 64;
+}
+
+secp256k1_batch* secp256k1_batch_create(const secp256k1_context* ctx, size_t max_terms, const unsigned char *aux_rand16) {
+    size_t batch_size;
+    secp256k1_batch* batch;
+    size_t batch_scratch_size;
+    unsigned char zeros[16] = {0};
+
+    VERIFY_CHECK(ctx != NULL);
+    ARG_CHECK(max_terms != 0);
+
+    batch_size = sizeof(secp256k1_batch);
+    batch = (secp256k1_batch *)checked_malloc(&ctx->error_callback, batch_size);
+    batch_scratch_size = secp256k1_batch_scratch_size(max_terms);
+    if (batch != NULL) {
+        /* create scratch space inside batch object, if that fails return NULL*/
+        batch->data = secp256k1_scratch_create(&ctx->error_callback, batch_scratch_size);
+        if (batch->data == NULL) {
+            return NULL;
+        }
+        /* allocate memeory for `max_terms` number of scalars and points on scratch space */
+        batch->capacity = max_terms;
+        if (!secp256k1_batch_scratch_alloc(&ctx->error_callback, batch)) {
+            /* if scratch memory allocation fails, free all the previous the allocated memory
+            and return NULL */
+            secp256k1_scratch_destroy(&ctx->error_callback, batch->data);
+            free(batch);
+            return NULL;
+        }
+
+        /* set remaining data members */
+        secp256k1_scalar_clear(&batch->sc_g);
+        secp256k1_batch_sha256_tagged(&batch->sha256);
+        if (aux_rand16 != NULL) {
+            secp256k1_sha256_write(&batch->sha256, aux_rand16, 16);
+        } else {
+            /* use 16 bytes of 0x0000...000, if no fresh randomness provided */
+            secp256k1_sha256_write(&batch->sha256, zeros, 16);
+        }
+        batch->len = 0;
+        batch->result = 1;
+    }
+
+    return batch;
+}
+
+void secp256k1_batch_destroy(const secp256k1_context *ctx, secp256k1_batch *batch) {
+    VERIFY_CHECK(ctx != NULL);
+
+    if (batch != NULL) {
+        if(batch->data != NULL) {
+            /* can't destroy a scratch space with non-zero size */
+            secp256k1_scratch_apply_checkpoint(&ctx->error_callback, batch->data, 0);
+            secp256k1_scratch_destroy(&ctx->error_callback, batch->data);
+        }
+        free(batch);
+    }
+}
+
 #endif /* SECP256K1_MODULE_BATCH_MAIN_H */