@rubicon-caliga/agent-sdk 0.1.1 → 0.1.3

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

@@ -15,8 +15,24 @@ 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. */
@@ -33,10 +49,10 @@ interface TypedDataRequest {
 }
 
 /**
- * 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.
+ * Circle CLI / Agent Wallet payment engine. It delegates EIP-712 signing to
+ * `circle wallet sign typed-data`, so agents never need raw private keys or
+ * hand-built Circle / Arc payloads. Current gateways may call the legacy
+ * one-word method as a chunk-compatibility path.
  */
 export class CircleCliGatewayPaymentEngine implements AgentPaymentEngine {
   private readonly x402 = new x402Client();
@@ -44,7 +60,8 @@ export class CircleCliGatewayPaymentEngine implements AgentPaymentEngine {
 
   constructor(options: CircleCliGatewayPaymentEngineOptions = {}) {
     this.signer = new CircleCliGatewaySigner({
-      walletAddress: options.walletAddress,
+      agentWalletAddress: options.agentWalletAddress ?? options.walletAddress,
+      buyerWalletAddress: options.buyerWalletAddress ?? options.backingEOA,
       chain: options.chain ?? "ARC-TESTNET",
       command: options.command ?? "circle",
       runner: options.runner ?? runCircleCli,
@@ -57,30 +74,56 @@ export class CircleCliGatewayPaymentEngine implements AgentPaymentEngine {
 
   async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
     if (!session.paymentRequired) {
-      throw new Error("Session did not include an x402 one-word payment requirement");
+      throw new Error("Session did not include a legacy x402 payment requirement");
     }
     await this.signer.ensureAddress();
     return {
       paymentPayload: await this.x402.createPaymentPayload(session.paymentRequired as never),
     };
   }
+
+  async createChunkPayment(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 payment requirement");
+    }
+    await this.signer.ensureAddress();
+    const amountAtomic = BigInt(session.wordPaymentAtomic) * BigInt(input.maxWords);
+    return {
+      paymentPayload: await this.x402.createPaymentPayload(
+        withChunkRequirement(session.paymentRequired, {
+          amountAtomic: `${amountAtomic}`,
+          maxWords: input.maxWords,
+          nextSequence: input.nextSequence,
+          sessionId: session.sessionId,
+        }) as never,
+      ),
+      maxWords: input.maxWords,
+    };
+  }
 }
 
-class CircleCliGatewaySigner {
+export class CircleCliGatewaySigner {
+  agentWalletAddress: `0x${string}` = "0x0000000000000000000000000000000000000000";
   address: `0x${string}` = "0x0000000000000000000000000000000000000000";
   private resolved = false;
   private resolving?: Promise<void>;
 
   constructor(
     private readonly options: {
-      walletAddress?: `0x${string}`;
+      agentWalletAddress?: `0x${string}`;
+      buyerWalletAddress?: `0x${string}`;
       chain: string;
       command: string;
       runner: CircleCliRunner;
     },
   ) {
-    if (options.walletAddress) {
-      this.address = options.walletAddress;
+    if (options.agentWalletAddress) {
+      this.agentWalletAddress = options.agentWalletAddress;
+    }
+    if (options.buyerWalletAddress) {
+      this.address = options.buyerWalletAddress;
+    }
+    if (options.agentWalletAddress && options.buyerWalletAddress) {
       this.resolved = true;
     }
   }
@@ -101,7 +144,7 @@ class CircleCliGatewaySigner {
       "typed-data",
       serializeTypedData(toEip712Payload(typed)),
       "--address",
-      this.address,
+      this.agentWalletAddress,
       "--chain",
       this.options.chain,
       "--quiet",
@@ -110,6 +153,15 @@ class CircleCliGatewaySigner {
   }
 
   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",
@@ -120,9 +172,21 @@ class CircleCliGatewaySigner {
       "--output",
       "json",
     ]);
-    const address = parseCircleCliWalletAddress(output);
-    this.address = address;
-    this.resolved = true;
+    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);
   }
 }
 
@@ -173,7 +237,16 @@ export function parseCircleCliWalletAddress(output: string): `0x${string}` {
   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");
+  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>[] {
@@ -209,6 +282,32 @@ function findString(value: unknown, keys: string[]): string | undefined {
   return undefined;
 }
 
+function withChunkRequirement(
+  paymentRequired: unknown,
+  chunk: { amountAtomic: `${bigint}`; maxWords: number; nextSequence: number; sessionId: string },
+): unknown {
+  const source = paymentRequired as { accepts?: Array<Record<string, unknown>> };
+  if (!Array.isArray(source.accepts)) {
+    return paymentRequired;
+  }
+  return {
+    ...(paymentRequired as Record<string, unknown>),
+    accepts: source.accepts.map((accept) => ({
+      ...accept,
+      amount: chunk.amountAtomic,
+      extra: {
+        ...((accept.extra as Record<string, unknown> | undefined) ?? {}),
+        amountAtomic: chunk.amountAtomic,
+        maxWords: chunk.maxWords,
+        sequence: chunk.nextSequence,
+        authorizationMode: "chunk",
+        nonce: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+        idempotencyKey: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+      },
+    })),
+  };
+}
+
 function parseJson(value: string): unknown {
   try {
     return JSON.parse(value);

package/src/payment-engine.ts

@@ -1,20 +1,54 @@
-import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import type { StartSessionResponse, StreamAuthorizationRequest, StreamPaymentRequest } from "@rubicon-caliga/core";
 
 /**
- * Produces the payment payload for exactly one word. Called once per word by the
- * SDK's read loop — application developers never assemble payments themselves.
+ * Produces Circle / Arc authorization payloads for Rubicon reads. Preferred
+ * engines authorize a whole session once; fallback engines authorize chunks.
+ * Legacy one-word payloads remain supported for older gateways and tests.
  */
 export interface AgentPaymentEngine {
+  createSessionAuthorization?(session: StartSessionResponse): Promise<StreamAuthorizationRequest>;
+  createChunkPayment?(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest>;
+  /** @deprecated Compatibility path for one-word x402 gateways. */
   createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
 }
 
 /**
- * Development engine. Declares the one-word amount without settling real funds,
- * for use against a dev-mode gateway. NOT for production.
+ * Development engine. Declares the authorized amount without settling real
+ * funds, for use against a dev-mode gateway. NOT for production.
  */
 export class StaticPaymentEngine implements AgentPaymentEngine {
   constructor(private readonly network = "eip155:5042002") {}
 
+  async createSessionAuthorization(session: StartSessionResponse): Promise<StreamAuthorizationRequest> {
+    return {
+      authorizationPayload: {
+        scheme: "development-static",
+        network: this.network,
+        sessionId: session.sessionId,
+        amountAtomic: session.authorizationRequired?.maxAuthorizedAtomic ?? session.maxArticlePriceAtomic,
+        meteringUnit: "word",
+        authorizationMode: "session",
+      },
+    };
+  }
+
+  async createChunkPayment(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest> {
+    const amountAtomic = BigInt(session.wordPaymentAtomic) * BigInt(input.maxWords);
+    return {
+      paymentPayload: {
+        scheme: "development-static",
+        network: this.network,
+        sessionId: session.sessionId,
+        amountAtomic: `${amountAtomic}`,
+        meteringUnit: "word",
+        authorizationMode: "chunk",
+        maxWords: input.maxWords,
+        nextSequence: input.nextSequence,
+      },
+      maxWords: input.maxWords,
+    };
+  }
+
   async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
     return {
       paymentPayload: {