DOCSEARCHbyAlgolia
Submit Docs

Semaphore V4

website·Indexed 35 days ago

https://docs.semaphore.pse.dev

A zero-knowledge protocol for anonymous group membership and signaling that allows users to prove membership without revealing their identity.

Tokens
1.2K
Snippets
6
Records
9
Agent score
17%

What's inside Semaphore

  1. Overview of Semaphore V4 Core Concepts

    Semaphore is a zero-knowledge protocol that allows users to cast messages (such as votes or endorsements) as provable group members without revealing their specific identity. It includes built-in double-signaling prevention.

    Key components include:

    • Identity: A user's cryptographic identity consisting of a private key, public key, and commitment.
    • Group: A Merkle tree containing identity commitments.
    • Proof: A zero-knowledge proof that a user is a member of a group and is sending a specific message.
    • Nullifier: A unique identifier that prevents a user from signaling multiple times within the same scope.
    • Scope: A topic or context that limits a user to one proof per scope.

  2. Install Semaphore V4 packages

    Install the core functionality package or specific individual packages depending on your needs.
    # Core functionality
npm install @semaphore-protocol/core

# Individual packages
npm install @semaphore-protocol/identity
npm install @semaphore-protocol/group  
npm install @semaphore-protocol/proof
npm install @semaphore-protocol/contracts

  3. Configure Semaphore circuit parameters

    When configuring the Semaphore circuit, consider the following parameters and security constraints:

    • MAX_DEPTH: Merkle tree depth must be between 1 and 32.
    • Default proof validity: Old Merkle roots are valid for 1 hour.
    • Identity Reuse: Using the same identity across different groups compromises the anonymity of all those groups.
    • Nullifier Uniqueness: Ensures a user cannot signal multiple times within the same scope.
    • Message Tampering: The circuit uses a dummy square calculation to prevent message tampering.

  4. Troubleshoot Semaphore proof and identity errors

    Common issues when working with Semaphore:

    • "Proof verification failed": Ensure the group contains the identity commitment, the scope matches exactly between generation and verification, and the Merkle proof is within the validity window.
    • "Nullifier already exists": This occurs when a user has already submitted a proof for the current scope. Use a different scope or implement nullifier tracking.
    • "Identity commitment not found": Ensure the identity was added to the group before generating the proof and that the correct group is being referenced.

  5. Generate and verify zero-knowledge proofs

    Use the @semaphore-protocol/proof package to generate a proof of membership for a specific message and scope, and to verify that proof.
    import { generateProof, verifyProof } from "@semaphore-protocol/proof"

// Generate proof
const scope = group.root // or any unique scope
const message = 1
const proof = await generateProof(identity, group, message, scope)

// Verify proof
const isValid = await verifyProof(proof)

  6. Manage cryptographic identities in Semaphore

    Use the @semaphore-protocol/identity package to create random or deterministic identities, sign/verify messages, and export/import identity data.
    import { Identity } from "@semaphore-protocol/identity"

// Random identity
const identity = new Identity()
const { privateKey, publicKey, commitment } = identity

// Deterministic identity (from secret)
const deterministicIdentity = new Identity("secret-value")

// Sign/verify messages
const message = "Hello World"
const signature = identity.signMessage(message)
const isValid = Identity.verifySignature(message, signature, identity.publicKey)

// Export/import
const exported = identity.export() // base64 private key
const imported = Identity.import(exported)

  7. Perform group operations and generate Merkle proofs

    Use the @semaphore-protocol/group package to create groups, manage members (add, remove, update), and generate Merkle proofs for specific members.
    import { Group } from "@semaphore-protocol/group"

// Create group
const group = new Group()
const groupWithMembers = new Group([commitment1, commitment2])

// Manage members
group.addMember(identity.commitment)
group.addMembers([commitment1, commitment2])
group.removeMember(0) // sets to 0, doesn't change size
group.updateMember(0, newCommitment)

// Generate Merkle proof
const merkleProof = group.generateMerkleProof(0)

  8. Use Semaphore CLI for project initialization and deployment

    Use the Semaphore CLI to scaffold new projects, fetch on-chain group data, and deploy contracts.
    # Create new project
npx @semaphore-protocol/cli create my-app --template monorepo-ethers

# Get on-chain groups
semaphore get-groups --network sepolia

# Deploy contract
yarn deploy --semaphore <address> --group <id> --network sepolia

  9. Integrate Semaphore proof validation in Solidity

    Integrate Semaphore into a smart contract by using the ISemaphore interface to create groups and validate proofs on-chain.
    // Contract setup
import "@semaphore-protocol/contracts/interfaces/ISemaphore.sol";

contract YourContract {
    ISemaphore public semaphore;
    uint256 public groupId;

    constructor(ISemaphore _semaphore) {
        semaphore = _semaphore;
        groupId = semaphore.createGroup();
    }

    // Validate proof on-chain
    function validateProof(ISemaphore.SemaphoreProof calldata proof) external {
        semaphore.validateProof(groupId, proof);
    }
}