@semaphore-protocol/group 4.0.0-alpha.7 → 4.0.0-beta

package/README.md

@@ -18,7 +18,7 @@
     <a href="https://npmjs.org/package/@semaphore-protocol/group">
         <img alt="Downloads" src="https://img.shields.io/npm/dm/@semaphore-protocol/group.svg?style=flat-square" />
     </a>
-    <a href="https://js.semaphore.pse.dev/group">
+    <a href="https://js.semaphore.pse.dev/modules/_semaphore_protocol_group">
         <img alt="Documentation typedoc" src="https://img.shields.io/badge/docs-typedoc-744C7C?style=flat-square">
     </a>
     <a href="https://eslint.org/">
@@ -70,6 +70,8 @@ yarn add @semaphore-protocol/group
 
 ## 📜 Usage
 
+For more information on the functions provided by `@semaphore-protocol/group`, please refer to the [TypeDoc documentation](https://js.semaphore.pse.dev/modules/_semaphore_protocol_group).
+
 \# **new Group**(members: _BigNumberish[]_ = []): _Group_
 
 ```typescript

package/dist/index.cjs

@@ -1,6 +1,6 @@
 /**
  * @module @semaphore-protocol/group
- * @version 4.0.0-alpha.7
+ * @version 4.0.0-beta
  * @file A library to create and manage Semaphore groups.
  * @copyright Ethereum Foundation 2024
  * @license MIT
@@ -111,10 +111,22 @@ function poseidon2(inputs) {
   return (0, _poseidon.default)(inputs, c);
 }
 
+/**
+ * The Semaphore group is a {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT}
+ * (Lean Incremental Merkle Tree), i.e. an optimized version of the incremental binary Merkle tree
+ * used by Semaphore V3. The new tree does not use zero hashes, and its depth is dynamic.
+ * The members of a Semaphore group, or the leaves of a tree, are the identity commitments.
+ * Thanks to the properties of Merkle trees, it can be efficiently demonstrated that a group
+ * member belongs to the group.
+ * This class supports operations such as member addition, update, removal and Merkle proof
+ * generation and verification. Groups can also be exported or imported.
+ */
 var Group = /** @class */ (function () {
     /**
-     * Initializes the group with the group id and the tree depth.
-     * @param members List of group members.
+     * Creates a new instance of the Group. Optionally, a list of identity commitments can
+     * be passed as a parameter. Adding members in chunks is more efficient than adding
+     * them one by one with the `addMember` function.
+     * @param members A list of identity commitments.
      */
     function Group(members) {
         if (members === void 0) { members = []; }
@@ -123,7 +135,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "root", {
         /**
          * Returns the root hash of the tree.
-         * @returns Root hash.
+         * @returns The root hash as a string.
          */
         get: function () {
             return this.leanIMT.root ? this.leanIMT.root.toString() : "0";
@@ -134,7 +146,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "depth", {
         /**
          * Returns the depth of the tree.
-         * @returns Tree depth.
+         * @returns The tree depth as a number.
          */
         get: function () {
             return this.leanIMT.depth;
@@ -145,7 +157,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "size", {
         /**
          * Returns the size of the tree (i.e. number of leaves).
-         * @returns Tree depth.
+         * @returns The tree size as a number.
          */
         get: function () {
             return this.leanIMT.size;
@@ -156,7 +168,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "members", {
         /**
          * Returns the members (i.e. identity commitments) of the group.
-         * @returns List of members.
+         * @returns The list of members of the group.
          */
         get: function () {
             return this.leanIMT.leaves.map(String);
@@ -166,15 +178,15 @@ var Group = /** @class */ (function () {
     });
     /**
      * Returns the index of a member. If the member does not exist it returns -1.
-     * @param member Group member.
-     * @returns Index of the member.
+     * @param member A member of the group.
+     * @returns The index of the member, or -1 if it does not exist.
      */
     Group.prototype.indexOf = function (member) {
         return this.leanIMT.indexOf(BigInt(member));
     };
     /**
      * Adds a new member to the group.
-     * @param member New member.
+     * @param member The new member to be added.
      */
     Group.prototype.addMember = function (member) {
         this.leanIMT.insert(BigInt(member));
@@ -196,15 +208,15 @@ var Group = /** @class */ (function () {
     };
     /**
      * Removes a member from the group.
-     * @param index Index of the member to be removed.
+     * @param index The index of the member to be removed.
      */
     Group.prototype.removeMember = function (index) {
         this.leanIMT.update(index, BigInt(0));
     };
     /**
-     * Creates a proof of membership.
-     * @param index Index of the proof's member.
-     * @returns Proof object.
+     * Creates a proof of membership for a member of the group.
+     * @param index The index of the member.
+     * @returns The {@link MerkleProof} object.
      */
     Group.prototype.generateMerkleProof = function (_index) {
         var _a = this.leanIMT.generateProof(_index), index = _a.index, leaf = _a.leaf, root = _a.root, siblings = _a.siblings;
@@ -216,7 +228,7 @@ var Group = /** @class */ (function () {
         };
     };
     /**
-     * It enables the conversion of the group into a JSON string that
+     * Enables the conversion of the group into a JSON string that
      * can be re-used for future imports. This approach is beneficial for
      * large groups, as it avoids re-calculating the tree hashes.
      * @returns The stringified JSON of the group.
@@ -225,11 +237,11 @@ var Group = /** @class */ (function () {
         return this.leanIMT.export();
     };
     /**
-     * It imports an entire group by initializing the tree without calculating
+     * Imports an entire group by initializing the tree without calculating
      * any hashes. Note that it is crucial to ensure the integrity of the
      * exported group.
      * @param nodes The stringified JSON of the group.
-     * @returns The group instance.
+     * @returns The {@link Group} instance.
      */
     Group.import = function (exportedGroup) {
         var group = new Group();

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * @module @semaphore-protocol/group
- * @version 4.0.0-alpha.7
+ * @version 4.0.0-beta
  * @file A library to create and manage Semaphore groups.
  * @copyright Ethereum Foundation 2024
  * @license MIT
@@ -109,10 +109,22 @@ function poseidon2(inputs) {
   return (0, _poseidon.default)(inputs, c);
 }
 
+/**
+ * The Semaphore group is a {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT}
+ * (Lean Incremental Merkle Tree), i.e. an optimized version of the incremental binary Merkle tree
+ * used by Semaphore V3. The new tree does not use zero hashes, and its depth is dynamic.
+ * The members of a Semaphore group, or the leaves of a tree, are the identity commitments.
+ * Thanks to the properties of Merkle trees, it can be efficiently demonstrated that a group
+ * member belongs to the group.
+ * This class supports operations such as member addition, update, removal and Merkle proof
+ * generation and verification. Groups can also be exported or imported.
+ */
 var Group = /** @class */ (function () {
     /**
-     * Initializes the group with the group id and the tree depth.
-     * @param members List of group members.
+     * Creates a new instance of the Group. Optionally, a list of identity commitments can
+     * be passed as a parameter. Adding members in chunks is more efficient than adding
+     * them one by one with the `addMember` function.
+     * @param members A list of identity commitments.
      */
     function Group(members) {
         if (members === void 0) { members = []; }
@@ -121,7 +133,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "root", {
         /**
          * Returns the root hash of the tree.
-         * @returns Root hash.
+         * @returns The root hash as a string.
          */
         get: function () {
             return this.leanIMT.root ? this.leanIMT.root.toString() : "0";
@@ -132,7 +144,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "depth", {
         /**
          * Returns the depth of the tree.
-         * @returns Tree depth.
+         * @returns The tree depth as a number.
          */
         get: function () {
             return this.leanIMT.depth;
@@ -143,7 +155,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "size", {
         /**
          * Returns the size of the tree (i.e. number of leaves).
-         * @returns Tree depth.
+         * @returns The tree size as a number.
          */
         get: function () {
             return this.leanIMT.size;
@@ -154,7 +166,7 @@ var Group = /** @class */ (function () {
     Object.defineProperty(Group.prototype, "members", {
         /**
          * Returns the members (i.e. identity commitments) of the group.
-         * @returns List of members.
+         * @returns The list of members of the group.
          */
         get: function () {
             return this.leanIMT.leaves.map(String);
@@ -164,15 +176,15 @@ var Group = /** @class */ (function () {
     });
     /**
      * Returns the index of a member. If the member does not exist it returns -1.
-     * @param member Group member.
-     * @returns Index of the member.
+     * @param member A member of the group.
+     * @returns The index of the member, or -1 if it does not exist.
      */
     Group.prototype.indexOf = function (member) {
         return this.leanIMT.indexOf(BigInt(member));
     };
     /**
      * Adds a new member to the group.
-     * @param member New member.
+     * @param member The new member to be added.
      */
     Group.prototype.addMember = function (member) {
         this.leanIMT.insert(BigInt(member));
@@ -194,15 +206,15 @@ var Group = /** @class */ (function () {
     };
     /**
      * Removes a member from the group.
-     * @param index Index of the member to be removed.
+     * @param index The index of the member to be removed.
      */
     Group.prototype.removeMember = function (index) {
         this.leanIMT.update(index, BigInt(0));
     };
     /**
-     * Creates a proof of membership.
-     * @param index Index of the proof's member.
-     * @returns Proof object.
+     * Creates a proof of membership for a member of the group.
+     * @param index The index of the member.
+     * @returns The {@link MerkleProof} object.
      */
     Group.prototype.generateMerkleProof = function (_index) {
         var _a = this.leanIMT.generateProof(_index), index = _a.index, leaf = _a.leaf, root = _a.root, siblings = _a.siblings;
@@ -214,7 +226,7 @@ var Group = /** @class */ (function () {
         };
     };
     /**
-     * It enables the conversion of the group into a JSON string that
+     * Enables the conversion of the group into a JSON string that
      * can be re-used for future imports. This approach is beneficial for
      * large groups, as it avoids re-calculating the tree hashes.
      * @returns The stringified JSON of the group.
@@ -223,11 +235,11 @@ var Group = /** @class */ (function () {
         return this.leanIMT.export();
     };
     /**
-     * It imports an entire group by initializing the tree without calculating
+     * Imports an entire group by initializing the tree without calculating
      * any hashes. Note that it is crucial to ensure the integrity of the
      * exported group.
      * @param nodes The stringified JSON of the group.
-     * @returns The group instance.
+     * @returns The {@link Group} instance.
      */
     Group.import = function (exportedGroup) {
         var group = new Group();

package/dist/types/group.d.ts

@@ -1,41 +1,53 @@
 import { LeanIMT } from "@zk-kit/imt";
 import { BigNumberish, MerkleProof } from "./types";
+/**
+ * The Semaphore group is a {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT}
+ * (Lean Incremental Merkle Tree), i.e. an optimized version of the incremental binary Merkle tree
+ * used by Semaphore V3. The new tree does not use zero hashes, and its depth is dynamic.
+ * The members of a Semaphore group, or the leaves of a tree, are the identity commitments.
+ * Thanks to the properties of Merkle trees, it can be efficiently demonstrated that a group
+ * member belongs to the group.
+ * This class supports operations such as member addition, update, removal and Merkle proof
+ * generation and verification. Groups can also be exported or imported.
+ */
 export default class Group {
     leanIMT: LeanIMT;
     /**
-     * Initializes the group with the group id and the tree depth.
-     * @param members List of group members.
+     * Creates a new instance of the Group. Optionally, a list of identity commitments can
+     * be passed as a parameter. Adding members in chunks is more efficient than adding
+     * them one by one with the `addMember` function.
+     * @param members A list of identity commitments.
      */
     constructor(members?: BigNumberish[]);
     /**
      * Returns the root hash of the tree.
-     * @returns Root hash.
+     * @returns The root hash as a string.
      */
     get root(): string;
     /**
      * Returns the depth of the tree.
-     * @returns Tree depth.
+     * @returns The tree depth as a number.
      */
     get depth(): number;
     /**
      * Returns the size of the tree (i.e. number of leaves).
-     * @returns Tree depth.
+     * @returns The tree size as a number.
      */
     get size(): number;
     /**
      * Returns the members (i.e. identity commitments) of the group.
-     * @returns List of members.
+     * @returns The list of members of the group.
      */
     get members(): string[];
     /**
      * Returns the index of a member. If the member does not exist it returns -1.
-     * @param member Group member.
-     * @returns Index of the member.
+     * @param member A member of the group.
+     * @returns The index of the member, or -1 if it does not exist.
      */
     indexOf(member: BigNumberish): number;
     /**
      * Adds a new member to the group.
-     * @param member New member.
+     * @param member The new member to be added.
      */
     addMember(member: BigNumberish): void;
     /**
@@ -51,28 +63,28 @@ export default class Group {
     updateMember(index: number, member: BigNumberish): void;
     /**
      * Removes a member from the group.
-     * @param index Index of the member to be removed.
+     * @param index The index of the member to be removed.
      */
     removeMember(index: number): void;
     /**
-     * Creates a proof of membership.
-     * @param index Index of the proof's member.
-     * @returns Proof object.
+     * Creates a proof of membership for a member of the group.
+     * @param index The index of the member.
+     * @returns The {@link MerkleProof} object.
      */
     generateMerkleProof(_index: number): MerkleProof;
     /**
-     * It enables the conversion of the group into a JSON string that
+     * Enables the conversion of the group into a JSON string that
      * can be re-used for future imports. This approach is beneficial for
      * large groups, as it avoids re-calculating the tree hashes.
      * @returns The stringified JSON of the group.
      */
     export(): string;
     /**
-     * It imports an entire group by initializing the tree without calculating
+     * Imports an entire group by initializing the tree without calculating
      * any hashes. Note that it is crucial to ensure the integrity of the
      * exported group.
      * @param nodes The stringified JSON of the group.
-     * @returns The group instance.
+     * @returns The {@link Group} instance.
      */
     static import(exportedGroup: string): Group;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semaphore-protocol/group",
-  "version": "4.0.0-alpha.7",
+  "version": "4.0.0-beta",
   "description": "A library to create and manage Semaphore groups.",
   "type": "module",
   "license": "MIT",

package/src/group.ts

@@ -2,12 +2,25 @@ import { LeanIMT } from "@zk-kit/imt"
 import { poseidon2 } from "poseidon-lite/poseidon2"
 import { BigNumberish, MerkleProof } from "./types"
 
+/**
+ * The Semaphore group is a {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT}
+ * (Lean Incremental Merkle Tree), i.e. an optimized version of the incremental binary Merkle tree
+ * used by Semaphore V3. The new tree does not use zero hashes, and its depth is dynamic.
+ * The members of a Semaphore group, or the leaves of a tree, are the identity commitments.
+ * Thanks to the properties of Merkle trees, it can be efficiently demonstrated that a group
+ * member belongs to the group.
+ * This class supports operations such as member addition, update, removal and Merkle proof
+ * generation and verification. Groups can also be exported or imported.
+ */
 export default class Group {
-    leanIMT: LeanIMT
+    // The {@link https://zkkit.pse.dev/classes/_zk_kit_imt.LeanIMT.html | LeanIMT} instance.
+    public leanIMT: LeanIMT
 
     /**
-     * Initializes the group with the group id and the tree depth.
-     * @param members List of group members.
+     * Creates a new instance of the Group. Optionally, a list of identity commitments can
+     * be passed as a parameter. Adding members in chunks is more efficient than adding
+     * them one by one with the `addMember` function.
+     * @param members A list of identity commitments.
      */
     constructor(members: BigNumberish[] = []) {
         this.leanIMT = new LeanIMT((a, b) => poseidon2([a, b]), members.map(BigInt))
@@ -15,50 +28,50 @@ export default class Group {
 
     /**
      * Returns the root hash of the tree.
-     * @returns Root hash.
+     * @returns The root hash as a string.
      */
-    get root(): string {
+    public get root(): string {
         return this.leanIMT.root ? this.leanIMT.root.toString() : "0"
     }
 
     /**
      * Returns the depth of the tree.
-     * @returns Tree depth.
+     * @returns The tree depth as a number.
      */
-    get depth(): number {
+    public get depth(): number {
         return this.leanIMT.depth
     }
 
     /**
      * Returns the size of the tree (i.e. number of leaves).
-     * @returns Tree depth.
+     * @returns The tree size as a number.
      */
-    get size(): number {
+    public get size(): number {
         return this.leanIMT.size
     }
 
     /**
      * Returns the members (i.e. identity commitments) of the group.
-     * @returns List of members.
+     * @returns The list of members of the group.
      */
-    get members(): string[] {
+    public get members(): string[] {
         return this.leanIMT.leaves.map(String)
     }
 
     /**
      * Returns the index of a member. If the member does not exist it returns -1.
-     * @param member Group member.
-     * @returns Index of the member.
+     * @param member A member of the group.
+     * @returns The index of the member, or -1 if it does not exist.
      */
-    indexOf(member: BigNumberish): number {
+    public indexOf(member: BigNumberish): number {
         return this.leanIMT.indexOf(BigInt(member))
     }
 
     /**
      * Adds a new member to the group.
-     * @param member New member.
+     * @param member The new member to be added.
      */
-    addMember(member: BigNumberish) {
+    public addMember(member: BigNumberish) {
         this.leanIMT.insert(BigInt(member))
     }
 
@@ -66,7 +79,7 @@ export default class Group {
      * Adds new members to the group.
      * @param members New members.
      */
-    addMembers(members: BigNumberish[]) {
+    public addMembers(members: BigNumberish[]) {
         this.leanIMT.insertMany(members.map(BigInt))
     }
 
@@ -75,24 +88,24 @@ export default class Group {
      * @param index Index of the member to be updated.
      * @param member New member value.
      */
-    updateMember(index: number, member: BigNumberish) {
+    public updateMember(index: number, member: BigNumberish) {
         this.leanIMT.update(index, BigInt(member))
     }
 
     /**
      * Removes a member from the group.
-     * @param index Index of the member to be removed.
+     * @param index The index of the member to be removed.
      */
-    removeMember(index: number) {
+    public removeMember(index: number) {
         this.leanIMT.update(index, BigInt(0))
     }
 
     /**
-     * Creates a proof of membership.
-     * @param index Index of the proof's member.
-     * @returns Proof object.
+     * Creates a proof of membership for a member of the group.
+     * @param index The index of the member.
+     * @returns The {@link MerkleProof} object.
      */
-    generateMerkleProof(_index: number): MerkleProof {
+    public generateMerkleProof(_index: number): MerkleProof {
         const { index, leaf, root, siblings } = this.leanIMT.generateProof(_index)
 
         return {
@@ -104,21 +117,21 @@ export default class Group {
     }
 
     /**
-     * It enables the conversion of the group into a JSON string that
+     * Enables the conversion of the group into a JSON string that
      * can be re-used for future imports. This approach is beneficial for
      * large groups, as it avoids re-calculating the tree hashes.
      * @returns The stringified JSON of the group.
      */
-    export(): string {
+    public export(): string {
         return this.leanIMT.export()
     }
 
     /**
-     * It imports an entire group by initializing the tree without calculating
+     * Imports an entire group by initializing the tree without calculating
      * any hashes. Note that it is crucial to ensure the integrity of the
      * exported group.
      * @param nodes The stringified JSON of the group.
-     * @returns The group instance.
+     * @returns The {@link Group} instance.
      */
     static import(exportedGroup: string): Group {
         const group = new Group()