Skip to content

v3.0.0
Compare
Choose a tag to compare
@cedoor cedoor released this 26 Jan 22:02
· 1139 commits to main since this release
v3.0.0
1bb57ca

Changelog

🚀 New Features

Semaphore CLI

Your Semaphore project can now be created with a simple command-line tool. For more information see the README file of our package or try our new Quick Setup in our documentation. Currently it can be used to create a project with Hardhat and Semaphore contracts (cli-template-hardhat) but we plan to integrate new templates (e.g. Foundry template).

By @cedoor in #191, #220, #228

Semaphore Hardhat plugin

The Hardhat plugin for Semaphore can be used to deploy the Semaphore.sol contract with a simple Hardhat task. For more information see the README file of our package.

By @cedoor in #140

🐛 Bug Fixes

Editor’s entity may be overwritten (V-SEM-VUL-003)

If an entity’s editor is overwritten, that entity would no longer be able to add or remove whistleblowers in the future. A malicious actor could therefore use createEntity to disrupt the expected operation of the contract.

For more information see the Github issue or read the Veridise report below.

By @cedoor in #199 (bug found by Veridise)

merkleRootDuration cannot be changed (V-SEM-VUL-007)

The admin might not know an appropriate value for the merkleRootDuration and may like to change it if the the initial value is inconvenient. In addition, under certain circumstances a poorly chosen value could cause verifyProof to fail.

For more information see the Github issue or read the Veridise report below.

by @cedoor in #208 (bug found by Veridise)

Infinite loop if input array is too large (V-SEM-VUL-006)

If an admin adds more than 255 members, the infinite loop will consume all of the transaction’s gas and then revert. This therefore can waste a user’s funds.

For more information see the Github issue or read the Veridise report below.

by @cedoor in #205 (bug found by Veridise)

Different checks used to determine if group exists (V-SEM-VUL-010)

In the unlikely scenario that the group exists and the root hash is 0, legitimate verify, update, and remove transactions would get rejected until the root hash changes.

For more information see the Github issue or read the Veridise report below.

by @cedoor in #206 (bug found by Veridise)

No zero value validation (V-SEM-VUL-001)

First, this value allows the creator of a group guaranteed access to the group. In certain circumstances this may be undesired (for example if the admin is not the group creator such as if the admin is a DAO that votes on who to add/remove or if an admin is changed) as the original creator has a permanent method of influencing the application that uses the groups. There are similar methods an admin (who might not be the group creator) can use without the zeroValue but these (1) are more visible as adding members is a matter of public record and (2) can be undone by removing the user.

Second, if common values such as 0 are repeatedly used and the identity commitment of this value is eventually compromised, such a user would be able to gain membership to all groups that use this value as the zeroValue.

For more information see the Github issue or read the Veridise report below.

By @cedoor in #197 (bug found by Veridise)

Minor bug fixes

  • No version range for snarkjs and poseidon-lite dependencies by @cedoor in #226
  • Fix/add ts suppress error comment by @vplasencia in #223
  • Merkle roots for any tree update by @cedoor in #167

♻️ Refactoring

One Verifier to rule them all

The old SemaphoreCore.sol contract allowed zero-knowledge proofs to be verified using 17 other Verifier.sol contracts, each of which contained the same functions but with different parameters generated according to the depth of the Merkle tree. The new SemaphoreVerifier.sol contract contains the same functions and an array of parameters that differ in the Verifier.sol contracts, thus not duplicating the code and reducing the number of lines of code by about 3800. Deploying Semaphore contracts on other networks therefore becomes extremely cheaper.

By @cedoor in #166, #168

New Poseidon library

@semaphore-protocol/identity now uses poseidon-lite, a stripped down Poseidon implementation pulled from circomlibjs v0.0.8. This made it possible to drastically reduce code previously imported from the circomlibjs library that was not actually used.

By @cedoor in #173 (thanks to @vimwitch)

Minor changes

  • Public merkleTree attribute and new method name by @cedoor in #163
  • Remove modifiers from proof verification functions by @cedoor in #164
  • New hash function to normalize signal & external nullifier by @cedoor in #170
  • No SNARK restrictions for Group IDs by @cedoor in #180
  • New hash function to generate identity secrets by @cedoor in #194
  • Migrate from hardhat-waffle to hardhat-chai-matchers by @cedoor in #195
  • Update circuits' nLevels comment by @cedoor in #204
  • General refactoring and additional documentation to contracts by @cedoor in #210
  • Arbitrum subgraph by @cedoor in #231

Migration

Some functions of the contracts and JavaScript libraries have been revised to make the dev experience smoother. Below are details of the changes to simplify your migration from v2.6.1 to v3.

@semaphore-protocol/contracts

SemaphoreVerifier.sol

The old Verifier contracts and the SemaphoreCore.sol contract were replaced by a single SemaphoreVerifier.sol contract, which contains a single external function to verify proofs. The old verifier parameter (the verifier contract address) was replaced by merkleTreeDepth.

- _verifyProof(signal, merkleTreeRoot, nullifierHash, externalNullifier, proof, verifier);
+ verifier.verifyProof(merkleTreeRoot, nullifierHash, signal, externalNullifier, proof, merkleTreeDepth);

SemaphoreGroups.sol

The zero value required for the Merkle trees of groups is now created internally based on the group id.

- _createGroup(groupId, merkleTreeDepth);
+ _createGroup(groupId, merkleTreeDepth, zeroValue);

Semaphore.sol

According to the new SemaphoreVerifier.sol contract, the constructor of Semaphore.sol only needs one address now.

- constructor(Verifier[] memory _verifiers) {
-   for (uint8 i = 0; i < _verifiers.length; ) {
-     verifiers[_verifiers[i].merkleTreeDepth] = IVerifier(_verifiers[i].contractAddress);
-
-     unchecked {
-       ++i;
-     }
-   }
- } 
+ constructor(ISemaphoreVerifier _verifier) {
+   verifier = _verifier;
+ }

According to the new SemaphoreGroups.sol contract, the createGroup function only needs three or four parameters now.

- createGroup(groupId, merkleTreeDepth, admin);
+ createGroup(groupId, merkleTreeDepth, zeroValue, admin);
- createGroup(groupId, merkleTreeDepth, admin, merkleTreeDuration);
+ createGroup(groupId, merkleTreeDepth, zeroValue, admin, merkleTreeDuration);

@semaphore-protocol/identity

Get the identity commitment

The identity commitment is generated in the constructor of the class, so that it is immediately available as an accessor property together with trapdoor a nullifier.

import { Identity } from "@semaphore-protocol/identity"
import { Group } from "@semaphore-protocol/group"

const identity = new Identity()
const group = new Group(1)

- group.addMember(identity.generateCommitment())
+ group.addMember(identity.commitment)

@semaphore-protocol/group

Create a group

The constructor parameters of the Group class are in accordance with the parameters of the createGroup function of the Semaphore.sol contract. The first parameter is the group id (required), and the second is the depth of the Merkle tree (optional). The zero value, as in Semaphore.sol, is created internally and is the Keccak hash of the group id.

import { Group } from "@semaphore-protocol/group"

const groupId = 1

- const group = new Group()
+ const group = new Group(groupId)

@semaphore-protocol/proof

Generate/Verify a proof

It is no longer necessary to call the packToSolidityProof function, the proof generated with the generateProof function (i.e. fullProof.proof) can be verified by both on-chain and off-chain verifier functions now.

import { generateProof } from "@semaphore-protocol/proof"

const fullProof = await generateProof(
  identity,
  group,
  externalNullifier,
  signal,
  {
    zkeyFilePath: "./semaphore.zkey",
    wasmFilePath: "./semaphore.wasm",
  }
)

- const solidityProof = packToSolidityProof(fullProof.proof)

The outuput of generateProof has been revised so that it contains exactly the parameters needed for the verifier functions (the on-chain one also requires the group id).

- fullProof.publicSignals.merkleTreeRoot
- fullProof.publicSignals.nullifierHash
- fullProof.publicSignals.signalHash
- fullProof.publicSignals.externalNullifier
- solidityProof
+ fullProof.merkleTreeRoot
+ fullProof.nullifierHash
+ fullProof.signal
+ fullProof.externalNullifier
+ fullProof.proof

Also, the function to verify off-chain proofs does not need any JSON file, but only the proof and the depth of the tree.

import { verifyProof } from "@semaphore-protocol/proof"
 
- const verificationKey = JSON.parse(fs.readFileSync("/semaphore.json", "utf-8"))
- 
- await verifyProof(verificationKey, fullProof)
+ await verifyProof(fullProof, 20)

Audit

Semaphore v3 was formally audited and verified by our friends at Veridise. You can read the full report here: Veridise Auditing Report - Semaphore version 3.0.

Contributors

chancehudson, cedoor, and vplasencia
Assets 2
Loading
0 Join discussion