@semaphore-protocol/utils 4.0.0-beta.1 → 4.0.0-beta.11

package/README.md

@@ -70,10 +70,10 @@ yarn add @semaphore-protocol/utils
 For more information on the functions and modules provided by `@semaphore-protocol/utils`, please refer to the [TypeDoc documentation](https://js.semaphore.pse.dev/modules/_semaphore_protocol_utils).
 
 ```typescript
-// You can import modules from the main bundle.
-import { errors, types } from "@semaphore-protocol/utils"
+// You can import functions/parameters from the main bundle.
+import { supportedNetworks, decodeMessage } from "@semaphore-protocol/utils"
 
 // Or by using conditional exports.
-import { requireNumber } from "@semaphore-protocol/utils/errors"
-import { isNumber } from "@semaphore-protocol/utils/types"
+import supportedNetworks from "@semaphore-protocol/utils/supported-networks"
+import decodeMessage from "@semaphore-protocol/utils/decode-message"
 ```

package/dist/index.cjs

@@ -1,6 +1,6 @@
 /**
  * @module @semaphore-protocol/utils
- * @version 4.0.0-beta.1
+ * @version 4.0.0-beta.11
  * @file A library to provide utility functions to the other Semaphore packages.
  * @copyright Ethereum Foundation 2024
  * @license MIT
@@ -8,252 +8,196 @@
 */
 'use strict';
 
-/**
- * @module Types
- * This module provides utility functions to check data types.
- * It defines a set of supported types and includes functions to check if
- * a value is defined and if it matches a supported type. These functions
- * are useful for type checking and validation in the other libraries,
- * enhancing code robustness and reliability.
- */
-// The list of types supported by this utility functions.
-var supportedTypes = ["number", "string", "function", "array", "uint8array", "object", "bigint"];
-/**
- * It returns true if the value is defined, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isDefined(value) {
-    return typeof value !== "undefined";
-}
-/**
- * It returns true if the value is a number, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isNumber(value) {
-    return typeof value === "number";
-}
-/**
- * It returns true if the value is a string, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isString(value) {
-    return typeof value === "string";
-}
-/**
- * It returns true if the value is a function, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isFunction(value) {
-    return typeof value === "function";
-}
-/**
- * It returns true if the value is an array, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isArray(value) {
-    return typeof value === "object" && Array.isArray(value);
-}
-/**
- * It returns true if the value is a uint8array, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isUint8Array(value) {
-    return value instanceof Uint8Array;
-}
-/**
- * It returns true if the value is an object, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isObject(value) {
-    return typeof value === "object";
-}
-/**
- * It returns true if the value is a bigint, false otherwise.
- * @param value The value to be checked.
- * @returns True or false.
- */
-function isBigInt(value) {
-    return typeof value === "bigint";
-}
-/**
- * It returns true if the value type is the same as the type passed
- * as the second parameter, false otherwise.
- * @param type The expected type.
- * @returns True or false.
- */
-function isType(value, type) {
-    switch (type) {
-        case "number":
-            return isNumber(value);
-        case "string":
-            return isString(value);
-        case "function":
-            return isFunction(value);
-        case "array":
-            return isArray(value);
-        case "uint8array":
-            return isUint8Array(value);
-        case "object":
-            return isObject(value);
-        case "bigint":
-            return isBigInt(value);
-        default:
-            return false;
-    }
-}
-/**
- * Return true if the type is being supported by this utility
- * functions, false otherwise.
- * @param type The type to be checked.
- * @returns True or false
- */
-function isSupportedType(type) {
-    return supportedTypes.includes(type);
-}
+var abi = require('ethers/abi');
+var utils = require('ethers/utils');
+
+// Minimum supported tree depth.
+const MIN_DEPTH = 1;
+// Maximum supported tree depth.
+const MAX_DEPTH = 32;
 
-var types = /*#__PURE__*/Object.freeze({
+var constants = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    isArray: isArray,
-    isBigInt: isBigInt,
-    isDefined: isDefined,
-    isFunction: isFunction,
-    isNumber: isNumber,
-    isObject: isObject,
-    isString: isString,
-    isSupportedType: isSupportedType,
-    isType: isType,
-    isUint8Array: isUint8Array
+    MAX_DEPTH: MAX_DEPTH,
+    MIN_DEPTH: MIN_DEPTH
 });
 
 /**
- * @module Errors
- * This module is designed to provide utility functions for validating
- * function parameters. It includes functions that throw type errors if
- * the parameters do not meet specified criteria, such as being defined,
- * a number, a string, a function, or an array. This module helps ensure
- * that functions receive the correct types of inputs, enhancing code
- * reliability and reducing runtime errors.
- */
-/**
- * It throws a type error if the parameter value has not been defined.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
- */
-function requireDefined(parameterValue, parameterName) {
-    if (!isDefined(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not defined"));
-    }
-}
-/**
- * It throws a type error if the parameter value is not a number.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
+ * Typically used for decoding on-chain Semaphore messages.
+ * When Semaphore messages are text they are converted to bigints before
+ * the proof is generated (and eventually sent on-chain).
+ * This function help devs converting bigint messages to text again.
+ * If the original message was not text the output of this
+ * function won't probably be human-readable text.
+ * @param message The Semaphore message as a bigint.
+ * @returns The Semaphore message as a text.
  */
-function requireNumber(parameterValue, parameterName) {
-    if (!isNumber(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not a number"));
-    }
-}
-/**
- * It throws a type error if the parameter value is not a string.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
- */
-function requireString(parameterValue, parameterName) {
-    if (!isString(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not a string"));
-    }
+function decodeMessage(message) {
+    return abi.decodeBytes32String(utils.toBeHex(message, 32));
 }
-/**
- * It throws a type error if the parameter value is not a function.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
- */
-function requireFunction(parameterValue, parameterName) {
-    if (!isFunction(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not a function"));
+
+var deployedContracts = [
+	{
+		network: "sepolia",
+		contracts: [
+			{
+				name: "SemaphoreVerifier",
+				address: "0x58AD7a4389E0F5d814815E5D5A3Ab903dAE9284a",
+				startBlock: 5539276
+			},
+			{
+				name: "PoseidonT3",
+				address: "0x4EFfF6a6a7BB31cdAd9Ee742b0faAA6Bb9BF096B",
+				startBlock: 5539276
+			},
+			{
+				name: "Semaphore",
+				address: "0x0A09FB3f63c13F1C54F2fA41AFB1e7a98cffc774",
+				startBlock: 5539276
+			}
+		]
+	},
+	{
+		network: "arbitrum-sepolia",
+		contracts: [
+			{
+				name: "SemaphoreVerifier",
+				address: "0x5f4edC58142f4395D1D536e793137A0252dA5a49",
+				startBlock: 25837653
+			},
+			{
+				name: "PoseidonT3",
+				address: "0x181B7f34538cE3BceC68597d4A212aB3f7881648",
+				startBlock: 25837653
+			},
+			{
+				name: "Semaphore",
+				address: "0x220fBdB6F996827b1Cf12f0C181E8d5e6de3a36F",
+				startBlock: 25837653
+			}
+		]
+	},
+	{
+		network: "optimism-sepolia",
+		contracts: [
+			{
+				name: "SemaphoreVerifier",
+				address: "0x3d3df6CFc6BFf68d9693e097F32bF4a9903E77a5",
+				startBlock: 9663266
+			},
+			{
+				name: "PoseidonT3",
+				address: "0x5f4edC58142f4395D1D536e793137A0252dA5a49",
+				startBlock: 9663266
+			},
+			{
+				name: "Semaphore",
+				address: "0x181B7f34538cE3BceC68597d4A212aB3f7881648",
+				startBlock: 9663266
+			}
+		]
+	},
+	{
+		network: "matic-mumbai",
+		contracts: [
+			{
+				name: "SemaphoreVerifier",
+				address: "0xE5269ae1E996C6FEEf6E832c7032401E73087568",
+				startBlock: 47356015
+			},
+			{
+				name: "PoseidonT3",
+				address: "0xC0ae1a8D3505B2bE9DCe0e826abd722Afd13F1c9",
+				startBlock: 47356015
+			},
+			{
+				name: "Semaphore",
+				address: "0x346a936b19071b2f619200848B8ADbb938D72250",
+				startBlock: 47356015
+			}
+		]
+	}
+];
+
+var supportedNetworks = {
+    sepolia: {
+        name: "Sepolia",
+        url: "https://rpc2.sepolia.org",
+        chainId: 11155111,
+        explorer: "https://sepolia.etherscan.io"
+    },
+    "arbitrum-sepolia": {
+        name: "Arbitrum Sepolia",
+        url: "https://sepolia-rollup.arbitrum.io/rpc",
+        chainId: 421614,
+        explorer: "https://sepolia.arbiscan.io"
+    },
+    "optimism-sepolia": {
+        name: "Optimism Sepolia",
+        url: "https://sepolia.optimism.io",
+        chainId: 11155420,
+        explorer: "https://sepolia-optimism.etherscan.io"
+    },
+    "matic-mumbai": {
+        name: "Matic Mumbai",
+        url: "https://rpc-mumbai.polygon.technology",
+        chainId: 80001,
+        explorer: "https://mumbai.polygonscan.com"
     }
-}
+};
+
 /**
- * It throws a type error if the parameter value is not an array.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
+ * @module Networks
+ * This module provides a collection of utility functions to provide the other internal
+ * packages and developers with information on deployed contracts and networks supported
+ * by Semaphore.
  */
-function requireArray(parameterValue, parameterName) {
-    if (!isArray(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not an array"));
-    }
-}
+// Default Semaphore network.
+const defaultNetwork = "sepolia";
 /**
- * It throws a type error if the parameter value is not a uint8array.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
+ * Returns true if a network is supported by Semaphore, false otherwise.
+ * @param supportedNetwork The network to be checked.
  */
-function requireUint8Array(parameterValue, parameterName) {
-    if (!isUint8Array(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not a Uint8Array"));
-    }
+function isSupportedNetwork(supportedNetwork) {
+    return Object.keys(supportedNetworks).includes(supportedNetwork);
 }
 /**
- * It throws a type error if the parameter value is not an object.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
+ * Utility function to get an object compatible with the Hardhat 'networks' option.
+ * If the private key is not defined it returns an empty object.
+ * @param privateKey Private key to be used with networks.
+ * @returns An object compatible with the Hardhat 'networks' option.
  */
-function requireObject(parameterValue, parameterName) {
-    if (!isObject(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not an object"));
+function getHardhatNetworks(privateKey) {
+    if (!privateKey) {
+        return {};
     }
-}
-/**
- * It throws a type error if the parameter value is not a bigint.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
- */
-function requireBigInt(parameterValue, parameterName) {
-    if (!isBigInt(parameterValue)) {
-        throw new TypeError("Parameter '".concat(parameterName, "' is not a bigint"));
+    const supportedNetworksCopy = JSON.parse(JSON.stringify(supportedNetworks));
+    for (const key in supportedNetworksCopy) {
+        if (Object.prototype.hasOwnProperty.call(supportedNetworksCopy, key)) {
+            supportedNetworksCopy[key].accounts = [`0x${privateKey}`];
+        }
     }
+    return supportedNetworksCopy;
 }
 /**
- * It throws a type error if the parameter value type is not part of the list of types.
- * @param parameterValue The parameter value.
- * @param parameterName The parameter name.
+ * Returns name, address and start block of a Semaphore contract deployed
+ * on a specific supported network.
+ * @param supportedNetwork The network supported by Semaphore.
+ * @returns An object with name, address and start block of the deployed contract.
  */
-function requireTypes(parameterValue, parameterName, types) {
-    for (var _i = 0, types_1 = types; _i < types_1.length; _i++) {
-        var type = types_1[_i];
-        if (!isSupportedType(type)) {
-            throw new Error("Type '".concat(type, "' is not supported"));
-        }
-    }
-    for (var _a = 0, types_2 = types; _a < types_2.length; _a++) {
-        var type = types_2[_a];
-        if (isType(parameterValue, type)) {
-            return;
-        }
+function getDeployedContract(supportedNetwork) {
+    if (!isSupportedNetwork(supportedNetwork)) {
+        throw new Error(`Semaphore has not been deployed on '${supportedNetwork}' yet`);
     }
-    throw new TypeError("Parameter '".concat(parameterName, "' is none of the following types: ").concat(types.join(", ")));
+    const deployedContract = deployedContracts.find(({ network }) => network === supportedNetwork);
+    return deployedContract.contracts.find(({ name }) => name === "Semaphore");
 }
 
-var errors = /*#__PURE__*/Object.freeze({
-    __proto__: null,
-    requireArray: requireArray,
-    requireBigInt: requireBigInt,
-    requireDefined: requireDefined,
-    requireFunction: requireFunction,
-    requireNumber: requireNumber,
-    requireObject: requireObject,
-    requireString: requireString,
-    requireTypes: requireTypes,
-    requireUint8Array: requireUint8Array
-});
-
-exports.errors = errors;
-exports.types = types;
+exports.constants = constants;
+exports.decodeMessage = decodeMessage;
+exports.defaultNetwork = defaultNetwork;
+exports.deployedContracts = deployedContracts;
+exports.getDeployedContract = getDeployedContract;
+exports.getHardhatNetworks = getHardhatNetworks;
+exports.isSupportedNetwork = isSupportedNetwork;
+exports.supportedNetworks = supportedNetworks;