@coordination-network/contracts 0.0.1

package/NetworkMemberGroup.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+import { Ownable2Step } from "@openzeppelin/contracts/access/Ownable2Step.sol";
+import { ISemaphore } from "@semaphore-protocol/contracts/interfaces/ISemaphore.sol";
+import { ISemaphoreGroups } from "@semaphore-protocol/contracts/interfaces/ISemaphoreGroups.sol";
+
+/// @title NetworkMemberGroup
+/// @notice The Semaphore group of approved network members. Owns nothing but the membership: who a
+/// member is lives in the NetworkMemberRegistry, and the group is created here at deployment.
+/// @dev The group is created on the Semaphore deployment in this contract's constructor, with this
+/// contract as its admin, so membership can only ever change through the two governance-gated calls
+/// below. The owner is the governance Safe, which makes a quorum of approved network members the
+/// only party that can add or remove a member.
+///
+/// Everything about the group beyond membership belongs to Semaphore: the tree, the root history and
+/// its duration, proof verification, and the nullifier set. Consumers that gate on membership read
+/// the group by id from the Semaphore deployment and never need this contract, which is why {GROUP_ID}
+/// and {SEMAPHORE} are public.
+contract NetworkMemberGroup is Ownable2Step {
+    /// @notice The Semaphore deployment holding the group.
+    ISemaphore public immutable SEMAPHORE;
+
+    /// @notice The approved-network-member group, created at deployment.
+    uint256 public immutable GROUP_ID;
+
+    event NetworkMemberAdded(uint256 identityCommitment);
+    event NetworkMemberRemoved(uint256 identityCommitment);
+
+    /// @param semaphore The Semaphore deployment to create the group on.
+    /// @param governance The governance Safe. It becomes the owner, and the sole writer.
+    constructor(ISemaphore semaphore, address governance) Ownable(governance) {
+        SEMAPHORE = semaphore;
+        GROUP_ID = semaphore.createGroup(address(this));
+    }
+
+    /// @notice Adds an approved network member's Semaphore identity commitment to the group.
+    /// @dev Callable only by the governance Safe, so a member joins the group under the same quorum
+    /// that admitted it to the registry. Semaphore rejects a zero commitment, one outside the SNARK
+    /// scalar field, and a duplicate.
+    /// @param identityCommitment The member's Semaphore identity commitment.
+    function addNetworkMember(uint256 identityCommitment) external onlyOwner {
+        SEMAPHORE.addMember(GROUP_ID, identityCommitment);
+
+        emit NetworkMemberAdded(identityCommitment);
+    }
+
+    /// @notice Removes a network member's commitment from the group.
+    /// @param identityCommitment The commitment to remove.
+    /// @param merkleProofSiblings The sibling nodes proving the commitment is in the group, computed
+    /// off chain against the group state this transaction will execute in.
+    function removeNetworkMember(uint256 identityCommitment, uint256[] calldata merkleProofSiblings)
+        external
+        onlyOwner
+    {
+        SEMAPHORE.removeMember(GROUP_ID, identityCommitment, merkleProofSiblings);
+
+        emit NetworkMemberRemoved(identityCommitment);
+    }
+
+    /// @notice Whether a commitment is currently in the group.
+    /// @param identityCommitment The commitment to look up.
+    /// @return True if the commitment is a member.
+    function hasNetworkMember(uint256 identityCommitment) external view returns (bool) {
+        return ISemaphoreGroups(address(SEMAPHORE)).hasMember(GROUP_ID, identityCommitment);
+    }
+
+    /// @notice The group's current Merkle root, the value a membership proof is checked against.
+    /// @return The current root.
+    function merkleTreeRoot() external view returns (uint256) {
+        return ISemaphoreGroups(address(SEMAPHORE)).getMerkleTreeRoot(GROUP_ID);
+    }
+}

package/NetworkMemberRegistry.sol

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+import { Ownable2Step } from "@openzeppelin/contracts/access/Ownable2Step.sol";
+import { IApprovedIssuerSet } from "./interfaces/IApprovedIssuerSet.sol";
+
+/// @title NetworkMemberRegistry
+/// @notice Holds network member state: who is approved, and each member's keys.
+/// @dev Governance. The owner is the governance Safe, a multisig of the governing members, and it
+/// is the only writer of the approved-network-member set: nothing here lets a single operator admit
+/// or remove a member. Joining is permissionless in the request direction and
+/// governed in the admission direction:
+///
+///  1. a prospective member calls {requestToJoin} itself, which stores nothing and only emits
+///     {NetworkMemberJoinRequested}. Already-approved members watch that event off chain;
+///  2. enough of them sign a Safe transaction calling {approveNetworkMember} to meet the Safe's
+///     threshold, and the Safe executes it.
+///
+/// Admission is three calls the Safe batches into one transaction, because the state that defines an
+/// approved network member lives in three places: the record here, the member's leaf in the Semaphore
+/// group NetworkMemberGroup administers, and the member's governance signer in the Safe's own owner
+/// set. Batching them means a member is never approved without its group leaf, and never an approver
+/// without being a member. This contract records which keys belong to which member; it holds neither
+/// the group nor the owner set.
+///
+/// The onboarding procedure is in `docs/network-member-onboarding.md`.
+contract NetworkMemberRegistry is Ownable2Step {
+    uint256 public constant META_STEALTH_ADDRESS_LENGTH = 66;
+
+    /// @notice The address that maintains a network member's record. Initialised from the networkId
+    mapping(bytes32 memberNetworkId => address authAddress) public networkMemberAuthAddress;
+
+    /// @notice The network member networkId => meta-stealth address mapping.
+    /// Network members resolve here, not in the IdentityRegistry.
+    mapping(bytes32 memberNetworkId => bytes metaStealthAddress) public identity;
+
+    /// @notice The network member's Semaphore identity commitment, its leaf in the approved-member
+    /// group NetworkMemberGroup administers.
+    mapping(bytes32 memberNetworkId => uint256 semaphoreCommitment) public semaphoreCommitmentOf;
+
+    /// @notice The network member's governance signer: the address that votes for it as an owner of
+    /// the governance Safe. Recorded here so a removal can find the owner to drop without replaying
+    /// the member's admission history.
+    mapping(bytes32 memberNetworkId => address governanceSigner) public governanceSignerOf;
+
+    /// @notice The set holding members' credential signing keys. Wired once, after deployment.
+    IApprovedIssuerSet public approvedIssuerSet;
+
+    event NetworkMemberJoinRequested(
+        bytes32 indexed memberNetworkId, uint256 semaphoreCommitment, address governanceSigner, string metadataURI
+    );
+    event NetworkMemberApproved(bytes32 indexed memberNetworkId);
+    event NetworkMemberRemoved(bytes32 indexed memberNetworkId);
+    event NetworkMemberIdentityRegistered(bytes32 indexed memberNetworkId, bytes metaStealthAddress);
+    event GovernanceSignerPublished(bytes32 indexed memberNetworkId, address indexed governanceSigner);
+    event ApprovedIssuerSetWired(address indexed approvedIssuerSet);
+
+    error AlreadyApproved(bytes32 memberNetworkId);
+    error NotApproved(bytes32 memberNetworkId);
+    error InvalidMetaStealthAddressLength();
+    error UnauthorizedCaller();
+    error ZeroGovernanceSigner();
+    error ZeroSemaphoreCommitment();
+    error GovernanceSignerIsAuthAddress();
+    error ZeroApprovedIssuerSet();
+    error ApprovedIssuerSetAlreadyWired();
+    error ApprovedIssuerSetNotBoundToThisRegistry();
+    error IssuerSetNotWired();
+
+    /// @dev Restricts a network member record write to the network member's current auth address,
+    /// or to governance.
+    /// @param memberNetworkId The network member whose record is being written.
+    modifier onlyAuthAddressOrGovernance(bytes32 memberNetworkId) {
+        _onlyAuthAddressOrGovernance(memberNetworkId);
+        _;
+    }
+
+    function _onlyAuthAddressOrGovernance(bytes32 memberNetworkId) internal view {
+        if (msg.sender != networkMemberAuthAddress[memberNetworkId] && msg.sender != owner()) {
+            revert UnauthorizedCaller();
+        }
+    }
+
+    /// @param governance The governance Safe. It becomes the owner, and the sole approver.
+    constructor(address governance) Ownable(governance) { }
+
+    /// @notice Whether a network member is currently approved.
+    /// @param memberNetworkId The network member's networkId.
+    /// @return True if the network member is approved.
+    function isApproved(bytes32 memberNetworkId) external view returns (bool) {
+        return networkMemberAuthAddress[memberNetworkId] != address(0);
+    }
+
+    /// @notice Asks the approved network members to admit `memberNetworkId`. Permissionless, and
+    /// callable by anyone holding the key behind the networkId.
+    /// @dev Stores nothing and confers nothing. It is the announcement half of the join flow: the
+    /// approved members watch this event, and admission happens only if enough of them sign the
+    /// governance Safe transaction that calls {approveNetworkMember}. The caller must be the auth
+    /// address the networkId encodes, so nobody can post a request on another member's behalf.
+    /// @param memberNetworkId The networkId asking to join.
+    /// @param semaphoreCommitment The Semaphore identity commitment the requester wants in the group.
+    /// @param governanceSigner The address the requester wants added to the governance Safe, so it can
+    /// vote on later candidates. Must differ from the auth address: the auth address is a hot key that
+    /// signs routine record writes, and Safe ownership should not sit on a key used that way.
+    /// @param metadataURI Where the approvers can fetch this requester's vetting material. Any URI the
+    /// network has agreed on, and it may be empty. The contract neither reads nor stores it.
+    function requestToJoin(
+        bytes32 memberNetworkId,
+        uint256 semaphoreCommitment,
+        address governanceSigner,
+        string calldata metadataURI
+    ) external {
+        address authAddress = address(uint160(uint256(memberNetworkId)));
+
+        if (msg.sender != authAddress) revert UnauthorizedCaller();
+        if (networkMemberAuthAddress[memberNetworkId] != address(0)) revert AlreadyApproved(memberNetworkId);
+        if (semaphoreCommitment == 0) revert ZeroSemaphoreCommitment();
+        if (governanceSigner == address(0)) revert ZeroGovernanceSigner();
+        if (governanceSigner == authAddress) revert GovernanceSignerIsAuthAddress();
+
+        emit NetworkMemberJoinRequested(memberNetworkId, semaphoreCommitment, governanceSigner, metadataURI);
+    }
+
+    /// @notice Admits a network member to the approved set.
+    /// @dev Callable only by the governance Safe, so admission always carries the signatures of a
+    /// threshold of approved members. Auth address is initialised from the networkId. The companion
+    /// calls in the same Safe transaction are `NetworkMemberGroup.addNetworkMember` and the Safe's own
+    /// `addOwnerWithThreshold`.
+    ///
+    /// Requires the issuer set to already be wired, for the same reason {removeNetworkMember} does:
+    /// without it a member could be admitted into a state {removeNetworkMember} can never remove it
+    /// from, since that function refuses to run while the set is unwired.
+    /// @param memberNetworkId The network member to approve.
+    /// @param semaphoreCommitment The member's Semaphore identity commitment. Must be non-zero, which
+    /// the Semaphore group requires too, so a record cannot hold a commitment the group would refuse.
+    /// @param governanceSigner The member's governance signer, the owner added to the Safe alongside
+    /// this call.
+    function approveNetworkMember(bytes32 memberNetworkId, uint256 semaphoreCommitment, address governanceSigner)
+        external
+        onlyOwner
+    {
+        if (address(approvedIssuerSet) == address(0)) revert IssuerSetNotWired();
+
+        address authAddress = address(uint160(uint256(memberNetworkId)));
+
+        if (networkMemberAuthAddress[memberNetworkId] != address(0)) revert AlreadyApproved(memberNetworkId);
+        if (semaphoreCommitment == 0) revert ZeroSemaphoreCommitment();
+        if (governanceSigner == address(0)) revert ZeroGovernanceSigner();
+        if (governanceSigner == authAddress) revert GovernanceSignerIsAuthAddress();
+
+        networkMemberAuthAddress[memberNetworkId] = authAddress;
+        semaphoreCommitmentOf[memberNetworkId] = semaphoreCommitment;
+        governanceSignerOf[memberNetworkId] = governanceSigner;
+
+        emit NetworkMemberApproved(memberNetworkId);
+        emit GovernanceSignerPublished(memberNetworkId, governanceSigner);
+    }
+
+    /// @notice Wires the approved-issuer set. Callable once.
+    /// @dev Deliberately not a constructor argument: the set needs this registry's address, so the
+    /// registry has to exist first.
+    /// @param newApprovedIssuerSet The set this registry retires keys in when it removes a member.
+    function setApprovedIssuerSet(address newApprovedIssuerSet) external onlyOwner {
+        if (address(approvedIssuerSet) != address(0)) revert ApprovedIssuerSetAlreadyWired();
+        if (newApprovedIssuerSet == address(0)) revert ZeroApprovedIssuerSet();
+
+        // The set only answers its own registry, and this write cannot be redone. Wiring one built
+        // against a different registry would make every removal revert, with no way to rewire.
+        if (IApprovedIssuerSet(newApprovedIssuerSet).memberRegistry() != address(this)) {
+            revert ApprovedIssuerSetNotBoundToThisRegistry();
+        }
+
+        approvedIssuerSet = IApprovedIssuerSet(newApprovedIssuerSet);
+        emit ApprovedIssuerSetWired(newApprovedIssuerSet);
+    }
+
+    /// @notice Removes a network member and retires every signing key it published.
+    /// @dev The companion calls in the same Safe transaction are
+    /// `NetworkMemberGroup.removeNetworkMember` and the Safe's own `removeOwner`.
+    ///
+    /// Both halves happen here so they cannot come apart. Removing a member while leaving its key in
+    /// the set would let it keep signing credentials that verify, and nothing detects that: a
+    /// verifier cannot attribute a credential to a member. Reverting while the set is unwired is the
+    /// safe direction, since the alternative is removing members without disarming their keys.
+    /// @param memberNetworkId The network member to remove.
+    function removeNetworkMember(bytes32 memberNetworkId) external onlyOwner {
+        if (networkMemberAuthAddress[memberNetworkId] == address(0)) revert NotApproved(memberNetworkId);
+
+        IApprovedIssuerSet issuerSet = approvedIssuerSet;
+        if (address(issuerSet) == address(0)) revert IssuerSetNotWired();
+
+        delete networkMemberAuthAddress[memberNetworkId];
+        delete identity[memberNetworkId];
+        delete semaphoreCommitmentOf[memberNetworkId];
+        delete governanceSignerOf[memberNetworkId];
+
+        emit NetworkMemberRemoved(memberNetworkId);
+
+        issuerSet.retireAllIssuerKeys(memberNetworkId);
+    }
+
+    /// @notice Sets a network member's meta-stealth address. Callable by the network member's auth
+    /// address or by governance.
+    /// @param memberNetworkId The network member whose identity is being set.
+    /// @param newMetaStealthAddress The ERC-6538 meta-stealth address to store. Must be 66 bytes.
+    function registerNetworkMemberIdentity(bytes32 memberNetworkId, bytes calldata newMetaStealthAddress)
+        external
+        onlyAuthAddressOrGovernance(memberNetworkId)
+    {
+        if (networkMemberAuthAddress[memberNetworkId] == address(0)) revert NotApproved(memberNetworkId);
+        if (newMetaStealthAddress.length != META_STEALTH_ADDRESS_LENGTH) revert InvalidMetaStealthAddressLength();
+
+        identity[memberNetworkId] = newMetaStealthAddress;
+        emit NetworkMemberIdentityRegistered(memberNetworkId, newMetaStealthAddress);
+    }
+}

package/README.md

@@ -0,0 +1,92 @@
+# @coordination-network/contracts
+
+The coordination network's core contracts.
+
+- `NetworkMemberRegistry`: the approved-network-member set, and each member's identity, Semaphore
+  commitment, credential signing key and governance signer. Member information only.
+- `NetworkMemberGroup`: the Semaphore group of approved members, created on the Semaphore deployment
+  at construction and administered by this contract.
+- `NetworkMemberGovernance`: the orchestrator. One call per governance operation (admit, remove, exit),
+  callable only by the Safe and enabled as a Safe module. It computes the majority threshold itself, so
+  no caller can carry a wrong one, and it refuses to shrink the member set to nobody.
+- `IdentityRegistry`: resolves a self-sovereign user's networkId to its meta-stealth address.
+- `CredentialRevocationRegistry`: the network's one revocation registry. A single tree for every
+  revoked credential, whoever issued it, held on a standalone [`Revocation`](revocation/README.md)
+  deployment.
+- `ApprovedIssuerSet`: the issuer set the credential circuit proves against.
+- `SemaphorePaymaster`: an ERC-4337 paymaster that sponsors a user operation against a Semaphore
+  membership proof.
+- `ERC5564Announcer`: the stealth-address announcement contract.
+
+The [revocation registries](revocation/README.md) ship in this package too: `CredentialRevocationRegistry`
+imports them directly.
+
+The governance Safe is the sole writer of the first two, and admission requires a majority of the
+current members: admitting one adds its governance signer to the Safe, so the network governs itself.
+See the
+[network member onboarding and governance runbook](https://github.com/zk-kit/coordination-network/blob/main/packages/contracts/docs/network-member-onboarding.md).
+
+Deploy all three with the governance Safe as their owner, then enable the orchestrator as a Safe module
+with a quorum:
+
+```shell
+GOVERNANCE_SAFE=0x<safe> SEMAPHORE=0x<semaphore> \
+  forge script script/DeployNetworkMemberRegistry.s.sol --rpc-url <rpc> --broadcast
+```
+
+## Installation
+
+```shell
+yarn add @coordination-network/contracts
+```
+
+```solidity
+import { IdentityRegistry } from "@coordination-network/contracts/IdentityRegistry.sol";
+```
+
+## Who can write to the IdentityRegistry
+
+Reads are public and ungated. Every write, `registerIdentity`, `updateIdentity` and `removeIdentity`, is authorised by a Semaphore membership proof against the approved-member group, bound to the exact update it carries. No address-based write path remains: nothing reads `msg.sender`, there is no owner or allowlist path into the identity mapping, and there is no emergency override. Fixing a bad row means a member submitting a corrective `updateIdentity` or `removeIdentity`, which is itself anonymous and auditable. Governance's only power over the registry is over group membership, and while the group is empty no write can succeed.
+
+## Why revocation is one registry
+
+The credential circuit hides which approved issuer signed a credential and outputs the root it proved non-membership against. A verifier then asks a registry whether that root is current, so picking which registry to ask would name the issuer. `CredentialRevocationRegistry.isValidRoot(root)` takes the root alone.
+
+The same holds off chain: with per-issuer registries, which tree a holder syncs leaks its issuer to whoever serves the snapshot.
+
+The one thing to design around is write contention. Every mutation takes the predecessor index of the affected leaf, valid only against the tree state the transaction executes in, so two members revoking in the same block collide and one reverts. In order of preference: batch with `revokeMany`, have the issuer service send revocations one at a time, or recompute the index and resubmit. A resubmit reuses the same proof, since the message does not bind the index and a revert does not burn the nullifier.
+
+## The first revocation
+
+The tree starts empty with root `0`, and the circuit canonicalises an empty-registry witness to `0`, so `isValidRoot(0)` holds and presentations verify from the first block.
+
+A replaced root keeps working for a grace window: the service stamps the moment it stopped being current and accepts it for `rootDuration` (one hour) after that, so a proof built moments before a revocation still verifies. The zero root is the exception, because the stamp lives in a mapping where `0` already means "not a past root".
+
+So the first revocation invalidates empty-tree proofs with no window at all:
+
+| Time     | Event                                                        | `isValidRoot`                |
+| -------- | ------------------------------------------------------------ | ---------------------------- |
+| 10:00:00 | a holder syncs the empty tree and proves against root `0`    | `0` accepted, it is current  |
+| 10:00:05 | the first revocation lands, root becomes `R1`, `0` unstamped | `0` rejected immediately     |
+| 11:00:00 | another holder syncs and proves against `R1`                 | `R1` accepted, it is current |
+| 11:00:05 | the second revocation lands, root becomes `R2`               | `R1` accepted until 12:00:05 |
+
+Same race, opposite outcome. It can only bite once, around the transaction that takes the tree from empty to non-empty, and anyone caught re-syncs and re-proves.
+
+Revoking one unused commitment at deployment avoids it. A commitment is `Poseidon2(revocationPubX, revocationPubY)`, so a value like `1` cannot collide with a real credential. The tree is then never empty and no proof is ever built against root `0`.
+
+## The approved-member group
+
+`NetworkMemberGate` is only the gate. It does not create the group, admit members or hold any membership state: it is pointed at an existing Semaphore group by id at construction, and stores it in `NETWORK_MEMBER_GROUP_ID`. Creating that group and administering it are governance concerns, done on the Semaphore deployment itself and tracked separately. Everything about the proof lifecycle is likewise Semaphore's:
+
+- Governance, as the group admin, maintains the set on the Semaphore contract: `addMember`, `addMembers`, `removeMember`, `updateMember`.
+- The recent-root window is the group's Merkle tree duration, one hour by default, so a proof built just before a membership change still lands. A removal therefore bites at `removal time + one hour`.
+- `validateProof` records the proof's nullifier, so the same proof cannot be submitted twice. Clients pick a fresh random scope per proof, which makes each nullifier unlinkable from the last and leaves members unrate-limited.
+
+What the gate adds is the binding, and it is structural rather than a check: the Semaphore message is never accepted from the caller. `NetworkMemberGate.NetworkMemberProof` is Semaphore's proof minus its message, and the `onlyNetworkMember(message, proof)` modifier fills that field in with the message the gated function derives from its own arguments. A proof repurposed for another payload therefore fails verification outright; there is no message field for an attacker to line up, and no comparison a future gated function could forget.
+
+The message is `keccak256(UPDATE_DOMAIN_SEPARATOR, chainId, action, networkId, metaStealthAddress)`, where the separator is `keccak256(domain string, address(this))` hashed once at deployment. The payload is what stops a proof authorising a different update; the separator and the chain id place that update at one deployment. Both matter precisely because the registry does not own its group: two registries can be pointed at the same group id, and one registry can exist at the same address on two chains with the same members and therefore the same root, so without them a proof meant for one would authorise the other.
+
+## Tests
+
+The gated-path tests verify real Semaphore proofs against a real `Semaphore` deployment. The proofs are checked in at `test/fixtures/network-member-proofs.json` and `test/fixtures/credential-revocation-proofs.json`, regenerated with `yarn workspace @coordination-network/network-member-proof generate:fixtures` and `generate:revocation-fixtures`. Every proof binds the chain id and the contract address, so the tests pin that chain id and deploy to that address.

package/SemaphorePaymaster.sol

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { IEntryPoint } from "@account-abstraction/contracts/interfaces/IEntryPoint.sol";
+import { BasePaymaster } from "@account-abstraction/contracts/core/BasePaymaster.sol";
+import { IPaymaster } from "@account-abstraction/contracts/interfaces/IPaymaster.sol";
+import { PackedUserOperation } from "@account-abstraction/contracts/interfaces/PackedUserOperation.sol";
+import { _packValidationData } from "@account-abstraction/contracts/core/Helpers.sol";
+import { UserOperationLib } from "@account-abstraction/contracts/core/UserOperationLib.sol";
+import { Semaphore } from "@semaphore-protocol/contracts/Semaphore.sol";
+import { ISemaphore } from "@semaphore-protocol/contracts/interfaces/ISemaphore.sol";
+import { ISemaphoreVerifier } from "@semaphore-protocol/contracts/interfaces/ISemaphoreVerifier.sol";
+import { MIN_DEPTH, MAX_DEPTH } from "@semaphore-protocol/contracts/base/Constants.sol";
+
+/**
+ * @title SemaphorePaymaster
+ * @notice A paymaster that validates user operations in a privacy preserving way using a single semaphore group
+ */
+contract SemaphorePaymaster is BasePaymaster, Semaphore {
+    using UserOperationLib for PackedUserOperation;
+
+    /**
+     * The paymaster uses a single Semaphore group
+     */
+    uint256 public immutable GROUP_ID;
+
+    /**
+     * `ISemaphore.SemaphoreProof` has a fixed length: five initial fields & exactly eight points
+     */
+    uint256 private constant ENCODED_PROOF_LENGTH = 13 * 32;
+
+    /**
+     * Sponsorship stops for the rest of the epoch once spend reaches this cap, bounding what a
+     * stolen identity can drain before the owner can revoke or withdraw
+     */
+    uint256 public immutable SPEND_CAP_PER_EPOCH;
+    uint256 public immutable EPOCH_DURATION;
+
+    /**
+     * Smaller than epoch cap, so exhausting the cap takes many userOps rather than one.
+     * `preVerificationGas` is self declared and never refunded, so `maxCost` can be used to drain the paymaster
+     */
+    uint256 public immutable MAX_COST_PER_OP;
+
+    /**
+     * Enough for `_postOp` to record spend. The EntryPoint charges the paymaster even when `postOp`
+     * runs out of gas, so validation requires the limit up front
+     */
+    uint256 public constant MIN_POSTOP_GAS = 40_000;
+
+    /**
+     * Validation cannot read `block.timestamp` (banned by ERC-7562), so the epoch lives in
+     * storage and is advanced by `updateEpoch`
+     */
+    uint256 public currentEpoch;
+
+    mapping(uint256 epoch => uint256 spent) public spentInEpoch;
+
+    error ZeroOwner();
+
+    constructor(
+        address _entryPoint,
+        address _verifier,
+        address _owner,
+        uint256 _spendCapPerEpoch,
+        uint256 _epochDuration,
+        uint256 _maxCostPerOp
+    ) BasePaymaster(IEntryPoint(_entryPoint)) Semaphore(ISemaphoreVerifier(_verifier)) {
+        SPEND_CAP_PER_EPOCH = _spendCapPerEpoch;
+        EPOCH_DURATION = _epochDuration;
+        MAX_COST_PER_OP = _maxCostPerOp;
+        currentEpoch = block.timestamp / _epochDuration;
+
+        // _transferOwnership skips zero-address guard
+        if (_owner == address(0)) revert ZeroOwner();
+
+        // BasePaymaster calls Ownable(msg.sender) — we want to set our own owner.
+        _transferOwnership(_owner);
+
+        // same logic as Semaphore.sol function `function createGroup(address) external;`
+        GROUP_ID = groupCounter++;
+        _createGroup(GROUP_ID, _owner);
+        groups[GROUP_ID].merkleTreeDuration = 1 hours;
+    }
+
+    /**
+     * Validate a user operation by verifying a Semaphore proof.
+     * @dev  Call `verifier.verifyProof` directly to avoid banned `block.timestamp` opcode
+     * @param userOp        - The user operation.
+     * @param // userOpHash - The hash of the user operation.
+     * @param maxCost       - The maximum cost of the user operation.
+     */
+    function _validatePaymasterUserOp(
+        PackedUserOperation calldata userOp,
+        bytes32,
+        /* userOpHash */
+        uint256 maxCost
+    )
+        internal
+        view
+        override
+        returns (bytes memory context, uint256 validationData)
+    {
+        if (maxCost > MAX_COST_PER_OP || spentInEpoch[currentEpoch] + maxCost > SPEND_CAP_PER_EPOCH) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        if (userOp.unpackPostOpGasLimit() < MIN_POSTOP_GAS) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        bytes calldata encodedProof = userOp.paymasterAndData[PAYMASTER_DATA_OFFSET:];
+        if (encodedProof.length != ENCODED_PROOF_LENGTH) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        ISemaphore.SemaphoreProof memory proof = abi.decode(encodedProof, (ISemaphore.SemaphoreProof));
+
+        // message & scope must be the sender address. message binds the proof to the account
+        // being sponsored. scope does the same, and ensures Semaphore nullifiers are unique per
+        // account, since nullifier = hash(scope, secret) — a stable scope would link
+        // multiple stealth accounts to a single semaphore identity.
+        uint256 expectedSender = uint256(uint160(userOp.sender));
+        if (proof.message != expectedSender || proof.scope != expectedSender) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        // Validation will fail if the Merkle tree depth is not supported.
+        if (proof.merkleTreeDepth < MIN_DEPTH || proof.merkleTreeDepth > MAX_DEPTH) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        // Gets the number of leaves in the Incremental Merkle Tree that represents the group
+        // with id groupId which is the same as the number of members in the group groupId.
+        uint256 merkleTreeSize = getMerkleTreeSize(GROUP_ID);
+
+        // Validation will fail if there are no members in the group.
+        if (merkleTreeSize == 0) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        // A superseded root is valid until its `merkleTreeDuration` window ends, so this becomes
+        // userOp validUntil.
+        uint48 validUntil = 0;
+
+        // Gets the Merkle root of the Incremental Merkle Tree that represents the group with id groupId.
+        uint256 currentMerkleTreeRoot = getMerkleTreeRoot(GROUP_ID);
+
+        // A proof could have used an old Merkle tree root.
+        // https://github.com/semaphore-protocol/semaphore/issues/98
+        if (proof.merkleTreeRoot != currentMerkleTreeRoot) {
+            uint256 merkleRootCreationDate = groups[GROUP_ID].merkleRootCreationDates[proof.merkleTreeRoot];
+            uint256 merkleTreeDuration = groups[GROUP_ID].merkleTreeDuration;
+
+            if (merkleRootCreationDate == 0) {
+                return ("", _packValidationData(true, 0, 0));
+            }
+
+            // merkleRootCreationDate is block.timestamp. Overflow would require owner
+            // setting very high merkleTreeDuration
+            // forge-lint: disable-next-line(unsafe-typecast)
+            validUntil = uint48(merkleRootCreationDate + merkleTreeDuration);
+        }
+
+        // Call `verifier.verifyProof` directly. `this.verifyProof` reads `block.timestamp` when the
+        // proof `merkleTreeRoot` does not match `currentMerkleTreeRoot`, which ERC-7562 bans.
+        bool verified = verifier.verifyProof(
+            [proof.points[0], proof.points[1]],
+            [[proof.points[2], proof.points[3]], [proof.points[4], proof.points[5]]],
+            [proof.points[6], proof.points[7]],
+            [proof.merkleTreeRoot, proof.nullifier, _hashToField(proof.message), _hashToField(proof.scope)],
+            proof.merkleTreeDepth
+        );
+        if (!verified) {
+            return ("", _packValidationData(true, 0, 0));
+        }
+
+        // a non empty context is what makes the EntryPoint call `postOp`
+        return (hex"01", _packValidationData(false, validUntil, 0));
+    }
+
+    function _postOp(IPaymaster.PostOpMode, bytes calldata, uint256 actualGasCost, uint256) internal override {
+        updateEpoch();
+        spentInEpoch[currentEpoch] += actualGasCost;
+    }
+
+    /**
+     * Advance to the current epoch, freeing the spend cap again.
+     */
+    function updateEpoch() public {
+        currentEpoch = block.timestamp / EPOCH_DURATION;
+    }
+
+    /**
+     * Same logic as `Semaphore.sol`'s `_hash`, which is private so cannot be called here.
+     */
+    function _hashToField(uint256 message) private pure returns (uint256) {
+        return uint256(keccak256(abi.encodePacked(message))) >> 8;
+    }
+}

package/base/NetworkMemberGate.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { ISemaphore } from "@semaphore-protocol/contracts/interfaces/ISemaphore.sol";
+
+/// @title NetworkMemberGate
+/// @notice Gates functions on an anonymous Semaphore membership proof from an approved network
+/// member, bound to the call it authorises.
+/// @dev A gated call learns that it came from some approved network member and nothing else. Nothing
+/// here reads `msg.sender`, so the call can be submitted from a stealth address and relayed by a
+/// paymaster.
+///
+/// This contract is only the gate. It does not create the approved-member group, admit members,
+/// remove them or hold any membership state: the group is created and administered on the Semaphore
+/// deployment itself, by governance, and this contract is pointed at it by id at construction.
+/// Everything about the proof lifecycle is likewise Semaphore's: membership, the recent-root window
+/// (the group's Merkle tree duration) and the nullifier set that stops a proof being submitted
+/// twice.
+///
+/// What the gate adds is the binding: the Semaphore message is not accepted from the caller at all,
+/// it is derived from the gated call's own arguments, so a proof authorises exactly one call and a
+/// proof repurposed for another payload simply fails verification.
+abstract contract NetworkMemberGate {
+    /// @notice A membership proof authorising one call.
+    /// @dev Semaphore's proof without its message field. The message is the one public signal the
+    /// caller does not supply, because the gated function derives it.
+    struct NetworkMemberProof {
+        uint256 merkleTreeDepth;
+        uint256 merkleTreeRoot;
+        uint256 nullifier;
+        uint256 scope;
+        uint256[8] points;
+    }
+
+    /// @notice The Semaphore deployment holding the approved-member group.
+    ISemaphore public immutable SEMAPHORE;
+
+    /// @notice The approved-member group this contract gates on.
+    uint256 public immutable NETWORK_MEMBER_GROUP_ID;
+
+    /// @dev Gates a function on a membership proof over `message`. The message is derived from the
+    /// call's own arguments, so the expression passed here is evaluated before the proof is checked.
+    /// @param message The call the proof must authorise.
+    /// @param proof The network member's Semaphore proof.
+    modifier onlyNetworkMember(uint256 message, NetworkMemberProof calldata proof) {
+        _validateNetworkMemberProof(message, proof);
+        _;
+    }
+
+    /// @param semaphore The Semaphore deployment holding the approved-member group.
+    /// @param networkMemberGroupId The group to gate on. It must already exist, and governance must
+    /// be its admin; creating it and maintaining its membership happen outside this contract.
+    constructor(ISemaphore semaphore, uint256 networkMemberGroupId) {
+        SEMAPHORE = semaphore;
+        NETWORK_MEMBER_GROUP_ID = networkMemberGroupId;
+    }
+
+    /// @dev Hands the proof to Semaphore with `message` as its message, which verifies membership
+    /// against a live root of the group and burns the nullifier so the proof cannot be submitted
+    /// again. A proof generated for a different call carries a different message and fails
+    /// verification here.
+    /// @param message The call the proof must authorise.
+    /// @param proof The network member's Semaphore proof.
+    function _validateNetworkMemberProof(uint256 message, NetworkMemberProof calldata proof) internal {
+        SEMAPHORE.validateProof(
+            NETWORK_MEMBER_GROUP_ID,
+            ISemaphore.SemaphoreProof({
+                merkleTreeDepth: proof.merkleTreeDepth,
+                merkleTreeRoot: proof.merkleTreeRoot,
+                nullifier: proof.nullifier,
+                message: message,
+                scope: proof.scope,
+                points: proof.points
+            })
+        );
+    }
+}