From 70e5358a794b1bed8ebdbcbff7e4d40e3d66fa12 Mon Sep 17 00:00:00 2001 From: bdim1 Date: Wed, 20 Oct 2021 23:36:10 +0200 Subject: [PATCH] README.md updates & inconsistencies fix --- README.md | 89 +++------------------------- packages/protocols/src/rln.ts | 4 +- packages/protocols/tests/rln.test.ts | 6 +- 3 files changed, 12 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index d501200..54e42df 100644 --- a/README.md +++ b/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; -- 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, - depth: number, zeroValue: BigInt, - leavesPerNode: number): Promise; -- genProofFromBuiltTree(identity: Identity, signal: string, merkleProof: any, externalNullifier: string, - wasmFilePath: string, finalZkeyPath: string): Promise; -``` - -#### FastSempahore (inherits BaseSemaphore) - -```typescript -- genIdentityCommitment(identity: Identity): bigint; -- genProofFromIdentityCommitments(identity: Identity, - externalNullifier: string | bigint, - signal: string, - wasmFilePath: string, - finalZkeyPath: string, - identityCommitments: Array, - depth: number, zeroValue: BigInt, - leavesPerNode: number): Promise -- genProofFromBuiltTree(identity: Identity, merkleProof: any, externalNullifier: string | bigint, signal: string, - wasmFilePath: string, finalZkeyPath: string): Promise; -``` - - - -#### 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, - depth: number, zeroValue: BigInt, - leavesPerNode: number): Promise; -- genProofFromBuiltTree(privateKey: Buffer, merkleProof: any, epoch: string | bigint, signal: string, - wasmFilePath: string, finalZkeyPath: string): Promise; -``` \ No newline at end of file +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. diff --git a/packages/protocols/src/rln.ts b/packages/protocols/src/rln.ts index 131b065..40c4f0b 100644 --- a/packages/protocols/src/rln.ts +++ b/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 { - const a1: bigint = poseidonHash([identitySecret, BigInt(epoch), rlnIdentifier]); + calculateOutput(identitySecret: bigint, epoch: bigint, rlnIdentifier: bigint, x: bigint): Array { + const a1: bigint = poseidonHash([identitySecret, epoch, rlnIdentifier]); const y: bigint = Fq.normalize(a1 * x + identitySecret); const nullifier = this.genNullifier(a1, rlnIdentifier); return [y, nullifier] diff --git a/packages/protocols/tests/rln.test.ts b/packages/protocols/tests/rln.test.ts index 8a84f1f..36b01d2 100644 --- a/packages/protocols/tests/rln.test.ts +++ b/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);