Merge pull request #1 from appliedzkp/refactoring

README.md updates & inconsistencies fix

README.md

@@ -1,91 +1,16 @@
-# semaphore-lib
+# libsemaphore
 
 ### Description
 
 A library that allows for easy access and interoperability for [Semaphore](https://semaphore.appliedzkp.org/) and [RLN](https://medium.com/privacy-scaling-explorations/rate-limiting-nullifier-a-spam-protection-mechanism-for-anonymous-environments-bbe4006a57d) constructs. It is meant to be used by third-party applications to easily integrate with Seamphore and RLN. The library provides an API (Semaphore and RLN) for:
 - Identity generation
 - Proof generation
-- Proof verification
+- Proof verification.
 
 
- ### Install instructions
+The library is structured as a three separate npm packages:
+- `identity` - Exposes utilities for Zk identity generation, necessary for interacting with the Zk protocols supported by this library
+- `protocols` - Utilities for proof genration and verification for various Zk protocols
+- `types` - Helper package which exposes the types used by `identity` and `protocols` packages.
 
-`yarn add git+https://github.com/akinovak/semaphore-lib.git#dev`
-
-### API
-
-The library provides APIs for three different constructs, which are: `OrdinarySemaphore`, `FastSemaphore` and `RLN`. The library provides a base class (`BaseSemaphore`) which provides all the common functions, and the specifics for each construct are implemented on top of the base class as sub classes.
-
-The difference between `OrdinarySemaphore` and `FastSemaphore` is that `FastSemaphore` does not use the EdDSA public key of the user for the identity commitment generation. This allows for "leaner" proofs and zkSNARK with less constrains which leads to better performance (thus the prefix `Fast`). The `OrdinarySemaphore` and `FastSemaphore` have the same interface, however their underlying implementation is different.
-
-#### BaseSemaphore
-
-```typescript
-- setHasher(hashFunction: string);
-- genIdentity(privKey: Buffer): Identity;
-- serializeIdentity(identity: Identity): string;
-- unSerializeIdentity(serialisedIdentity: string): Identity;
-- genNullifierHash(externalNullifier: string | bigint, identityNullifier: string | bigint, nLevels: number): BigInt;
-- genExternalNullifier(plaintext: string): string;
-- genMsg(externalNullifier: string, signalHash: BigInt): string;
-- packToSolidityProof(fullProof: IProof): object;
-- createTree(depth: number, zeroValue: number | BigInt, leavesPerNode: number): IncrementalQuinTree;
-- verifyProof(vKey: string, fullProof: IProof): Promise<boolean>;
-- signMsg(privKey: EddsaPrivateKey, msg: bigint | string): EdDSASignature;
-- verifySignature(msg: bigint, signature: EdDSASignature, pubKey: EddsaPublicKey): boolean;
-```
-
-#### OrdinarySemaphore (inherits BaseSemaphore)
-
-```typescript
-- genIdentityCommitment(identity: Identity): bigint;
-- genProofFromIdentityCommitments(identity: Identity, 
-        externalNullifier: string, 
-        signal: string,
-        wasmFilePath: string, 
-        finalZkeyPath: string, 
-        identityCommitments: Array<BigInt>, 
-        depth: number, zeroValue: BigInt, 
-        leavesPerNode: number): Promise<IWitnessData>;
-- genProofFromBuiltTree(identity: Identity, signal: string, merkleProof: any, externalNullifier: string, 
-        wasmFilePath: string, finalZkeyPath: string): Promise<IProof>;
-```
-
-#### FastSempahore (inherits BaseSemaphore)
-
-```typescript
-- genIdentityCommitment(identity: Identity): bigint;
-- genProofFromIdentityCommitments(identity: Identity, 
-        externalNullifier: string | bigint, 
-        signal: string, 
-        wasmFilePath: string, 
-        finalZkeyPath: string, 
-        identityCommitments: Array<BigInt>, 
-        depth: number, zeroValue: BigInt, 
-        leavesPerNode: number): Promise<IWitnessData>
-- genProofFromBuiltTree(identity: Identity, merkleProof: any, externalNullifier: string | bigint, signal: string, 
-        wasmFilePath: string, finalZkeyPath: string): Promise<IProof>;
-```
-
-
-
-#### RLN (inherits BaseSemaphore)
-
-```typescript
-- calculateIdentitySecret(privateKey: Buffer): bigint;
-- calculateA1(privateKey: Buffer, epoch: string): bigint;
-- calculateY(a1:bigint, privateKey: Buffer, signalHash: bigint): bigint;
-- genNullifier(a1: bigint): bigint;
-- retrievePrivateKey(x1: bigint, x2:bigint, y1:bigint, y2:bigint): bigint;
-- genIdentityCommitment(privateKey: Buffer): bigint;
-- genProofFromIdentityCommitments(privateKey: Buffer, 
-        epoch: string | bigint, 
-        signal: string, 
-        wasmFilePath: string, 
-        finalZkeyPath: string, 
-        identityCommitments: Array<BigInt>, 
-        depth: number, zeroValue: BigInt, 
-        leavesPerNode: number): Promise<IWitnessData>;
-- genProofFromBuiltTree(privateKey: Buffer, merkleProof: any, epoch: string | bigint, signal: string, 
-        wasmFilePath: string, finalZkeyPath: string): Promise<IProof>;
-```
+Please refer to the [identity](https://github.com/appliedzkp/libsemaphore/tree/master/packages/identity)and [protocols](https://github.com/appliedzkp/libsemaphore/tree/master/packages/protocols) packages accordingly for installation and usage instructions. The packages also provide tests which can be used as a guide for interaction.

packages/protocols/src/rln.ts

@@ -34,8 +34,8 @@ class Rln extends ZkProtocol {
      * @param x signal hash
      * @returns y & slashing nullfier
      */
-    calculateOutput(identitySecret: bigint, epoch: string, rlnIdentifier: bigint, x: bigint): Array<bigint> {
-        const a1: bigint = poseidonHash([identitySecret, BigInt(epoch), rlnIdentifier]);
+    calculateOutput(identitySecret: bigint, epoch: bigint, rlnIdentifier: bigint, x: bigint): Array<bigint> {
+        const a1: bigint = poseidonHash([identitySecret, epoch, rlnIdentifier]);
         const y: bigint = Fq.normalize(a1 * x + identitySecret);
         const nullifier = this.genNullifier(a1, rlnIdentifier);
         return [y, nullifier]

packages/protocols/tests/rln.test.ts

@@ -59,7 +59,7 @@ describe("Rln", () => {
             const merkleProof: MerkleProof = generateMerkleProof(15, BigInt(0), 2, commitments, identityCommitment);
             const witness: IProof = Rln.genWitness(secretHash, merkleProof, epoch, signal, rlnIdentifier);
 
-            const [y, nullifier] = Rln.calculateOutput(secretHash, epoch, rlnIdentifier, signalHash);
+            const [y, nullifier] = Rln.calculateOutput(secretHash, BigInt(epoch), rlnIdentifier, signalHash);
             const publicSignals = [y, merkleProof.root, nullifier, signalHash, epoch, rlnIdentifier];
 
             const vkeyPath: string = path.join('./zkeyFiles', 'rln', 'verification_key.json');
@@ -86,8 +86,8 @@ describe("Rln", () => {
             const epoch: string = genExternalNullifier('test-epoch');
             const rlnIdentifier: bigint = Rln.genIdentifier();
 
-            const [y1] = Rln.calculateOutput(secretHash, epoch, rlnIdentifier, signalHash1);
-            const [y2] = Rln.calculateOutput(secretHash, epoch, rlnIdentifier, signalHash2);
+            const [y1] = Rln.calculateOutput(secretHash, BigInt(epoch), rlnIdentifier, signalHash1);
+            const [y2] = Rln.calculateOutput(secretHash, BigInt(epoch), rlnIdentifier, signalHash2);
 
             const retrievedSecret: bigint = Rln.retrieveSecret(signalHash1, signalHash2, y1, y2);