@rubicon-caliga/agent-sdk 0.1.0 → 0.1.2

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

@@ -0,0 +1,182 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CircleCliGatewaySigner,
+  parseCircleGatewayBackingEOA,
+  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("parses backing EOA from Circle Gateway balance output", () => {
+  assert.equal(
+    parseCircleGatewayBackingEOA(
+      JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      }),
+    ),
+    "0x2222222222222222222222222222222222222222",
+  );
+});
+
+test("separates Circle CLI Agent Wallet address from x402 backing EOA", async () => {
+  const calls: string[][] = [];
+  const signer = new CircleCliGatewaySigner({
+    agentWalletAddress: "0x1111111111111111111111111111111111111111",
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      calls.push(args);
+      assert.deepEqual(args, [
+        "gateway",
+        "balance",
+        "--address",
+        "0x1111111111111111111111111111111111111111",
+        "--chain",
+        "ARC-TESTNET",
+        "--output",
+        "json",
+      ]);
+      return JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      });
+    },
+  });
+
+  await signer.ensureAddress();
+
+  assert.equal(signer.agentWalletAddress, "0x1111111111111111111111111111111111111111");
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+  assert.equal(calls.length, 1);
+});
+
+test("discovers sole Agent Wallet and then its Gateway backing EOA", async () => {
+  const calls: string[][] = [];
+  const signer = new CircleCliGatewaySigner({
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      calls.push(args);
+      if (args[0] === "wallet") {
+        return JSON.stringify({
+          data: {
+            wallets: [{ address: "0x1111111111111111111111111111111111111111" }],
+          },
+        });
+      }
+      return JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      });
+    },
+  });
+
+  await signer.ensureAddress();
+
+  assert.equal(signer.agentWalletAddress, "0x1111111111111111111111111111111111111111");
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+  assert.deepEqual(calls, [
+    ["wallet", "list", "--chain", "ARC-TESTNET", "--type", "agent", "--output", "json"],
+    [
+      "gateway",
+      "balance",
+      "--address",
+      "0x1111111111111111111111111111111111111111",
+      "--chain",
+      "ARC-TESTNET",
+      "--output",
+      "json",
+    ],
+  ]);
+});
+
+test("typed data message.from uses backing EOA while CLI signs with Agent Wallet", async () => {
+  let signedPayload: Record<string, unknown> | undefined;
+  const signer = new CircleCliGatewaySigner({
+    agentWalletAddress: "0x1111111111111111111111111111111111111111",
+    buyerWalletAddress: "0x2222222222222222222222222222222222222222",
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      const addressFlag = args.indexOf("--address");
+      assert.equal(args[addressFlag + 1], "0x1111111111111111111111111111111111111111");
+      signedPayload = JSON.parse(args[3] ?? "{}") as Record<string, unknown>;
+      return "0xabc123";
+    },
+  });
+  await signer.ensureAddress();
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+
+  await signer.signTypedData({
+    domain: { name: "USD Coin", version: "2", chainId: 5042002 },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+      ],
+    },
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: signer.address,
+      to: "0x3333333333333333333333333333333333333333",
+      value: 1n,
+    },
+  });
+
+  assert.equal(
+    (signedPayload?.message as Record<string, unknown>).from,
+    "0x2222222222222222222222222222222222222222",
+  );
+});
+
+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,284 @@
+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`.
+   *
+   * @deprecated Use `agentWalletAddress`. This alias is kept for existing SDK
+   * callers and is treated as the Circle CLI signing wallet, not the x402
+   * authorization `from` address.
+   */
+  walletAddress?: `0x${string}`;
+  /**
+   * Agent Wallet address controlled by Circle CLI. This is passed to
+   * `circle wallet sign typed-data --address`.
+   */
+  agentWalletAddress?: `0x${string}`;
+  /**
+   * Gateway backing EOA used as the x402 authorization `from` address. When
+   * omitted, the engine resolves it from `circle gateway balance`.
+   */
+  buyerWalletAddress?: `0x${string}`;
+  /** Alias for `buyerWalletAddress`. */
+  backingEOA?: `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({
+      agentWalletAddress: options.agentWalletAddress ?? options.walletAddress,
+      buyerWalletAddress: options.buyerWalletAddress ?? options.backingEOA,
+      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),
+    };
+  }
+}
+
+export class CircleCliGatewaySigner {
+  agentWalletAddress: `0x${string}` = "0x0000000000000000000000000000000000000000";
+  address: `0x${string}` = "0x0000000000000000000000000000000000000000";
+  private resolved = false;
+  private resolving?: Promise<void>;
+
+  constructor(
+    private readonly options: {
+      agentWalletAddress?: `0x${string}`;
+      buyerWalletAddress?: `0x${string}`;
+      chain: string;
+      command: string;
+      runner: CircleCliRunner;
+    },
+  ) {
+    if (options.agentWalletAddress) {
+      this.agentWalletAddress = options.agentWalletAddress;
+    }
+    if (options.buyerWalletAddress) {
+      this.address = options.buyerWalletAddress;
+    }
+    if (options.agentWalletAddress && options.buyerWalletAddress) {
+      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.agentWalletAddress,
+      "--chain",
+      this.options.chain,
+      "--quiet",
+    ]);
+    return parseCircleCliSignature(signature);
+  }
+
+  private async resolveAddress(): Promise<void> {
+    const agentWalletAddress =
+      this.options.agentWalletAddress ?? (await this.resolveAgentWalletAddress());
+    this.agentWalletAddress = agentWalletAddress;
+    this.address =
+      this.options.buyerWalletAddress ?? (await this.resolveBackingEOA(agentWalletAddress));
+    this.resolved = true;
+  }
+
+  private async resolveAgentWalletAddress(): Promise<`0x${string}`> {
+    const output = await this.options.runner(this.options.command, [
+      "wallet",
+      "list",
+      "--chain",
+      this.options.chain,
+      "--type",
+      "agent",
+      "--output",
+      "json",
+    ]);
+    return parseCircleCliWalletAddress(output);
+  }
+
+  private async resolveBackingEOA(agentWalletAddress: `0x${string}`): Promise<`0x${string}`> {
+    const output = await this.options.runner(this.options.command, [
+      "gateway",
+      "balance",
+      "--address",
+      agentWalletAddress,
+      "--chain",
+      this.options.chain,
+      "--output",
+      "json",
+    ]);
+    return parseCircleGatewayBackingEOA(output);
+  }
+}
+
+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 agentWalletAddress explicitly");
+}
+
+export function parseCircleGatewayBackingEOA(output: string): `0x${string}` {
+  const parsed = parseJson(output);
+  const backingEOA = findString(parsed, ["data.backingEOA", "backingEOA"]);
+  if (backingEOA && isAddress(backingEOA)) {
+    return backingEOA;
+  }
+  throw new Error("Circle Gateway balance did not return a backingEOA address");
+}
+
+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),
-    };
-  }
-}