@coordination-network/network-member-client 0.0.1

package/src/types.ts

@@ -0,0 +1,128 @@
+import type { Hex32, SerializedZkCredential } from "@coordination-network/credential"
+import type { IssuerMembershipWitness } from "@coordination-network/issuer-set"
+import type { Address, Hex, buildAnnouncement } from "@coordination-network/identity"
+import type {
+    IdentityUpdate,
+    NetworkMemberProof,
+    RegistryLocation,
+    RevocationUpdate
+} from "@coordination-network/network-member-proof"
+import type { Group } from "@semaphore-protocol/group"
+
+export type { ApprovalResolver, CredentialSigner } from "@coordination-network/credential"
+export type { ContractLeafReader, IssuerMembershipWitness } from "@coordination-network/issuer-set"
+export type { ChainDomain, RegistrationRequest } from "@coordination-network/user-client"
+
+/** issueVC's result: the signed claim-tree credential plus a fresh Merkle path into the approved-issuer set. */
+export interface IssuedCredential {
+    credential: SerializedZkCredential
+    issuerSetRoot: bigint
+    issuerMembershipWitness: IssuerMembershipWitness
+}
+
+/**
+ * Reads `IdentityRegistry.identity(networkId)`. Empty bytes on chain (unregistered) resolves to
+ * null. The method name matches the UserClient's registry-reader port so one adapter serves both.
+ */
+export interface IdentityReader {
+    /** The IdentityRegistry deployment this reader targets, when the reader knows one. submitRegistration checks it against `domain`. */
+    readonly registryAddress?: Address
+    getIdentity(networkId: Hex32): Promise<Hex | null>
+}
+
+/** `buildAnnouncement`'s return shape, derived rather than restated so it can't drift. */
+export type Announcement = ReturnType<typeof buildAnnouncement>
+
+/** Submits a built ERC-5564 announcement on chain. */
+export interface AnnouncementSubmitter {
+    announce(announcement: Announcement): Promise<Hex>
+}
+
+/**
+ * deliverToStealth's result. txHash is the hash of the submitted announce transaction, not proof
+ * of inclusion: confirm it before treating the delivery as done.
+ */
+export interface DeliveredToStealth {
+    stealthAddress: Address
+    announcement: Announcement
+    txHash: Hex
+}
+
+/** The approved-member group, rebuilt fresh on every call so a proof always proves against a live root. */
+export interface GroupMirror {
+    currentGroup(): Promise<Group>
+}
+
+/** Produces the membership proof authorising one IdentityRegistry write. */
+export interface RegistrationProver {
+    /** The IdentityRegistry deployment this proof is bound to. submitRegistration checks it against `domain`. */
+    readonly registry: RegistryLocation
+    prove(update: IdentityUpdate): Promise<NetworkMemberProof>
+}
+
+/** Produces the membership proof authorising one CredentialRevocationRegistry write. */
+export interface RevocationProver {
+    /** The CredentialRevocationRegistry deployment this proof is bound to. */
+    readonly registry: RegistryLocation
+    prove(update: RevocationUpdate): Promise<NetworkMemberProof>
+}
+
+/**
+ * Facts about a sponsored registerIdentity call: what the disposable sender and the paymaster's
+ * deposit looked like before and after, so a caller can show what the paymaster actually paid.
+ */
+export interface Sponsorship {
+    sender: Address
+    senderBalanceBefore: bigint
+    senderBalanceAfter: bigint
+    userOpHash: Hex
+    bundleTxHash: Hex
+    actualGasCost: bigint
+    paymaster: Address
+    paymasterDepositBefore: bigint
+    paymasterDepositAfter: bigint
+}
+
+/**
+ * registerIdentity's result. txHash is the hash of the write (or, when sponsored, the bundle)
+ * transaction, not proof of inclusion: confirm it before treating the registration as done.
+ */
+export interface RegistrationWrite {
+    txHash: Hex
+    sponsorship?: Sponsorship
+}
+
+/** Submits a network-member-authorised write to `IdentityRegistry`. */
+export interface RegistrationWriter {
+    /** The IdentityRegistry deployment this writer targets. submitRegistration checks it against `domain`. */
+    readonly registry: RegistryLocation
+    /** An `AlreadyRegistered` revert must surface as `RegistryRevertError`: submitRegistration's
+     *  lost-race handling keys on that one specifically. Any other revert may surface as any error. */
+    registerIdentity(networkId: Hex32, metaStealthAddress: Hex, proof: NetworkMemberProof): Promise<RegistrationWrite>
+}
+
+/**
+ * revoke's result. txHash is the hash of the write (or, when sponsored, the bundle) transaction,
+ * not proof of inclusion: confirm it before treating the revocation as done.
+ */
+export interface RevocationWrite {
+    txHash: Hex
+    sponsorship?: Sponsorship
+}
+
+/** Submits a network-member-authorised write to `CredentialRevocationRegistry`. */
+export interface RevocationRegistryWriter {
+    /** The CredentialRevocationRegistry deployment this writer targets. */
+    readonly registry: RegistryLocation
+    /** A revert must surface as `RevocationRevertError`: a caller has to tell a stale
+     *  `lowLeafIndex`, which it retries, from an already-revoked commitment, which it does not. */
+    revoke(commitment: bigint, lowLeafIndex: bigint, proof: NetworkMemberProof): Promise<RevocationWrite>
+}
+
+/**
+ * submitRegistration's result. txHash on `submitted` is the hash of the write transaction, not
+ * proof of inclusion: confirm it before treating the registration as done.
+ */
+export type SubmitRegistrationResult =
+    | { status: "submitted"; networkId: Hex32; metaStealthAddress: Hex; txHash: Hex; sponsorship?: Sponsorship }
+    | { status: "alreadyRegistered"; networkId: Hex32; metaStealthAddress: Hex; matchesRequest: boolean }

package/src/user-operation.ts

@@ -0,0 +1,162 @@
+import { encodeFunctionData, http, parseEventLogs } from "viem"
+import type {
+    Account,
+    Address,
+    Chain,
+    Hex,
+    PublicClient,
+    SignedAuthorization,
+    Transport,
+    TransactionReceipt,
+    WalletClient
+} from "viem"
+import {
+    createBundlerClient,
+    entryPoint08Abi,
+    formatUserOperationRequest,
+    getUserOperationHash,
+    toPackedUserOperation
+} from "viem/account-abstraction"
+
+/**
+ * A fully assembled ERC-4337 v0.8 user operation for a 7702-delegated, paymaster-sponsored call.
+ * Every gas and paymaster field is required, never left to a bundler default: `factory` is always
+ * the 7702 marker and `authorization` is always present, since this track has no other kind of op.
+ */
+export interface SponsoredUserOperation {
+    sender: Address
+    nonce: bigint
+    factory: "0x7702"
+    callData: Hex
+    callGasLimit: bigint
+    verificationGasLimit: bigint
+    preVerificationGas: bigint
+    maxFeePerGas: bigint
+    maxPriorityFeePerGas: bigint
+    paymaster: Address
+    paymasterVerificationGasLimit: bigint
+    paymasterPostOpGasLimit: bigint
+    paymasterData: Hex
+    authorization: SignedAuthorization
+    signature: Hex
+}
+
+/** One submitted user operation's outcome, parsed from the EntryPoint's own events so both submitters report the same shape. */
+export interface UserOperationReceipt {
+    transactionHash: Hex
+    success: boolean
+    actualGasCost: bigint
+    actualGasUsed: bigint
+    /** Raw `UserOperationRevertReason` data, present only when `success` is false. */
+    revertReason?: Hex
+}
+
+/** Submits a signed user operation and waits for its outcome. `waitForReceipt` takes the hash `send` returns. */
+export interface UserOperationSubmitter {
+    send(userOperation: SponsoredUserOperation): Promise<Hex>
+    waitForReceipt(userOpHash: Hex): Promise<UserOperationReceipt>
+}
+
+/** Decodes `UserOperationEvent`/`UserOperationRevertReason` for one userOpHash out of a mined transaction's logs. */
+export function parseUserOperationReceipt(
+    transactionReceipt: TransactionReceipt,
+    entryPointAbi: typeof entryPoint08Abi,
+    userOpHash: Hex
+): UserOperationReceipt {
+    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. */
+export class BundlerRpcSubmitter implements UserOperationSubmitter {
+    private readonly client: ReturnType<typeof createBundlerClient>
+
+    constructor(
+        url: string,
+        private readonly entryPoint: Address
+    ) {
+        this.client = createBundlerClient({ transport: http(url) })
+    }
+
+    async send(userOperation: SponsoredUserOperation): Promise<Hex> {
+        return this.client.request({
+            method: "eth_sendUserOperation",
+            params: [formatUserOperationRequest(userOperation), this.entryPoint]
+        })
+    }
+
+    async waitForReceipt(userOpHash: Hex): Promise<UserOperationReceipt> {
+        const receipt = await this.client.waitForUserOperationReceipt({ hash: userOpHash })
+        return parseUserOperationReceipt(receipt.receipt, entryPoint08Abi, userOpHash)
+    }
+}
+
+type EntryPointChainClient = Pick<WalletClient<Transport, Chain, Account>, "account" | "chain" | "sendTransaction"> &
+    Pick<PublicClient, "waitForTransactionReceipt">
+
+/**
+ * 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.
+ */
+export class EntryPointSubmitter implements UserOperationSubmitter {
+    private readonly transactionHashes = new Map<Hex, Hex>()
+
+    constructor(
+        private readonly client: EntryPointChainClient,
+        private readonly entryPoint: Address
+    ) {}
+
+    async send(userOperation: SponsoredUserOperation): Promise<Hex> {
+        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: Hex): Promise<UserOperationReceipt> {
+        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)
+    }
+}

package/src/witness.ts

@@ -0,0 +1,30 @@
+import { ApprovedIssuerSet } from "@coordination-network/issuer-set"
+import type { ContractLeafReader, IssuerMembershipWitness, IssuerPublicKey } from "@coordination-network/issuer-set"
+import { NetworkMemberClientError } from "./errors"
+
+export interface FetchIssuerMembershipWitnessParams {
+    issuerSetReader: ContractLeafReader
+    issuerPublicKey: IssuerPublicKey
+}
+
+export interface IssuerMembershipWitnessResult {
+    root: bigint
+    witness: IssuerMembershipWitness
+}
+
+/** Rebuilds the approved-issuer set from its current on-chain leaves and proves membership against the fresh root. */
+export async function fetchIssuerMembershipWitness({
+    issuerSetReader,
+    issuerPublicKey
+}: FetchIssuerMembershipWitnessParams): Promise<IssuerMembershipWitnessResult> {
+    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) }
+}