ISemaphore

Title: ISemaphore

Authors: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80), Modified from Semaphore (https://github.com/semaphore-protocol/semaphore)

External interface for the Semaphore anonymous-membership / signaling module. Members join a group (a Poseidon incremental Merkle tree of identity commitments) and later prove membership in zero knowledge while broadcasting a message under a scope — without revealing which member they are. A per-(group) nullifier prevents the same identity from signaling twice in a scope.

Wraps the audited Semaphore v4 Groth16 verifier (called via setVerifier). Group membership uses the shared incremental Merkle tree (Poseidon LeanIMT) with a recent-root history, so a proof built against a slightly stale root still validates.

Functions

createGroup

Creates a new group administered by the caller.

function createGroup() external returns (uint256 groupId);

Returns

Name	Type	Description
groupId	`uint256`	The new group id.

createGroup

Creates a new group administered by admin.

function createGroup(address admin) external returns (uint256 groupId);

Parameters

Name	Type	Description
admin	`address`	The group admin (may add members).

Returns

Name	Type	Description
groupId	`uint256`	The new group id.

addMember

Adds a member (identity commitment) to a group. Only the group admin.

function addMember(uint256 groupId, uint256 identityCommitment) external;

Parameters

Name	Type	Description
groupId	`uint256`	The group id.
identityCommitment	`uint256`	The member's identity commitment.

addMembers

Adds many members to a group. Only the group admin.

function addMembers(uint256 groupId, uint256[] calldata identityCommitments) external;

Parameters

Name	Type	Description
groupId	`uint256`	The group id.
identityCommitments	`uint256[]`	The members' identity commitments, in order.

validateProof

Validates a proof against a group and consumes its nullifier (state-changing).

Reverts if the group/depth/root/nullifier checks fail or the proof is invalid.

function validateProof(uint256 groupId, SemaphoreProof calldata proof) external;

Parameters

Name	Type	Description
groupId	`uint256`	The group id.
proof	`SemaphoreProof`	The Semaphore proof.

verifyProof

Verifies a proof against a group WITHOUT consuming the nullifier.

function verifyProof(uint256 groupId, SemaphoreProof calldata proof) external view returns (bool);

Parameters

Name	Type	Description
groupId	`uint256`	The group id.
proof	`SemaphoreProof`	The Semaphore proof.

Returns

Name	Type	Description
<none>	`bool`	True iff the proof is valid for the group.

setVerifier

Sets the Semaphore verifier contract. Gated on the default admin role.

function setVerifier(address verifier) external;

Parameters

Name	Type	Description
verifier	`address`	The `ISemaphoreVerifier` address.

groupCount

Returns the number of groups created.

function groupCount() external view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

groupAdmin

Returns the admin of groupId.

function groupAdmin(uint256 groupId) external view returns (address);

Parameters

Name	Type	Description
groupId	`uint256`

Returns

Name	Type	Description
<none>	`address`

getMerkleTreeRoot

Returns the current Merkle root of groupId.

function getMerkleTreeRoot(uint256 groupId) external view returns (uint256);

Parameters

Name	Type	Description
groupId	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

getMerkleTreeSize

Returns the number of members in groupId.

function getMerkleTreeSize(uint256 groupId) external view returns (uint256);

Parameters

Name	Type	Description
groupId	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

hasMember

Returns whether identityCommitment is a member of groupId.

function hasMember(uint256 groupId, uint256 identityCommitment) external view returns (bool);

Parameters

Name	Type	Description
groupId	`uint256`
identityCommitment	`uint256`

Returns

Name	Type	Description
<none>	`bool`

verifier

Returns the configured Semaphore verifier address.

function verifier() external view returns (address);

Returns

Name	Type	Description
<none>	`address`

Events

GroupCreated

Emitted when a group is created.

event GroupCreated(uint256 indexed groupId, address indexed admin);

Parameters

Name	Type	Description
groupId	`uint256`
admin	`address`

MemberAdded

Emitted when a member is added to a group.

event MemberAdded(uint256 indexed groupId, uint256 index, uint256 identityCommitment, uint256 merkleTreeRoot);

Parameters

Name	Type	Description
groupId	`uint256`
index	`uint256`
identityCommitment	`uint256`
merkleTreeRoot	`uint256`

ProofValidated

Emitted when a proof is validated against a group.

event ProofValidated(
        uint256 indexed groupId,
        uint256 merkleTreeDepth,
        uint256 indexed merkleTreeRoot,
        uint256 nullifier,
        uint256 message,
        uint256 indexed scope,
        uint256[8] points
    );

Parameters

Name	Type	Description
groupId	`uint256`
merkleTreeDepth	`uint256`
merkleTreeRoot	`uint256`
nullifier	`uint256`
message	`uint256`
scope	`uint256`
points	`uint256[8]`

VerifierUpdated

Emitted when the Semaphore verifier address is set.

event VerifierUpdated(address verifier);

Parameters

Name	Type	Description
verifier	`address`

Errors

SemaphoreGroupDoesNotExist

Thrown when operating on a group that does not exist.

error SemaphoreGroupDoesNotExist();

SemaphoreCallerIsNotGroupAdmin

Thrown when the caller is not the group admin.

error SemaphoreCallerIsNotGroupAdmin();

SemaphoreGroupHasNoMembers

Thrown when validating a proof against a group with no members.

error SemaphoreGroupHasNoMembers();

SemaphoreMerkleTreeDepthUnsupported

Thrown when the proof's Merkle tree depth is outside the supported range (1..32).

error SemaphoreMerkleTreeDepthUnsupported();

SemaphoreMerkleTreeRootNotInGroup

Thrown when the proof's Merkle root is not a current or recent root of the group.

error SemaphoreMerkleTreeRootNotInGroup();

SemaphoreNullifierAlreadyUsed

Thrown when the proof's nullifier was already used in the group.

error SemaphoreNullifierAlreadyUsed();

SemaphoreInvalidProof

Thrown when proof verification fails.

error SemaphoreInvalidProof();

SemaphoreVerifierNotSet

Thrown when the verifier address has not been set.

error SemaphoreVerifierNotSet();

SemaphoreVerifierIsZero

Thrown when setting the verifier to the zero address.

error SemaphoreVerifierIsZero();

Structs

SemaphoreProof

A Semaphore proof.

struct SemaphoreProof {
        uint256 merkleTreeDepth;
        uint256 merkleTreeRoot;
        uint256 nullifier;
        uint256 message;
        uint256 scope;
        uint256[8] points;
    }

Properties

Name	Type	Description
merkleTreeDepth	`uint256`	The depth of the tree the proof was generated against (1..32).
merkleTreeRoot	`uint256`	The group Merkle root the proof was generated against.
nullifier	`uint256`	The scope nullifier (prevents double-signaling within a scope).
message	`uint256`	The signaled message.
scope	`uint256`	The scope the proof is bound to.
points	`uint256[8]`	The Groth16 proof points (`pA`, `pB`, `pC` flattened to 8 words).