@coordination-network/network-member-proof 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @coordination-network/network-member-proof
+
+Generates the zero-knowledge proof that authorises an Identity Registry write as an approved network member.
+
+The registry keeps no allowlist of member addresses. Authorisation is a Semaphore membership proof against the approved-member group, and every mutating function takes one: `registerIdentity`, `updateIdentity`, `removeIdentity`. What the chain learns is "an approved member made this change". It does not learn which one, and because no write path reads `msg.sender`, it learns nothing from the sending account either: submit from a fresh stealth address, with a paymaster paying, and the write is unlinkable to you.
+
+**Scope.** This package does one thing: turn an identity, a group and an intended update into a proof the registry accepts. Creating a member identity, admitting members and mirroring the group from chain state are onboarding and governance concerns, handled separately. `generateSemaphoreProof` takes Semaphore's own `Identity` and `Group` as given.
+
+## What the proof commits to
+
+- **The message is the update itself.** `updateMessage()` hashes the action (register, update, remove), the `networkId`, the meta-stealth address, the registry address and the chain id. You do not submit it: the proof struct the registry takes has no message field, and the registry fills it in with the message it derives from the payload you passed. So a proof for "register A" submitted with the "register B" payload fails verification, and the registry address and chain id keep it from being usable at another deployment, including one sharing the same Semaphore group. `generateSemaphoreProof` handles the derivation; `updateMessage` is exported for anyone verifying a proof off chain, which does need it.
+- **The scope is random, once per proof.** A Semaphore nullifier is `poseidon(secret, scope)`, so a fresh scope means a fresh nullifier: your updates do not link to each other, and there is no per-member rate limit. Semaphore still records every nullifier it has seen for the group, which is what makes resubmitting the same proof revert. Leave `scope` alone unless you have a reason not to; `randomScope()` is what the default uses.
+
+## Usage
+
+```ts
+import { Group, Identity } from "@semaphore-protocol/core"
+import { generateSemaphoreProof, UpdateAction } from "@coordination-network/network-member-proof"
+
+const identity = Identity.import(process.env.MEMBER_IDENTITY!)
+
+// The approved-member group as the registry's Semaphore group currently holds it, rebuilt from its
+// on-chain membership events.
+const group = new Group([123n, identity.commitment])
+
+const proof = await generateSemaphoreProof({
+    identity,
+    group,
+    registry: { chainId: 11155111n, address: "0x..." },
+    update: {
+        action: UpdateAction.Register,
+        networkId: "0x...",
+        metaStealthAddress: "0x..." // 66 bytes, ERC-6538 scheme 1
+    }
+})
+
+// registerIdentity(networkId, metaStealthAddress, proof)
+```
+
+Submit it from wherever you like. The proof is the authorisation; the sender is not.
+
+Two things to get right before submitting:
+
+- **The group must match the chain.** A stale mirror produces a proof against an old root, which Semaphore accepts only inside the recent-root window below. Note that a removal leaves a zero leaf in place rather than compacting the tree, so a mirror has to replay the membership history rather than collect the current commitments.
+- **The payload must match the proof.** Submit the exact `networkId` and meta-stealth address you passed to `generateSemaphoreProof`. Anything else reverts `Semaphore__InvalidProof`, because the registry will be verifying against the message for the payload you actually sent.
+
+## The recent-root window
+
+Membership changes move the group root, and a proof generated a moment earlier is against the old one. Semaphore accepts a superseded root for the group's Merkle tree duration, one hour by default, so in-flight proofs are not lost every time governance admits a member.
+
+The cost is the mirror image: a removed member's already-generated proof stays usable until that root expires. Governance removing a member for cause should treat the removal as effective at `removal time + one hour`. After that the ex-member has no live root left to prove against and cannot build a proof against the current one, because their leaf is gone.
+
+## Regenerating the Solidity fixtures
+
+The contract tests verify real proofs, produced here and checked in at `packages/contracts/test/fixtures/network-member-proofs.json`. Regenerate them after any change to the message derivation:
+
+```sh
+yarn workspace @coordination-network/network-member-proof generate:fixtures
+```
+
+The fixtures pin the chain id and the registry address the proofs are bound to, and use fixed scopes so they are reproducible; the Solidity test base deploys the registry to that address.

package/dist/index.cjs

@@ -0,0 +1,189 @@
+'use strict';
+
+var viem = require('viem');
+var proof = require('@semaphore-protocol/proof');
+
+/** Which mutation of the IdentityRegistry a proof authorises. Matches the on-chain enum. */
+exports.UpdateAction = void 0;
+(function (UpdateAction) {
+    UpdateAction[UpdateAction["Register"] = 0] = "Register";
+    UpdateAction[UpdateAction["Update"] = 1] = "Update";
+    UpdateAction[UpdateAction["Remove"] = 2] = "Remove";
+})(exports.UpdateAction || (exports.UpdateAction = {}));
+/** Which mutation of the CredentialRevocationRegistry a proof authorises. Matches the on-chain enum. */
+exports.RevocationAction = void 0;
+(function (RevocationAction) {
+    RevocationAction[RevocationAction["Revoke"] = 0] = "Revoke";
+    RevocationAction[RevocationAction["RevokeMany"] = 1] = "RevokeMany";
+    RevocationAction[RevocationAction["Unrevoke"] = 2] = "Unrevoke";
+    RevocationAction[RevocationAction["UpdateCommitment"] = 3] = "UpdateCommitment";
+})(exports.RevocationAction || (exports.RevocationAction = {}));
+
+/** Domain string in the registry's `UPDATE_DOMAIN_SEPARATOR`. */
+const UPDATE_MESSAGE_DOMAIN = "coordination-network.identity-registry.update.v1";
+/** Empty meta-stealth address, the placeholder a removal binds. */
+const NO_META_STEALTH_ADDRESS = "0x";
+/**
+ * The constant half of an update message, mirroring the registry's `UPDATE_DOMAIN_SEPARATOR`. The
+ * registry hashes it once at deployment, so a client can also read it from there.
+ */
+function updateDomainSeparator(registryAddress) {
+    return viem.keccak256(viem.encodeAbiParameters([{ type: "string" }, { type: "address" }], [UPDATE_MESSAGE_DOMAIN, registryAddress]));
+}
+/**
+ * The Semaphore message binding a proof to one registry update, mirroring the message the registry
+ * derives from the arguments it is about to apply: the payload, the registry and the chain.
+ *
+ * The payload is what stops a proof authorising a different update. The registry address and the
+ * chain id place that update at one deployment: a registry does not own its Semaphore group, so two
+ * registries can share one, and the same registry can exist at the same address on two chains with
+ * the same members and therefore the same root.
+ *
+ * The registry never accepts a message from the caller, so a proof built for the wrong update does
+ * not fail a comparison, it fails verification.
+ */
+function updateMessage(registry, update) {
+    if (update.action === exports.UpdateAction.Remove && update.metaStealthAddress !== undefined) {
+        throw new Error("a removal binds no meta-stealth address");
+    }
+    // Caught here rather than on chain: a proof over the wrong payload costs a full verification to
+    // fail, and the proof took real work to produce.
+    if (update.action !== exports.UpdateAction.Remove && update.metaStealthAddress === undefined) {
+        throw new Error("a registration or update binds a meta-stealth address");
+    }
+    const metaStealthAddress = update.metaStealthAddress ?? NO_META_STEALTH_ADDRESS;
+    return BigInt(viem.keccak256(viem.encodePacked(["bytes32", "uint256", "uint8", "bytes32", "bytes"], [
+        updateDomainSeparator(registry.address),
+        registry.chainId,
+        update.action,
+        update.networkId,
+        metaStealthAddress
+    ])));
+}
+/**
+ * A fresh random scope.
+ *
+ * A Semaphore nullifier is `poseidon(secret, scope)`, so a random scope gives every proof an
+ * unlinkable nullifier: the registry only ever learns that some approved member authorised the
+ * update, never that two updates came from the same one. The registry does not constrain the scope;
+ * what it relies on is that the nullifier a proof carries can only be spent once.
+ */
+function randomScope() {
+    // 31 bytes, so the scope is always a field element. Web Crypto and viem only, so this works
+    // in a browser as well as in Node.
+    const bytes = new Uint8Array(31);
+    crypto.getRandomValues(bytes);
+    return BigInt(viem.bytesToHex(bytes));
+}
+
+/**
+ * Proves membership over an already derived message, in the shape a NetworkMemberGate expects.
+ *
+ * The message is absent from the result: the gated contract derives it from the call's own arguments,
+ * so submitting a proof means submitting the payload it was generated for.
+ */
+async function proveMessage(identity, group, message, scope) {
+    const proof$1 = await proof.generateProof(identity, group, message, scope);
+    return {
+        merkleTreeDepth: BigInt(proof$1.merkleTreeDepth),
+        merkleTreeRoot: BigInt(proof$1.merkleTreeRoot),
+        nullifier: BigInt(proof$1.nullifier),
+        scope: BigInt(proof$1.scope),
+        points: proof$1.points.map(BigInt)
+    };
+}
+
+/** Domain string in the registry's `REVOCATION_DOMAIN_SEPARATOR`. */
+const REVOCATION_MESSAGE_DOMAIN = "coordination-network.credential-revocation-registry.revocation.v1";
+/**
+ * The constant half of a revocation message, mirroring the registry's `REVOCATION_DOMAIN_SEPARATOR`.
+ * The registry hashes it once at deployment, so a client can read it from there instead.
+ */
+function revocationDomainSeparator(registryAddress) {
+    return viem.keccak256(viem.encodeAbiParameters([{ type: "string" }, { type: "address" }], [REVOCATION_MESSAGE_DOMAIN, registryAddress]));
+}
+/**
+ * The message binding a proof to one mutation of the credential revocation registry: the action and
+ * the commitments, at that registry on that chain. It mirrors what the registry derives from the
+ * arguments it applies, so a proof aimed elsewhere fails verification.
+ *
+ * Predecessor indices are absent here as they are on chain. An index is a witness the LeanIMT+
+ * validates, not a privilege, so leaving it unbound lets a member who lost a race recompute it and
+ * resubmit the same proof; a revert does not burn the nullifier.
+ *
+ * `RevokeMany` is a distinct action because a one-commitment batch would otherwise pack identically
+ * to a single revocation.
+ */
+function revocationMessage(registry, update) {
+    switch (update.action) {
+        case exports.RevocationAction.Revoke:
+        case exports.RevocationAction.Unrevoke:
+            return BigInt(viem.keccak256(viem.encodePacked(["bytes32", "uint256", "uint8", "uint256"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                update.revocationCommitment
+            ])));
+        case exports.RevocationAction.RevokeMany:
+            if (update.revocationCommitments.length === 0) {
+                throw new Error("a batch binds at least one commitment");
+            }
+            return BigInt(viem.keccak256(viem.encodePacked(["bytes32", "uint256", "uint8", "uint256[]"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                [...update.revocationCommitments]
+            ])));
+        case exports.RevocationAction.UpdateCommitment:
+            return BigInt(viem.keccak256(viem.encodePacked(["bytes32", "uint256", "uint8", "uint256", "uint256"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                update.oldRevocationCommitment,
+                update.newRevocationCommitment
+            ])));
+        default:
+            throw new Error("unknown revocation action");
+    }
+}
+
+/**
+ * Generates the membership proof that authorises one write to the credential revocation registry.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact revocation,
+ * and nothing else: not which leaf, and not who submits it. Submit it from any address, including a
+ * fresh stealth address with a paymaster covering the gas, since no write path reads `msg.sender`.
+ *
+ * One tree holds the whole network's revocations, so nothing about the write names the issuer either.
+ */
+async function generateRevocationProof({ identity, group, registry, update, scope = randomScope() }) {
+    return proveMessage(identity, group, revocationMessage(registry, update), scope);
+}
+
+/**
+ * Generates the membership proof that authorises one registry update.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact update, and
+ * nothing else: not which leaf, and not who submits it. Submit it from any address, since no write
+ * path reads `msg.sender`.
+ *
+ * `identity` and `group` are Semaphore's own types, taken as given here. Creating a member identity
+ * and maintaining the group are governance and onboarding concerns, not proof generation.
+ *
+ * The message binds the proof to this update at this registry on this chain, so it cannot be
+ * replayed against another payload, and Semaphore burns the nullifier on the way in, so the proof
+ * itself cannot be submitted twice.
+ */
+async function generateSemaphoreProof({ identity, group, registry, update, scope = randomScope() }) {
+    return proveMessage(identity, group, updateMessage(registry, update), scope);
+}
+
+exports.REVOCATION_MESSAGE_DOMAIN = REVOCATION_MESSAGE_DOMAIN;
+exports.UPDATE_MESSAGE_DOMAIN = UPDATE_MESSAGE_DOMAIN;
+exports.generateRevocationProof = generateRevocationProof;
+exports.generateSemaphoreProof = generateSemaphoreProof;
+exports.randomScope = randomScope;
+exports.revocationDomainSeparator = revocationDomainSeparator;
+exports.revocationMessage = revocationMessage;
+exports.updateDomainSeparator = updateDomainSeparator;
+exports.updateMessage = updateMessage;

package/dist/index.js

@@ -0,0 +1,179 @@
+import { bytesToHex, keccak256, encodeAbiParameters, encodePacked } from 'viem';
+import { generateProof } from '@semaphore-protocol/proof';
+
+/** Which mutation of the IdentityRegistry a proof authorises. Matches the on-chain enum. */
+var UpdateAction;
+(function (UpdateAction) {
+    UpdateAction[UpdateAction["Register"] = 0] = "Register";
+    UpdateAction[UpdateAction["Update"] = 1] = "Update";
+    UpdateAction[UpdateAction["Remove"] = 2] = "Remove";
+})(UpdateAction || (UpdateAction = {}));
+/** Which mutation of the CredentialRevocationRegistry a proof authorises. Matches the on-chain enum. */
+var RevocationAction;
+(function (RevocationAction) {
+    RevocationAction[RevocationAction["Revoke"] = 0] = "Revoke";
+    RevocationAction[RevocationAction["RevokeMany"] = 1] = "RevokeMany";
+    RevocationAction[RevocationAction["Unrevoke"] = 2] = "Unrevoke";
+    RevocationAction[RevocationAction["UpdateCommitment"] = 3] = "UpdateCommitment";
+})(RevocationAction || (RevocationAction = {}));
+
+/** Domain string in the registry's `UPDATE_DOMAIN_SEPARATOR`. */
+const UPDATE_MESSAGE_DOMAIN = "coordination-network.identity-registry.update.v1";
+/** Empty meta-stealth address, the placeholder a removal binds. */
+const NO_META_STEALTH_ADDRESS = "0x";
+/**
+ * The constant half of an update message, mirroring the registry's `UPDATE_DOMAIN_SEPARATOR`. The
+ * registry hashes it once at deployment, so a client can also read it from there.
+ */
+function updateDomainSeparator(registryAddress) {
+    return keccak256(encodeAbiParameters([{ type: "string" }, { type: "address" }], [UPDATE_MESSAGE_DOMAIN, registryAddress]));
+}
+/**
+ * The Semaphore message binding a proof to one registry update, mirroring the message the registry
+ * derives from the arguments it is about to apply: the payload, the registry and the chain.
+ *
+ * The payload is what stops a proof authorising a different update. The registry address and the
+ * chain id place that update at one deployment: a registry does not own its Semaphore group, so two
+ * registries can share one, and the same registry can exist at the same address on two chains with
+ * the same members and therefore the same root.
+ *
+ * The registry never accepts a message from the caller, so a proof built for the wrong update does
+ * not fail a comparison, it fails verification.
+ */
+function updateMessage(registry, update) {
+    if (update.action === UpdateAction.Remove && update.metaStealthAddress !== undefined) {
+        throw new Error("a removal binds no meta-stealth address");
+    }
+    // Caught here rather than on chain: a proof over the wrong payload costs a full verification to
+    // fail, and the proof took real work to produce.
+    if (update.action !== UpdateAction.Remove && update.metaStealthAddress === undefined) {
+        throw new Error("a registration or update binds a meta-stealth address");
+    }
+    const metaStealthAddress = update.metaStealthAddress ?? NO_META_STEALTH_ADDRESS;
+    return BigInt(keccak256(encodePacked(["bytes32", "uint256", "uint8", "bytes32", "bytes"], [
+        updateDomainSeparator(registry.address),
+        registry.chainId,
+        update.action,
+        update.networkId,
+        metaStealthAddress
+    ])));
+}
+/**
+ * A fresh random scope.
+ *
+ * A Semaphore nullifier is `poseidon(secret, scope)`, so a random scope gives every proof an
+ * unlinkable nullifier: the registry only ever learns that some approved member authorised the
+ * update, never that two updates came from the same one. The registry does not constrain the scope;
+ * what it relies on is that the nullifier a proof carries can only be spent once.
+ */
+function randomScope() {
+    // 31 bytes, so the scope is always a field element. Web Crypto and viem only, so this works
+    // in a browser as well as in Node.
+    const bytes = new Uint8Array(31);
+    crypto.getRandomValues(bytes);
+    return BigInt(bytesToHex(bytes));
+}
+
+/**
+ * Proves membership over an already derived message, in the shape a NetworkMemberGate expects.
+ *
+ * The message is absent from the result: the gated contract derives it from the call's own arguments,
+ * so submitting a proof means submitting the payload it was generated for.
+ */
+async function proveMessage(identity, group, message, scope) {
+    const proof = await generateProof(identity, group, message, scope);
+    return {
+        merkleTreeDepth: BigInt(proof.merkleTreeDepth),
+        merkleTreeRoot: BigInt(proof.merkleTreeRoot),
+        nullifier: BigInt(proof.nullifier),
+        scope: BigInt(proof.scope),
+        points: proof.points.map(BigInt)
+    };
+}
+
+/** Domain string in the registry's `REVOCATION_DOMAIN_SEPARATOR`. */
+const REVOCATION_MESSAGE_DOMAIN = "coordination-network.credential-revocation-registry.revocation.v1";
+/**
+ * The constant half of a revocation message, mirroring the registry's `REVOCATION_DOMAIN_SEPARATOR`.
+ * The registry hashes it once at deployment, so a client can read it from there instead.
+ */
+function revocationDomainSeparator(registryAddress) {
+    return keccak256(encodeAbiParameters([{ type: "string" }, { type: "address" }], [REVOCATION_MESSAGE_DOMAIN, registryAddress]));
+}
+/**
+ * The message binding a proof to one mutation of the credential revocation registry: the action and
+ * the commitments, at that registry on that chain. It mirrors what the registry derives from the
+ * arguments it applies, so a proof aimed elsewhere fails verification.
+ *
+ * Predecessor indices are absent here as they are on chain. An index is a witness the LeanIMT+
+ * validates, not a privilege, so leaving it unbound lets a member who lost a race recompute it and
+ * resubmit the same proof; a revert does not burn the nullifier.
+ *
+ * `RevokeMany` is a distinct action because a one-commitment batch would otherwise pack identically
+ * to a single revocation.
+ */
+function revocationMessage(registry, update) {
+    switch (update.action) {
+        case RevocationAction.Revoke:
+        case RevocationAction.Unrevoke:
+            return BigInt(keccak256(encodePacked(["bytes32", "uint256", "uint8", "uint256"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                update.revocationCommitment
+            ])));
+        case RevocationAction.RevokeMany:
+            if (update.revocationCommitments.length === 0) {
+                throw new Error("a batch binds at least one commitment");
+            }
+            return BigInt(keccak256(encodePacked(["bytes32", "uint256", "uint8", "uint256[]"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                [...update.revocationCommitments]
+            ])));
+        case RevocationAction.UpdateCommitment:
+            return BigInt(keccak256(encodePacked(["bytes32", "uint256", "uint8", "uint256", "uint256"], [
+                revocationDomainSeparator(registry.address),
+                registry.chainId,
+                update.action,
+                update.oldRevocationCommitment,
+                update.newRevocationCommitment
+            ])));
+        default:
+            throw new Error("unknown revocation action");
+    }
+}
+
+/**
+ * Generates the membership proof that authorises one write to the credential revocation registry.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact revocation,
+ * and nothing else: not which leaf, and not who submits it. Submit it from any address, including a
+ * fresh stealth address with a paymaster covering the gas, since no write path reads `msg.sender`.
+ *
+ * One tree holds the whole network's revocations, so nothing about the write names the issuer either.
+ */
+async function generateRevocationProof({ identity, group, registry, update, scope = randomScope() }) {
+    return proveMessage(identity, group, revocationMessage(registry, update), scope);
+}
+
+/**
+ * Generates the membership proof that authorises one registry update.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact update, and
+ * nothing else: not which leaf, and not who submits it. Submit it from any address, since no write
+ * path reads `msg.sender`.
+ *
+ * `identity` and `group` are Semaphore's own types, taken as given here. Creating a member identity
+ * and maintaining the group are governance and onboarding concerns, not proof generation.
+ *
+ * The message binds the proof to this update at this registry on this chain, so it cannot be
+ * replayed against another payload, and Semaphore burns the nullifier on the way in, so the proof
+ * itself cannot be submitted twice.
+ */
+async function generateSemaphoreProof({ identity, group, registry, update, scope = randomScope() }) {
+    return proveMessage(identity, group, updateMessage(registry, update), scope);
+}
+
+export { REVOCATION_MESSAGE_DOMAIN, RevocationAction, UPDATE_MESSAGE_DOMAIN, UpdateAction, generateRevocationProof, generateSemaphoreProof, randomScope, revocationDomainSeparator, revocationMessage, updateDomainSeparator, updateMessage };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@coordination-network/network-member-proof",
+  "version": "0.0.1",
+  "description": "Generates the Semaphore membership proofs that authorise an IdentityRegistry or CredentialRevocationRegistry write as an approved network member, bound to that exact update.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/network-member-proof"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/network-member-proof",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist types && rollup -c rollup.config.mjs",
+    "generate:fixtures": "tsx tests/generate-fixtures.ts",
+    "generate:revocation-fixtures": "tsx tests/generate-revocation-fixtures.ts"
+  },
+  "dependencies": {
+    "@semaphore-protocol/group": "4.14.3",
+    "@semaphore-protocol/identity": "4.14.3",
+    "@semaphore-protocol/proof": "4.14.3",
+    "viem": "^2.40.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/jest": "^30.0.0",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.0",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/generate-revocation-proof.ts

@@ -0,0 +1,42 @@
+import { Group } from "@semaphore-protocol/group"
+import { Identity } from "@semaphore-protocol/identity"
+import { randomScope } from "./message"
+import { proveMessage } from "./prove"
+import { revocationMessage } from "./revocation-message"
+import { NetworkMemberProof, RegistryLocation, RevocationUpdate } from "./types"
+
+export type GenerateRevocationProofOptions = {
+    /** The network member's Semaphore identity. Its commitment must be a leaf of `group`. */
+    identity: Identity
+    /**
+     * The approved-member group, as the Semaphore contract currently holds it. Rebuild it from the
+     * group's on-chain membership events: a proof against a root the group no longer holds is only
+     * accepted inside the recent-root window.
+     */
+    group: Group
+    /** Where the credential revocation registry is deployed. */
+    registry: RegistryLocation
+    /** The revocation being authorised. */
+    update: RevocationUpdate
+    /** The proof's scope. Defaults to a fresh random one, which is what keeps proofs unlinkable. */
+    scope?: bigint
+}
+
+/**
+ * Generates the membership proof that authorises one write to the credential revocation registry.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact revocation,
+ * and nothing else: not which leaf, and not who submits it. Submit it from any address, including a
+ * fresh stealth address with a paymaster covering the gas, since no write path reads `msg.sender`.
+ *
+ * One tree holds the whole network's revocations, so nothing about the write names the issuer either.
+ */
+export async function generateRevocationProof({
+    identity,
+    group,
+    registry,
+    update,
+    scope = randomScope()
+}: GenerateRevocationProofOptions): Promise<NetworkMemberProof> {
+    return proveMessage(identity, group, revocationMessage(registry, update), scope)
+}

package/src/generate-semaphore-proof.ts

@@ -0,0 +1,46 @@
+import { Group } from "@semaphore-protocol/group"
+import { Identity } from "@semaphore-protocol/identity"
+import { randomScope, updateMessage } from "./message"
+import { proveMessage } from "./prove"
+import { IdentityUpdate, NetworkMemberProof, RegistryLocation } from "./types"
+
+export type GenerateSemaphoreProofOptions = {
+    /** The network member's Semaphore identity. Its commitment must be a leaf of `group`. */
+    identity: Identity
+    /**
+     * The approved-member group, as the registry's Semaphore group currently holds it. Rebuild it
+     * from the group's on-chain membership events: a proof against a root the group no longer holds
+     * is only accepted inside Semaphore's recent-root window.
+     */
+    group: Group
+    /** Where the registry is deployed. */
+    registry: RegistryLocation
+    /** The update being authorised. */
+    update: IdentityUpdate
+    /** The proof's scope. Defaults to a fresh random one, which is what keeps proofs unlinkable. */
+    scope?: bigint
+}
+
+/**
+ * Generates the membership proof that authorises one registry update.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact update, and
+ * nothing else: not which leaf, and not who submits it. Submit it from any address, since no write
+ * path reads `msg.sender`.
+ *
+ * `identity` and `group` are Semaphore's own types, taken as given here. Creating a member identity
+ * and maintaining the group are governance and onboarding concerns, not proof generation.
+ *
+ * The message binds the proof to this update at this registry on this chain, so it cannot be
+ * replayed against another payload, and Semaphore burns the nullifier on the way in, so the proof
+ * itself cannot be submitted twice.
+ */
+export async function generateSemaphoreProof({
+    identity,
+    group,
+    registry,
+    update,
+    scope = randomScope()
+}: GenerateSemaphoreProofOptions): Promise<NetworkMemberProof> {
+    return proveMessage(identity, group, updateMessage(registry, update), scope)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { generateRevocationProof } from "./generate-revocation-proof"
+export type { GenerateRevocationProofOptions } from "./generate-revocation-proof"
+export { generateSemaphoreProof } from "./generate-semaphore-proof"
+export type { GenerateSemaphoreProofOptions } from "./generate-semaphore-proof"
+export { UPDATE_MESSAGE_DOMAIN, randomScope, updateDomainSeparator, updateMessage } from "./message"
+export { REVOCATION_MESSAGE_DOMAIN, revocationDomainSeparator, revocationMessage } from "./revocation-message"
+export { RevocationAction, UpdateAction } from "./types"
+export type { IdentityUpdate, NetworkMemberProof, RegistryLocation, RevocationUpdate } from "./types"

package/src/message.ts

@@ -0,0 +1,76 @@
+import { bytesToHex, encodeAbiParameters, encodePacked, keccak256 } from "viem"
+import { IdentityUpdate, RegistryLocation, UpdateAction } from "./types"
+
+/** Domain string in the registry's `UPDATE_DOMAIN_SEPARATOR`. */
+export const UPDATE_MESSAGE_DOMAIN = "coordination-network.identity-registry.update.v1"
+
+/** Empty meta-stealth address, the placeholder a removal binds. */
+const NO_META_STEALTH_ADDRESS = "0x" as const
+
+/**
+ * The constant half of an update message, mirroring the registry's `UPDATE_DOMAIN_SEPARATOR`. The
+ * registry hashes it once at deployment, so a client can also read it from there.
+ */
+export function updateDomainSeparator(registryAddress: `0x${string}`): `0x${string}` {
+    return keccak256(
+        encodeAbiParameters([{ type: "string" }, { type: "address" }], [UPDATE_MESSAGE_DOMAIN, registryAddress])
+    )
+}
+
+/**
+ * The Semaphore message binding a proof to one registry update, mirroring the message the registry
+ * derives from the arguments it is about to apply: the payload, the registry and the chain.
+ *
+ * The payload is what stops a proof authorising a different update. The registry address and the
+ * chain id place that update at one deployment: a registry does not own its Semaphore group, so two
+ * registries can share one, and the same registry can exist at the same address on two chains with
+ * the same members and therefore the same root.
+ *
+ * The registry never accepts a message from the caller, so a proof built for the wrong update does
+ * not fail a comparison, it fails verification.
+ */
+export function updateMessage(registry: RegistryLocation, update: IdentityUpdate): bigint {
+    if (update.action === UpdateAction.Remove && update.metaStealthAddress !== undefined) {
+        throw new Error("a removal binds no meta-stealth address")
+    }
+
+    // Caught here rather than on chain: a proof over the wrong payload costs a full verification to
+    // fail, and the proof took real work to produce.
+    if (update.action !== UpdateAction.Remove && update.metaStealthAddress === undefined) {
+        throw new Error("a registration or update binds a meta-stealth address")
+    }
+
+    const metaStealthAddress = update.metaStealthAddress ?? NO_META_STEALTH_ADDRESS
+
+    return BigInt(
+        keccak256(
+            encodePacked(
+                ["bytes32", "uint256", "uint8", "bytes32", "bytes"],
+                [
+                    updateDomainSeparator(registry.address),
+                    registry.chainId,
+                    update.action,
+                    update.networkId,
+                    metaStealthAddress
+                ]
+            )
+        )
+    )
+}
+
+/**
+ * A fresh random scope.
+ *
+ * A Semaphore nullifier is `poseidon(secret, scope)`, so a random scope gives every proof an
+ * unlinkable nullifier: the registry only ever learns that some approved member authorised the
+ * update, never that two updates came from the same one. The registry does not constrain the scope;
+ * what it relies on is that the nullifier a proof carries can only be spent once.
+ */
+export function randomScope(): bigint {
+    // 31 bytes, so the scope is always a field element. Web Crypto and viem only, so this works
+    // in a browser as well as in Node.
+    const bytes = new Uint8Array(31)
+    crypto.getRandomValues(bytes)
+
+    return BigInt(bytesToHex(bytes))
+}

package/src/prove.ts

@@ -0,0 +1,27 @@
+import { Group } from "@semaphore-protocol/group"
+import { Identity } from "@semaphore-protocol/identity"
+import { generateProof } from "@semaphore-protocol/proof"
+import { NetworkMemberProof } from "./types"
+
+/**
+ * Proves membership over an already derived message, in the shape a NetworkMemberGate expects.
+ *
+ * The message is absent from the result: the gated contract derives it from the call's own arguments,
+ * so submitting a proof means submitting the payload it was generated for.
+ */
+export async function proveMessage(
+    identity: Identity,
+    group: Group,
+    message: bigint,
+    scope: bigint
+): Promise<NetworkMemberProof> {
+    const proof = await generateProof(identity, group, message, scope)
+
+    return {
+        merkleTreeDepth: BigInt(proof.merkleTreeDepth),
+        merkleTreeRoot: BigInt(proof.merkleTreeRoot),
+        nullifier: BigInt(proof.nullifier),
+        scope: BigInt(proof.scope),
+        points: proof.points.map(BigInt) as unknown as NetworkMemberProof["points"]
+    }
+}

package/src/revocation-message.ts

@@ -0,0 +1,82 @@
+import { encodeAbiParameters, encodePacked, keccak256 } from "viem"
+import { RegistryLocation, RevocationAction, RevocationUpdate } from "./types"
+
+/** Domain string in the registry's `REVOCATION_DOMAIN_SEPARATOR`. */
+export const REVOCATION_MESSAGE_DOMAIN = "coordination-network.credential-revocation-registry.revocation.v1"
+
+/**
+ * The constant half of a revocation message, mirroring the registry's `REVOCATION_DOMAIN_SEPARATOR`.
+ * The registry hashes it once at deployment, so a client can read it from there instead.
+ */
+export function revocationDomainSeparator(registryAddress: `0x${string}`): `0x${string}` {
+    return keccak256(
+        encodeAbiParameters([{ type: "string" }, { type: "address" }], [REVOCATION_MESSAGE_DOMAIN, registryAddress])
+    )
+}
+
+/**
+ * The message binding a proof to one mutation of the credential revocation registry: the action and
+ * the commitments, at that registry on that chain. It mirrors what the registry derives from the
+ * arguments it applies, so a proof aimed elsewhere fails verification.
+ *
+ * Predecessor indices are absent here as they are on chain. An index is a witness the LeanIMT+
+ * validates, not a privilege, so leaving it unbound lets a member who lost a race recompute it and
+ * resubmit the same proof; a revert does not burn the nullifier.
+ *
+ * `RevokeMany` is a distinct action because a one-commitment batch would otherwise pack identically
+ * to a single revocation.
+ */
+export function revocationMessage(registry: RegistryLocation, update: RevocationUpdate): bigint {
+    switch (update.action) {
+        case RevocationAction.Revoke:
+        case RevocationAction.Unrevoke:
+            return BigInt(
+                keccak256(
+                    encodePacked(
+                        ["bytes32", "uint256", "uint8", "uint256"],
+                        [
+                            revocationDomainSeparator(registry.address),
+                            registry.chainId,
+                            update.action,
+                            update.revocationCommitment
+                        ]
+                    )
+                )
+            )
+        case RevocationAction.RevokeMany:
+            if (update.revocationCommitments.length === 0) {
+                throw new Error("a batch binds at least one commitment")
+            }
+
+            return BigInt(
+                keccak256(
+                    encodePacked(
+                        ["bytes32", "uint256", "uint8", "uint256[]"],
+                        [
+                            revocationDomainSeparator(registry.address),
+                            registry.chainId,
+                            update.action,
+                            [...update.revocationCommitments]
+                        ]
+                    )
+                )
+            )
+        case RevocationAction.UpdateCommitment:
+            return BigInt(
+                keccak256(
+                    encodePacked(
+                        ["bytes32", "uint256", "uint8", "uint256", "uint256"],
+                        [
+                            revocationDomainSeparator(registry.address),
+                            registry.chainId,
+                            update.action,
+                            update.oldRevocationCommitment,
+                            update.newRevocationCommitment
+                        ]
+                    )
+                )
+            )
+        default:
+            throw new Error("unknown revocation action")
+    }
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+/** Which mutation of the IdentityRegistry a proof authorises. Matches the on-chain enum. */
+export enum UpdateAction {
+    Register = 0,
+    Update = 1,
+    Remove = 2
+}
+
+/** The update a member is authorising, exactly as it will be submitted. */
+export type IdentityUpdate = {
+    action: UpdateAction
+    /** The networkId being written. */
+    networkId: `0x${string}`
+    /** The 66-byte ERC-6538 meta-stealth address being written. Omitted for a removal. */
+    metaStealthAddress?: `0x${string}`
+}
+
+/** Where the registry is deployed. The message binds an update to this pair. */
+export type RegistryLocation = {
+    chainId: bigint
+    address: `0x${string}`
+}
+
+/**
+ * A membership proof in the shape the registry's NetworkMemberProof struct expects: Semaphore's proof
+ * without its message. The registry derives the message from the call's own arguments, so it is the
+ * one public signal a caller never supplies.
+ */
+export type NetworkMemberProof = {
+    merkleTreeDepth: bigint
+    merkleTreeRoot: bigint
+    nullifier: bigint
+    scope: bigint
+    points: readonly [bigint, bigint, bigint, bigint, bigint, bigint, bigint, bigint]
+}
+
+/** Which mutation of the CredentialRevocationRegistry a proof authorises. Matches the on-chain enum. */
+export enum RevocationAction {
+    Revoke = 0,
+    RevokeMany = 1,
+    Unrevoke = 2,
+    UpdateCommitment = 3
+}
+
+/**
+ * The revocation the member is authorising, exactly as it will be submitted. Predecessor indices are
+ * absent because the message does not bind them, so one proof survives a recomputed index.
+ */
+export type RevocationUpdate =
+    | { action: RevocationAction.Revoke; revocationCommitment: bigint }
+    | { action: RevocationAction.Unrevoke; revocationCommitment: bigint }
+    | { action: RevocationAction.RevokeMany; revocationCommitments: readonly bigint[] }
+    | {
+          action: RevocationAction.UpdateCommitment
+          oldRevocationCommitment: bigint
+          newRevocationCommitment: bigint
+      }

package/types/index.d.ts

@@ -0,0 +1,172 @@
+import { Group } from '@semaphore-protocol/group';
+import { Identity } from '@semaphore-protocol/identity';
+
+/** Which mutation of the IdentityRegistry a proof authorises. Matches the on-chain enum. */
+declare enum UpdateAction {
+    Register = 0,
+    Update = 1,
+    Remove = 2
+}
+/** The update a member is authorising, exactly as it will be submitted. */
+type IdentityUpdate = {
+    action: UpdateAction;
+    /** The networkId being written. */
+    networkId: `0x${string}`;
+    /** The 66-byte ERC-6538 meta-stealth address being written. Omitted for a removal. */
+    metaStealthAddress?: `0x${string}`;
+};
+/** Where the registry is deployed. The message binds an update to this pair. */
+type RegistryLocation = {
+    chainId: bigint;
+    address: `0x${string}`;
+};
+/**
+ * A membership proof in the shape the registry's NetworkMemberProof struct expects: Semaphore's proof
+ * without its message. The registry derives the message from the call's own arguments, so it is the
+ * one public signal a caller never supplies.
+ */
+type NetworkMemberProof = {
+    merkleTreeDepth: bigint;
+    merkleTreeRoot: bigint;
+    nullifier: bigint;
+    scope: bigint;
+    points: readonly [bigint, bigint, bigint, bigint, bigint, bigint, bigint, bigint];
+};
+/** Which mutation of the CredentialRevocationRegistry a proof authorises. Matches the on-chain enum. */
+declare enum RevocationAction {
+    Revoke = 0,
+    RevokeMany = 1,
+    Unrevoke = 2,
+    UpdateCommitment = 3
+}
+/**
+ * The revocation the member is authorising, exactly as it will be submitted. Predecessor indices are
+ * absent because the message does not bind them, so one proof survives a recomputed index.
+ */
+type RevocationUpdate = {
+    action: RevocationAction.Revoke;
+    revocationCommitment: bigint;
+} | {
+    action: RevocationAction.Unrevoke;
+    revocationCommitment: bigint;
+} | {
+    action: RevocationAction.RevokeMany;
+    revocationCommitments: readonly bigint[];
+} | {
+    action: RevocationAction.UpdateCommitment;
+    oldRevocationCommitment: bigint;
+    newRevocationCommitment: bigint;
+};
+
+type GenerateRevocationProofOptions = {
+    /** The network member's Semaphore identity. Its commitment must be a leaf of `group`. */
+    identity: Identity;
+    /**
+     * The approved-member group, as the Semaphore contract currently holds it. Rebuild it from the
+     * group's on-chain membership events: a proof against a root the group no longer holds is only
+     * accepted inside the recent-root window.
+     */
+    group: Group;
+    /** Where the credential revocation registry is deployed. */
+    registry: RegistryLocation;
+    /** The revocation being authorised. */
+    update: RevocationUpdate;
+    /** The proof's scope. Defaults to a fresh random one, which is what keeps proofs unlinkable. */
+    scope?: bigint;
+};
+/**
+ * Generates the membership proof that authorises one write to the credential revocation registry.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact revocation,
+ * and nothing else: not which leaf, and not who submits it. Submit it from any address, including a
+ * fresh stealth address with a paymaster covering the gas, since no write path reads `msg.sender`.
+ *
+ * One tree holds the whole network's revocations, so nothing about the write names the issuer either.
+ */
+declare function generateRevocationProof({ identity, group, registry, update, scope }: GenerateRevocationProofOptions): Promise<NetworkMemberProof>;
+
+type GenerateSemaphoreProofOptions = {
+    /** The network member's Semaphore identity. Its commitment must be a leaf of `group`. */
+    identity: Identity;
+    /**
+     * The approved-member group, as the registry's Semaphore group currently holds it. Rebuild it
+     * from the group's on-chain membership events: a proof against a root the group no longer holds
+     * is only accepted inside Semaphore's recent-root window.
+     */
+    group: Group;
+    /** Where the registry is deployed. */
+    registry: RegistryLocation;
+    /** The update being authorised. */
+    update: IdentityUpdate;
+    /** The proof's scope. Defaults to a fresh random one, which is what keeps proofs unlinkable. */
+    scope?: bigint;
+};
+/**
+ * Generates the membership proof that authorises one registry update.
+ *
+ * The proof states that some leaf of the approved-member group signed off on this exact update, and
+ * nothing else: not which leaf, and not who submits it. Submit it from any address, since no write
+ * path reads `msg.sender`.
+ *
+ * `identity` and `group` are Semaphore's own types, taken as given here. Creating a member identity
+ * and maintaining the group are governance and onboarding concerns, not proof generation.
+ *
+ * The message binds the proof to this update at this registry on this chain, so it cannot be
+ * replayed against another payload, and Semaphore burns the nullifier on the way in, so the proof
+ * itself cannot be submitted twice.
+ */
+declare function generateSemaphoreProof({ identity, group, registry, update, scope }: GenerateSemaphoreProofOptions): Promise<NetworkMemberProof>;
+
+/** Domain string in the registry's `UPDATE_DOMAIN_SEPARATOR`. */
+declare const UPDATE_MESSAGE_DOMAIN = "coordination-network.identity-registry.update.v1";
+/**
+ * The constant half of an update message, mirroring the registry's `UPDATE_DOMAIN_SEPARATOR`. The
+ * registry hashes it once at deployment, so a client can also read it from there.
+ */
+declare function updateDomainSeparator(registryAddress: `0x${string}`): `0x${string}`;
+/**
+ * The Semaphore message binding a proof to one registry update, mirroring the message the registry
+ * derives from the arguments it is about to apply: the payload, the registry and the chain.
+ *
+ * The payload is what stops a proof authorising a different update. The registry address and the
+ * chain id place that update at one deployment: a registry does not own its Semaphore group, so two
+ * registries can share one, and the same registry can exist at the same address on two chains with
+ * the same members and therefore the same root.
+ *
+ * The registry never accepts a message from the caller, so a proof built for the wrong update does
+ * not fail a comparison, it fails verification.
+ */
+declare function updateMessage(registry: RegistryLocation, update: IdentityUpdate): bigint;
+/**
+ * A fresh random scope.
+ *
+ * A Semaphore nullifier is `poseidon(secret, scope)`, so a random scope gives every proof an
+ * unlinkable nullifier: the registry only ever learns that some approved member authorised the
+ * update, never that two updates came from the same one. The registry does not constrain the scope;
+ * what it relies on is that the nullifier a proof carries can only be spent once.
+ */
+declare function randomScope(): bigint;
+
+/** Domain string in the registry's `REVOCATION_DOMAIN_SEPARATOR`. */
+declare const REVOCATION_MESSAGE_DOMAIN = "coordination-network.credential-revocation-registry.revocation.v1";
+/**
+ * The constant half of a revocation message, mirroring the registry's `REVOCATION_DOMAIN_SEPARATOR`.
+ * The registry hashes it once at deployment, so a client can read it from there instead.
+ */
+declare function revocationDomainSeparator(registryAddress: `0x${string}`): `0x${string}`;
+/**
+ * The message binding a proof to one mutation of the credential revocation registry: the action and
+ * the commitments, at that registry on that chain. It mirrors what the registry derives from the
+ * arguments it applies, so a proof aimed elsewhere fails verification.
+ *
+ * Predecessor indices are absent here as they are on chain. An index is a witness the LeanIMT+
+ * validates, not a privilege, so leaving it unbound lets a member who lost a race recompute it and
+ * resubmit the same proof; a revert does not burn the nullifier.
+ *
+ * `RevokeMany` is a distinct action because a one-commitment batch would otherwise pack identically
+ * to a single revocation.
+ */
+declare function revocationMessage(registry: RegistryLocation, update: RevocationUpdate): bigint;
+
+export { REVOCATION_MESSAGE_DOMAIN, RevocationAction, UPDATE_MESSAGE_DOMAIN, UpdateAction, generateRevocationProof, generateSemaphoreProof, randomScope, revocationDomainSeparator, revocationMessage, updateDomainSeparator, updateMessage };
+export type { GenerateRevocationProofOptions, GenerateSemaphoreProofOptions, IdentityUpdate, NetworkMemberProof, RegistryLocation, RevocationUpdate };