batch_interface: move batch context functions to empty batch modules

- move create, destroy and verify function into batch module
- rename `batch_context` to `batch` (in function names)
- rename `batch_ctx` variable to `batch`
- documentation uses "batch object" instead of "batch context"

Author: siv2r

Makefile.am

@@ -50,7 +50,6 @@ noinst_HEADERS += src/assumptions.h
 noinst_HEADERS += src/util.h
 noinst_HEADERS += src/scratch.h
 noinst_HEADERS += src/scratch_impl.h
-noinst_HEADERS += src/batch_impl.h
 noinst_HEADERS += src/selftest.h
 noinst_HEADERS += src/testrand.h
 noinst_HEADERS += src/testrand_impl.h
@@ -172,6 +171,7 @@ if BUILD_WINDOWS
 schnorr_example_LDFLAGS += -lbcrypt
 endif
 TESTS += schnorr_example
+if ENABLE_MODULE_BATCH
 noinst_PROGRAMS += batch_example
 batch_example_SOURCES = examples/batch.c
 batch_example_CPPFLAGS = -I$(top_srcdir)/include
@@ -183,6 +183,7 @@ endif
 TESTS += batch_example
 endif
 endif
+endif
 
 ### Precomputed tables
 EXTRA_PROGRAMS = precompute_ecmult precompute_ecmult_gen

examples/batch.c

@@ -3,6 +3,7 @@
 #include <string.h>
 
 #include <secp256k1.h>
+#include <secp256k1_batch.h>
 #include <secp256k1_schnorrsig.h>
 
 #include "random.h"
@@ -82,12 +83,14 @@ int generate_xonlypub_tweak_checks(secp256k1_context *ctx) {
 int main(void) {
     int ret;
     size_t i;
-    /* batch_context uses secp256k1_context only for the error callback function*/
+    /* batch object uses secp256k1_context only for the error callback function
+     * here, we create secp256k1_context that can sign and verify, only to generate
+     * input data (schnorrsigs, tweak checks) required for the batch */
     secp256k1_context *ctx = secp256k1_context_create(SECP256K1_CONTEXT_SIGN | SECP256K1_CONTEXT_VERIFY);
-    secp256k1_batch_context *batch_ctx = secp256k1_batch_context_create(ctx, N_TERMS);
+    secp256k1_batch *batch = secp256k1_batch_create(ctx, N_TERMS);
 
     assert(ctx != NULL);
-    assert(batch_ctx != NULL);
+    assert(batch != NULL);
 
     /* key pair generation */
     printf("Creating a key pair.........................");
@@ -105,9 +108,9 @@ int main(void) {
     }
     printf("ok\n");
 
-    printf("Adding signatures to the batch context......");
+    printf("Adding signatures to the batch object.......");
     for (i = 0; i < N_SIGS; i++) {
-        ret = secp256k1_batch_context_add_schnorrsig(ctx, batch_ctx, sig[i], msg[i], sizeof(msg[i]), &pk);
+        ret = secp256k1_batch_add_schnorrsig(ctx, batch, sig[i], msg[i], sizeof(msg[i]), &pk);
         if(!ret) {
             printf("FAILED\n");
             return 1;
@@ -122,24 +125,24 @@ int main(void) {
     }
     printf("ok\n");
 
-    printf("Adding tweak checks to the batch context....");
+    printf("Adding tweak checks to the batch object.....");
     for (i = 0; i < N_CHECKS; i++) {
-        ret = secp256k1_batch_context_add_xonlypub_tweak(ctx, batch_ctx, tweaked_pubkey[i], tweaked_pk_parity[i], &pk, tweak[i]);
+        ret = secp256k1_batch_add_xonlypub_tweak(ctx, batch, tweaked_pubkey[i], tweaked_pk_parity[i], &pk, tweak[i]);
         if(!ret) {
             printf("FAILED\n");
             return 1;
         }
     }
     printf("ok\n");
 
-    printf("Verifying the batch context.................");
-    if(!secp256k1_batch_context_verify(ctx, batch_ctx)) {
+    printf("Verifying the batch object..................");
+    if(!secp256k1_batch_verify(ctx, batch)) {
         printf("FAILED\n");
         return 1;
     }
     printf("ok\n");
 
-    secp256k1_batch_context_destroy(ctx, batch_ctx);
+    secp256k1_batch_destroy(ctx, batch);
     secp256k1_context_destroy(ctx);
 
     return 0;

include/secp256k1.h

@@ -58,15 +58,6 @@ typedef struct secp256k1_context_struct secp256k1_context;
  */
 typedef struct secp256k1_scratch_space_struct secp256k1_scratch_space;
 
-/** Opaque data structure that holds context information for schnorr batch verification.
- *
- *  The purpose of this structure is to store elliptic curve points, their scalars,
- *  and scalar of generator point participating in Multi-Scalar Point Multiplication
- *  computation. This computation is done by secp256k1_ecmult_strauss_batch or
- *  secp256k1_ecmult_pippenger_batch.
- */
-typedef struct secp256k1_batch_context_struct secp256k1_batch_context;
-
 /** Opaque data structure that holds a parsed and valid public key.
  *
  *  The exact representation of data inside is implementation defined and not
@@ -360,51 +351,6 @@ SECP256K1_API void secp256k1_scratch_space_destroy(
     secp256k1_scratch_space* scratch
 ) SECP256K1_ARG_NONNULL(1);
 
-/** Create a secp256k1 batch context 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 context object.
- *  Args:        ctx:  an existing secp256k1_context object. Not to be confused
- *                     with the batch context object that this function creates.
- *  In:      max_terms:  max number of (scalar, curve point) pairs that the batch
- *                     object can store.
- */
-SECP256K1_API secp256k1_batch_context* secp256k1_batch_context_create(
-    const secp256k1_context* ctx,
-    size_t max_terms
-) SECP256K1_ARG_NONNULL(1) SECP256K1_WARN_UNUSED_RESULT;
-
-/** Destroy a secp256k1 batch context object (created in dynamically allocated memory).
- *
- *  The context pointer may not be used afterwards.
- *
- *  Args:       ctx: a secp256k1 context object.
- *        batch_ctx: an existing batch context to destroy, constructed
- *                   using secp256k1_batch_context_create
- */
-SECP256K1_API void secp256k1_batch_context_destroy(
-    const secp256k1_context* ctx,
-    secp256k1_batch_context* batch_ctx
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
-
-/** Verify the set of schnorr signatures or tweaked pubkeys present in the secp256k1_batch_context.
- *
- *  Returns: 1: correct schnorrsigs/tweaks
- *           0: incorrect schnorrsigs/tweaks
- *
- *  In particular, returns 1 if the batch context is empty (i.e, batch_ctx->len = 0).
- *
- *  Args:    ctx: a secp256k1 context object (can be initialized for none).
- *     batch_ctx: a secp256k1 batch context object that contains a
- *                set of schnorrsigs/tweaks.
- */
-SECP256K1_API int secp256k1_batch_context_verify(
-    const secp256k1_context *ctx,
-    secp256k1_batch_context *batch_ctx
-) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
-
 /** Parse a variable-length public key into the pubkey object.
  *
  *  Returns: 1 if the public key was fully valid.

include/secp256k1_batch.h

@@ -1,11 +1,13 @@
 #ifndef SECP256K1_BATCH_H
 #define SECP256K1_BATCH_H
 
+#include "include/secp256k1.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/** This module implements a Batch Verification context that supports:
+/** This module implements a Batch Verification object that supports:
  *
  *  1. Schnorr signatures compliant with Bitcoin Improvement Proposal 340
  *     "Schnorr Signatures for secp256k1"
@@ -16,6 +18,59 @@ 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 scalars,
+ *  and scalar of generator point participating in Multi-Scalar Point Multiplication
+ *  computation. This computation is done by secp256k1_ecmult_strauss_batch or
+ *  secp256k1_ecmult_pippenger_batch.
+ */
+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.
+ */
+SECP256K1_API secp256k1_batch* secp256k1_batch_create(
+    const secp256k1_context* ctx,
+    size_t max_terms
+) 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);
+
+/** Verify the set of schnorr signatures or tweaked pubkeys present in the secp256k1_batch.
+ *
+ *  Returns: 1: correct schnorrsigs/tweaks
+ *           0: incorrect schnorrsigs/tweaks
+ *
+ *  In particular, returns 1 if the batch object is empty (i.e, batch->len = 0).
+ *
+ *  Args:    ctx: a secp256k1 context object (can be initialized for none).
+ *     batch: a secp256k1 batch object that contains a set of schnorrsigs/tweaks.
+ */
+SECP256K1_API int secp256k1_batch_verify(
+    const secp256k1_context *ctx,
+    secp256k1_batch *batch
+) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2);
+
 #ifdef __cplusplus
 }
 #endif

include/secp256k1_schnorrsig.h

@@ -3,6 +3,7 @@
 
 #include "secp256k1.h"
 #include "secp256k1_extrakeys.h"
+#include "include/secp256k1_batch.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -164,8 +165,8 @@ SECP256K1_API int secp256k1_schnorrsig_sign_custom(
  *  Args:    ctx: a secp256k1 context object, initialized for verification.
  *  In:    sig64: pointer to the 64-byte signature to verify.
  *           msg: the message being verified. Can only be NULL if msglen is 0.
- *        msglen: length of the message
- *        pubkey: pointer to an x-only public key to verify with (cannot be NULL)
+ *        msglen: length of the message.
+ *        pubkey: pointer to an x-only public key to verify with (cannot be NULL).
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify(
     const secp256k1_context* ctx,
@@ -175,36 +176,34 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify(
     const secp256k1_xonly_pubkey *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(5);
 
-/** Adds the given schnorrsig verification data to secp256k1_batch_context.
+/** Adds the given schnorrsig verification data to secp256k1_batch.
  *
  *  Returns 1 on success, 0 on failure.
  *  Args:    ctx: a secp256k1 context object (can be initialized for none).
- *     batch_ctx: a secp256k1 batch context object created using
- *                the secp256k1_batch_context_create API
+ *         batch: a secp256k1 batch object created using `secp256k1_batch_create`.
  *  In:    sig64: pointer to the 64-byte signature to verify.
  *           msg: the message being verified. Can only be NULL if msglen is 0.
- *        msglen: length of the message
- *        pubkey: pointer to an x-only public key to verify with (cannot be NULL)
+ *        msglen: length of the message.
+ *        pubkey: pointer to an x-only public key to verify with (cannot be NULL).
  */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_batch_context_add_schnorrsig(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_batch_add_schnorrsig(
     const secp256k1_context* ctx,
-    secp256k1_batch_context *batch_ctx,
+    secp256k1_batch *batch,
     const unsigned char *sig64,
     const unsigned char *msg,
     size_t msglen,
     const secp256k1_xonly_pubkey *pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(6);
 
-/** Adds the given tweaked pubkey, internal pubkey, and tweak32 to secp256k1_batch_context.
+/** Adds the given tweaked pubkey, internal pubkey, and tweak32 to secp256k1_batch.
  *
  *  The tweaked pubkey is represented by its 32-byte x-only serialization and
  *  its pk_parity, which can both be obtained by converting the result of
  *  tweak_add to a secp256k1_xonly_pubkey.
  *
  *  Returns 1 on success, 0 on failure.
  *  Args:            ctx: pointer to a context object initialized for verification.
- *             batch_ctx: a secp256k1 batch context object created using
- *                        the secp256k1_batch_context_create API.
+ *                 batch: a secp256k1 batch object created using `secp256k1_batch_create`.
  *  In: tweaked_pubkey32: pointer to a serialized xonly_pubkey.
  *     tweaked_pk_parity: the parity of the tweaked pubkey (whose serialization
  *                        is passed in as tweaked_pubkey32). This must match the
@@ -214,9 +213,9 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_batch_context_add_schno
  *       internal_pubkey: pointer to an x-only public key object to apply the tweak to.
  *               tweak32: pointer to a 32-byte tweak.
  */
-SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_batch_context_add_xonlypub_tweak(
+SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_batch_add_xonlypub_tweak(
     const secp256k1_context* ctx,
-    secp256k1_batch_context *batch_ctx,
+    secp256k1_batch *batch,
     const unsigned char *tweaked_pubkey32,
     int tweaked_pk_parity,
     const secp256k1_xonly_pubkey *internal_pubkey,