@coordination-network/network-member-client 0.0.1

package/src/index.ts

@@ -0,0 +1,53 @@
+export type { NetworkMemberClientErrorCode } from "./errors"
+export { NetworkMemberClientError, RegistryRevertError, RevocationRevertError } from "./errors"
+export type {
+    Announcement,
+    AnnouncementSubmitter,
+    ApprovalResolver,
+    ChainDomain,
+    ContractLeafReader,
+    CredentialSigner,
+    DeliveredToStealth,
+    GroupMirror,
+    IdentityReader,
+    IssuedCredential,
+    IssuerMembershipWitness,
+    RegistrationProver,
+    RegistrationRequest,
+    RegistrationWrite,
+    RegistrationWriter,
+    RevocationProver,
+    RevocationRegistryWriter,
+    RevocationWrite,
+    Sponsorship,
+    SubmitRegistrationResult
+} from "./types"
+export type { FetchIssuerMembershipWitnessParams, IssuerMembershipWitnessResult } from "./witness"
+export { fetchIssuerMembershipWitness } from "./witness"
+export type { IssueVCPorts } from "./issue"
+export { issueVC } from "./issue"
+export type { DeliverToStealthParams, DeliverToStealthPorts } from "./deliver"
+export { deliverToStealth } from "./deliver"
+export type { SubmitRegistrationPorts } from "./submit"
+export { submitRegistration } from "./submit"
+export type { SemaphoreRegistrationProverParams, SemaphoreRevocationProverParams } from "./adapters"
+export {
+    ApprovedIssuerSetClient,
+    ERC5564AnnouncerClient,
+    IdentityRegistryClient,
+    IdentityRegistryWriter,
+    SemaphoreGroupClient,
+    SemaphoreRegistrationProver,
+    SemaphoreRevocationProver
+} from "./adapters"
+export type { SponsoredIdentityRegistryWriterParams } from "./sponsored"
+export { SponsoredIdentityRegistryWriter } from "./sponsored"
+export type { RelayCall, RelayedCall, SponsoredMemberKeys, SponsoredRelayParams } from "./sponsored-relay"
+export { SponsoredRelay } from "./sponsored-relay"
+export {
+    CREDENTIAL_REVOCATION_REGISTRY_ABI,
+    DirectRevocationWriter,
+    SponsoredRevocationWriter
+} from "./sponsored-revocation"
+export type { SponsoredUserOperation, UserOperationReceipt, UserOperationSubmitter } from "./user-operation"
+export { BundlerRpcSubmitter, EntryPointSubmitter, parseUserOperationReceipt } from "./user-operation"

package/src/issue.ts

@@ -0,0 +1,29 @@
+import { issueZkCredential, serializeZkCredential } from "@coordination-network/credential"
+import type { ApprovalResolver, CredentialSigner, ZkCredentialIssueParams } from "@coordination-network/credential"
+import type { ContractLeafReader } from "@coordination-network/issuer-set"
+import type { IssuedCredential } from "./types"
+import { fetchIssuerMembershipWitness } from "./witness"
+
+export interface IssueVCPorts {
+    signer: CredentialSigner
+    approval: ApprovalResolver
+    issuerSetReader: ContractLeafReader
+}
+
+/**
+ * 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.
+ */
+export async function issueVC(
+    params: ZkCredentialIssueParams,
+    { signer, approval, issuerSetReader }: IssueVCPorts
+): Promise<IssuedCredential> {
+    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 }
+}

package/src/sponsored-relay.ts

@@ -0,0 +1,242 @@
+import { encodeAbiParameters, encodeFunctionData } from "viem"
+import type { Address, Hex, PublicClient } from "viem"
+import { entryPoint08Abi, getUserOperationHash } from "viem/account-abstraction"
+import { privateKeyToAccount } from "viem/accounts"
+import { buildAnnouncement, generateStealthPrivateKey } from "@coordination-network/identity"
+import { generateProof } from "@semaphore-protocol/proof"
+import type { Identity } from "@semaphore-protocol/identity"
+import type { GroupMirror, Sponsorship } from "./types"
+import type { SponsoredUserOperation, UserOperationReceipt, UserOperationSubmitter } from "./user-operation"
+
+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: []
+    }
+] as const
+
+const PAYMASTER_ABI = [
+    { type: "function", name: "getDeposit", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] }
+] as const
+
+/** `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]" }
+] as const
+
+/** Fixed at the contract's own minimums/limits; not worth exposing as constructor knobs for one call site. */
+const GAS_LIMITS = {
+    callGasLimit: 700_000n,
+    verificationGasLimit: 500_000n,
+    preVerificationGas: 100_000n,
+    paymasterVerificationGasLimit: 600_000n,
+    paymasterPostOpGasLimit: 50_000n
+} as const
+const GAS_FEE_PER_GAS = 1_000_000_000n // 1 gwei
+
+export interface SponsoredMemberKeys {
+    /** The member's own long-term meta-stealth address; each call derives a fresh, disposable sender from it. */
+    metaStealthAddress: Hex
+    spendingPrivateKey: Hex
+    viewingPrivateKey: Hex
+}
+
+export interface SponsoredRelayParams {
+    chainId: number
+    entryPoint: Address
+    paymaster: Address
+    accountImplementation: Address
+    memberKeys: SponsoredMemberKeys
+    /** The member's own Semaphore identity; must be a leaf of `paymasterGroup`. */
+    paymasterIdentity: Identity
+    /** The paymaster's own mirrored Semaphore group (its admitted members, not the network's). */
+    paymasterGroup: GroupMirror
+    submitter: UserOperationSubmitter
+    publicClient: Pick<PublicClient, "getBalance" | "getTransactionCount" | "readContract">
+}
+
+/** One relayed call's outcome: whatever the EntryPoint reported, plus what the sponsorship cost. */
+export interface RelayedCall {
+    receipt: UserOperationReceipt
+    sponsorship: Sponsorship
+}
+
+/** The call to relay. `value` defaults to zero, which is every call this track makes today. */
+export interface RelayCall {
+    target: Address
+    value?: bigint
+    data: Hex
+}
+
+/**
+ * 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.
+ */
+export class SponsoredRelay {
+    private readonly chainId: number
+    private readonly entryPoint: Address
+    private readonly paymaster: Address
+    private readonly accountImplementation: Address
+    private readonly memberKeys: SponsoredMemberKeys
+    private readonly paymasterIdentity: Identity
+    private readonly paymasterGroup: GroupMirror
+    private readonly submitter: UserOperationSubmitter
+    private readonly publicClient: Pick<PublicClient, "getBalance" | "getTransactionCount" | "readContract">
+
+    constructor(params: SponsoredRelayParams) {
+        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 }: RelayCall): Promise<RelayedCall> {
+        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: SponsoredUserOperation = {
+            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: SponsoredUserOperation = { ...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.
+     */
+    private 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)
+    }
+
+    private readPaymasterDeposit(): Promise<bigint> {
+        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). */
+    private async buildPaymasterProof(sender: Address): Promise<Hex> {
+        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) as unknown as readonly [
+                bigint,
+                bigint,
+                bigint,
+                bigint,
+                bigint,
+                bigint,
+                bigint,
+                bigint
+            ]
+        ])
+    }
+}

package/src/sponsored-revocation.ts

@@ -0,0 +1,120 @@
+import { decodeErrorResult, encodeFunctionData } from "viem"
+import type { Account, Chain, Hex, Transport, WalletClient } from "viem"
+import type { NetworkMemberProof, RegistryLocation } from "@coordination-network/network-member-proof"
+import { revertErrorName } from "./adapters"
+import { RevocationRevertError } from "./errors"
+import { SponsoredRelay } from "./sponsored-relay"
+import type { RevocationRegistryWriter, RevocationWrite } from "./types"
+
+/**
+ * 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.
+ */
+export 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: [] }
+] as const
+
+/**
+ * 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.
+ */
+export class SponsoredRevocationWriter implements RevocationRegistryWriter {
+    constructor(
+        readonly registry: RegistryLocation,
+        private readonly relay: SponsoredRelay
+    ) {}
+
+    async revoke(commitment: bigint, lowLeafIndex: bigint, proof: NetworkMemberProof): Promise<RevocationWrite> {
+        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`.
+ */
+export class DirectRevocationWriter implements RevocationRegistryWriter {
+    constructor(
+        readonly registry: RegistryLocation,
+        private readonly walletClient: Pick<WalletClient<Transport, Chain, Account>, "writeContract">
+    ) {}
+
+    async revoke(commitment: bigint, lowLeafIndex: bigint, proof: NetworkMemberProof): Promise<RevocationWrite> {
+        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: Hex | undefined): string {
+    if (revertReason === undefined) return "reverted without a reason"
+    try {
+        return decodeErrorResult({ abi: CREDENTIAL_REVOCATION_REGISTRY_ABI, data: revertReason }).errorName
+    } catch {
+        return revertReason
+    }
+}

package/src/sponsored.ts

@@ -0,0 +1,63 @@
+import { decodeErrorResult, encodeFunctionData } from "viem"
+import type { Hex } from "viem"
+import type { Hex32 } from "@coordination-network/credential"
+import type { NetworkMemberProof, RegistryLocation } from "@coordination-network/network-member-proof"
+import { IDENTITY_REGISTRY_ABI } from "./adapters"
+import { RegistryRevertError } from "./errors"
+import { SponsoredRelay } from "./sponsored-relay"
+import type { SponsoredRelayParams } from "./sponsored-relay"
+import type { RegistrationWrite, RegistrationWriter } from "./types"
+
+export type { SponsoredMemberKeys } from "./sponsored-relay"
+
+export interface SponsoredIdentityRegistryWriterParams extends SponsoredRelayParams {
+    registry: RegistryLocation
+}
+
+/**
+ * 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.
+ */
+export class SponsoredIdentityRegistryWriter implements RegistrationWriter {
+    readonly registry: RegistryLocation
+    private readonly relay: SponsoredRelay
+
+    constructor({ registry, ...relayParams }: SponsoredIdentityRegistryWriterParams) {
+        this.registry = registry
+        this.relay = new SponsoredRelay(relayParams)
+    }
+
+    async registerIdentity(
+        networkId: Hex32,
+        metaStealthAddress: Hex,
+        proof: NetworkMemberProof
+    ): Promise<RegistrationWrite> {
+        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: Hex): string | undefined {
+    try {
+        return decodeErrorResult({ abi: IDENTITY_REGISTRY_ABI, data: revertReason }).errorName
+    } catch {
+        return undefined
+    }
+}

package/src/submit.ts

@@ -0,0 +1,111 @@
+import { verifyRegistrationRequest } from "@coordination-network/user-client"
+import type { ChainDomain, RegistrationRequest } from "@coordination-network/user-client"
+import { UpdateAction } from "@coordination-network/network-member-proof"
+import type { RegistryLocation } from "@coordination-network/network-member-proof"
+import type { Address, Hex } from "@coordination-network/identity"
+import { NetworkMemberClientError, RegistryRevertError } from "./errors"
+import type { IdentityReader, RegistrationProver, RegistrationWriter, SubmitRegistrationResult } from "./types"
+
+export interface SubmitRegistrationPorts {
+    domain: ChainDomain
+    identityReader: IdentityReader
+    prover: RegistrationProver
+    writer: RegistrationWriter
+}
+
+/** Throws when `port`'s bound registry doesn't match `domain`: a member-app wiring bug, not something a request can trigger. */
+function assertRegistryMatches(port: "prover" | "writer", registry: RegistryLocation, domain: RegistryLocation): void {
+    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: Address | undefined, domain: RegistryLocation): void {
+    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: IdentityReader, networkId: Hex): Promise<Hex | null> {
+    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.
+ */
+export async function submitRegistration(
+    request: RegistrationRequest,
+    { domain, identityReader, prover, writer }: SubmitRegistrationPorts
+): Promise<SubmitRegistrationResult> {
+    const registryDomain: RegistryLocation = { 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: Hex | null
+                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
+        )
+    }
+}