@rubicon-caliga/agent-sdk 0.1.0 → 0.1.1

package/src/circle-agent-wallet.ts

@@ -0,0 +1,210 @@
+import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import { x402Client } from "@x402/core/client";
+import { registerBatchScheme } from "@circle-fin/x402-batching/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import {
+  initiateDeveloperControlledWalletsClient,
+  type CircleDeveloperControlledWalletsClient,
+} from "@circle-fin/developer-controlled-wallets";
+import type { AgentPaymentEngine } from "./payment-engine.js";
+
+export interface CircleAgentWalletEngineOptions {
+  /** Circle API key that controls the Agent Wallet. */
+  apiKey: string;
+  /** Entity secret registered for the Circle developer account. */
+  entitySecret: string;
+  /** The Agent Wallet that holds USDC and signs each one-word payment. */
+  walletId: string;
+  /**
+   * The wallet's on-chain address. Optional — when omitted it is resolved once
+   * from the Circle API via `getWallet` before the first payment is signed.
+   */
+  walletAddress?: `0x${string}`;
+  /** Override the Circle API base URL (e.g. sandbox vs. production). */
+  baseUrl?: string;
+  /** Pre-built Circle client. Mainly an injection point for tests. */
+  client?: CircleDeveloperControlledWalletsClient;
+}
+
+/** The minimal EIP-712 signing request the x402 client hands to a signer. */
+interface TypedDataRequest {
+  domain: Record<string, unknown>;
+  types: Record<string, unknown>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+/**
+ * viem-shaped signer (`{ address, signTypedData }`) that delegates EIP-712
+ * signing to a Circle Agent Wallet over the API instead of holding a raw
+ * private key. Satisfies both the batch (`BatchEvmSigner`) and exact
+ * (`ClientEvmSigner`) signer contracts used by the Circle x402 schemes.
+ */
+class CircleAgentWalletSigner {
+  // Populated before the first signature — either from options or via getWallet.
+  address: `0x${string}` = "0x0000000000000000000000000000000000000000";
+  private resolved = false;
+  private resolving?: Promise<void>;
+
+  constructor(
+    private readonly client: CircleDeveloperControlledWalletsClient,
+    private readonly walletId: string,
+    address?: `0x${string}`,
+  ) {
+    if (address) {
+      this.address = address;
+      this.resolved = true;
+    }
+  }
+
+  /** Resolves and caches the wallet's on-chain address (idempotent). */
+  async ensureAddress(): Promise<void> {
+    if (this.resolved) return;
+    if (!this.resolving) {
+      this.resolving = this.client.getWallet({ id: this.walletId }).then((res) => {
+        const address = res.data?.wallet.address;
+        if (!address) {
+          throw new Error(`Circle wallet ${this.walletId} did not return an on-chain address`);
+        }
+        this.address = address as `0x${string}`;
+        this.resolved = true;
+      });
+    }
+    return this.resolving;
+  }
+
+  async signTypedData(typed: TypedDataRequest): Promise<`0x${string}`> {
+    // The schemes read `address` synchronously while building the payload, so
+    // make sure it is resolved before we sign.
+    await this.ensureAddress();
+    const res = await this.client.signTypedData({
+      walletId: this.walletId,
+      data: serializeTypedData(toEip712Payload(typed)),
+      memo: "Rubicon one-word payment",
+    });
+    const signature = res.data?.signature;
+    if (!signature) {
+      throw new Error("Circle Agent Wallet did not return a signature for the x402 payment");
+    }
+    return signature as `0x${string}`;
+  }
+}
+
+/**
+ * Circle Agent Wallet engine. Signs the gateway's one-word x402 terms with a
+ * custodial Circle Agent Wallet — the recommended buyer setup — so the agent
+ * never handles a local signing key. Settlement may be batched by Circle, but
+ * each signed payload still corresponds to exactly one word.
+ */
+export class CircleAgentWalletEngine implements AgentPaymentEngine {
+  private readonly x402 = new x402Client();
+  private readonly signer: CircleAgentWalletSigner;
+
+  constructor(options: CircleAgentWalletEngineOptions) {
+    const client =
+      options.client ??
+      initiateDeveloperControlledWalletsClient({
+        apiKey: options.apiKey,
+        entitySecret: options.entitySecret,
+        ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+      });
+    this.signer = new CircleAgentWalletSigner(client, options.walletId, options.walletAddress);
+    // Gasless Gateway batching with an `exact` EIP-3009 fallback. The signer is
+    // a custodial Circle Agent Wallet, not a local private key.
+    registerBatchScheme(this.x402, {
+      signer: this.signer,
+      fallbackScheme: new ExactEvmScheme(this.signer),
+    });
+  }
+
+  async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 one-word payment requirement");
+    }
+    // Resolve the wallet address up front so the synchronous `address` read
+    // inside createPaymentPayload sees a real value.
+    await this.signer.ensureAddress();
+    return {
+      paymentPayload: await this.x402.createPaymentPayload(session.paymentRequired as never),
+    };
+  }
+}
+
+/**
+ * Circle's signTypedData API expects a complete EIP-712 document as a JSON
+ * string. The x402 schemes pass viem-style typed data, which omits the implicit
+ * `EIP712Domain` type, so add it back from whichever domain fields are present.
+ *
+ * Exported for unit testing — application code never calls this directly.
+ */
+/**
+ * Serialize an EIP-712 document to the JSON string Circle's API expects. The
+ * `exact` fallback scheme passes the authorization's `value`/`validAfter`/
+ * `validBefore` as bigints, which `JSON.stringify` cannot encode — emit them as
+ * decimal strings (the EIP-712 JSON convention) instead of throwing.
+ *
+ * Exported for unit testing — application code never calls this directly.
+ */
+export function serializeTypedData(typed: ReturnType<typeof toEip712Payload>): string {
+  return JSON.stringify(typed, (_key, value) =>
+    typeof value === "bigint" ? value.toString() : value,
+  );
+}
+
+export function toEip712Payload(typed: TypedDataRequest) {
+  const domain = typed.domain ?? {};
+  const types = { ...(typed.types as Record<string, unknown>) };
+  if (!types.EIP712Domain) {
+    types.EIP712Domain = eip712DomainFields(domain);
+  }
+  return {
+    domain,
+    types,
+    primaryType: typed.primaryType,
+    message: eip712PrimaryMessage(typed.message, types, typed.primaryType),
+  };
+}
+
+function eip712DomainFields(domain: Record<string, unknown>): Array<{ name: string; type: string }> {
+  const candidates: Array<[string, string]> = [
+    ["name", "string"],
+    ["version", "string"],
+    ["chainId", "uint256"],
+    ["verifyingContract", "address"],
+    ["salt", "bytes32"],
+  ];
+  return candidates
+    .filter(([field]) => domain[field] !== undefined)
+    .map(([name, type]) => ({ name, type }));
+}
+
+function eip712PrimaryMessage(
+  message: Record<string, unknown>,
+  types: Record<string, unknown>,
+  primaryType: string,
+): Record<string, unknown> {
+  const fields = types[primaryType];
+  if (!Array.isArray(fields)) {
+    return message;
+  }
+
+  const allowed = new Set(
+    fields
+      .map((field) => (isEip712Field(field) ? field.name : undefined))
+      .filter((name): name is string => Boolean(name)),
+  );
+  if (allowed.size === 0) {
+    return message;
+  }
+
+  return Object.fromEntries(Object.entries(message).filter(([key]) => allowed.has(key)));
+}
+
+function isEip712Field(field: unknown): field is { name: string; type: string } {
+  return (
+    typeof field === "object" &&
+    field !== null &&
+    typeof (field as { name?: unknown }).name === "string" &&
+    typeof (field as { type?: unknown }).type === "string"
+  );
+}

package/src/circle-cli-gateway-payment.test.ts

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  parseCircleCliSignature,
+  parseCircleCliWalletAddress,
+} from "./circle-cli-gateway-payment.js";
+
+test("parses quiet Circle CLI signatures", () => {
+  assert.equal(parseCircleCliSignature("0xabc123\n"), "0xabc123");
+});
+
+test("parses JSON Circle CLI signatures", () => {
+  assert.equal(
+    parseCircleCliSignature(JSON.stringify({ data: { signature: "0xdef456" } })),
+    "0xdef456",
+  );
+});
+
+test("rejects non-signature Circle CLI output", () => {
+  assert.throws(() => parseCircleCliSignature("signed"), /did not return a hex EIP-712 signature/);
+});
+
+test("parses a sole wallet address from Circle CLI list output", () => {
+  assert.equal(
+    parseCircleCliWalletAddress(
+      JSON.stringify({
+        data: {
+          wallets: [
+            {
+              address: "0x1111111111111111111111111111111111111111",
+            },
+          ],
+        },
+      }),
+    ),
+    "0x1111111111111111111111111111111111111111",
+  );
+});
+
+test("requires explicit wallet address when multiple Agent Wallets are present", () => {
+  assert.throws(
+    () =>
+      parseCircleCliWalletAddress(
+        JSON.stringify({
+          data: [
+            { address: "0x1111111111111111111111111111111111111111" },
+            { address: "0x2222222222222222222222222222222222222222" },
+          ],
+        }),
+      ),
+    /Multiple Circle Agent Wallets found/,
+  );
+});

package/src/circle-cli-gateway-payment.ts

@@ -0,0 +1,230 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import { registerBatchScheme } from "@circle-fin/x402-batching/client";
+import { x402Client } from "@x402/core/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import type { AgentPaymentEngine } from "./payment-engine.js";
+import { serializeTypedData, toEip712Payload } from "./circle-agent-wallet.js";
+
+const execFileAsync = promisify(execFile);
+
+export type CircleCliRunner = (command: string, args: string[]) => Promise<string>;
+
+export interface CircleCliGatewayPaymentEngineOptions {
+  /**
+   * Agent Wallet address controlled by Circle CLI. When omitted, the engine
+   * resolves the sole agent wallet returned by `circle wallet list`.
+   */
+  walletAddress?: `0x${string}`;
+  /** Circle CLI chain name. Rubicon real reads settle on Arc Testnet by default. */
+  chain?: string;
+  /** Circle CLI binary name or path. */
+  command?: string;
+  /** Command runner injection point for tests or hosted agent sandboxes. */
+  runner?: CircleCliRunner;
+}
+
+interface TypedDataRequest {
+  domain: Record<string, unknown>;
+  types: Record<string, unknown>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+/**
+ * Circle CLI / Agent Wallet payment engine. It creates the one-word x402
+ * payment payload for Rubicon's session-first flow and delegates EIP-712
+ * signing to `circle wallet sign typed-data`, so agents never need raw private
+ * keys or hand-built x402 payloads.
+ */
+export class CircleCliGatewayPaymentEngine implements AgentPaymentEngine {
+  private readonly x402 = new x402Client();
+  private readonly signer: CircleCliGatewaySigner;
+
+  constructor(options: CircleCliGatewayPaymentEngineOptions = {}) {
+    this.signer = new CircleCliGatewaySigner({
+      walletAddress: options.walletAddress,
+      chain: options.chain ?? "ARC-TESTNET",
+      command: options.command ?? "circle",
+      runner: options.runner ?? runCircleCli,
+    });
+    registerBatchScheme(this.x402, {
+      signer: this.signer,
+      fallbackScheme: new ExactEvmScheme(this.signer),
+    });
+  }
+
+  async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 one-word payment requirement");
+    }
+    await this.signer.ensureAddress();
+    return {
+      paymentPayload: await this.x402.createPaymentPayload(session.paymentRequired as never),
+    };
+  }
+}
+
+class CircleCliGatewaySigner {
+  address: `0x${string}` = "0x0000000000000000000000000000000000000000";
+  private resolved = false;
+  private resolving?: Promise<void>;
+
+  constructor(
+    private readonly options: {
+      walletAddress?: `0x${string}`;
+      chain: string;
+      command: string;
+      runner: CircleCliRunner;
+    },
+  ) {
+    if (options.walletAddress) {
+      this.address = options.walletAddress;
+      this.resolved = true;
+    }
+  }
+
+  async ensureAddress(): Promise<void> {
+    if (this.resolved) return;
+    if (!this.resolving) {
+      this.resolving = this.resolveAddress();
+    }
+    return this.resolving;
+  }
+
+  async signTypedData(typed: TypedDataRequest): Promise<`0x${string}`> {
+    await this.ensureAddress();
+    const signature = await this.options.runner(this.options.command, [
+      "wallet",
+      "sign",
+      "typed-data",
+      serializeTypedData(toEip712Payload(typed)),
+      "--address",
+      this.address,
+      "--chain",
+      this.options.chain,
+      "--quiet",
+    ]);
+    return parseCircleCliSignature(signature);
+  }
+
+  private async resolveAddress(): Promise<void> {
+    const output = await this.options.runner(this.options.command, [
+      "wallet",
+      "list",
+      "--chain",
+      this.options.chain,
+      "--type",
+      "agent",
+      "--output",
+      "json",
+    ]);
+    const address = parseCircleCliWalletAddress(output);
+    this.address = address;
+    this.resolved = true;
+  }
+}
+
+async function runCircleCli(command: string, args: string[]): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(command, args, {
+      maxBuffer: 1024 * 1024,
+    });
+    return stdout;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Circle CLI command failed. Ensure Circle CLI is installed, logged in, and has an Agent Wallet on the selected chain. ${message}`,
+    );
+  }
+}
+
+export function parseCircleCliSignature(output: string): `0x${string}` {
+  const trimmed = output.trim();
+  if (isHexSignature(trimmed)) {
+    return trimmed;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseJson(trimmed);
+  } catch {
+    throw new Error("Circle CLI did not return a hex EIP-712 signature");
+  }
+  const signature = findString(parsed, ["signature", "signedData", "data.signature"]);
+  if (signature && isHexSignature(signature)) {
+    return signature;
+  }
+  throw new Error("Circle CLI did not return a hex EIP-712 signature");
+}
+
+export function parseCircleCliWalletAddress(output: string): `0x${string}` {
+  const parsed = parseJson(output);
+  const wallets = collectWalletCandidates(parsed);
+  const addresses = wallets
+    .map((wallet) => findString(wallet, ["address", "walletAddress", "blockchainAddress"]))
+    .filter((address): address is `0x${string}` => Boolean(address && isAddress(address)));
+
+  const unique = [...new Set(addresses.map((address) => address.toLowerCase()))];
+  if (unique.length === 1) {
+    return addresses.find((address) => address.toLowerCase() === unique[0])!;
+  }
+  if (unique.length === 0) {
+    throw new Error("Circle CLI did not return an Agent Wallet address");
+  }
+  throw new Error("Multiple Circle Agent Wallets found; pass walletAddress explicitly");
+}
+
+function collectWalletCandidates(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) {
+    return value.filter(isRecord);
+  }
+  if (!isRecord(value)) {
+    return [];
+  }
+  for (const key of ["wallets", "items", "data"]) {
+    const nested = value[key];
+    if (Array.isArray(nested)) {
+      return nested.filter(isRecord);
+    }
+    if (isRecord(nested)) {
+      const deeper = collectWalletCandidates(nested);
+      if (deeper.length > 0) return deeper;
+    }
+  }
+  return [value];
+}
+
+function findString(value: unknown, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const found = key.split(".").reduce<unknown>((current, part) => {
+      if (!isRecord(current)) return undefined;
+      return current[part];
+    }, value);
+    if (typeof found === "string") {
+      return found;
+    }
+  }
+  return undefined;
+}
+
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error("Circle CLI returned non-JSON output");
+  }
+}
+
+function isHexSignature(value: string): value is `0x${string}` {
+  return /^0x[0-9a-fA-F]+$/.test(value);
+}
+
+function isAddress(value: string): value is `0x${string}` {
+  return /^0x[0-9a-fA-F]{40}$/.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from "./agent-client.js";
 export * from "./payment-engine.js";
+export * from "./circle-agent-wallet.js";
+export * from "./circle-cli-gateway-payment.js";
 export { RubiconClient as Rubicon, RubiconClient as default } from "./agent-client.js";

package/src/payment-engine.ts

@@ -1,8 +1,4 @@
 import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
-import { x402Client } from "@x402/core/client";
-import { registerBatchScheme, type GatewayClientConfig } from "@circle-fin/x402-batching/client";
-import { ExactEvmScheme } from "@x402/evm/exact/client";
-import { privateKeyToAccount } from "viem/accounts";
 
 /**
  * Produces the payment payload for exactly one word. Called once per word by the
@@ -31,37 +27,3 @@ export class StaticPaymentEngine implements AgentPaymentEngine {
     };
   }
 }
-
-export type CircleGatewayPaymentEngineOptions = GatewayClientConfig;
-
-/**
- * Circle/x402 engine. Signs the gateway's one-word `paymentRequired` terms.
- * Circle may batch settlement internally, but each signed payload corresponds to
- * exactly one word.
- */
-export class CircleGatewayPaymentEngine implements AgentPaymentEngine {
-  private readonly client = new x402Client();
-  private readonly account: ReturnType<typeof privateKeyToAccount>;
-
-  constructor(private readonly options: CircleGatewayPaymentEngineOptions) {
-    this.account = privateKeyToAccount(this.options.privateKey);
-    // Recommended buyer integration (Circle x402 buyer how-to): register the
-    // gasless batched scheme with an `exact` fallback. `registerBatchScheme`
-    // wires a CompositeEvmScheme that uses Gateway batching when the seller
-    // supports it and falls back to a standard EIP-3009 `exact` payment
-    // otherwise — no per-request routing logic needed.
-    registerBatchScheme(this.client, {
-      signer: this.account,
-      fallbackScheme: new ExactEvmScheme(this.account),
-    });
-  }
-
-  async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
-    if (!session.paymentRequired) {
-      throw new Error("Session did not include an x402 one-word payment requirement");
-    }
-    return {
-      paymentPayload: await this.client.createPaymentPayload(session.paymentRequired as never),
-    };
-  }
-}