arc402-cli 0.2.0

package/scripts/register-agent-userop.ts

@@ -0,0 +1,186 @@
+/**
+ * register-agent-userop.ts
+ * Register GigaBrain in AgentRegistry via ERC-4337 UserOperation.
+ * Machine key signs → Pimlico bundler → EntryPoint executes → wallet is msg.sender.
+ */
+
+import { ethers } from "ethers";
+import { loadConfig } from "../src/config";
+import { BundlerClient, buildUserOp } from "../src/bundler";
+import { ARC402_WALLET_EXECUTE_ABI, AGENT_REGISTRY_ABI } from "../src/abis";
+
+const ENTRY_POINT = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+const CHAIN_ID = 8453;
+
+// EntryPoint v0.7 nonce getter ABI
+const EP_ABI = [
+  "function getNonce(address sender, uint192 key) external view returns (uint256)",
+  "function depositTo(address account) external payable",
+  "function balanceOf(address account) external view returns (uint256)",
+];
+
+async function main() {
+  const config = loadConfig();
+  if (!config.walletContractAddress) throw new Error("walletContractAddress not in config");
+  if (!config.privateKey) throw new Error("privateKey not in config");
+
+  const provider = new ethers.JsonRpcProvider(config.rpcUrl);
+  const machineKey = new ethers.Wallet(config.privateKey, provider);
+  const walletAddress = config.walletContractAddress;
+
+  const agentRegistryAddress =
+    config.agentRegistryV2Address ??
+    "0xD5c2851B00090c92Ba7F4723FB548bb30C9B6865";
+
+  console.log("Wallet:         ", walletAddress);
+  console.log("Machine key:    ", machineKey.address);
+  console.log("AgentRegistry:  ", agentRegistryAddress);
+
+  // ── 1. Check ETH balance ───────────────────────────────────────────────────
+  const balance = await provider.getBalance(walletAddress);
+  console.log("Wallet balance: ", ethers.formatEther(balance), "ETH");
+  if (balance < ethers.parseEther("0.0005")) {
+    throw new Error("Wallet balance too low — need at least 0.0005 ETH");
+  }
+
+  // ── 2. Get nonce from EntryPoint ───────────────────────────────────────────
+  const ep = new ethers.Contract(ENTRY_POINT, EP_ABI, provider);
+  const nonce: bigint = await ep.getNonce(walletAddress, 0);
+  console.log("Nonce:          ", nonce.toString());
+
+  // ── 3. Encode AgentRegistry.register() calldata ───────────────────────────
+  const registryIface = new ethers.Interface(AGENT_REGISTRY_ABI);
+  const registerCalldata = registryIface.encodeFunctionData("register", [
+    "GigaBrain",           // name
+    [],                    // capabilities (empty for now)
+    "ai.assistant",        // serviceType
+    "https://gigabrain.arc402.xyz",  // endpoint
+    "",                    // metadataURI
+  ]);
+
+  // ── 4. Encode ARC402Wallet.executeContractCall() — this is the UserOp callData ──
+  const walletIface = new ethers.Interface(ARC402_WALLET_EXECUTE_ABI);
+  const userOpCallData = walletIface.encodeFunctionData("executeContractCall", [{
+    target: agentRegistryAddress,
+    data: registerCalldata,
+    value: BigInt(0),
+    minReturnValue: BigInt(0),
+    maxApprovalAmount: BigInt(0),
+    approvalToken: ethers.ZeroAddress,
+  }]);
+
+  console.log("UserOp callData built ✓");
+
+  // ── 5. Build UserOp — fetch live gas price from Pimlico ───────────────────
+  // Declare bundlerUrl here so it's available for gas price fetch AND sending
+  const bundlerUrl = (config as unknown as Record<string, unknown>)["bundlerUrl"] as string | undefined ?? "https://public.pimlico.io/v2/8453/rpc";
+  const gasPriceRes = await fetch(bundlerUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "pimlico_getUserOperationGasPrice", params: [] }),
+  });
+  const gasPriceJson = await gasPriceRes.json() as { result?: { fast?: { maxFeePerGas: string; maxPriorityFeePerGas: string } } };
+  const fast = gasPriceJson.result?.fast;
+  if (!fast) throw new Error("Could not fetch gas price from bundler");
+  console.log("Gas price (fast): maxFee=", fast.maxFeePerGas, "maxPriority=", fast.maxPriorityFeePerGas);
+
+  const userOp = await buildUserOp(userOpCallData, walletAddress, nonce, config);
+  // Override with bundler-recommended gas prices
+  userOp.maxFeePerGas = fast.maxFeePerGas;
+  userOp.maxPriorityFeePerGas = fast.maxPriorityFeePerGas;
+  // Bump callGasLimit — executeContractCall + AgentRegistry.register needs ~330k
+  userOp.callGasLimit = ethers.toBeHex(500_000);
+  userOp.verificationGasLimit = ethers.toBeHex(200_000);
+
+  // ── 6. Sign UserOp with machine key ───────────────────────────────────────
+  // ERC-4337 v0.7: hash = keccak256(abi.encode(userOpHash, entryPoint, chainId))
+  // where userOpHash = keccak256(packed(userOp fields))
+  const packedFields = ethers.AbiCoder.defaultAbiCoder().encode(
+    ["address","uint256","bytes32","bytes32","bytes32","uint256","bytes32","bytes32"],
+    [
+      userOp.sender,
+      BigInt(userOp.nonce),
+      ethers.keccak256(ethers.concat(
+        userOp.factory ? [userOp.factory, userOp.factoryData ?? "0x"] : []
+      )),
+      ethers.keccak256(userOp.callData),
+      ethers.concat([
+        ethers.zeroPadValue(ethers.toBeHex(userOp.callGasLimit), 16),
+        ethers.zeroPadValue(ethers.toBeHex(userOp.verificationGasLimit), 16),
+      ]),
+      BigInt(userOp.preVerificationGas),
+      ethers.concat([
+        ethers.zeroPadValue(ethers.toBeHex(userOp.maxPriorityFeePerGas), 16),
+        ethers.zeroPadValue(ethers.toBeHex(userOp.maxFeePerGas), 16),
+      ]),
+      ethers.keccak256(
+        userOp.paymaster
+          ? ethers.concat([
+              userOp.paymaster,
+              ethers.zeroPadValue(ethers.toBeHex(userOp.paymasterVerificationGasLimit ?? "0x0"), 16),
+              ethers.zeroPadValue(ethers.toBeHex(userOp.paymasterPostOpGasLimit ?? "0x0"), 16),
+              userOp.paymasterData ?? "0x",
+            ])
+          : "0x"
+      ),
+    ]
+  );
+  const userOpHash = ethers.keccak256(
+    ethers.AbiCoder.defaultAbiCoder().encode(
+      ["bytes32","address","uint256"],
+      [
+        ethers.keccak256(packedFields),
+        ENTRY_POINT,
+        CHAIN_ID,
+      ]
+    )
+  );
+  console.log("UserOp hash:    ", userOpHash);
+
+  // validateUserOp uses toEthSignedMessageHash — sign the eth-prefixed hash
+  const signature = await machineKey.signMessage(ethers.getBytes(userOpHash));
+  userOp.signature = signature;
+  console.log("Signed ✓");
+
+  // ── 7. Send to bundler ─────────────────────────────────────────────────────
+  const bundler = new BundlerClient(bundlerUrl, ENTRY_POINT, CHAIN_ID);
+
+  console.log("Sending UserOperation to bundler...");
+  let opHash: string;
+  try {
+    opHash = await bundler.sendUserOperation(userOp);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`Bundler rejected UserOp: ${msg}`);
+  }
+  console.log("UserOp hash:    ", opHash);
+  console.log("Waiting for confirmation (up to 60s)...");
+
+  const receipt = await bundler.getUserOperationReceipt(opHash);
+  if (!receipt.success) {
+    throw new Error(`UserOp failed on-chain. Tx: ${receipt.receipt.transactionHash}`);
+  }
+  console.log("✓ AgentRegistry.register() confirmed");
+  console.log("  Tx:", receipt.receipt.transactionHash);
+
+  // ── 8. Claim subdomain ─────────────────────────────────────────────────────
+  console.log("\nClaiming gigabrain.arc402.xyz...");
+  const res = await fetch("https://api.arc402.xyz/register-subdomain", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      subdomain: "gigabrain",
+      walletAddress,
+      tunnelTarget: "https://gigabrain.arc402.xyz",
+    }),
+  });
+  const body = await res.json() as Record<string, unknown>;
+  if (!res.ok) {
+    console.error("✗ Subdomain claim failed:", body["error"] ?? body);
+    process.exit(1);
+  }
+  console.log("✓ Subdomain claimed:", body["subdomain"]);
+  console.log("\nAll done. GigaBrain is registered and live.");
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/src/abis.ts

@@ -0,0 +1,187 @@
+/**
+ * ABIs extracted from the ARC-402 contract sources.
+ * Source: /products/arc-402/reference/contracts/
+ */
+
+export const AGENT_REGISTRY_ABI = [
+  // Registration
+  "function register(string name, string[] capabilities, string serviceType, string endpoint, string metadataURI) external",
+  "function update(string name, string[] capabilities, string serviceType, string endpoint, string metadataURI) external",
+  "function deactivate() external",
+  "function reactivate() external",
+  // Queries
+  "function getAgent(address wallet) external view returns (tuple(address wallet, string name, string[] capabilities, string serviceType, string endpoint, string metadataURI, bool active, uint256 registeredAt))",
+  "function isRegistered(address wallet) external view returns (bool)",
+  "function isActive(address wallet) external view returns (bool)",
+  "function getCapabilities(address wallet) external view returns (string[])",
+  "function getTrustScore(address wallet) external view returns (uint256)",
+  "function agentCount() external view returns (uint256)",
+  "function getAgentAtIndex(uint256 index) external view returns (address)",
+  // Events
+  "event AgentRegistered(address indexed wallet, string name, string serviceType, uint256 timestamp)",
+  "event AgentUpdated(address indexed wallet, string name, string serviceType)",
+  "event AgentDeactivated(address indexed wallet)",
+] as const;
+
+export const SERVICE_AGREEMENT_ABI = [
+  "function propose(address provider, string serviceType, string description, uint256 price, address token, uint256 deadline, bytes32 deliverablesHash) external payable returns (uint256 agreementId)",
+  "function accept(uint256 agreementId) external",
+  "function fulfill(uint256 agreementId, bytes32 actualDeliverablesHash) external",
+  "function commitDeliverable(uint256 agreementId, bytes32 deliverableHash) external",
+  "function verifyDeliverable(uint256 agreementId) external",
+  "function autoRelease(uint256 agreementId) external",
+  "function dispute(uint256 agreementId, string reason) external",
+  "function directDispute(uint256 agreementId, uint8 directReason, string reason) external",
+  "function escalateToDispute(uint256 agreementId, string reason) external",
+  "function requestRevision(uint256 agreementId, bytes32 feedbackHash, string feedbackURI, bytes32 previousTranscriptHash) external",
+  "function respondToRevision(uint256 agreementId, uint8 responseType, uint256 proposedProviderPayout, bytes32 responseHash, string responseURI, bytes32 previousTranscriptHash) external",
+  "function submitDisputeEvidence(uint256 agreementId, uint8 evidenceType, bytes32 evidenceHash, string evidenceURI) external",
+  "function nominateArbitrator(uint256 agreementId, address arbitrator) external",
+  "function castArbitrationVote(uint256 agreementId, uint8 vote, uint256 providerAward, uint256 clientAward) external",
+  "function requestHumanEscalation(uint256 agreementId, string reason) external",
+  "function cancel(uint256 agreementId) external",
+  "function expiredCancel(uint256 agreementId) external",
+  "function resolveDispute(uint256 agreementId, bool favorProvider) external",
+  "function resolveDisputeDetailed(uint256 agreementId, uint8 outcome, uint256 providerAward, uint256 clientAward) external",
+  "function openDisputeWithMode(uint256 agreementId, uint8 mode, uint8 class, string reason) external payable",
+  "function ownerResolveDispute(uint256 agreementId, bool favorProvider) external",
+  "function canDirectDispute(uint256 agreementId, uint8 directReason) external view returns (bool)",
+  "function getAgreement(uint256 id) external view returns (tuple(uint256 id, address client, address provider, string serviceType, string description, uint256 price, address token, uint256 deadline, bytes32 deliverablesHash, uint8 status, uint256 createdAt, uint256 resolvedAt, uint256 verifyWindowEnd, bytes32 committedHash))",
+  "function getDisputeCase(uint256 agreementId) external view returns (tuple(uint256 agreementId, uint256 openedAt, uint256 responseDeadlineAt, uint8 outcome, uint256 providerAward, uint256 clientAward, bool humanReviewRequested, uint256 evidenceCount))",
+  "function getDisputeEvidence(uint256 agreementId, uint256 index) external view returns (tuple(address submitter, uint8 evidenceType, bytes32 evidenceHash, string evidenceURI, uint256 timestamp))",
+  "function getArbitrationCase(uint256 agreementId) external view returns (tuple(uint256 agreementId, address[3] arbitrators, uint8 arbitratorCount, uint8 providerVotes, uint8 clientVotes, uint8 splitVotes, uint8 humanVotes, uint256 selectionDeadlineAt, uint256 decisionDeadlineAt, uint256 splitProviderAward, uint256 splitClientAward, bool finalized, bool humanBackstopUsed))",
+  "function getAgreementsByClient(address client) external view returns (uint256[])",
+  "function getAgreementsByProvider(address provider) external view returns (uint256[])",
+  "function agreementCount() external view returns (uint256)",
+  "function openSessionChannel(address provider, address token, uint256 maxAmount, uint256 ratePerCall, uint256 deadline) external payable returns (bytes32)",
+  "function closeChannel(bytes32 channelId, bytes finalState) external",
+  "function challengeChannel(bytes32 channelId, bytes latestState) external",
+  "function finaliseChallenge(bytes32 channelId) external",
+  "function reclaimExpiredChannel(bytes32 channelId) external",
+  "function getChannel(bytes32 channelId) external view returns (tuple(address client, address provider, address token, uint256 depositAmount, uint256 settledAmount, uint256 lastSequenceNumber, uint256 deadline, uint256 challengeExpiry, uint8 status))",
+  "function getChannelsByClient(address client) external view returns (bytes32[])",
+  "function getChannelsByProvider(address provider) external view returns (bytes32[])",
+  "function resolveFromArbitration(uint256 agreementId, address recipient, uint256 amount) external",
+  "event AgreementProposed(uint256 indexed id, address indexed client, address indexed provider, string serviceType, uint256 price, address token, uint256 deadline)",
+  "event AgreementAccepted(uint256 indexed id, address indexed provider)",
+  "event AgreementFulfilled(uint256 indexed id, address indexed provider, bytes32 deliverablesHash)",
+  "event AgreementDisputed(uint256 indexed id, address indexed initiator, string reason)",
+  "event AgreementCancelled(uint256 indexed id, address indexed client)",
+] as const;
+
+export const TRUST_REGISTRY_ABI = [
+  "function getScore(address wallet) external view returns (uint256)",
+  "function getTrustLevel(address wallet) external view returns (string)",
+  "function initWallet(address wallet) external",
+  "function recordSuccess(address wallet) external",
+  "function recordAnomaly(address wallet) external",
+  "function owner() external view returns (address)",
+] as const;
+
+export const ERC20_ABI = [
+  "function approve(address spender, uint256 amount) external returns (bool)",
+  "function allowance(address owner, address spender) external view returns (uint256)",
+  "function balanceOf(address owner) external view returns (uint256)",
+  "function decimals() external view returns (uint8)",
+  "function symbol() external view returns (string)",
+] as const;
+
+export const WALLET_FACTORY_ABI = [
+  "function createWallet(address _entryPoint) external returns (address)",
+  "function getWallets(address owner) external view returns (address[] memory)",
+  "function totalWallets() external view returns (uint256)",
+  "event WalletCreated(address indexed owner, address indexed walletAddress)",
+] as const;
+
+export const POLICY_ENGINE_LIMITS_ABI = [
+  // Auto-getters from public mappings (actual on-chain function names)
+  "function categoryLimits(address wallet, string category) external view returns (uint256)",
+  "function dailyCategoryLimit(address wallet, string category) external view returns (uint256)",
+  // Owner-callable setters
+  "function setCategoryLimitFor(address wallet, string category, uint256 limitPerTx) external",
+  "function setDailyLimitFor(address wallet, string category, uint256 limit) external",
+] as const;
+
+// PolicyEngine governance functions — for onboarding ceremony
+export const POLICY_ENGINE_GOVERNANCE_ABI = [
+  // registerWallet requires msg.sender == wallet — route through wallet's executeContractCall
+  "function registerWallet(address wallet, address owner) external",
+  // enableDefiAccess: onlyWalletOwnerOrWallet — owner can call directly on PolicyEngine
+  "function enableDefiAccess(address wallet) external",
+  // isRegistered check helper
+  "function walletOwners(address wallet) external view returns (address)",
+  "function defiAccessEnabled(address wallet) external view returns (bool)",
+] as const;
+
+export const ARC402_WALLET_EXECUTE_ABI = [
+  "function executeContractCall((address target, bytes data, uint256 value, uint256 minReturnValue, uint256 maxApprovalAmount, address approvalToken) params) external returns (bytes memory)",
+] as const;
+
+// Direct protocol functions — all onlyOwnerOrMachineKey, never route through executeContractCall
+export const ARC402_WALLET_PROTOCOL_ABI = [
+  "function openContext(bytes32 contextId, string calldata taskType) external",
+  "function closeContext() external",
+  "function contextOpen() external view returns (bool)",
+  "function attest(bytes32 attestationId, string calldata action, string calldata reason, address recipient, uint256 amount, address token, uint256 expiresAt) external returns (bytes32)",
+  "function executeSpend(address payable recipient, uint256 amount, string calldata category, bytes32 attestationId) external",
+  "function executeTokenSpend(address recipient, uint256 amount, address token, string calldata category, bytes32 attestationId) external",
+] as const;
+
+export const ARC402_WALLET_GUARDIAN_ABI = [
+  // Guardian management (owner only)
+  "function setGuardian(address _guardian) external",
+  // Guardian freeze functions (guardian key only)
+  "function freeze() external",
+  "function freezeAndDrain() external",
+  // Owner freeze (with reason)
+  "function freeze(string reason) external",
+  // Owner unfreeze
+  "function unfreeze() external",
+  // State queries
+  "function frozen() external view returns (bool)",
+  "function frozenBy() external view returns (address)",
+  "function frozenAt() external view returns (uint256)",
+  "function guardian() external view returns (address)",
+  "function owner() external view returns (address)",
+  // Events
+  "event WalletFrozen(address indexed by, string reason, uint256 timestamp)",
+  "event WalletUnfrozen(address indexed by, uint256 timestamp)",
+  "event GuardianUpdated(address indexed newGuardian)",
+] as const;
+
+export const ARC402_WALLET_REGISTRY_ABI = [
+  "function proposeRegistryUpdate(address newRegistry) external",
+  "function executeRegistryUpdate() external",
+  "function cancelRegistryUpdate() external",
+  "function pendingRegistry() external view returns (address)",
+  "function registryUpdateUnlockAt() external view returns (uint256)",
+  "function registry() external view returns (address)",
+] as const;
+
+export const ARC402_WALLET_OWNER_ABI = [
+  // Owner-only setters
+  "function setAuthorizedInterceptor(address interceptor) external",
+  "function setVelocityLimit(uint256 limit) external",
+  "function updatePolicy(bytes32 newPolicyId) external",
+  // State queries
+  "function authorizedInterceptor() external view returns (address)",
+  "function velocityLimit() external view returns (uint256)",
+  "function velocityWindowStart() external view returns (uint256)",
+  "function cumulativeSpend() external view returns (uint256)",
+  "function activePolicyId() external view returns (bytes32)",
+] as const;
+
+export const ARC402_WALLET_MACHINE_KEY_ABI = [
+  "function authorizeMachineKey(address key) external",
+  "function revokeMachineKey(address key) external",
+  "function authorizedMachineKeys(address key) external view returns (bool)",
+] as const;
+
+export const ARC402_WALLET_PASSKEY_ABI = [
+  "function setPasskey(bytes32 pubKeyX, bytes32 pubKeyY) external",
+  "function clearPasskey() external",
+  "function emergencyOwnerOverride(bytes32 newPubKeyX, bytes32 newPubKeyY) external",
+  "function emergencyOwnerOverride() external",
+  "function ownerAuth() external view returns (uint8 signerType, bytes32 pubKeyX, bytes32 pubKeyY)",
+  "event PasskeySet(bytes32 indexed pubKeyX, bytes32 pubKeyY)",
+] as const;

package/src/bundler.ts

@@ -0,0 +1,235 @@
+import { ethers } from "ethers";
+import { createPrivateKey } from "crypto";
+import type { Arc402Config } from "./config";
+
+export const DEFAULT_ENTRY_POINT = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+export const DEFAULT_BUNDLER_URL = "https://api.pimlico.io/v2/base/rpc";
+
+export type UserOperation = {
+  sender: string;
+  nonce: string;                              // hex
+  callData: string;                           // hex
+  callGasLimit: string;                       // hex
+  verificationGasLimit: string;               // hex
+  preVerificationGas: string;                 // hex
+  maxFeePerGas: string;                       // hex
+  maxPriorityFeePerGas: string;              // hex
+  signature: string;                          // hex — empty for policy-auto-approved ops
+  factory?: string;
+  factoryData?: string;
+  paymaster?: string;
+  paymasterData?: string;
+  paymasterVerificationGasLimit?: string;
+  paymasterPostOpGasLimit?: string;
+};
+
+export type GasEstimate = {
+  callGasLimit: string;
+  verificationGasLimit: string;
+  preVerificationGas: string;
+  paymasterVerificationGasLimit?: string;
+  paymasterPostOpGasLimit?: string;
+};
+
+export type UserOpReceipt = {
+  userOpHash: string;
+  entryPoint: string;
+  sender: string;
+  nonce: string;
+  success: boolean;
+  actualGasCost: string;
+  actualGasUsed: string;
+  logs: unknown[];
+  receipt: {
+    transactionHash: string;
+    blockNumber: string;
+    blockHash: string;
+    [key: string]: unknown;
+  };
+};
+
+type RpcResponse = {
+  result?: unknown;
+  error?: { code: number; message: string };
+};
+
+export class BundlerClient {
+  private bundlerUrl: string;
+  private entryPointAddress: string;
+  private chainId: number;
+
+  constructor(bundlerUrl: string, entryPointAddress: string, chainId: number) {
+    this.bundlerUrl = bundlerUrl;
+    this.entryPointAddress = entryPointAddress;
+    this.chainId = chainId;
+  }
+
+  private async rpc(method: string, params: unknown[]): Promise<unknown> {
+    const response = await fetch(this.bundlerUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    if (!response.ok) {
+      throw new Error(`Bundler HTTP ${response.status}: ${response.statusText}`);
+    }
+    const json = (await response.json()) as RpcResponse;
+    if (json.error) {
+      throw new Error(`Bundler RPC error [${json.error.code}]: ${json.error.message}`);
+    }
+    return json.result;
+  }
+
+  async sendUserOperation(userOp: UserOperation): Promise<string> {
+    const hash = await this.rpc("eth_sendUserOperation", [userOp, this.entryPointAddress]);
+    return hash as string;
+  }
+
+  async getUserOperationReceipt(userOpHash: string): Promise<UserOpReceipt> {
+    const POLL_INTERVAL_MS = 2000;
+    const MAX_ATTEMPTS = 30;
+    for (let i = 0; i < MAX_ATTEMPTS; i++) {
+      const receipt = await this.rpc("eth_getUserOperationReceipt", [userOpHash]);
+      if (receipt !== null && receipt !== undefined) {
+        return receipt as UserOpReceipt;
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    throw new Error(
+      `UserOperation ${userOpHash} not confirmed after ${(MAX_ATTEMPTS * POLL_INTERVAL_MS) / 1000}s`
+    );
+  }
+
+  async estimateUserOperationGas(userOp: Partial<UserOperation>): Promise<GasEstimate> {
+    const estimate = await this.rpc("eth_estimateUserOperationGas", [
+      userOp,
+      this.entryPointAddress,
+    ]);
+    return estimate as GasEstimate;
+  }
+}
+
+// ─── PaymasterClient ──────────────────────────────────────────────────────────
+
+export class PaymasterClient {
+  private paymasterUrl: string;
+  private cdpKeyName?: string;
+  private cdpPrivateKey?: string;
+
+  constructor(paymasterUrl: string, cdpKeyName?: string, cdpPrivateKey?: string) {
+    this.paymasterUrl = paymasterUrl;
+    this.cdpKeyName = cdpKeyName;
+    this.cdpPrivateKey = cdpPrivateKey;
+  }
+
+  private async buildJwt(): Promise<string | null> {
+    if (!this.cdpKeyName || !this.cdpPrivateKey) return null;
+    const { SignJWT, importPKCS8 } = await import("jose");
+
+    // Convert SEC1 base64 DER or SEC1 PEM → PKCS8 PEM using Node's crypto module
+    let pkcs8Pem: string;
+    if (this.cdpPrivateKey.includes("-----BEGIN")) {
+      if (this.cdpPrivateKey.includes("EC PRIVATE KEY")) {
+        const key = createPrivateKey({ key: this.cdpPrivateKey, format: "pem", type: "sec1" });
+        pkcs8Pem = key.export({ format: "pem", type: "pkcs8" }) as string;
+      } else {
+        pkcs8Pem = this.cdpPrivateKey;
+      }
+    } else {
+      const der = Buffer.from(this.cdpPrivateKey, "base64");
+      const key = createPrivateKey({ key: der, format: "der", type: "sec1" });
+      pkcs8Pem = key.export({ format: "pem", type: "pkcs8" }) as string;
+    }
+
+    const privateKey = await importPKCS8(pkcs8Pem, "ES256");
+    const now = Math.floor(Date.now() / 1000);
+    return new SignJWT({ sub: this.cdpKeyName })
+      .setProtectedHeader({ alg: "ES256", kid: this.cdpKeyName })
+      .setIssuer(this.cdpKeyName)
+      .setNotBefore(now)
+      .setExpirationTime(now + 120)
+      .sign(privateKey);
+  }
+
+  private async rpc(method: string, params: unknown[]): Promise<unknown> {
+    const jwt = await this.buildJwt();
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (jwt) headers["Authorization"] = `Bearer ${jwt}`;
+    const response = await fetch(this.paymasterUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    if (!response.ok) {
+      throw new Error(`Paymaster HTTP ${response.status}: ${response.statusText}`);
+    }
+    const json = (await response.json()) as { result?: unknown; error?: { code: number; message: string } };
+    if (json.error) {
+      throw new Error(`Paymaster RPC error [${json.error.code}]: ${json.error.message}`);
+    }
+    return json.result;
+  }
+
+  async sponsorUserOperation(
+    userOp: Partial<UserOperation>,
+    entryPoint: string
+  ): Promise<UserOperation> {
+    const result = (await this.rpc("pm_sponsorUserOperation", [userOp, entryPoint, {}])) as {
+      paymaster: string;
+      paymasterData: string;
+      paymasterVerificationGasLimit: string;
+      paymasterPostOpGasLimit: string;
+      callGasLimit?: string;
+      verificationGasLimit?: string;
+      preVerificationGas?: string;
+    };
+    return {
+      ...(userOp as UserOperation),
+      paymaster: result.paymaster,
+      paymasterData: result.paymasterData,
+      paymasterVerificationGasLimit: result.paymasterVerificationGasLimit,
+      paymasterPostOpGasLimit: result.paymasterPostOpGasLimit,
+      ...(result.callGasLimit && { callGasLimit: result.callGasLimit }),
+      ...(result.verificationGasLimit && { verificationGasLimit: result.verificationGasLimit }),
+      ...(result.preVerificationGas && { preVerificationGas: result.preVerificationGas }),
+    };
+  }
+}
+
+// ─── buildUserOp / buildSponsoredUserOp ───────────────────────────────────────
+
+export async function buildUserOp(
+  callData: string,
+  sender: string,
+  nonce: bigint,
+  config: Arc402Config
+): Promise<UserOperation> {
+  const provider = new ethers.JsonRpcProvider(config.rpcUrl);
+  const feeData = await provider.getFeeData();
+
+  const maxFeePerGas = feeData.maxFeePerGas ?? BigInt(1_000_000_000);
+  const maxPriorityFeePerGas = feeData.maxPriorityFeePerGas ?? BigInt(100_000_000);
+
+  return {
+    sender,
+    nonce: ethers.toBeHex(nonce),
+    callData,
+    callGasLimit: ethers.toBeHex(300_000),
+    verificationGasLimit: ethers.toBeHex(150_000),
+    preVerificationGas: ethers.toBeHex(50_000),
+    maxFeePerGas: ethers.toBeHex(maxFeePerGas),
+    maxPriorityFeePerGas: ethers.toBeHex(maxPriorityFeePerGas),
+    signature: "0x",
+  };
+}
+
+export async function buildSponsoredUserOp(
+  callData: string,
+  sender: string,
+  nonce: bigint,
+  config: Arc402Config,
+  paymasterClient: PaymasterClient
+): Promise<UserOperation> {
+  const userOp = await buildUserOp(callData, sender, nonce, config);
+  return paymasterClient.sponsorUserOperation(userOp, DEFAULT_ENTRY_POINT);
+}

package/src/client.ts

@@ -0,0 +1,34 @@
+import { ethers } from "ethers";
+import { Arc402Config } from "./config";
+
+export interface Arc402Client {
+  provider: ethers.JsonRpcProvider;
+  signer: ethers.Wallet | null;
+  address: string | null;
+}
+
+export async function getClient(config: Arc402Config): Promise<Arc402Client> {
+  const provider = new ethers.JsonRpcProvider(config.rpcUrl);
+
+  if (config.privateKey) {
+    const signer = new ethers.Wallet(config.privateKey, provider);
+    const address = await signer.getAddress();
+    return { provider, signer, address };
+  }
+
+  return { provider, signer: null, address: null };
+}
+
+export async function requireSigner(
+  config: Arc402Config
+): Promise<{ provider: ethers.JsonRpcProvider; signer: ethers.Wallet; address: string }> {
+  const { provider, signer } = await getClient(config);
+  if (!signer) {
+    console.error(
+      "No private key configured. Run `arc402 config init` and provide a private key."
+    );
+    process.exit(1);
+  }
+  const address = await signer.getAddress();
+  return { provider, signer, address };
+}