@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/x402/budget.ts

@@ -0,0 +1,168 @@
+// [MAX-ADDED] x402 Budget Controls — per-service spending caps and transaction logging
+// viem types imported on-demand within class methods
+import type {
+  X402ClientConfig,
+  X402ServiceBudget,
+  X402TransactionLog,
+} from "./types.js";
+
+/**
+ * [MAX-ADDED] In-memory budget tracker for x402 payments.
+ * Enforces per-service caps, daily limits, and per-request maximums.
+ * On-chain spend limits are ALSO enforced by the AgentWallet contract —
+ * this is an additional client-side layer for granular service-level control.
+ */
+export class X402BudgetTracker {
+  private serviceBudgets: Map<string, X402ServiceBudget> = new Map();
+  private dailySpend: Map<string, bigint> = new Map(); // service -> today's total
+  private globalDailySpend: bigint = 0n;
+  private dailyResetTimestamp: number;
+  private transactionLog: X402TransactionLog[] = [];
+
+  private globalDailyLimit: bigint;
+  private globalPerRequestMax: bigint;
+
+  constructor(config: X402ClientConfig = {}) {
+    this.globalDailyLimit =
+      config.globalDailyLimit ?? BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFF"); // effectively unlimited
+    this.globalPerRequestMax =
+      config.globalPerRequestMax ?? BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFF");
+    this.dailyResetTimestamp = this.startOfDay();
+
+    if (config.serviceBudgets) {
+      for (const budget of config.serviceBudgets) {
+        this.serviceBudgets.set(budget.service, budget);
+      }
+    }
+  }
+
+  /**
+   * Check if a payment is within budget limits.
+   * Returns { allowed: true } or { allowed: false, reason: string }.
+   */
+  checkBudget(
+    service: string,
+    amount: bigint,
+  ): { allowed: boolean; reason?: string } {
+    this.maybeResetDaily();
+
+    // Global per-request check
+    if (amount > this.globalPerRequestMax) {
+      return {
+        allowed: false,
+        reason: `Amount ${amount} exceeds global per-request max ${this.globalPerRequestMax}`,
+      };
+    }
+
+    // Global daily check
+    if (this.globalDailySpend + amount > this.globalDailyLimit) {
+      return {
+        allowed: false,
+        reason: `Would exceed global daily limit ${this.globalDailyLimit}`,
+      };
+    }
+
+    // Service-specific checks
+    const budget = this.findServiceBudget(service);
+    if (budget) {
+      if (amount > budget.maxPerRequest) {
+        return {
+          allowed: false,
+          reason: `Amount ${amount} exceeds service per-request max ${budget.maxPerRequest} for ${service}`,
+        };
+      }
+      const serviceDailySpend = this.dailySpend.get(service) ?? 0n;
+      if (serviceDailySpend + amount > budget.dailyLimit) {
+        return {
+          allowed: false,
+          reason: `Would exceed daily limit ${budget.dailyLimit} for ${service}`,
+        };
+      }
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Record a completed payment.
+   */
+  recordPayment(log: X402TransactionLog): void {
+    this.maybeResetDaily();
+    this.transactionLog.push(log);
+
+    if (log.success) {
+      const service = log.service;
+      this.dailySpend.set(
+        service,
+        (this.dailySpend.get(service) ?? 0n) + log.amount,
+      );
+      this.globalDailySpend += log.amount;
+    }
+  }
+
+  /**
+   * Get transaction history, optionally filtered.
+   */
+  getTransactionLog(filter?: {
+    service?: string;
+    since?: number;
+  }): X402TransactionLog[] {
+    let logs = this.transactionLog;
+    if (filter?.service) {
+      logs = logs.filter((l) => l.service === filter.service);
+    }
+    if (filter?.since !== undefined) {
+      const since = filter.since;
+      logs = logs.filter((l) => l.timestamp >= since);
+    }
+    return logs;
+  }
+
+  /**
+   * Get current daily spend summary.
+   */
+  getDailySpendSummary(): {
+    global: bigint;
+    byService: Record<string, bigint>;
+    resetsAt: number;
+  } {
+    this.maybeResetDaily();
+    const byService: Record<string, bigint> = {};
+    for (const [service, amount] of this.dailySpend) {
+      byService[service] = amount;
+    }
+    return {
+      global: this.globalDailySpend,
+      byService,
+      resetsAt: this.dailyResetTimestamp + 86400,
+    };
+  }
+
+  /**
+   * Add or update a service budget at runtime.
+   */
+  setServiceBudget(budget: X402ServiceBudget): void {
+    this.serviceBudgets.set(budget.service, budget);
+  }
+
+  // ─── Internals ───
+
+  private findServiceBudget(service: string): X402ServiceBudget | undefined {
+    // Exact match first, then wildcard
+    return this.serviceBudgets.get(service) ?? this.serviceBudgets.get("*");
+  }
+
+  private maybeResetDaily(): void {
+    const now = this.startOfDay();
+    if (now > this.dailyResetTimestamp) {
+      this.dailySpend.clear();
+      this.globalDailySpend = 0n;
+      this.dailyResetTimestamp = now;
+    }
+  }
+
+  private startOfDay(): number {
+    const now = Math.floor(Date.now() / 1000);
+    return now - (now % 86400);
+  }
+}

package/src/sdk/x402/chains/abstract/index.ts

@@ -0,0 +1,280 @@
+/**
+ * Abstract x402 Delegated Payment Facilitator Adapter
+ *
+ * Abstract's x402 implementation uses a delegated facilitator pattern:
+ * 1. The agent wallet does NOT sign the payment tx directly
+ * 2. A "payment facilitator" contract is designated per-merchant
+ * 3. The agent's wallet delegates authorization via a signed EIP-712 permit
+ * 4. The facilitator executes the actual chain transaction
+ *
+ * Chain IDs:
+ *   - Abstract Mainnet: 2741
+ *   - Abstract Testnet: 11124
+ */
+
+import type { Address, Hex, WalletClient } from "viem";
+import { encodeAbiParameters, parseAbiParameters } from "viem";
+
+// ─── Abstract Chain Constants ────────────────────────────────────────────────
+
+export const ABSTRACT_CHAIN_IDS = {
+  mainnet: 2741,
+  testnet: 11124,
+} as const;
+
+/** USDC on Abstract Mainnet (official Bridged USDC) */
+export const ABSTRACT_USDC: Record<number, Address> = {
+  2741: "0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1", // Abstract Mainnet USDC
+  11124: "0x3eBdeaA0DB3FfDe96E7a0DBBAFEC961FC50F725f", // Abstract Testnet USDC
+};
+
+/** Abstract's approved payment facilitator contracts */
+export const ABSTRACT_APPROVED_FACILITATORS: Address[] = [
+  "0x5FbDB2315678afecb367f032d93F642f64180aa3", // Abstract official facilitator (mainnet)
+];
+
+// ─── EIP-712 Types for Abstract Delegated Payment ───────────────────────────
+
+const ABSTRACT_PERMIT_DOMAIN = {
+  name: "AbstractDelegatedPayment",
+  version: "1",
+  chainId: ABSTRACT_CHAIN_IDS.mainnet,
+} as const;
+
+const ABSTRACT_PERMIT_TYPES = {
+  DelegatedPaymentPermit: [
+    { name: "facilitator", type: "address" },
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" },
+    { name: "payTo", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "resource", type: "string" },
+  ],
+} as const;
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface AbstractDelegatedPaymentConfig {
+  /** The facilitator contract address (must be on approved list or user-allowlisted) */
+  facilitatorAddress: Address;
+  /** Token to pay with (default: USDC on Abstract) */
+  token?: Address;
+  /** Permit deadline in seconds from now (default: 300 = 5 min) */
+  deadlineSeconds?: number;
+  /** User-allowlisted facilitator addresses (extends the approved list) */
+  userAllowlist?: Address[];
+}
+
+export interface DelegatedPaymentPermit {
+  facilitator: Address;
+  token: Address;
+  amount: bigint;
+  payTo: Address;
+  nonce: bigint;
+  deadline: bigint;
+  resource: string;
+}
+
+export interface AbstractPaymentResult {
+  /** EIP-712 signature for the facilitator permit */
+  permitSignature: Hex;
+  /** Encoded permit data to submit to the facilitator contract */
+  permitData: Hex;
+  /** The permit fields for verification */
+  permit: DelegatedPaymentPermit;
+  /** Chain ID this payment is valid on */
+  chainId: number;
+}
+
+// ─── AbstractDelegatedFacilitatorAdapter ─────────────────────────────────────
+
+/**
+ * Adapter for Abstract's delegated payment facilitator x402 model.
+ *
+ * Instead of signing a direct payment transaction, the agent signs an EIP-712
+ * permit authorizing a facilitator contract to execute the payment on its behalf.
+ * This is Abstract's model — the agent's keys never touch the chain directly.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new AbstractDelegatedFacilitatorAdapter(walletClient, {
+ *   facilitatorAddress: '0x5FbDB2315678afecb367f032d93F642f64180aa3',
+ * });
+ *
+ * const result = await adapter.signPaymentPermit({
+ *   amount: 1_000_000n, // 1 USDC (6 decimals)
+ *   payTo: '0xmerchant...',
+ *   nonce: 0n,
+ *   resource: 'https://api.example.com/resource',
+ * });
+ * ```
+ */
+export class AbstractDelegatedFacilitatorAdapter {
+  private walletClient: WalletClient;
+  private config: Required<AbstractDelegatedPaymentConfig>;
+  private chainId: number;
+
+  constructor(
+    walletClient: WalletClient,
+    config: AbstractDelegatedPaymentConfig,
+    chainId: number = ABSTRACT_CHAIN_IDS.mainnet,
+  ) {
+    this.walletClient = walletClient;
+    this.chainId = chainId;
+
+    // Validate facilitator
+    const approved = [
+      ...ABSTRACT_APPROVED_FACILITATORS,
+      ...(config.userAllowlist ?? []),
+    ];
+    const isApproved = approved.some(
+      (a) => a.toLowerCase() === config.facilitatorAddress.toLowerCase(),
+    );
+    if (!isApproved) {
+      throw new Error(
+        `Facilitator ${config.facilitatorAddress} is not on the Abstract approved list. ` +
+          `Pass it in userAllowlist to explicitly allow it.`,
+      );
+    }
+
+    this.config = {
+      facilitatorAddress: config.facilitatorAddress,
+      token:
+        config.token ??
+        ABSTRACT_USDC[chainId] ??
+        ABSTRACT_USDC[ABSTRACT_CHAIN_IDS.mainnet],
+      deadlineSeconds: config.deadlineSeconds ?? 300,
+      userAllowlist: config.userAllowlist ?? [],
+    };
+  }
+
+  /**
+   * Sign an EIP-712 delegated payment permit for the Abstract facilitator.
+   * This replaces direct tx signing — the permit is submitted to the facilitator contract.
+   */
+  async signPaymentPermit(params: {
+    amount: bigint;
+    payTo: Address;
+    nonce: bigint;
+    resource: string;
+  }): Promise<AbstractPaymentResult> {
+    const deadline = BigInt(
+      Math.floor(Date.now() / 1000) + this.config.deadlineSeconds,
+    );
+
+    const permit: DelegatedPaymentPermit = {
+      facilitator: this.config.facilitatorAddress,
+      token: this.config.token,
+      amount: params.amount,
+      payTo: params.payTo,
+      nonce: params.nonce,
+      deadline,
+      resource: params.resource,
+    };
+
+    const domain = {
+      ...ABSTRACT_PERMIT_DOMAIN,
+      chainId: this.chainId,
+    };
+
+    const account = this.walletClient.account;
+    if (!account) throw new Error("WalletClient has no account attached");
+
+    const signature = await this.walletClient.signTypedData({
+      account,
+      domain,
+      types: ABSTRACT_PERMIT_TYPES,
+      primaryType: "DelegatedPaymentPermit",
+      message: permit,
+    });
+
+    // Encode the permit for submission to the facilitator contract
+    const permitData = encodeAbiParameters(
+      parseAbiParameters(
+        "address facilitator, address token, uint256 amount, address payTo, uint256 nonce, uint256 deadline, string resource, bytes signature",
+      ),
+      [
+        permit.facilitator,
+        permit.token,
+        permit.amount,
+        permit.payTo,
+        permit.nonce,
+        permit.deadline,
+        permit.resource,
+        signature,
+      ],
+    );
+
+    return {
+      permitSignature: signature,
+      permitData,
+      permit,
+      chainId: this.chainId,
+    };
+  }
+
+  /**
+   * Build the x402 payment payload for Abstract's delegated facilitator model.
+   * This payload replaces the standard txHash payload in the X-PAYMENT header.
+   */
+  async buildX402Payload(params: {
+    amount: bigint;
+    payTo: Address;
+    nonce: bigint;
+    resource: string;
+  }): Promise<Record<string, unknown>> {
+    const result = await this.signPaymentPermit(params);
+
+    return {
+      scheme: "abstract-delegated",
+      chainId: result.chainId,
+      facilitator: result.permit.facilitator,
+      token: result.permit.token,
+      amount: result.permit.amount.toString(),
+      payTo: result.permit.payTo,
+      nonce: result.permit.nonce.toString(),
+      deadline: result.permit.deadline.toString(),
+      resource: result.permit.resource,
+      permitSignature: result.permitSignature,
+      permitData: result.permitData,
+    };
+  }
+
+  /** Check if a chain ID is an Abstract chain */
+  static isAbstractChain(chainId: number): boolean {
+    return Object.values(ABSTRACT_CHAIN_IDS).includes(chainId as 2741 | 11124);
+  }
+
+  /** Get the network string for x402 payment requirements (e.g. "abstract:2741") */
+  static getNetworkString(chainId: number): string {
+    return `abstract:${chainId}`;
+  }
+}
+
+// ─── SUPPORTED_CHAINS Extension ──────────────────────────────────────────────
+
+/**
+ * Abstract chain IDs to add to SUPPORTED_CHAINS in the main SDK.
+ * These route through AbstractDelegatedFacilitatorAdapter for x402 payments.
+ */
+export const ABSTRACT_SUPPORTED_CHAINS = {
+  "abstract:2741": {
+    chainId: ABSTRACT_CHAIN_IDS.mainnet,
+    name: "Abstract Mainnet",
+    rpcUrl: "https://api.mainnet.abs.xyz",
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    blockExplorer: "https://explorer.mainnet.abs.xyz",
+    x402Model: "delegated-facilitator" as const,
+    usdc: ABSTRACT_USDC[ABSTRACT_CHAIN_IDS.mainnet],
+  },
+  "abstract-testnet:11124": {
+    chainId: ABSTRACT_CHAIN_IDS.testnet,
+    name: "Abstract Testnet",
+    rpcUrl: "https://api.testnet.abs.xyz",
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    blockExplorer: "https://explorer.testnet.abs.xyz",
+    x402Model: "delegated-facilitator" as const,
+    usdc: ABSTRACT_USDC[ABSTRACT_CHAIN_IDS.testnet],
+  },
+} as const;