@coordination-network/network-member-client 0.0.1

package/dist/index.js

@@ -0,0 +1,952 @@
+import { ApprovedIssuerSet } from '@coordination-network/issuer-set';
+import { issueZkCredential, serializeZkCredential } from '@coordination-network/credential';
+import { validateMetaStealthAddress, buildAnnouncement, generateStealthPrivateKey } from '@coordination-network/identity';
+import { verifyRegistrationRequest } from '@coordination-network/user-client';
+import { UpdateAction, generateSemaphoreProof, generateRevocationProof } from '@coordination-network/network-member-proof';
+import { BaseError, ContractFunctionRevertedError, encodeFunctionData, encodeAbiParameters, decodeErrorResult, http, parseEventLogs } from 'viem';
+import { Group } from '@semaphore-protocol/group';
+import { entryPoint08Abi, getUserOperationHash, createBundlerClient, formatUserOperationRequest, toPackedUserOperation } from 'viem/account-abstraction';
+import { privateKeyToAccount } from 'viem/accounts';
+import { generateProof } from '@semaphore-protocol/proof';
+
+class NetworkMemberClientError extends Error {
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "NetworkMemberClientError";
+        this.code = code;
+        if (cause !== undefined) {
+            // Non-enumerable, matching the standard Error.cause: a provider error's circular
+            // transport graph would otherwise make JSON.stringify throw in a caller's handler.
+            Object.defineProperty(this, "cause", { value: cause, writable: true, configurable: true });
+        }
+    }
+}
+/** A named revert from IdentityRegistry or Semaphore, walked out of a viem contract-call error. */
+class RegistryRevertError extends NetworkMemberClientError {
+    constructor(errorName, cause) {
+        super("REGISTRATION_REJECTED", errorName, cause);
+        this.name = "RegistryRevertError";
+        this.errorName = errorName;
+    }
+}
+/**
+ * A revert from CredentialRevocationRegistry, or from the revocation service or Semaphore behind
+ * it. `reason` is the decoded error name, or the raw revert data when nothing in the registry's
+ * ABI matches it: a caller retries `InvalidLowLeaf` against a re-synced mirror and gives up on
+ * `LeafAlreadyExists`, so it has to be able to tell them apart.
+ */
+class RevocationRevertError extends NetworkMemberClientError {
+    constructor(reason, cause) {
+        super("REVOCATION_REJECTED", reason, cause);
+        this.name = "RevocationRevertError";
+        this.reason = reason;
+    }
+}
+
+/** Rebuilds the approved-issuer set from its current on-chain leaves and proves membership against the fresh root. */
+async function fetchIssuerMembershipWitness({ issuerSetReader, issuerPublicKey }) {
+    const issuerSet = await ApprovedIssuerSet.fromContract(issuerSetReader);
+    if (!issuerSet.isApproved(issuerPublicKey)) {
+        throw new NetworkMemberClientError("ISSUER_KEY_NOT_PUBLISHED", "issuer signing key is not published to the approved-issuer set");
+    }
+    return { root: issuerSet.root, witness: issuerSet.generateProof(issuerPublicKey) };
+}
+
+/**
+ * Issues a UserApproval credential plus the issuer's fresh Merkle path into the
+ * approved-issuer set. The witness is fetched before any signing, so an issuer
+ * whose key was never published fails at issuance without spending a signature.
+ */
+async function issueVC(params, { signer, approval, issuerSetReader }) {
+    const { root, witness } = await fetchIssuerMembershipWitness({
+        issuerSetReader,
+        issuerPublicKey: await signer.getPublicKey()
+    });
+    const credential = await issueZkCredential(params, signer, approval);
+    return { credential: serializeZkCredential(credential), issuerSetRoot: root, issuerMembershipWitness: witness };
+}
+
+/**
+ * Delivers value to a network member's recipient: resolves their registered identity and announces
+ * a fresh stealth address for it. `ERC5564Announcer.announce` is permissionless, so the member's
+ * approval is checked here, first, before any other port runs.
+ */
+async function deliverToStealth({ memberNetworkId, recipientNetworkId }, { approval, identityReader, submitter }) {
+    if (!(await approval.isApprovedNetworkMember(memberNetworkId))) {
+        throw new NetworkMemberClientError("MEMBER_NOT_APPROVED", "network member is not approved");
+    }
+    const metaStealthAddress = await identityReader.getIdentity(recipientNetworkId);
+    if (metaStealthAddress === null) {
+        throw new NetworkMemberClientError("RECIPIENT_NOT_REGISTERED", "recipient has no registered identity");
+    }
+    if (!validateMetaStealthAddress(metaStealthAddress)) {
+        throw new NetworkMemberClientError("INVALID_META_STEALTH_ADDRESS", "recipient's registered meta-stealth address is malformed");
+    }
+    const announcement = buildAnnouncement({ metaStealthAddress });
+    const txHash = await submitter.announce(announcement);
+    return { stealthAddress: announcement.stealthAddress, announcement, txHash };
+}
+
+/** Throws when `port`'s bound registry doesn't match `domain`: a member-app wiring bug, not something a request can trigger. */
+function assertRegistryMatches(port, registry, domain) {
+    if (registry.chainId !== domain.chainId || registry.address.toLowerCase() !== domain.address.toLowerCase()) {
+        throw new Error(`${port} targets registry ${registry.address} on chain ${registry.chainId}, but domain is ${domain.address} on chain ${domain.chainId}`);
+    }
+}
+/** Same guard as `assertRegistryMatches`, for a reader that only reports the address it reads.
+ *  Optional on `IdentityReader`, so a no-op when the reader doesn't report one. */
+function assertReaderMatches(registryAddress, domain) {
+    if (registryAddress !== undefined && registryAddress.toLowerCase() !== domain.address.toLowerCase()) {
+        throw new Error(`identityReader targets registry ${registryAddress}, but domain is ${domain.address} on chain ${domain.chainId}`);
+    }
+}
+/** Reads the current registry entry, mapping a transport failure to REGISTRY_UNAVAILABLE. */
+async function readIdentity(identityReader, networkId) {
+    try {
+        return await identityReader.getIdentity(networkId);
+    }
+    catch (error) {
+        throw new NetworkMemberClientError("REGISTRY_UNAVAILABLE", `identity read failed for ${networkId}`, error);
+    }
+}
+/**
+ * Submits a user's signed registration consent to `IdentityRegistry`, as an approved network
+ * member. The ports' own registry binding is checked first, then consent, both before any port
+ * runs, so a misconfigured member app or a forged/mistargeted request never reaches the registry.
+ */
+async function submitRegistration(request, { domain, identityReader, prover, writer }) {
+    const registryDomain = { chainId: BigInt(domain.chainId), address: domain.verifyingContract };
+    assertRegistryMatches("prover", prover.registry, registryDomain);
+    assertRegistryMatches("writer", writer.registry, registryDomain);
+    assertReaderMatches(identityReader.registryAddress, registryDomain);
+    if (!verifyRegistrationRequest(request, domain)) {
+        throw new NetworkMemberClientError("INVALID_REGISTRATION_REQUEST", "registration request failed verification");
+    }
+    const { networkId, metaStealthAddress } = request;
+    const existing = await readIdentity(identityReader, networkId);
+    if (existing !== null) {
+        return {
+            status: "alreadyRegistered",
+            networkId,
+            metaStealthAddress: existing,
+            matchesRequest: existing.toLowerCase() === metaStealthAddress.toLowerCase()
+        };
+    }
+    const proof = await prover.prove({ action: UpdateAction.Register, networkId, metaStealthAddress });
+    try {
+        const write = await writer.registerIdentity(networkId, metaStealthAddress, proof);
+        return { status: "submitted", networkId, metaStealthAddress, ...write };
+    }
+    catch (error) {
+        if (error instanceof RegistryRevertError) {
+            // Lost a race between the read above and this write: someone else registered this
+            // networkId in between. The re-read, not the revert's own payload, is the source of
+            // truth for what the caller should treat as the current entry.
+            if (error.errorName === "AlreadyRegistered") {
+                let raced;
+                try {
+                    raced = await readIdentity(identityReader, networkId);
+                }
+                catch {
+                    // The write's revert already confirmed the entry exists; a failed re-read
+                    // doesn't change that, so surface the confirmed revert, not the read failure.
+                    throw error;
+                }
+                // The registry answered; the write's gas estimate saw pending state the read
+                // above did not. The revert is still the right thing to surface.
+                if (raced === null)
+                    throw error;
+                return {
+                    status: "alreadyRegistered",
+                    networkId,
+                    metaStealthAddress: raced,
+                    matchesRequest: raced.toLowerCase() === metaStealthAddress.toLowerCase()
+                };
+            }
+            throw error;
+        }
+        throw new NetworkMemberClientError("REGISTRY_UNAVAILABLE", `registration submission failed for ${networkId}`, error);
+    }
+}
+
+/** Shared with `sponsored.ts`: encoding the same call and decoding the same reverts from two writers must not drift apart. */
+const IDENTITY_REGISTRY_ABI = [
+    {
+        type: "function",
+        name: "identity",
+        stateMutability: "view",
+        inputs: [{ name: "networkId", type: "bytes32" }],
+        outputs: [{ type: "bytes" }]
+    },
+    {
+        type: "function",
+        name: "registerIdentity",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "networkId", type: "bytes32" },
+            { name: "metaStealthAddress", type: "bytes" },
+            {
+                name: "proof",
+                type: "tuple",
+                components: [
+                    { name: "merkleTreeDepth", type: "uint256" },
+                    { name: "merkleTreeRoot", type: "uint256" },
+                    { name: "nullifier", type: "uint256" },
+                    { name: "scope", type: "uint256" },
+                    { name: "points", type: "uint256[8]" }
+                ]
+            }
+        ],
+        outputs: []
+    },
+    { type: "error", name: "AlreadyRegistered", inputs: [{ name: "networkId", type: "bytes32" }] },
+    { type: "error", name: "InvalidMetaStealthAddressLength", inputs: [] },
+    { type: "error", name: "NotRegistered", inputs: [{ name: "networkId", type: "bytes32" }] },
+    { type: "error", name: "Semaphore__GroupHasNoMembers", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeDepthIsNotSupported", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeRootIsExpired", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeRootIsNotPartOfTheGroup", inputs: [] },
+    { type: "error", name: "Semaphore__YouAreUsingTheSameNullifierTwice", inputs: [] },
+    { type: "error", name: "Semaphore__InvalidProof", inputs: [] }
+];
+/** The four Semaphore group-membership events a mirror replays, in the order emission can produce them. */
+const SEMAPHORE_GROUP_EVENTS = [
+    {
+        type: "event",
+        name: "MemberAdded",
+        inputs: [
+            { name: "groupId", type: "uint256", indexed: true },
+            { name: "index", type: "uint256", indexed: false },
+            { name: "identityCommitment", type: "uint256", indexed: false },
+            { name: "merkleTreeRoot", type: "uint256", indexed: false }
+        ]
+    },
+    {
+        type: "event",
+        name: "MembersAdded",
+        inputs: [
+            { name: "groupId", type: "uint256", indexed: true },
+            { name: "startIndex", type: "uint256", indexed: false },
+            { name: "identityCommitments", type: "uint256[]", indexed: false },
+            { name: "merkleTreeRoot", type: "uint256", indexed: false }
+        ]
+    },
+    {
+        type: "event",
+        name: "MemberUpdated",
+        inputs: [
+            { name: "groupId", type: "uint256", indexed: true },
+            { name: "index", type: "uint256", indexed: false },
+            { name: "identityCommitment", type: "uint256", indexed: false },
+            { name: "newIdentityCommitment", type: "uint256", indexed: false },
+            { name: "merkleTreeRoot", type: "uint256", indexed: false }
+        ]
+    },
+    {
+        type: "event",
+        name: "MemberRemoved",
+        inputs: [
+            { name: "groupId", type: "uint256", indexed: true },
+            { name: "index", type: "uint256", indexed: false },
+            { name: "identityCommitment", type: "uint256", indexed: false },
+            { name: "merkleTreeRoot", type: "uint256", indexed: false }
+        ]
+    }
+];
+/** The `ISemaphoreGroups` slice a group mirror needs: the four membership events plus the live root. */
+const SEMAPHORE_GROUPS_ABI = [
+    ...SEMAPHORE_GROUP_EVENTS,
+    {
+        type: "function",
+        name: "getMerkleTreeRoot",
+        stateMutability: "view",
+        inputs: [{ name: "groupId", type: "uint256" }],
+        outputs: [{ type: "uint256" }]
+    }
+];
+/** Whether a replayed leaf array has no gaps: every index up to the highest one seen was set. */
+function isDense(leaves) {
+    return leaves.every((leaf) => leaf !== undefined);
+}
+/** The revert's decoded error name, if `error` (or something it wraps) is a contract revert.
+ *  Shared with `sponsored-revocation.ts`, whose direct writer walks the same viem error shape. */
+function revertErrorName(error) {
+    if (!(error instanceof BaseError))
+        return undefined;
+    const revert = error.walk((e) => e instanceof ContractFunctionRevertedError);
+    return revert instanceof ContractFunctionRevertedError ? revert.data?.errorName : undefined;
+}
+/**
+ * Chain-backed IdentityReader over `IdentityRegistry`'s public `identity` mapping. Each read puts
+ * the recipient's networkId in `eth_call` calldata, visible to whoever serves the RPC.
+ */
+class IdentityRegistryClient {
+    constructor(registryAddress, client) {
+        this.registryAddress = registryAddress;
+        this.client = client;
+    }
+    async getIdentity(networkId) {
+        const metaStealthAddress = await this.client.readContract({
+            address: this.registryAddress,
+            abi: IDENTITY_REGISTRY_ABI,
+            functionName: "identity",
+            args: [networkId]
+        });
+        return metaStealthAddress === "0x" ? null : metaStealthAddress;
+    }
+}
+const APPROVED_ISSUER_SET_ABI = [
+    {
+        type: "function",
+        name: "getLeafCount",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ type: "uint256" }]
+    },
+    {
+        type: "function",
+        name: "getLeaves",
+        stateMutability: "view",
+        inputs: [
+            { name: "start", type: "uint256" },
+            { name: "end", type: "uint256" }
+        ],
+        outputs: [{ name: "leaves", type: "uint256[]" }]
+    }
+];
+/**
+ * Chain-backed ContractLeafReader over ApprovedIssuerSet's paging getters. Reads are pinned to
+ * the block observed at `getLeafCount`, so a multi-page rebuild can't mix chain states into a
+ * root that never existed; serve one rebuild at a time per instance.
+ */
+class ApprovedIssuerSetClient {
+    constructor(setAddress, client) {
+        this.setAddress = setAddress;
+        this.client = client;
+    }
+    async getLeafCount() {
+        this.blockNumber = await this.client.getBlockNumber();
+        return this.client.readContract({
+            address: this.setAddress,
+            abi: APPROVED_ISSUER_SET_ABI,
+            functionName: "getLeafCount",
+            blockNumber: this.blockNumber
+        });
+    }
+    async getLeaves(start, end) {
+        const leaves = await this.client.readContract({
+            address: this.setAddress,
+            abi: APPROVED_ISSUER_SET_ABI,
+            functionName: "getLeaves",
+            args: [BigInt(start), BigInt(end)],
+            blockNumber: this.blockNumber
+        });
+        return [...leaves];
+    }
+}
+const ERC5564_ANNOUNCER_ABI = [
+    {
+        type: "function",
+        name: "announce",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "schemeId", type: "uint256" },
+            { name: "stealthAddress", type: "address" },
+            { name: "ephemeralPubKey", type: "bytes" },
+            { name: "metadata", type: "bytes" }
+        ],
+        outputs: []
+    }
+];
+/** Chain-backed AnnouncementSubmitter over `ERC5564Announcer.announce`. */
+class ERC5564AnnouncerClient {
+    constructor(announcerAddress, walletClient) {
+        this.announcerAddress = announcerAddress;
+        this.walletClient = walletClient;
+    }
+    async announce(announcement) {
+        return this.walletClient.writeContract({
+            address: this.announcerAddress,
+            abi: ERC5564_ANNOUNCER_ABI,
+            functionName: "announce",
+            args: [
+                BigInt(announcement.schemeId),
+                announcement.stealthAddress,
+                announcement.ephemeralPublicKey,
+                announcement.metadata
+            ]
+        });
+    }
+}
+/**
+ * Chain-backed GroupMirror over Semaphore's own group events. Rebuilds the approved-member group
+ * by replaying every MemberAdded/MembersAdded/MemberUpdated/MemberRemoved event for `groupId` in
+ * emission order, pinned to one `getBlockNumber` so the replay and the root check below can't
+ * straddle two chain states. A removal zeroes its leaf rather than deleting it, since Semaphore
+ * never reuses an index, so the replay must carry the zero forward into the rebuilt tree.
+ *
+ * The rebuilt root is then checked against `getMerkleTreeRoot` at that same block: a mismatch
+ * means the replay is wrong, not that membership is false, and this is what makes that loud
+ * instead of silently producing a proof nothing will accept.
+ */
+class SemaphoreGroupClient {
+    constructor(semaphoreAddress, groupId, client, { fromBlock = 0n } = {}) {
+        this.semaphoreAddress = semaphoreAddress;
+        this.groupId = groupId;
+        this.client = client;
+        this.fromBlock = fromBlock;
+    }
+    async currentGroup() {
+        try {
+            // viem caches getBlockNumber for `pollingInterval`, so two calls made in quick
+            // succession — as a caller re-mirroring right after its own write — can otherwise
+            // return the same stale height and silently miss that write's own group event.
+            const toBlock = await this.client.getBlockNumber({ cacheTime: 0 });
+            const [leaves, onChainRoot] = await Promise.all([
+                this.replayLeaves(toBlock),
+                this.client.readContract({
+                    address: this.semaphoreAddress,
+                    abi: SEMAPHORE_GROUPS_ABI,
+                    functionName: "getMerkleTreeRoot",
+                    args: [this.groupId],
+                    blockNumber: toBlock
+                })
+            ]);
+            if (leaves.length === 0) {
+                throw new NetworkMemberClientError("GROUP_MIRROR_UNAVAILABLE", `no membership events for group ${this.groupId} at ${this.semaphoreAddress}; wrong group id, wrong Semaphore address, or fromBlock past the first admission`);
+            }
+            if (!isDense(leaves)) {
+                const missing = [];
+                let holeCount = 0;
+                for (let index = 0; index < leaves.length; index += 1) {
+                    if (leaves[index] === undefined) {
+                        holeCount += 1;
+                        if (missing.length < 10)
+                            missing.push(index);
+                    }
+                }
+                throw new NetworkMemberClientError("GROUP_MIRROR_UNAVAILABLE", `group ${this.groupId} replay is missing ${holeCount} leaf index(es), starting with ${missing.join(", ")}; fromBlock is likely later than the first admission`);
+            }
+            const group = new Group(leaves);
+            if (BigInt(group.root) !== onChainRoot) {
+                throw new NetworkMemberClientError("GROUP_MIRROR_UNAVAILABLE", `rebuilt group root does not match the chain's for group ${this.groupId}`);
+            }
+            return group;
+        }
+        catch (error) {
+            if (error instanceof NetworkMemberClientError)
+                throw error;
+            throw new NetworkMemberClientError("GROUP_MIRROR_UNAVAILABLE", `failed to rebuild the approved-member group ${this.groupId}`, error);
+        }
+    }
+    /** Replays the four membership events into a dense, index-ordered leaf array. `undefined`
+     *  marks an index no admission log ever set, so a hole can't silently pass as leaf `0n`. */
+    async replayLeaves(toBlock) {
+        // One topic-filtered eth_getLogs per event type, not one unfiltered call for all four:
+        // a shared Semaphore deployment hosts other groups too, and their history isn't ours to
+        // download on every mirror.
+        const logsByEvent = await Promise.all(SEMAPHORE_GROUP_EVENTS.map((event) => this.client.getLogs({
+            address: this.semaphoreAddress,
+            event,
+            args: { groupId: this.groupId },
+            fromBlock: this.fromBlock,
+            toBlock,
+            strict: true
+        })));
+        const logs = logsByEvent.flat().sort((a, b) => {
+            if (a.blockNumber !== b.blockNumber)
+                return a.blockNumber < b.blockNumber ? -1 : 1;
+            return a.logIndex - b.logIndex;
+        });
+        const byIndex = new Map();
+        let maxIndex = -1;
+        const set = (index, commitment) => {
+            byIndex.set(index, commitment);
+            if (index > maxIndex)
+                maxIndex = index;
+        };
+        for (const log of logs) {
+            switch (log.eventName) {
+                case "MemberAdded":
+                    set(Number(log.args.index), log.args.identityCommitment);
+                    break;
+                case "MembersAdded":
+                    log.args.identityCommitments.forEach((commitment, offset) => {
+                        set(Number(log.args.startIndex) + offset, commitment);
+                    });
+                    break;
+                case "MemberUpdated":
+                    set(Number(log.args.index), log.args.newIdentityCommitment);
+                    break;
+                case "MemberRemoved":
+                    set(Number(log.args.index), 0n);
+                    break;
+            }
+        }
+        return Array.from({ length: maxIndex + 1 }, (_, index) => byIndex.get(index));
+    }
+}
+/**
+ * Chain-backed RegistrationProver: mirrors the approved-member group fresh for every call, then
+ * generates the Semaphore proof authorising one IdentityRegistry write.
+ */
+class SemaphoreRegistrationProver {
+    constructor({ identity, groupMirror, registry }) {
+        this.identity = identity;
+        this.groupMirror = groupMirror;
+        this.registry = registry;
+    }
+    async prove(update) {
+        const group = await this.groupMirror.currentGroup();
+        if (group.indexOf(this.identity.commitment) === -1) {
+            throw new NetworkMemberClientError("MEMBER_NOT_IN_GROUP", "identity is not a member of the approved-member group");
+        }
+        return generateSemaphoreProof({ identity: this.identity, group, registry: this.registry, update });
+    }
+}
+/**
+ * Chain-backed RevocationProver: mirrors the approved-member group fresh for every call, then
+ * generates the Semaphore proof authorising one write to the network's credential revocation
+ * registry. The same group as registration's, reached through the same mirror: the registry
+ * inherits `NetworkMemberGate`, so `SEMAPHORE()` and `NETWORK_MEMBER_GROUP_ID()` are public on it
+ * too and the mirror only needs a different address.
+ */
+class SemaphoreRevocationProver {
+    constructor({ identity, groupMirror, registry }) {
+        this.identity = identity;
+        this.groupMirror = groupMirror;
+        this.registry = registry;
+    }
+    async prove(update) {
+        const group = await this.groupMirror.currentGroup();
+        if (group.indexOf(this.identity.commitment) === -1) {
+            throw new NetworkMemberClientError("MEMBER_NOT_IN_GROUP", "identity is not a member of the approved-member group");
+        }
+        return generateRevocationProof({ identity: this.identity, group, registry: this.registry, update });
+    }
+}
+/**
+ * Chain-backed RegistrationWriter over `IdentityRegistry.registerIdentity`. No receipt wait:
+ * `AlreadyRegistered` surfaces at viem's gas estimate, and a returned txHash means submitted,
+ * matching `RegistrationSubmitter`'s contract in `@coordination-network/user-client`.
+ */
+class IdentityRegistryWriter {
+    constructor(registry, walletClient) {
+        this.registry = registry;
+        this.walletClient = walletClient;
+    }
+    async registerIdentity(networkId, metaStealthAddress, proof) {
+        try {
+            const txHash = await this.walletClient.writeContract({
+                address: this.registry.address,
+                abi: IDENTITY_REGISTRY_ABI,
+                functionName: "registerIdentity",
+                args: [networkId, metaStealthAddress, proof]
+            });
+            return { txHash };
+        }
+        catch (error) {
+            const errorName = revertErrorName(error);
+            if (errorName !== undefined)
+                throw new RegistryRevertError(errorName, error);
+            throw error;
+        }
+    }
+}
+
+const SIMPLE_7702_ACCOUNT_ABI = [
+    {
+        type: "function",
+        name: "execute",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "target", type: "address" },
+            { name: "value", type: "uint256" },
+            { name: "data", type: "bytes" }
+        ],
+        outputs: []
+    }
+];
+const PAYMASTER_ABI = [
+    { type: "function", name: "getDeposit", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] }
+];
+/** `ISemaphore.SemaphoreProof`'s own ABI shape: five scalar words plus eight proof points, matching `SemaphorePaymaster._validatePaymasterUserOp`'s decode. */
+const PAYMASTER_PROOF_ABI_PARAMS = [
+    { name: "merkleTreeDepth", type: "uint256" },
+    { name: "merkleTreeRoot", type: "uint256" },
+    { name: "nullifier", type: "uint256" },
+    { name: "message", type: "uint256" },
+    { name: "scope", type: "uint256" },
+    { name: "points", type: "uint256[8]" }
+];
+/** Fixed at the contract's own minimums/limits; not worth exposing as constructor knobs for one call site. */
+const GAS_LIMITS = {
+    callGasLimit: 700000n,
+    verificationGasLimit: 500000n,
+    preVerificationGas: 100000n,
+    paymasterVerificationGasLimit: 600000n,
+    paymasterPostOpGasLimit: 50000n
+};
+const GAS_FEE_PER_GAS = 1000000000n; // 1 gwei
+/**
+ * Relays one call through a fresh, disposable stealth sender delegated to Simple7702Account and
+ * sponsored by SemaphorePaymaster, so the member pays nothing and no sender links two of the
+ * member's relayed calls to each other.
+ *
+ * A reverted operation comes back as a receipt, not an error: which reverts are worth retrying and
+ * which are final depends on the contract being called, so the caller owns that reading.
+ */
+class SponsoredRelay {
+    constructor(params) {
+        this.chainId = params.chainId;
+        this.entryPoint = params.entryPoint;
+        this.paymaster = params.paymaster;
+        this.accountImplementation = params.accountImplementation;
+        this.memberKeys = params.memberKeys;
+        this.paymasterIdentity = params.paymasterIdentity;
+        this.paymasterGroup = params.paymasterGroup;
+        this.submitter = params.submitter;
+        this.publicClient = params.publicClient;
+    }
+    async relay({ target, value = 0n, data }) {
+        const sender = this.deriveSender();
+        const [senderBalanceBefore, paymasterDepositBefore] = await Promise.all([
+            this.publicClient.getBalance({ address: sender.address }),
+            this.readPaymasterDeposit()
+        ]);
+        const callData = encodeFunctionData({
+            abi: SIMPLE_7702_ACCOUNT_ABI,
+            functionName: "execute",
+            args: [target, value, data]
+        });
+        const paymasterData = await this.buildPaymasterProof(sender.address);
+        const [nonce, transactionCount] = await Promise.all([
+            this.publicClient.readContract({
+                address: this.entryPoint,
+                abi: entryPoint08Abi,
+                functionName: "getNonce",
+                args: [sender.address, 0n]
+            }),
+            this.publicClient.getTransactionCount({ address: sender.address })
+        ]);
+        const authorization = await sender.signAuthorization({
+            address: this.accountImplementation,
+            chainId: this.chainId,
+            nonce: transactionCount
+        });
+        const unsignedUserOperation = {
+            sender: sender.address,
+            nonce,
+            factory: "0x7702",
+            callData,
+            ...GAS_LIMITS,
+            maxFeePerGas: GAS_FEE_PER_GAS,
+            maxPriorityFeePerGas: GAS_FEE_PER_GAS,
+            paymaster: this.paymaster,
+            paymasterData,
+            authorization,
+            signature: "0x"
+        };
+        const userOpHash = getUserOperationHash({
+            chainId: this.chainId,
+            entryPointAddress: this.entryPoint,
+            entryPointVersion: "0.8",
+            userOperation: unsignedUserOperation
+        });
+        const signature = await sender.sign({ hash: userOpHash });
+        const userOperation = { ...unsignedUserOperation, signature };
+        const submittedHash = await this.submitter.send(userOperation);
+        // A bundler on another EntryPoint (or a bug in this one) would otherwise surface as
+        // waitForReceipt timing out on a hash nothing will ever mine.
+        if (submittedHash !== userOpHash) {
+            throw new Error(`bundler returned userOpHash ${submittedHash}, expected ${userOpHash}`);
+        }
+        const receipt = await this.submitter.waitForReceipt(userOpHash);
+        const [senderBalanceAfter, paymasterDepositAfter] = await Promise.all([
+            this.publicClient.getBalance({ address: sender.address }),
+            this.readPaymasterDeposit()
+        ]);
+        return {
+            receipt,
+            sponsorship: {
+                sender: sender.address,
+                senderBalanceBefore,
+                senderBalanceAfter,
+                userOpHash,
+                bundleTxHash: receipt.transactionHash,
+                actualGasCost: receipt.actualGasCost,
+                paymaster: this.paymaster,
+                paymasterDepositBefore,
+                paymasterDepositAfter
+            }
+        };
+    }
+    /**
+     * A fresh, disposable stealth address derived from the member's own meta-address: used once
+     * to sign and pay (nothing, since it's sponsored) for this call, then dropped. No announcement
+     * is made, so it can't link two of the member's relayed calls to each other.
+     */
+    deriveSender() {
+        const announcement = buildAnnouncement({ metaStealthAddress: this.memberKeys.metaStealthAddress });
+        const privateKey = generateStealthPrivateKey({
+            ephemeralPublicKey: announcement.ephemeralPublicKey,
+            viewingPrivateKey: this.memberKeys.viewingPrivateKey,
+            spendingPrivateKey: this.memberKeys.spendingPrivateKey
+        });
+        return privateKeyToAccount(privateKey);
+    }
+    readPaymasterDeposit() {
+        return this.publicClient.readContract({
+            address: this.paymaster,
+            abi: PAYMASTER_ABI,
+            functionName: "getDeposit"
+        });
+    }
+    /** The paymaster's own proof: the member's Semaphore identity against its mirrored group, message and scope both the disposable sender (`SemaphorePaymaster`'s own binding). */
+    async buildPaymasterProof(sender) {
+        const group = await this.paymasterGroup.currentGroup();
+        const senderAsScalar = BigInt(sender);
+        const proof = await generateProof(this.paymasterIdentity, group, senderAsScalar, senderAsScalar);
+        return encodeAbiParameters(PAYMASTER_PROOF_ABI_PARAMS, [
+            BigInt(proof.merkleTreeDepth),
+            BigInt(proof.merkleTreeRoot),
+            BigInt(proof.nullifier),
+            BigInt(proof.message),
+            BigInt(proof.scope),
+            proof.points.map(BigInt)
+        ]);
+    }
+}
+
+/**
+ * Sponsored RegistrationWriter: relays a `registerIdentity` call through {@link SponsoredRelay},
+ * so the member pays nothing and no sender links two of the member's relayed registrations to
+ * each other.
+ */
+class SponsoredIdentityRegistryWriter {
+    constructor({ registry, ...relayParams }) {
+        this.registry = registry;
+        this.relay = new SponsoredRelay(relayParams);
+    }
+    async registerIdentity(networkId, metaStealthAddress, proof) {
+        const { receipt, sponsorship } = await this.relay.relay({
+            target: this.registry.address,
+            data: encodeFunctionData({
+                abi: IDENTITY_REGISTRY_ABI,
+                functionName: "registerIdentity",
+                args: [networkId, metaStealthAddress, proof]
+            })
+        });
+        if (!receipt.success) {
+            if (receipt.revertReason !== undefined && decodedErrorName(receipt.revertReason) === "AlreadyRegistered") {
+                throw new RegistryRevertError("AlreadyRegistered", receipt.revertReason);
+            }
+            throw new Error(`sponsored registerIdentity user operation reverted for ${networkId}`);
+        }
+        return { txHash: receipt.transactionHash, sponsorship };
+    }
+}
+/** The IdentityRegistry error name `revertReason` decodes to, or undefined for anything else (a different error, or no revert data at all). */
+function decodedErrorName(revertReason) {
+    try {
+        return decodeErrorResult({ abi: IDENTITY_REGISTRY_ABI, data: revertReason }).errorName;
+    }
+    catch {
+        return undefined;
+    }
+}
+
+/**
+ * The `CredentialRevocationRegistry` fragments a writer needs. The errors matter as much as the
+ * function: `InvalidLowLeaf` is the one a caller recomputes an index and retries on, and
+ * `LeafAlreadyExists` the one it stops on, so both writers must decode the same names.
+ */
+const CREDENTIAL_REVOCATION_REGISTRY_ABI = [
+    {
+        type: "function",
+        name: "revoke",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "revocationCommitment", type: "uint256" },
+            { name: "lowLeafIndex", type: "uint256" },
+            {
+                name: "proof",
+                type: "tuple",
+                components: [
+                    { name: "merkleTreeDepth", type: "uint256" },
+                    { name: "merkleTreeRoot", type: "uint256" },
+                    { name: "nullifier", type: "uint256" },
+                    { name: "scope", type: "uint256" },
+                    { name: "points", type: "uint256[8]" }
+                ]
+            }
+        ],
+        outputs: []
+    },
+    { type: "error", name: "InvalidLowLeaf", inputs: [] },
+    { type: "error", name: "LeafAlreadyExists", inputs: [] },
+    { type: "error", name: "LeafCannotBeZero", inputs: [] },
+    { type: "error", name: "LeafGreaterThanSnarkScalarField", inputs: [] },
+    { type: "error", name: "RegistryDoesNotExist", inputs: [] },
+    { type: "error", name: "CallerIsNotTheRegistryAdmin", inputs: [] },
+    { type: "error", name: "Semaphore__GroupHasNoMembers", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeDepthIsNotSupported", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeRootIsExpired", inputs: [] },
+    { type: "error", name: "Semaphore__MerkleTreeRootIsNotPartOfTheGroup", inputs: [] },
+    { type: "error", name: "Semaphore__YouAreUsingTheSameNullifierTwice", inputs: [] },
+    { type: "error", name: "Semaphore__InvalidProof", inputs: [] }
+];
+/**
+ * Sponsored RevocationRegistryWriter: relays a `revoke` call through {@link SponsoredRelay}, so
+ * the write costs the member nothing and its sender names no member. That matters more here than for
+ * registration: one tree holds the whole network's revocations, and an EOA paying for the write
+ * would say which member revoked which credential.
+ */
+class SponsoredRevocationWriter {
+    constructor(registry, relay) {
+        this.registry = registry;
+        this.relay = relay;
+    }
+    async revoke(commitment, lowLeafIndex, proof) {
+        const { receipt, sponsorship } = await this.relay.relay({
+            target: this.registry.address,
+            data: encodeFunctionData({
+                abi: CREDENTIAL_REVOCATION_REGISTRY_ABI,
+                functionName: "revoke",
+                args: [commitment, lowLeafIndex, proof]
+            })
+        });
+        if (!receipt.success) {
+            throw new RevocationRevertError(decodedRevertReason(receipt.revertReason), receipt.revertReason);
+        }
+        return { txHash: receipt.transactionHash, sponsorship };
+    }
+}
+/**
+ * Chain-backed RevocationRegistryWriter over `CredentialRevocationRegistry.revoke`, for a member
+ * server running without an account-abstraction stack. The submitting EOA is on chain, so it says
+ * which member revoked; the sponsored writer above is what keeps that unattributable.
+ *
+ * No receipt wait: a reverting write surfaces at viem's gas estimate, and a returned txHash means
+ * submitted, matching `IdentityRegistryWriter`.
+ */
+class DirectRevocationWriter {
+    constructor(registry, walletClient) {
+        this.registry = registry;
+        this.walletClient = walletClient;
+    }
+    async revoke(commitment, lowLeafIndex, proof) {
+        try {
+            const txHash = await this.walletClient.writeContract({
+                address: this.registry.address,
+                abi: CREDENTIAL_REVOCATION_REGISTRY_ABI,
+                functionName: "revoke",
+                args: [commitment, lowLeafIndex, proof]
+            });
+            return { txHash };
+        }
+        catch (error) {
+            const errorName = revertErrorName(error);
+            if (errorName !== undefined)
+                throw new RevocationRevertError(errorName, error);
+            throw error;
+        }
+    }
+}
+/** The registry error name `revertReason` decodes to, falling back to the raw data so a caller
+ *  that can't match a name still has something to report. */
+function decodedRevertReason(revertReason) {
+    if (revertReason === undefined)
+        return "reverted without a reason";
+    try {
+        return decodeErrorResult({ abi: CREDENTIAL_REVOCATION_REGISTRY_ABI, data: revertReason }).errorName;
+    }
+    catch {
+        return revertReason;
+    }
+}
+
+/** Decodes `UserOperationEvent`/`UserOperationRevertReason` for one userOpHash out of a mined transaction's logs. */
+function parseUserOperationReceipt(transactionReceipt, entryPointAbi, userOpHash) {
+    const operationEvent = parseEventLogs({
+        abi: entryPointAbi,
+        eventName: "UserOperationEvent",
+        logs: transactionReceipt.logs
+    }).find((event) => event.args.userOpHash === userOpHash);
+    if (!operationEvent) {
+        throw new Error(`no UserOperationEvent for ${userOpHash} in transaction ${transactionReceipt.transactionHash}`);
+    }
+    const revertEvent = parseEventLogs({
+        abi: entryPointAbi,
+        eventName: "UserOperationRevertReason",
+        logs: transactionReceipt.logs
+    }).find((event) => event.args.userOpHash === userOpHash);
+    return {
+        transactionHash: transactionReceipt.transactionHash,
+        success: operationEvent.args.success,
+        actualGasCost: operationEvent.args.actualGasCost,
+        actualGasUsed: operationEvent.args.actualGasUsed,
+        revertReason: revertEvent?.args.revertReason
+    };
+}
+/** Submits to a bundler's JSON-RPC (`eth_sendUserOperation`/`eth_getUserOperationReceipt`), for the member server. */
+class BundlerRpcSubmitter {
+    constructor(url, entryPoint) {
+        this.entryPoint = entryPoint;
+        this.client = createBundlerClient({ transport: http(url) });
+    }
+    async send(userOperation) {
+        return this.client.request({
+            method: "eth_sendUserOperation",
+            params: [formatUserOperationRequest(userOperation), this.entryPoint]
+        });
+    }
+    async waitForReceipt(userOpHash) {
+        const receipt = await this.client.waitForUserOperationReceipt({ hash: userOpHash });
+        return parseUserOperationReceipt(receipt.receipt, entryPoint08Abi, userOpHash);
+    }
+}
+/**
+ * Submits straight to the EntryPoint's `handleOps`, for the stack bundler and the integration
+ * test: no mempool, one operation per call, the beneficiary is the submitting account itself.
+ */
+class EntryPointSubmitter {
+    constructor(client, entryPoint) {
+        this.client = client;
+        this.entryPoint = entryPoint;
+        this.transactionHashes = new Map();
+    }
+    async send(userOperation) {
+        const userOpHash = getUserOperationHash({
+            chainId: this.client.chain.id,
+            entryPointAddress: this.entryPoint,
+            entryPointVersion: "0.8",
+            userOperation
+        });
+        const data = encodeFunctionData({
+            abi: entryPoint08Abi,
+            functionName: "handleOps",
+            args: [[toPackedUserOperation(userOperation)], this.client.account.address]
+        });
+        const transactionHash = await this.client.sendTransaction({
+            account: this.client.account,
+            chain: this.client.chain,
+            to: this.entryPoint,
+            data,
+            authorizationList: [userOperation.authorization]
+        });
+        // waitForReceipt only gets the userOpHash back, so the mapping to the transaction that
+        // carried it has to live here.
+        this.transactionHashes.set(userOpHash, transactionHash);
+        return userOpHash;
+    }
+    async waitForReceipt(userOpHash) {
+        const transactionHash = this.transactionHashes.get(userOpHash);
+        if (transactionHash === undefined)
+            throw new Error(`no transaction sent for user operation ${userOpHash}`);
+        const transactionReceipt = await this.client.waitForTransactionReceipt({ hash: transactionHash });
+        return parseUserOperationReceipt(transactionReceipt, entryPoint08Abi, userOpHash);
+    }
+}
+
+export { ApprovedIssuerSetClient, BundlerRpcSubmitter, CREDENTIAL_REVOCATION_REGISTRY_ABI, DirectRevocationWriter, ERC5564AnnouncerClient, EntryPointSubmitter, IdentityRegistryClient, IdentityRegistryWriter, NetworkMemberClientError, RegistryRevertError, RevocationRevertError, SemaphoreGroupClient, SemaphoreRegistrationProver, SemaphoreRevocationProver, SponsoredIdentityRegistryWriter, SponsoredRelay, SponsoredRevocationWriter, deliverToStealth, fetchIssuerMembershipWitness, issueVC, parseUserOperationReceipt, submitRegistration };