@semaphore-protocol/proof 4.0.0-alpha.8 → 4.0.0-beta

package/README.md

@@ -18,7 +18,7 @@
     <a href="https://npmjs.org/package/@semaphore-protocol/proof">
         <img alt="Downloads" src="https://img.shields.io/npm/dm/@semaphore-protocol/proof.svg?style=flat-square" />
     </a>
-    <a href="https://js.semaphore.pse.dev/proof">
+    <a href="https://js.semaphore.pse.dev/modules/_semaphore_protocol_proof">
         <img alt="Documentation typedoc" src="https://img.shields.io/badge/docs-typedoc-744C7C?style=flat-square">
     </a>
     <a href="https://eslint.org/">
@@ -49,8 +49,8 @@
     </h4>
 </div>
 
-| This library provides utility functions to generate and verify Semaphore proofs compatible with the Semaphore [circuits](https://github.com/semaphore-protocol/semaphore/tree/main/circuits). Generating valid zero-knowledge proofs requires files that can only be obtained in an attested [trusted-setup ceremony](https://storage.googleapis.com/trustedsetup-a86f4.appspot.com/semaphore/semaphore_top_index.html). For a complete list of ready-to-use files visit [trusted-setup-pse.org](http://www.trusted-setup-pse.org/). |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| This library provides utility functions to generate and verify Semaphore proofs compatible with the Semaphore [circuits](https://github.com/semaphore-protocol/semaphore/tree/main/circuits). Generating valid zero-knowledge proofs requires files that can only be obtained in an attested trusted-setup ceremony. |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 
 ## 🛠 Install
 
@@ -70,6 +70,8 @@ yarn add @semaphore-protocol/identity @semaphore-protocol/group @semaphore-proto
 
 ## 📜 Usage
 
+For more information on the functions provided by `@semaphore-protocol/proof`, please refer to the [TypeDoc documentation](https://js.semaphore.pse.dev/modules/_semaphore_protocol_proof).
+
 \# **generateProof**(
 identity: _Identity_,
 group: _Group_,

package/dist/index.browser.js

@@ -1,11 +1,14 @@
 /**
  * @module @semaphore-protocol/proof
- * @version 4.0.0-alpha.8
+ * @version 4.0.0-beta
  * @file A library to generate and verify Semaphore proofs.
  * @copyright Ethereum Foundation 2024
  * @license MIT
  * @see [Github]{@link https://github.com/semaphore-protocol/semaphore/tree/main/packages/proof}
 */
+import { packGroth16Proof, unpackGroth16Proof } from '@zk-kit/utils';
+export { packGroth16Proof, unpackGroth16Proof } from '@zk-kit/utils';
+import { requireNumber, requireDefined, requireObject, requireTypes, requireString, requireArray } from '@semaphore-protocol/utils/errors';
 import { groth16 } from 'snarkjs';
 import { keccak256 } from 'ethers/crypto';
 import { toBeHex, toBigInt as toBigInt$1 } from 'ethers/utils';
@@ -82,9 +85,16 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * Returns the zero-knowledge artifact paths. Artifacts exist for each tree
+ * depth supported by Semaphore, and they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 function getSnarkArtifacts(treeDepth) {
     return __awaiter(this, void 0, void 0, function () {
         return __generator(this, function (_a) {
+            requireNumber(treeDepth, "treeDepth");
             return [2 /*return*/, {
                     wasmFilePath: "https://semaphore.cedoor.dev/artifacts/".concat(treeDepth, "/semaphore.wasm"),
                     zkeyFilePath: "https://semaphore.cedoor.dev/artifacts/".concat(treeDepth, "/semaphore.zkey")
@@ -103,23 +113,10 @@ function hash(message) {
 }
 
 /**
- * Packs the Groth16 proof points into a format compatible with Semaphore.
- * @param proof The proof points generated with SnarkJS.
- * @returns The proof points compatible with Semaphore.
+ * Converts a bignumberish to a bigint.
+ * @param value The value to be converted to bigint.
+ * @return The value converted to bigint.
  */
-function packPoints(proof) {
-    return [
-        proof.pi_a[0],
-        proof.pi_a[1],
-        proof.pi_b[0][1],
-        proof.pi_b[0][0],
-        proof.pi_b[1][1],
-        proof.pi_b[1][0],
-        proof.pi_c[0],
-        proof.pi_c[1]
-    ];
-}
-
 function toBigInt(value) {
     try {
         return toBigInt$1(value);
@@ -133,7 +130,17 @@ function toBigInt(value) {
 }
 
 /**
- * Generates a Semaphore proof.
+ * It generates a Semaphore proof, i.e. a zero-knowledge proof that an identity that
+ * is part of a group has shared an anonymous message.
+ * The message may be any arbitrary user-defined value (e.g. a vote), or the hash of that value.
+ * The scope is a value used like a topic on which users can generate a valid proof only once,
+ * for example the id of an election in which voters can only vote once.
+ * The hash of the identity's scope and secret scalar is called a nullifier and can be
+ * used to verify whether that identity has already generated a valid proof in that scope.
+ * The depth of the tree determines which zero-knowledge artifacts to use to generate the proof.
+ * If it is not defined, it will be inferred from the group or Merkle proof passed as the second parameter.
+ * Finally, the artifacts themselves can be passed manually with file paths,
+ * or they will be automatically fetched.
  * @param identity The Semaphore identity.
  * @param groupOrMerkleProof The Semaphore group or its Merkle proof.
  * @param scope The Semaphore scope.
@@ -148,8 +155,26 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
         return __generator(this, function (_b) {
             switch (_b.label) {
                 case 0:
+                    requireDefined(identity, "identity");
+                    requireDefined(groupOrMerkleProof, "groupOrMerkleProof");
+                    requireDefined(message, "message");
+                    requireDefined(scope, "scope");
+                    requireObject(identity, "identity");
+                    requireObject(groupOrMerkleProof, "groupOrMerkleProof");
+                    requireTypes(message, "message", ["string", "bigint", "number", "uint8array"]);
+                    requireTypes(scope, "scope", ["string", "bigint", "number", "uint8array"]);
+                    if (merkleTreeDepth) {
+                        requireNumber(merkleTreeDepth, "merkleTreeDepth");
+                    }
+                    if (snarkArtifacts) {
+                        requireObject(snarkArtifacts, "snarkArtifacts");
+                    }
+                    // Message and scope can be strings, numbers or buffers (i.e. Uint8Array).
+                    // They will be converted to bigints anyway.
                     message = toBigInt(message);
                     scope = toBigInt(scope);
+                    // The second parameter can be either a Merkle proof or a group.
+                    // If it is a group the Merkle proof will be calculated here.
                     if ("siblings" in groupOrMerkleProof) {
                         merkleProof = groupOrMerkleProof;
                     }
@@ -196,31 +221,13 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
                             nullifier: publicSignals[1],
                             message: message.toString(),
                             scope: scope.toString(),
-                            points: packPoints(proof)
+                            points: packGroth16Proof(proof)
                         }];
             }
         });
     });
 }
 
-/**
- * Unpacks the Groth16 proof points into their original form.
- * @param proof The proof points compatible with Semaphore.
- * @returns The proof points compatible with SnarkJS.
- */
-function unpackPoints(proof) {
-    return {
-        pi_a: [proof[0], proof[1]],
-        pi_b: [
-            [proof[3], proof[2]],
-            [proof[5], proof[4]]
-        ],
-        pi_c: [proof[6], proof[7]],
-        protocol: "groth16",
-        curve: "bn128"
-    };
-}
-
 var protocol = "groth16";
 var curve = "bn128";
 var nPublic = 4;
@@ -796,23 +803,32 @@ var verificationKeys = {
 };
 
 /**
- * Verifies a Semaphore proof.
+ * Verifies whether a Semaphore proof is valid. Depending on the depth of the tree used to
+ * generate the proof, a different verification key will be used.
  * @param proof The Semaphore proof.
  * @returns True if the proof is valid, false otherwise.
  */
-function verifyProof(_a) {
-    var merkleTreeDepth = _a.merkleTreeDepth, merkleTreeRoot = _a.merkleTreeRoot, nullifier = _a.nullifier, message = _a.message, scope = _a.scope, points = _a.points;
+function verifyProof(proof) {
     return __awaiter(this, void 0, void 0, function () {
-        var verificationKey;
-        return __generator(this, function (_b) {
+        var merkleTreeDepth, merkleTreeRoot, nullifier, message, scope, points, verificationKey;
+        return __generator(this, function (_a) {
+            requireDefined(proof, "proof");
+            requireObject(proof, "proof");
+            merkleTreeDepth = proof.merkleTreeDepth, merkleTreeRoot = proof.merkleTreeRoot, nullifier = proof.nullifier, message = proof.message, scope = proof.scope, points = proof.points;
+            requireNumber(merkleTreeDepth, "proof.merkleTreeDepth");
+            requireString(merkleTreeRoot, "proof.merkleTreeRoot");
+            requireString(nullifier, "proof.nullifier");
+            requireString(message, "proof.message");
+            requireString(scope, "proof.scope");
+            requireArray(points, "proof.points");
             // TODO: support all tree depths after trusted-setup.
             if (merkleTreeDepth < 1 || merkleTreeDepth > 12) {
                 throw new TypeError("The tree depth must be a number between 1 and 12");
             }
             verificationKey = __assign(__assign({}, verificationKeys), { vk_delta_2: verificationKeys.vk_delta_2[merkleTreeDepth - 1], IC: verificationKeys.IC[merkleTreeDepth - 1] });
-            return [2 /*return*/, groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], unpackPoints(points))];
+            return [2 /*return*/, groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], unpackGroth16Proof(points))];
         });
     });
 }
 
-export { generateProof, getSnarkArtifacts, packPoints, unpackPoints, verifyProof };
+export { generateProof, verifyProof };

package/dist/index.node.cjs

@@ -1,6 +1,6 @@
 /**
  * @module @semaphore-protocol/proof
- * @version 4.0.0-alpha.8
+ * @version 4.0.0-beta
  * @file A library to generate and verify Semaphore proofs.
  * @copyright Ethereum Foundation 2024
  * @license MIT
@@ -8,6 +8,8 @@
 */
 'use strict';
 
+var utils = require('@zk-kit/utils');
+var errors = require('@semaphore-protocol/utils/errors');
 var snarkjs = require('snarkjs');
 var node_fs = require('node:fs');
 var promises$1 = require('node:fs/promises');
@@ -16,7 +18,7 @@ var node_path = require('node:path');
 var node_stream = require('node:stream');
 var promises = require('node:stream/promises');
 var crypto = require('ethers/crypto');
-var utils = require('ethers/utils');
+var utils$1 = require('ethers/utils');
 var abi = require('ethers/abi');
 
 /******************************************************************************
@@ -90,6 +92,11 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * A utility function to download the zero-knowledge artifacts from an external server.
+ * @param url The URL from which to download the artifacts.
+ * @param outputPath The path in which to save the artifacts.
+ */
 function download(url, outputPath) {
     return __awaiter(this, void 0, void 0, function () {
         var response, dir, fileStream;
@@ -114,12 +121,20 @@ function download(url, outputPath) {
         });
     });
 }
+/**
+ * Downloads the zero-knowledge artifacts and returns their paths.
+ * Artifacts exist for each tree depth supported by Semaphore, and
+ * they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 function getSnarkArtifacts(treeDepth) {
     return __awaiter(this, void 0, void 0, function () {
         var tmpDir, tmpPath;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
+                    errors.requireNumber(treeDepth, "treeDepth");
                     tmpDir = "semaphore-proof";
                     tmpPath = "".concat(os.tmpdir(), "/").concat(tmpDir, "-").concat(treeDepth);
                     if (!(!node_fs.existsSync(tmpPath) || node_fs.readdirSync(tmpPath).length !== 2)) return [3 /*break*/, 3];
@@ -145,41 +160,38 @@ function getSnarkArtifacts(treeDepth) {
  * @returns The message digest.
  */
 function hash(message) {
-    return (BigInt(crypto.keccak256(utils.toBeHex(message, 32))) >> BigInt(8)).toString();
+    return (BigInt(crypto.keccak256(utils$1.toBeHex(message, 32))) >> BigInt(8)).toString();
 }
 
 /**
- * Packs the Groth16 proof points into a format compatible with Semaphore.
- * @param proof The proof points generated with SnarkJS.
- * @returns The proof points compatible with Semaphore.
+ * Converts a bignumberish to a bigint.
+ * @param value The value to be converted to bigint.
+ * @return The value converted to bigint.
  */
-function packPoints(proof) {
-    return [
-        proof.pi_a[0],
-        proof.pi_a[1],
-        proof.pi_b[0][1],
-        proof.pi_b[0][0],
-        proof.pi_b[1][1],
-        proof.pi_b[1][0],
-        proof.pi_c[0],
-        proof.pi_c[1]
-    ];
-}
-
 function toBigInt(value) {
     try {
-        return utils.toBigInt(value);
+        return utils$1.toBigInt(value);
     }
     catch (error) {
         if (typeof value === "string") {
-            return utils.toBigInt(abi.encodeBytes32String(value));
+            return utils$1.toBigInt(abi.encodeBytes32String(value));
         }
         throw TypeError(error.message);
     }
 }
 
 /**
- * Generates a Semaphore proof.
+ * It generates a Semaphore proof, i.e. a zero-knowledge proof that an identity that
+ * is part of a group has shared an anonymous message.
+ * The message may be any arbitrary user-defined value (e.g. a vote), or the hash of that value.
+ * The scope is a value used like a topic on which users can generate a valid proof only once,
+ * for example the id of an election in which voters can only vote once.
+ * The hash of the identity's scope and secret scalar is called a nullifier and can be
+ * used to verify whether that identity has already generated a valid proof in that scope.
+ * The depth of the tree determines which zero-knowledge artifacts to use to generate the proof.
+ * If it is not defined, it will be inferred from the group or Merkle proof passed as the second parameter.
+ * Finally, the artifacts themselves can be passed manually with file paths,
+ * or they will be automatically fetched.
  * @param identity The Semaphore identity.
  * @param groupOrMerkleProof The Semaphore group or its Merkle proof.
  * @param scope The Semaphore scope.
@@ -194,8 +206,26 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
         return __generator(this, function (_b) {
             switch (_b.label) {
                 case 0:
+                    errors.requireDefined(identity, "identity");
+                    errors.requireDefined(groupOrMerkleProof, "groupOrMerkleProof");
+                    errors.requireDefined(message, "message");
+                    errors.requireDefined(scope, "scope");
+                    errors.requireObject(identity, "identity");
+                    errors.requireObject(groupOrMerkleProof, "groupOrMerkleProof");
+                    errors.requireTypes(message, "message", ["string", "bigint", "number", "uint8array"]);
+                    errors.requireTypes(scope, "scope", ["string", "bigint", "number", "uint8array"]);
+                    if (merkleTreeDepth) {
+                        errors.requireNumber(merkleTreeDepth, "merkleTreeDepth");
+                    }
+                    if (snarkArtifacts) {
+                        errors.requireObject(snarkArtifacts, "snarkArtifacts");
+                    }
+                    // Message and scope can be strings, numbers or buffers (i.e. Uint8Array).
+                    // They will be converted to bigints anyway.
                     message = toBigInt(message);
                     scope = toBigInt(scope);
+                    // The second parameter can be either a Merkle proof or a group.
+                    // If it is a group the Merkle proof will be calculated here.
                     if ("siblings" in groupOrMerkleProof) {
                         merkleProof = groupOrMerkleProof;
                     }
@@ -242,31 +272,13 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
                             nullifier: publicSignals[1],
                             message: message.toString(),
                             scope: scope.toString(),
-                            points: packPoints(proof)
+                            points: utils.packGroth16Proof(proof)
                         }];
             }
         });
     });
 }
 
-/**
- * Unpacks the Groth16 proof points into their original form.
- * @param proof The proof points compatible with Semaphore.
- * @returns The proof points compatible with SnarkJS.
- */
-function unpackPoints(proof) {
-    return {
-        pi_a: [proof[0], proof[1]],
-        pi_b: [
-            [proof[3], proof[2]],
-            [proof[5], proof[4]]
-        ],
-        pi_c: [proof[6], proof[7]],
-        protocol: "groth16",
-        curve: "bn128"
-    };
-}
-
 var protocol = "groth16";
 var curve = "bn128";
 var nPublic = 4;
@@ -842,27 +854,41 @@ var verificationKeys = {
 };
 
 /**
- * Verifies a Semaphore proof.
+ * Verifies whether a Semaphore proof is valid. Depending on the depth of the tree used to
+ * generate the proof, a different verification key will be used.
  * @param proof The Semaphore proof.
  * @returns True if the proof is valid, false otherwise.
  */
-function verifyProof(_a) {
-    var merkleTreeDepth = _a.merkleTreeDepth, merkleTreeRoot = _a.merkleTreeRoot, nullifier = _a.nullifier, message = _a.message, scope = _a.scope, points = _a.points;
+function verifyProof(proof) {
     return __awaiter(this, void 0, void 0, function () {
-        var verificationKey;
-        return __generator(this, function (_b) {
+        var merkleTreeDepth, merkleTreeRoot, nullifier, message, scope, points, verificationKey;
+        return __generator(this, function (_a) {
+            errors.requireDefined(proof, "proof");
+            errors.requireObject(proof, "proof");
+            merkleTreeDepth = proof.merkleTreeDepth, merkleTreeRoot = proof.merkleTreeRoot, nullifier = proof.nullifier, message = proof.message, scope = proof.scope, points = proof.points;
+            errors.requireNumber(merkleTreeDepth, "proof.merkleTreeDepth");
+            errors.requireString(merkleTreeRoot, "proof.merkleTreeRoot");
+            errors.requireString(nullifier, "proof.nullifier");
+            errors.requireString(message, "proof.message");
+            errors.requireString(scope, "proof.scope");
+            errors.requireArray(points, "proof.points");
             // TODO: support all tree depths after trusted-setup.
             if (merkleTreeDepth < 1 || merkleTreeDepth > 12) {
                 throw new TypeError("The tree depth must be a number between 1 and 12");
             }
             verificationKey = __assign(__assign({}, verificationKeys), { vk_delta_2: verificationKeys.vk_delta_2[merkleTreeDepth - 1], IC: verificationKeys.IC[merkleTreeDepth - 1] });
-            return [2 /*return*/, snarkjs.groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], unpackPoints(points))];
+            return [2 /*return*/, snarkjs.groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], utils.unpackGroth16Proof(points))];
         });
     });
 }
 
+Object.defineProperty(exports, "packGroth16Proof", {
+    enumerable: true,
+    get: function () { return utils.packGroth16Proof; }
+});
+Object.defineProperty(exports, "unpackGroth16Proof", {
+    enumerable: true,
+    get: function () { return utils.unpackGroth16Proof; }
+});
 exports.generateProof = generateProof;
-exports.getSnarkArtifacts = getSnarkArtifacts;
-exports.packPoints = packPoints;
-exports.unpackPoints = unpackPoints;
 exports.verifyProof = verifyProof;

package/dist/index.node.js

@@ -1,11 +1,14 @@
 /**
  * @module @semaphore-protocol/proof
- * @version 4.0.0-alpha.8
+ * @version 4.0.0-beta
  * @file A library to generate and verify Semaphore proofs.
  * @copyright Ethereum Foundation 2024
  * @license MIT
  * @see [Github]{@link https://github.com/semaphore-protocol/semaphore/tree/main/packages/proof}
 */
+import { packGroth16Proof, unpackGroth16Proof } from '@zk-kit/utils';
+export { packGroth16Proof, unpackGroth16Proof } from '@zk-kit/utils';
+import { requireNumber, requireDefined, requireObject, requireTypes, requireString, requireArray } from '@semaphore-protocol/utils/errors';
 import { groth16 } from 'snarkjs';
 import { existsSync, readdirSync, createWriteStream } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
@@ -88,6 +91,11 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * A utility function to download the zero-knowledge artifacts from an external server.
+ * @param url The URL from which to download the artifacts.
+ * @param outputPath The path in which to save the artifacts.
+ */
 function download(url, outputPath) {
     return __awaiter(this, void 0, void 0, function () {
         var response, dir, fileStream;
@@ -112,12 +120,20 @@ function download(url, outputPath) {
         });
     });
 }
+/**
+ * Downloads the zero-knowledge artifacts and returns their paths.
+ * Artifacts exist for each tree depth supported by Semaphore, and
+ * they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 function getSnarkArtifacts(treeDepth) {
     return __awaiter(this, void 0, void 0, function () {
         var tmpDir, tmpPath;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
+                    requireNumber(treeDepth, "treeDepth");
                     tmpDir = "semaphore-proof";
                     tmpPath = "".concat(os.tmpdir(), "/").concat(tmpDir, "-").concat(treeDepth);
                     if (!(!existsSync(tmpPath) || readdirSync(tmpPath).length !== 2)) return [3 /*break*/, 3];
@@ -147,23 +163,10 @@ function hash(message) {
 }
 
 /**
- * Packs the Groth16 proof points into a format compatible with Semaphore.
- * @param proof The proof points generated with SnarkJS.
- * @returns The proof points compatible with Semaphore.
+ * Converts a bignumberish to a bigint.
+ * @param value The value to be converted to bigint.
+ * @return The value converted to bigint.
  */
-function packPoints(proof) {
-    return [
-        proof.pi_a[0],
-        proof.pi_a[1],
-        proof.pi_b[0][1],
-        proof.pi_b[0][0],
-        proof.pi_b[1][1],
-        proof.pi_b[1][0],
-        proof.pi_c[0],
-        proof.pi_c[1]
-    ];
-}
-
 function toBigInt(value) {
     try {
         return toBigInt$1(value);
@@ -177,7 +180,17 @@ function toBigInt(value) {
 }
 
 /**
- * Generates a Semaphore proof.
+ * It generates a Semaphore proof, i.e. a zero-knowledge proof that an identity that
+ * is part of a group has shared an anonymous message.
+ * The message may be any arbitrary user-defined value (e.g. a vote), or the hash of that value.
+ * The scope is a value used like a topic on which users can generate a valid proof only once,
+ * for example the id of an election in which voters can only vote once.
+ * The hash of the identity's scope and secret scalar is called a nullifier and can be
+ * used to verify whether that identity has already generated a valid proof in that scope.
+ * The depth of the tree determines which zero-knowledge artifacts to use to generate the proof.
+ * If it is not defined, it will be inferred from the group or Merkle proof passed as the second parameter.
+ * Finally, the artifacts themselves can be passed manually with file paths,
+ * or they will be automatically fetched.
  * @param identity The Semaphore identity.
  * @param groupOrMerkleProof The Semaphore group or its Merkle proof.
  * @param scope The Semaphore scope.
@@ -192,8 +205,26 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
         return __generator(this, function (_b) {
             switch (_b.label) {
                 case 0:
+                    requireDefined(identity, "identity");
+                    requireDefined(groupOrMerkleProof, "groupOrMerkleProof");
+                    requireDefined(message, "message");
+                    requireDefined(scope, "scope");
+                    requireObject(identity, "identity");
+                    requireObject(groupOrMerkleProof, "groupOrMerkleProof");
+                    requireTypes(message, "message", ["string", "bigint", "number", "uint8array"]);
+                    requireTypes(scope, "scope", ["string", "bigint", "number", "uint8array"]);
+                    if (merkleTreeDepth) {
+                        requireNumber(merkleTreeDepth, "merkleTreeDepth");
+                    }
+                    if (snarkArtifacts) {
+                        requireObject(snarkArtifacts, "snarkArtifacts");
+                    }
+                    // Message and scope can be strings, numbers or buffers (i.e. Uint8Array).
+                    // They will be converted to bigints anyway.
                     message = toBigInt(message);
                     scope = toBigInt(scope);
+                    // The second parameter can be either a Merkle proof or a group.
+                    // If it is a group the Merkle proof will be calculated here.
                     if ("siblings" in groupOrMerkleProof) {
                         merkleProof = groupOrMerkleProof;
                     }
@@ -240,31 +271,13 @@ function generateProof(identity, groupOrMerkleProof, message, scope, merkleTreeD
                             nullifier: publicSignals[1],
                             message: message.toString(),
                             scope: scope.toString(),
-                            points: packPoints(proof)
+                            points: packGroth16Proof(proof)
                         }];
             }
         });
     });
 }
 
-/**
- * Unpacks the Groth16 proof points into their original form.
- * @param proof The proof points compatible with Semaphore.
- * @returns The proof points compatible with SnarkJS.
- */
-function unpackPoints(proof) {
-    return {
-        pi_a: [proof[0], proof[1]],
-        pi_b: [
-            [proof[3], proof[2]],
-            [proof[5], proof[4]]
-        ],
-        pi_c: [proof[6], proof[7]],
-        protocol: "groth16",
-        curve: "bn128"
-    };
-}
-
 var protocol = "groth16";
 var curve = "bn128";
 var nPublic = 4;
@@ -840,23 +853,32 @@ var verificationKeys = {
 };
 
 /**
- * Verifies a Semaphore proof.
+ * Verifies whether a Semaphore proof is valid. Depending on the depth of the tree used to
+ * generate the proof, a different verification key will be used.
  * @param proof The Semaphore proof.
  * @returns True if the proof is valid, false otherwise.
  */
-function verifyProof(_a) {
-    var merkleTreeDepth = _a.merkleTreeDepth, merkleTreeRoot = _a.merkleTreeRoot, nullifier = _a.nullifier, message = _a.message, scope = _a.scope, points = _a.points;
+function verifyProof(proof) {
     return __awaiter(this, void 0, void 0, function () {
-        var verificationKey;
-        return __generator(this, function (_b) {
+        var merkleTreeDepth, merkleTreeRoot, nullifier, message, scope, points, verificationKey;
+        return __generator(this, function (_a) {
+            requireDefined(proof, "proof");
+            requireObject(proof, "proof");
+            merkleTreeDepth = proof.merkleTreeDepth, merkleTreeRoot = proof.merkleTreeRoot, nullifier = proof.nullifier, message = proof.message, scope = proof.scope, points = proof.points;
+            requireNumber(merkleTreeDepth, "proof.merkleTreeDepth");
+            requireString(merkleTreeRoot, "proof.merkleTreeRoot");
+            requireString(nullifier, "proof.nullifier");
+            requireString(message, "proof.message");
+            requireString(scope, "proof.scope");
+            requireArray(points, "proof.points");
             // TODO: support all tree depths after trusted-setup.
             if (merkleTreeDepth < 1 || merkleTreeDepth > 12) {
                 throw new TypeError("The tree depth must be a number between 1 and 12");
             }
             verificationKey = __assign(__assign({}, verificationKeys), { vk_delta_2: verificationKeys.vk_delta_2[merkleTreeDepth - 1], IC: verificationKeys.IC[merkleTreeDepth - 1] });
-            return [2 /*return*/, groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], unpackPoints(points))];
+            return [2 /*return*/, groth16.verify(verificationKey, [merkleTreeRoot, nullifier, hash(message), hash(scope)], unpackGroth16Proof(points))];
         });
     });
 }
 
-export { generateProof, getSnarkArtifacts, packPoints, unpackPoints, verifyProof };
+export { generateProof, verifyProof };

package/dist/types/generate-proof.d.ts

@@ -2,7 +2,17 @@ import type { Group, MerkleProof } from "@semaphore-protocol/group";
 import type { Identity } from "@semaphore-protocol/identity";
 import { BigNumberish, SemaphoreProof, SnarkArtifacts } from "./types";
 /**
- * Generates a Semaphore proof.
+ * It generates a Semaphore proof, i.e. a zero-knowledge proof that an identity that
+ * is part of a group has shared an anonymous message.
+ * The message may be any arbitrary user-defined value (e.g. a vote), or the hash of that value.
+ * The scope is a value used like a topic on which users can generate a valid proof only once,
+ * for example the id of an election in which voters can only vote once.
+ * The hash of the identity's scope and secret scalar is called a nullifier and can be
+ * used to verify whether that identity has already generated a valid proof in that scope.
+ * The depth of the tree determines which zero-knowledge artifacts to use to generate the proof.
+ * If it is not defined, it will be inferred from the group or Merkle proof passed as the second parameter.
+ * Finally, the artifacts themselves can be passed manually with file paths,
+ * or they will be automatically fetched.
  * @param identity The Semaphore identity.
  * @param groupOrMerkleProof The Semaphore group or its Merkle proof.
  * @param scope The Semaphore scope.

package/dist/types/get-snark-artifacts.browser.d.ts

@@ -1,2 +1,8 @@
 import { SnarkArtifacts } from "./types";
+/**
+ * Returns the zero-knowledge artifact paths. Artifacts exist for each tree
+ * depth supported by Semaphore, and they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 export default function getSnarkArtifacts(treeDepth: number): Promise<SnarkArtifacts>;

package/dist/types/get-snark-artifacts.node.d.ts

@@ -1,2 +1,9 @@
 import { SnarkArtifacts } from "./types";
+/**
+ * Downloads the zero-knowledge artifacts and returns their paths.
+ * Artifacts exist for each tree depth supported by Semaphore, and
+ * they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 export default function getSnarkArtifacts(treeDepth: number): Promise<SnarkArtifacts>;

package/dist/types/index.d.ts

@@ -1,7 +1,5 @@
+import { packGroth16Proof, unpackGroth16Proof } from "@zk-kit/utils";
 import generateProof from "./generate-proof";
-import getSnarkArtifacts from "./get-snark-artifacts.node";
-import packPoints from "./pack-points";
-import unpackPoints from "./unpack-points";
 import verifyProof from "./verify-proof";
 export * from "./types";
-export { generateProof, getSnarkArtifacts, packPoints, unpackPoints, verifyProof };
+export { generateProof, packGroth16Proof, unpackGroth16Proof, verifyProof };

package/dist/types/to-bigint.d.ts

@@ -1,2 +1,7 @@
 import { BigNumberish } from "./types";
+/**
+ * Converts a bignumberish to a bigint.
+ * @param value The value to be converted to bigint.
+ * @return The value converted to bigint.
+ */
 export default function toBigInt(value: BigNumberish | Uint8Array | string): bigint;

package/dist/types/verify-proof.d.ts

@@ -1,7 +1,8 @@
 import { SemaphoreProof } from "./types";
 /**
- * Verifies a Semaphore proof.
+ * Verifies whether a Semaphore proof is valid. Depending on the depth of the tree used to
+ * generate the proof, a different verification key will be used.
  * @param proof The Semaphore proof.
  * @returns True if the proof is valid, false otherwise.
  */
-export default function verifyProof({ merkleTreeDepth, merkleTreeRoot, nullifier, message, scope, points }: SemaphoreProof): Promise<boolean>;
+export default function verifyProof(proof: SemaphoreProof): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semaphore-protocol/proof",
-  "version": "4.0.0-alpha.8",
+  "version": "4.0.0-beta",
   "description": "A library to generate and verify Semaphore proofs.",
   "type": "module",
   "license": "MIT",
@@ -41,19 +41,21 @@
     "@rollup/plugin-alias": "^5.1.0",
     "@rollup/plugin-json": "^6.1.0",
     "@types/download": "^8.0.5",
+    "@types/snarkjs": "0.7.8",
     "@types/tmp": "^0.2.6",
     "poseidon-lite": "^0.2.0",
     "rimraf": "^5.0.5",
-    "rollup": "^4.0.2",
+    "rollup": "^4.9.6",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-typescript2": "^0.36.0"
   },
   "peerDependencies": {
-    "@semaphore-protocol/group": "4.0.0-alpha.8",
-    "@semaphore-protocol/identity": "4.0.0-alpha.8"
+    "@semaphore-protocol/group": "4.0.0-beta",
+    "@semaphore-protocol/identity": "4.0.0-beta"
   },
   "dependencies": {
-    "@types/snarkjs": "0.7.8",
+    "@semaphore-protocol/utils": "4.0.0-beta",
+    "@zk-kit/utils": "0.2.0",
     "ethers": "6.10.0",
     "snarkjs": "0.7.3"
   }

package/src/generate-proof.ts

@@ -1,14 +1,25 @@
 import type { Group, MerkleProof } from "@semaphore-protocol/group"
 import type { Identity } from "@semaphore-protocol/identity"
+import { requireDefined, requireNumber, requireObject, requireTypes } from "@semaphore-protocol/utils/errors"
 import { NumericString, groth16 } from "snarkjs"
+import { packGroth16Proof } from "@zk-kit/utils"
 import getSnarkArtifacts from "./get-snark-artifacts.node"
 import hash from "./hash"
-import packPoints from "./pack-points"
-import { BigNumberish, SemaphoreProof, SnarkArtifacts } from "./types"
 import toBigInt from "./to-bigint"
+import { BigNumberish, SemaphoreProof, SnarkArtifacts } from "./types"
 
 /**
- * Generates a Semaphore proof.
+ * It generates a Semaphore proof, i.e. a zero-knowledge proof that an identity that
+ * is part of a group has shared an anonymous message.
+ * The message may be any arbitrary user-defined value (e.g. a vote), or the hash of that value.
+ * The scope is a value used like a topic on which users can generate a valid proof only once,
+ * for example the id of an election in which voters can only vote once.
+ * The hash of the identity's scope and secret scalar is called a nullifier and can be
+ * used to verify whether that identity has already generated a valid proof in that scope.
+ * The depth of the tree determines which zero-knowledge artifacts to use to generate the proof.
+ * If it is not defined, it will be inferred from the group or Merkle proof passed as the second parameter.
+ * Finally, the artifacts themselves can be passed manually with file paths,
+ * or they will be automatically fetched.
  * @param identity The Semaphore identity.
  * @param groupOrMerkleProof The Semaphore group or its Merkle proof.
  * @param scope The Semaphore scope.
@@ -25,11 +36,33 @@ export default async function generateProof(
     merkleTreeDepth?: number,
     snarkArtifacts?: SnarkArtifacts
 ): Promise<SemaphoreProof> {
+    requireDefined(identity, "identity")
+    requireDefined(groupOrMerkleProof, "groupOrMerkleProof")
+    requireDefined(message, "message")
+    requireDefined(scope, "scope")
+
+    requireObject(identity, "identity")
+    requireObject(groupOrMerkleProof, "groupOrMerkleProof")
+    requireTypes(message, "message", ["string", "bigint", "number", "uint8array"])
+    requireTypes(scope, "scope", ["string", "bigint", "number", "uint8array"])
+
+    if (merkleTreeDepth) {
+        requireNumber(merkleTreeDepth, "merkleTreeDepth")
+    }
+
+    if (snarkArtifacts) {
+        requireObject(snarkArtifacts, "snarkArtifacts")
+    }
+
+    // Message and scope can be strings, numbers or buffers (i.e. Uint8Array).
+    // They will be converted to bigints anyway.
     message = toBigInt(message)
     scope = toBigInt(scope)
 
     let merkleProof
 
+    // The second parameter can be either a Merkle proof or a group.
+    // If it is a group the Merkle proof will be calculated here.
     if ("siblings" in groupOrMerkleProof) {
         merkleProof = groupOrMerkleProof
     } else {
@@ -84,6 +117,6 @@ export default async function generateProof(
         nullifier: publicSignals[1],
         message: message.toString() as NumericString,
         scope: scope.toString() as NumericString,
-        points: packPoints(proof)
+        points: packGroth16Proof(proof)
     }
 }

package/src/get-snark-artifacts.browser.ts

@@ -1,7 +1,16 @@
 /* istanbul ignore file */
+import { requireNumber } from "@semaphore-protocol/utils/errors"
 import { SnarkArtifacts } from "./types"
 
+/**
+ * Returns the zero-knowledge artifact paths. Artifacts exist for each tree
+ * depth supported by Semaphore, and they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 export default async function getSnarkArtifacts(treeDepth: number): Promise<SnarkArtifacts> {
+    requireNumber(treeDepth, "treeDepth")
+
     return {
         wasmFilePath: `https://semaphore.cedoor.dev/artifacts/${treeDepth}/semaphore.wasm`,
         zkeyFilePath: `https://semaphore.cedoor.dev/artifacts/${treeDepth}/semaphore.zkey`

package/src/get-snark-artifacts.node.ts

@@ -1,4 +1,5 @@
 /* istanbul ignore file */
+import { requireNumber } from "@semaphore-protocol/utils/errors"
 import { createWriteStream, existsSync, readdirSync } from "node:fs"
 import { mkdir } from "node:fs/promises"
 import os from "node:os"
@@ -7,6 +8,11 @@ import { Readable } from "node:stream"
 import { finished } from "node:stream/promises"
 import { SnarkArtifacts } from "./types"
 
+/**
+ * A utility function to download the zero-knowledge artifacts from an external server.
+ * @param url The URL from which to download the artifacts.
+ * @param outputPath The path in which to save the artifacts.
+ */
 async function download(url: string, outputPath: string) {
     const response = await fetch(url)
 
@@ -22,7 +28,16 @@ async function download(url: string, outputPath: string) {
     await finished(Readable.fromWeb(response.body as any).pipe(fileStream))
 }
 
+/**
+ * Downloads the zero-knowledge artifacts and returns their paths.
+ * Artifacts exist for each tree depth supported by Semaphore, and
+ * they were generated in a trusted-setup.
+ * @param treeDepth The depth of the tree.
+ * @returns The zero-knowledge artifacts paths.
+ */
 export default async function getSnarkArtifacts(treeDepth: number): Promise<SnarkArtifacts> {
+    requireNumber(treeDepth, "treeDepth")
+
     const tmpDir = "semaphore-proof"
     const tmpPath = `${os.tmpdir()}/${tmpDir}-${treeDepth}`
 

package/src/index.ts

@@ -1,8 +1,6 @@
+import { packGroth16Proof, unpackGroth16Proof } from "@zk-kit/utils"
 import generateProof from "./generate-proof"
-import getSnarkArtifacts from "./get-snark-artifacts.node"
-import packPoints from "./pack-points"
-import unpackPoints from "./unpack-points"
 import verifyProof from "./verify-proof"
 
 export * from "./types"
-export { generateProof, getSnarkArtifacts, packPoints, unpackPoints, verifyProof }
+export { generateProof, packGroth16Proof, unpackGroth16Proof, verifyProof }

package/src/to-bigint.ts

@@ -2,6 +2,11 @@ import { encodeBytes32String } from "ethers/abi"
 import { toBigInt as _toBigInt } from "ethers/utils"
 import { BigNumberish } from "./types"
 
+/**
+ * Converts a bignumberish to a bigint.
+ * @param value The value to be converted to bigint.
+ * @return The value converted to bigint.
+ */
 export default function toBigInt(value: BigNumberish | Uint8Array | string): bigint {
     try {
         return _toBigInt(value)

package/src/verify-proof.ts

@@ -1,22 +1,35 @@
+import {
+    requireArray,
+    requireDefined,
+    requireNumber,
+    requireObject,
+    requireString
+} from "@semaphore-protocol/utils/errors"
 import { groth16 } from "snarkjs"
+import { unpackGroth16Proof } from "@zk-kit/utils"
 import hash from "./hash"
 import { SemaphoreProof } from "./types"
-import unpackPoints from "./unpack-points"
 import verificationKeys from "./verification-keys.json"
 
 /**
- * Verifies a Semaphore proof.
+ * Verifies whether a Semaphore proof is valid. Depending on the depth of the tree used to
+ * generate the proof, a different verification key will be used.
  * @param proof The Semaphore proof.
  * @returns True if the proof is valid, false otherwise.
  */
-export default async function verifyProof({
-    merkleTreeDepth,
-    merkleTreeRoot,
-    nullifier,
-    message,
-    scope,
-    points
-}: SemaphoreProof): Promise<boolean> {
+export default async function verifyProof(proof: SemaphoreProof): Promise<boolean> {
+    requireDefined(proof, "proof")
+    requireObject(proof, "proof")
+
+    const { merkleTreeDepth, merkleTreeRoot, nullifier, message, scope, points } = proof
+
+    requireNumber(merkleTreeDepth, "proof.merkleTreeDepth")
+    requireString(merkleTreeRoot, "proof.merkleTreeRoot")
+    requireString(nullifier, "proof.nullifier")
+    requireString(message, "proof.message")
+    requireString(scope, "proof.scope")
+    requireArray(points, "proof.points")
+
     // TODO: support all tree depths after trusted-setup.
     if (merkleTreeDepth < 1 || merkleTreeDepth > 12) {
         throw new TypeError("The tree depth must be a number between 1 and 12")
@@ -31,6 +44,6 @@ export default async function verifyProof({
     return groth16.verify(
         verificationKey,
         [merkleTreeRoot, nullifier, hash(message), hash(scope)],
-        unpackPoints(points)
+        unpackGroth16Proof(points)
     )
 }

package/dist/types/pack-points.d.ts

@@ -1,8 +0,0 @@
-import { Groth16Proof } from "snarkjs";
-import { PackedPoints } from "./types";
-/**
- * Packs the Groth16 proof points into a format compatible with Semaphore.
- * @param proof The proof points generated with SnarkJS.
- * @returns The proof points compatible with Semaphore.
- */
-export default function packPoints(proof: Groth16Proof): PackedPoints;

package/dist/types/unpack-points.d.ts

@@ -1,8 +0,0 @@
-import { Groth16Proof } from "snarkjs";
-import { PackedPoints } from "./types";
-/**
- * Unpacks the Groth16 proof points into their original form.
- * @param proof The proof points compatible with Semaphore.
- * @returns The proof points compatible with SnarkJS.
- */
-export default function unpackPoints(proof: PackedPoints): Groth16Proof;

package/src/pack-points.ts

@@ -1,20 +0,0 @@
-import { Groth16Proof } from "snarkjs"
-import { PackedPoints } from "./types"
-
-/**
- * Packs the Groth16 proof points into a format compatible with Semaphore.
- * @param proof The proof points generated with SnarkJS.
- * @returns The proof points compatible with Semaphore.
- */
-export default function packPoints(proof: Groth16Proof): PackedPoints {
-    return [
-        proof.pi_a[0],
-        proof.pi_a[1],
-        proof.pi_b[0][1],
-        proof.pi_b[0][0],
-        proof.pi_b[1][1],
-        proof.pi_b[1][0],
-        proof.pi_c[0],
-        proof.pi_c[1]
-    ]
-}

package/src/unpack-points.ts

@@ -1,20 +0,0 @@
-import { Groth16Proof } from "snarkjs"
-import { PackedPoints } from "./types"
-
-/**
- * Unpacks the Groth16 proof points into their original form.
- * @param proof The proof points compatible with Semaphore.
- * @returns The proof points compatible with SnarkJS.
- */
-export default function unpackPoints(proof: PackedPoints): Groth16Proof {
-    return {
-        pi_a: [proof[0], proof[1]],
-        pi_b: [
-            [proof[3], proof[2]],
-            [proof[5], proof[4]]
-        ],
-        pi_c: [proof[6], proof[7]],
-        protocol: "groth16",
-        curve: "bn128"
-    }
-}