@semaphore-protocol/group 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+<p align="center">
+    <h1 align="center">
+        Semaphore group
+    </h1>
+    <p align="center">A library for managing Semaphore groups.</p>
+</p>
+
+<p align="center">
+    <a href="https://github.com/semaphore-protocol/semaphore.js">
+        <img src="https://img.shields.io/badge/project-semaphore-blue.svg?style=flat-square">
+    </a>
+    <a href="https://github.com/semaphore-protocol/semaphore.js/blob/main/packages/group/LICENSE">
+        <img alt="Github license" src="https://img.shields.io/github/license/semaphore-protocol/semaphore.js.svg?style=flat-square">
+    </a>
+    <a href="https://www.npmjs.com/package/@semaphore-protocol/group">
+        <img alt="NPM version" src="https://img.shields.io/npm/v/@semaphore-protocol/group?style=flat-square" />
+    </a>
+    <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://eslint.org/">
+        <img alt="Linter eslint" src="https://img.shields.io/badge/linter-eslint-8080f2?style=flat-square&logo=eslint" />
+    </a>
+    <a href="https://prettier.io/">
+        <img alt="Code style prettier" src="https://img.shields.io/badge/code%20style-prettier-f8bc45?style=flat-square&logo=prettier" />
+    </a>
+</p>
+
+<div align="center">
+    <h4>
+        <a href="https://t.me/joinchat/B-PQx1U3GtAh--Z4Fwo56A">
+            🗣️ Chat &amp; Support
+        </a>
+        <span>&nbsp;&nbsp;|&nbsp;&nbsp;</span>
+        <a href="https://semaphore-protocol.github.io/semaphore.js/group">
+            📘 Docs
+        </a>
+    </h4>
+</div>
+
+| This library is an abstraction of [`@zk-kit/incremental-merkle-tree`](https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/incremental-merkle-tree). The main goal is to make it easier to create offchain groups, which are also used to generate Semaphore proofs. Semaphore groups are actually incremental Merkle trees, and the group members are tree leaves. Since the Merkle tree implementation we are using is a binary tree, the maximum number of members of a group is equal to `2^treeDepth`. |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+## 🛠 Install
+
+### npm or yarn
+
+Install the `@semaphore-protocol/group` package with npm:
+
+```bash
+npm i @semaphore-protocol/group
+```
+
+or yarn:
+
+```bash
+yarn add @semaphore-protocol/group
+```
+
+## 📜 Usage
+
+\# **new Group**(treeDepth = 20, zeroValue = BigInt(0)): _Group_
+
+```typescript
+import { Group } from "@semaphore-protocol/group"
+
+// Group with max 1048576 members (20^²).
+const group1 = new Group()
+
+// Group with max 65536 members (16^²).
+const group2 = new Group(16)
+
+// Group with max 16777216 members (24^²).
+const group3 = new Group(24)
+```
+
+\# **addMember**(identityCommitment: _Member_)
+
+```typescript
+import { Identity } from "@semaphore-protocol/identity"
+
+const identity = new Identity()
+const commitment = identity.generateCommitment()
+
+group.addMember(commitment)
+```
+
+\# **addMembers**(identityCommitments: _Member\[]_)
+
+```typescript
+let identityCommitments: bigint[]
+
+for (let i = 0; i < 10; i++) {
+    const identity = new Identity()
+    const commitment = identity.generateCommitment()
+
+    identityCommitments.push(commitment)
+}
+
+group.addMember(identityCommitments)
+```
+
+\# **removeMember**(index: _number_)
+
+```typescript
+group.removeMember(0)
+```
+
+\# **indexOf**(member: _Member_): _number_
+
+```typescript
+group.indexOf(commitment) // 0
+```
+
+\# **generateProofOfMembership**(index: _number_): _MerkleProof_
+
+```typescript
+const proof = group.generateProofOfMembership(0)
+```
+
+\# **verifyProofOfMembership**(proof: _MerkleProof_): _boolean_
+
+```typescript
+group.verifyProofOfMembership(proof) // true
+```

package/dist/index.mjs

@@ -0,0 +1,121 @@
+/**
+ * @module @semaphore-protocol/group
+ * @version 0.1.0
+ * @file A library for managing Semaphore groups.
+ * @copyright Ethereum Foundation 2022
+ * @license MIT
+ * @see [Github]{@link https://github.com/semaphore-protocol/semaphore.js/tree/main/packages/group}
+*/
+import { IncrementalMerkleTree } from '@zk-kit/incremental-merkle-tree';
+import { poseidon } from 'circomlibjs';
+
+var Group = /** @class */ (function () {
+    /**
+     * Initializes the group with the tree depth and the zero value.
+     * @param treeDepth Tree depth.
+     * @param zeroValue Zero values for zeroes.
+     */
+    function Group(treeDepth, zeroValue) {
+        if (treeDepth === void 0) { treeDepth = 20; }
+        if (zeroValue === void 0) { zeroValue = BigInt(0); }
+        if (treeDepth < 16 || treeDepth > 32) {
+            throw new Error("The tree depth must be between 16 and 32");
+        }
+        this._merkleTree = new IncrementalMerkleTree(poseidon, treeDepth, zeroValue, 2);
+    }
+    Object.defineProperty(Group.prototype, "root", {
+        /**
+         * Returns the root hash of the tree.
+         * @returns Root hash.
+         */
+        get: function () {
+            return this._merkleTree.root;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "depth", {
+        /**
+         * Returns the depth of the tree.
+         * @returns Tree depth.
+         */
+        get: function () {
+            return this._merkleTree.depth;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "zeroValue", {
+        /**
+         * Returns the zero value of the tree.
+         * @returns Tree zero value.
+         */
+        get: function () {
+            return this._merkleTree.zeroes[0];
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "members", {
+        /**
+         * Returns the members (i.e. identity commitments) of the group.
+         * @returns List of members.
+         */
+        get: function () {
+            return this._merkleTree.leaves;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Returns the index of a member. If the member does not exist it returns -1.
+     * @param member Group member.
+     * @returns Index of the member.
+     */
+    Group.prototype.indexOf = function (member) {
+        return this._merkleTree.indexOf(member);
+    };
+    /**
+     * Adds a new member to the group.
+     * @param identityCommitment New member.
+     */
+    Group.prototype.addMember = function (identityCommitment) {
+        this._merkleTree.insert(identityCommitment);
+    };
+    /**
+     * Adds new members to the group.
+     * @param identityCommitments New members.
+     */
+    Group.prototype.addMembers = function (identityCommitments) {
+        for (var _i = 0, identityCommitments_1 = identityCommitments; _i < identityCommitments_1.length; _i++) {
+            var identityCommitment = identityCommitments_1[_i];
+            this.addMember(identityCommitment);
+        }
+    };
+    /**
+     * Removes a member from the group.
+     * @param index Index of the member to be removed.
+     */
+    Group.prototype.removeMember = function (index) {
+        this._merkleTree.delete(index);
+    };
+    /**
+     * Creates a proof of membership.
+     * @param index Index of the proof's member.
+     * @returns Proof object.
+     */
+    Group.prototype.generateProofOfMembership = function (index) {
+        return this._merkleTree.createProof(index);
+    };
+    /**
+     * Verifies a proof of membership and return true or false.
+     * @param proof Proof to be verified.
+     * @returns True or false.
+     */
+    Group.prototype.verifyProofOfMembership = function (proof) {
+        return this._merkleTree.verifyProof(proof);
+    };
+    return Group;
+}());
+
+export { Group };

package/dist/index.node.js

@@ -0,0 +1,125 @@
+/**
+ * @module @semaphore-protocol/group
+ * @version 0.1.0
+ * @file A library for managing Semaphore groups.
+ * @copyright Ethereum Foundation 2022
+ * @license MIT
+ * @see [Github]{@link https://github.com/semaphore-protocol/semaphore.js/tree/main/packages/group}
+*/
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var incrementalMerkleTree = require('@zk-kit/incremental-merkle-tree');
+var circomlibjs = require('circomlibjs');
+
+var Group = /** @class */ (function () {
+    /**
+     * Initializes the group with the tree depth and the zero value.
+     * @param treeDepth Tree depth.
+     * @param zeroValue Zero values for zeroes.
+     */
+    function Group(treeDepth, zeroValue) {
+        if (treeDepth === void 0) { treeDepth = 20; }
+        if (zeroValue === void 0) { zeroValue = BigInt(0); }
+        if (treeDepth < 16 || treeDepth > 32) {
+            throw new Error("The tree depth must be between 16 and 32");
+        }
+        this._merkleTree = new incrementalMerkleTree.IncrementalMerkleTree(circomlibjs.poseidon, treeDepth, zeroValue, 2);
+    }
+    Object.defineProperty(Group.prototype, "root", {
+        /**
+         * Returns the root hash of the tree.
+         * @returns Root hash.
+         */
+        get: function () {
+            return this._merkleTree.root;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "depth", {
+        /**
+         * Returns the depth of the tree.
+         * @returns Tree depth.
+         */
+        get: function () {
+            return this._merkleTree.depth;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "zeroValue", {
+        /**
+         * Returns the zero value of the tree.
+         * @returns Tree zero value.
+         */
+        get: function () {
+            return this._merkleTree.zeroes[0];
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Group.prototype, "members", {
+        /**
+         * Returns the members (i.e. identity commitments) of the group.
+         * @returns List of members.
+         */
+        get: function () {
+            return this._merkleTree.leaves;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Returns the index of a member. If the member does not exist it returns -1.
+     * @param member Group member.
+     * @returns Index of the member.
+     */
+    Group.prototype.indexOf = function (member) {
+        return this._merkleTree.indexOf(member);
+    };
+    /**
+     * Adds a new member to the group.
+     * @param identityCommitment New member.
+     */
+    Group.prototype.addMember = function (identityCommitment) {
+        this._merkleTree.insert(identityCommitment);
+    };
+    /**
+     * Adds new members to the group.
+     * @param identityCommitments New members.
+     */
+    Group.prototype.addMembers = function (identityCommitments) {
+        for (var _i = 0, identityCommitments_1 = identityCommitments; _i < identityCommitments_1.length; _i++) {
+            var identityCommitment = identityCommitments_1[_i];
+            this.addMember(identityCommitment);
+        }
+    };
+    /**
+     * Removes a member from the group.
+     * @param index Index of the member to be removed.
+     */
+    Group.prototype.removeMember = function (index) {
+        this._merkleTree.delete(index);
+    };
+    /**
+     * Creates a proof of membership.
+     * @param index Index of the proof's member.
+     * @returns Proof object.
+     */
+    Group.prototype.generateProofOfMembership = function (index) {
+        return this._merkleTree.createProof(index);
+    };
+    /**
+     * Verifies a proof of membership and return true or false.
+     * @param proof Proof to be verified.
+     * @returns True or false.
+     */
+    Group.prototype.verifyProofOfMembership = function (proof) {
+        return this._merkleTree.verifyProof(proof);
+    };
+    return Group;
+}());
+
+exports.Group = Group;

package/dist/types/group.d.ts

@@ -0,0 +1,64 @@
+import { MerkleProof } from "@zk-kit/incremental-merkle-tree";
+import { Member } from "./types";
+export default class Group {
+    private _merkleTree;
+    /**
+     * Initializes the group with the tree depth and the zero value.
+     * @param treeDepth Tree depth.
+     * @param zeroValue Zero values for zeroes.
+     */
+    constructor(treeDepth?: number, zeroValue?: Member);
+    /**
+     * Returns the root hash of the tree.
+     * @returns Root hash.
+     */
+    get root(): Member;
+    /**
+     * Returns the depth of the tree.
+     * @returns Tree depth.
+     */
+    get depth(): number;
+    /**
+     * Returns the zero value of the tree.
+     * @returns Tree zero value.
+     */
+    get zeroValue(): Member;
+    /**
+     * Returns the members (i.e. identity commitments) of the group.
+     * @returns List of members.
+     */
+    get members(): Member[];
+    /**
+     * Returns the index of a member. If the member does not exist it returns -1.
+     * @param member Group member.
+     * @returns Index of the member.
+     */
+    indexOf(member: Member): number;
+    /**
+     * Adds a new member to the group.
+     * @param identityCommitment New member.
+     */
+    addMember(identityCommitment: Member): void;
+    /**
+     * Adds new members to the group.
+     * @param identityCommitments New members.
+     */
+    addMembers(identityCommitments: Member[]): void;
+    /**
+     * Removes a member from the group.
+     * @param index 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.
+     */
+    generateProofOfMembership(index: number): MerkleProof;
+    /**
+     * Verifies a proof of membership and return true or false.
+     * @param proof Proof to be verified.
+     * @returns True or false.
+     */
+    verifyProofOfMembership(proof: MerkleProof): boolean;
+}

package/dist/types/group.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+import Group from "./group";
+export { Group };
+export * from "./types";

package/dist/types/types/index.d.ts

@@ -0,0 +1 @@
+export declare type Member = string | bigint;

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@semaphore-protocol/group",
+    "version": "0.1.0",
+    "description": "A library for managing Semaphore groups.",
+    "license": "MIT",
+    "main": "dist/index.node.js",
+    "exports": {
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.node.js"
+    },
+    "types": "dist/types/index.d.ts",
+    "files": [
+        "dist/",
+        "src/",
+        "LICENSE",
+        "README.md"
+    ],
+    "repository": "https://github.com/semaphore-protocol/semaphore.js",
+    "homepage": "https://github.com/semaphore-protocol/semaphore.js/tree/main/packages/group",
+    "scripts": {
+        "build:watch": "rollup -c rollup.config.ts -w --configPlugin typescript",
+        "build": "rimraf dist && rollup -c rollup.config.ts --configPlugin typescript",
+        "prepublishOnly": "yarn build",
+        "docs": "typedoc src/index.ts --out ../../docs/group"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "rollup-plugin-cleanup": "^3.2.1",
+        "rollup-plugin-typescript2": "^0.31.2",
+        "typedoc": "^0.22.11"
+    },
+    "dependencies": {
+        "@zk-kit/incremental-merkle-tree": "0.4.3",
+        "circomlibjs": "0.0.8"
+    }
+}

package/src/group.test.ts

@@ -0,0 +1,95 @@
+import Group from "./group"
+
+describe("Group", () => {
+    describe("# Group", () => {
+        it("Should create a group", () => {
+            const group = new Group()
+
+            expect(group.root.toString()).toContain("150197")
+            expect(group.depth).toBe(20)
+            expect(group.zeroValue).toBe(BigInt(0))
+            expect(group.members).toHaveLength(0)
+        })
+
+        it("Should not create a group with a wrong tree depth", () => {
+            const fun = () => new Group(33)
+
+            expect(fun).toThrow("The tree depth must be between 16 and 32")
+        })
+
+        it("Should create a group with different parameters", () => {
+            const group = new Group(32, BigInt(1))
+
+            expect(group.root.toString()).toContain("640470")
+            expect(group.depth).toBe(32)
+            expect(group.zeroValue).toBe(BigInt(1))
+            expect(group.members).toHaveLength(0)
+        })
+    })
+
+    describe("# addMember", () => {
+        it("Should add a member to a group", () => {
+            const group = new Group()
+
+            group.addMember(BigInt(3))
+
+            expect(group.members).toHaveLength(1)
+        })
+    })
+
+    describe("# addMembers", () => {
+        it("Should add many members to a group", () => {
+            const group = new Group()
+
+            group.addMembers([BigInt(1), BigInt(3)])
+
+            expect(group.members).toHaveLength(2)
+        })
+    })
+
+    describe("# indexOf", () => {
+        it("Should return the index of a member in a group", () => {
+            const group = new Group()
+            group.addMembers([BigInt(1), BigInt(3)])
+
+            const index = group.indexOf(BigInt(3))
+
+            expect(index).toBe(1)
+        })
+    })
+
+    describe("# removeMember", () => {
+        it("Should remove a member from a group", () => {
+            const group = new Group()
+            group.addMembers([BigInt(1), BigInt(3)])
+
+            group.removeMember(0)
+
+            expect(group.members).toHaveLength(2)
+            expect(group.members[0]).toBe(group.zeroValue)
+        })
+    })
+
+    describe("# generateProofOfMembership", () => {
+        it("Should generate a proof of membership", () => {
+            const group = new Group()
+            group.addMembers([BigInt(1), BigInt(3)])
+
+            const proof = group.generateProofOfMembership(0)
+
+            expect(proof.leaf).toBe(BigInt(1))
+        })
+    })
+
+    describe("# verifyProofOfMembership", () => {
+        it("Should verify a proof of membership", () => {
+            const group = new Group()
+            group.addMembers([BigInt(1), BigInt(3)])
+            const proof = group.generateProofOfMembership(0)
+
+            const response = group.verifyProofOfMembership(proof)
+
+            expect(response).toBeTruthy()
+        })
+    })
+})

package/src/group.ts

@@ -0,0 +1,105 @@
+import { IncrementalMerkleTree, MerkleProof } from "@zk-kit/incremental-merkle-tree"
+import { poseidon } from "circomlibjs"
+import { Member } from "./types"
+
+export default class Group {
+    private _merkleTree: IncrementalMerkleTree
+
+    /**
+     * Initializes the group with the tree depth and the zero value.
+     * @param treeDepth Tree depth.
+     * @param zeroValue Zero values for zeroes.
+     */
+    constructor(treeDepth = 20, zeroValue: Member = BigInt(0)) {
+        if (treeDepth < 16 || treeDepth > 32) {
+            throw new Error("The tree depth must be between 16 and 32")
+        }
+
+        this._merkleTree = new IncrementalMerkleTree(poseidon, treeDepth, zeroValue, 2)
+    }
+
+    /**
+     * Returns the root hash of the tree.
+     * @returns Root hash.
+     */
+    get root(): Member {
+        return this._merkleTree.root
+    }
+
+    /**
+     * Returns the depth of the tree.
+     * @returns Tree depth.
+     */
+    get depth(): number {
+        return this._merkleTree.depth
+    }
+
+    /**
+     * Returns the zero value of the tree.
+     * @returns Tree zero value.
+     */
+    get zeroValue(): Member {
+        return this._merkleTree.zeroes[0]
+    }
+
+    /**
+     * Returns the members (i.e. identity commitments) of the group.
+     * @returns List of members.
+     */
+    get members(): Member[] {
+        return this._merkleTree.leaves
+    }
+
+    /**
+     * Returns the index of a member. If the member does not exist it returns -1.
+     * @param member Group member.
+     * @returns Index of the member.
+     */
+    indexOf(member: Member): number {
+        return this._merkleTree.indexOf(member)
+    }
+
+    /**
+     * Adds a new member to the group.
+     * @param identityCommitment New member.
+     */
+    addMember(identityCommitment: Member) {
+        this._merkleTree.insert(identityCommitment)
+    }
+
+    /**
+     * Adds new members to the group.
+     * @param identityCommitments New members.
+     */
+    addMembers(identityCommitments: Member[]) {
+        for (const identityCommitment of identityCommitments) {
+            this.addMember(identityCommitment)
+        }
+    }
+
+    /**
+     * Removes a member from the group.
+     * @param index Index of the member to be removed.
+     */
+    removeMember(index: number) {
+        this._merkleTree.delete(index)
+    }
+
+    /**
+     * Creates a proof of membership.
+     * @param index Index of the proof's member.
+     * @returns Proof object.
+     */
+    generateProofOfMembership(index: number): MerkleProof {
+        return this._merkleTree.createProof(index)
+    }
+
+    /**
+     * Verifies a proof of membership and return true or false.
+     * @param proof Proof to be verified.
+     * @returns True or false.
+     */
+    verifyProofOfMembership(proof: MerkleProof): boolean {
+        return this._merkleTree.verifyProof(proof)
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+import Group from "./group"
+
+export { Group }
+export * from "./types"

package/src/types/index.ts

@@ -0,0 +1 @@
+export type Member = string | bigint