@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/router/PaymentRouter.ts

@@ -0,0 +1,215 @@
+/**
+ * PaymentRouter — Three-rail payment architecture.
+ *
+ * Routes payments across three rails:
+ *   1. **x402** (crypto-native) — on-chain USDC payments via the x402 protocol. Optimal for
+ *      micropayments, autonomous agents, and scenarios requiring on-chain audit trails.
+ *   2. **MPP** (Managed Payment Protocol / Stripe) — fiat-based payments with dispute resolution.
+ *      Optimal for larger amounts, supervised agents, and high-frequency session batching.
+ *   3. **Google AP2** (Agent Payment Protocol) — Google's managed agent payment rail combining
+ *      identity verification and payment in a single flow. Roadmap; activates when Google
+ *      publishes the full AP2 spec. Settlement on Base.
+ *
+ * Routing criteria:
+ *   - Transaction amount (micropayments → x402, high-frequency → MPP)
+ *   - Session context (ongoing session → MPP for batching efficiency)
+ *   - Agent autonomy level (autonomous → x402, supervised → MPP)
+ *   - Chain/ecosystem preference (Google ecosystem → AP2, Solana → x402-solana)
+ *   - Rail availability (live vs. roadmap)
+ *
+ * @module router/PaymentRouter
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type PaymentRail = "x402" | "mpp" | "x402-solana" | "google-ap2";
+
+export type RailStatus = "live" | "roadmap" | "disabled";
+
+export interface RailConfig {
+  rail: PaymentRail;
+  status: RailStatus;
+  /** Maximum per-transaction amount in USDC micro-units (6 decimals) */
+  maxAmount?: number;
+  /** Minimum per-transaction amount in USDC micro-units */
+  minAmount?: number;
+}
+
+export interface PaymentContext {
+  /** Amount in USDC micro-units (6 decimals). e.g. 1_000_000 = $1.00 */
+  amount: number;
+  /** Recipient address or merchant domain */
+  recipient: string;
+  /** Whether this payment is part of an active session with repeated transactions */
+  isSessionContext?: boolean;
+  /** Number of transactions in the current session (if applicable) */
+  sessionTxCount?: number;
+  /** Whether the agent is operating autonomously (no human in loop) */
+  autonomous?: boolean;
+  /** Preferred chain, if any */
+  preferredChain?: "base" | "solana" | "google-ap2";
+}
+
+export interface RoutingDecision {
+  rail: PaymentRail;
+  reason: string;
+  /** Estimated cost overhead (basis points) */
+  estimatedOverheadBps: number;
+  /** Whether this rail is currently live */
+  isLive: boolean;
+}
+
+// ─── Default Rail Configuration ───────────────────────────────────────────────
+
+const DEFAULT_RAILS: RailConfig[] = [
+  {
+    rail: "x402",
+    status: "live",
+    minAmount: 1_000, // $0.001 minimum
+    maxAmount: 100_000_000, // $100 max per tx (soft limit)
+  },
+  {
+    rail: "mpp",
+    status: "live",
+    minAmount: 100_000, // $0.10 minimum (Stripe floor)
+    maxAmount: 10_000_000_000, // $10,000 max
+  },
+  {
+    rail: "x402-solana",
+    status: "roadmap",
+  },
+  {
+    rail: "google-ap2",
+    status: "roadmap",
+    minAmount: 1_000, // $0.001 minimum (aligned with x402)
+    maxAmount: 50_000_000, // $50 max per tx (conservative until spec finalized)
+  },
+];
+
+// ─── Router ───────────────────────────────────────────────────────────────────
+
+export class PaymentRouter {
+  private rails: RailConfig[];
+  /** Amount threshold (micro-units) below which x402 is preferred. Default: $1.00 */
+  private microPaymentThreshold: number;
+  /** Session tx count above which MPP is preferred for batching. Default: 5 */
+  private highFrequencyThreshold: number;
+
+  constructor(options?: {
+    rails?: RailConfig[];
+    microPaymentThreshold?: number;
+    highFrequencyThreshold?: number;
+  }) {
+    this.rails = options?.rails ?? DEFAULT_RAILS;
+    this.microPaymentThreshold = options?.microPaymentThreshold ?? 1_000_000; // $1.00
+    this.highFrequencyThreshold = options?.highFrequencyThreshold ?? 5;
+  }
+
+  /**
+   * Select the optimal payment rail for a given context.
+   */
+  route(context: PaymentContext): RoutingDecision {
+    const {
+      amount,
+      isSessionContext,
+      sessionTxCount,
+      autonomous,
+      preferredChain,
+    } = context;
+
+    // If Google AP2 rail is live and context indicates Google ecosystem preference
+    // Google AP2 (Agent Payment Protocol) — Google's native agent payment rail
+    // Currently roadmap; will activate when Google publishes the full AP2 spec
+    const googleRail = this.getRail("google-ap2");
+    if (googleRail?.status === "live" && preferredChain === "base") {
+      // Google AP2 routes through Base for on-chain settlement
+      // When live, AP2 provides Google-managed identity + payment in a single flow
+      return {
+        rail: "google-ap2",
+        reason: "Google AP2 rail — managed identity + payment bundle",
+        estimatedOverheadBps: 100, // Estimated Google platform fee
+        isLive: true,
+      };
+    }
+
+    // If Solana is explicitly preferred and x402-solana is available
+    if (preferredChain === "solana") {
+      const solanaRail = this.getRail("x402-solana");
+      if (solanaRail?.status === "live") {
+        return {
+          rail: "x402-solana",
+          reason: "Preferred chain: Solana x402",
+          estimatedOverheadBps: 0,
+          isLive: true,
+        };
+      }
+      // Solana not yet live — fall through to other rails
+    }
+
+    // Rule 1: High-frequency session context → MPP (batching efficiency)
+    if (
+      isSessionContext &&
+      (sessionTxCount ?? 0) >= this.highFrequencyThreshold
+    ) {
+      const mppRail = this.getRail("mpp");
+      if (mppRail?.status === "live") {
+        return {
+          rail: "mpp",
+          reason: `High-frequency session (${sessionTxCount} txns) — MPP batching is more efficient`,
+          estimatedOverheadBps: 290, // Stripe's ~2.9%
+          isLive: true,
+        };
+      }
+    }
+
+    // Rule 2: Micropayments + autonomous → x402 (lower overhead, no session needed)
+    if (amount < this.microPaymentThreshold && autonomous !== false) {
+      const x402Rail = this.getRail("x402");
+      if (x402Rail?.status === "live") {
+        return {
+          rail: "x402",
+          reason: `Micropayment ($${(amount / 1_000_000).toFixed(2)}) + autonomous — x402 optimal`,
+          estimatedOverheadBps: 0, // x402 has no protocol fee
+          isLive: true,
+        };
+      }
+    }
+
+    // Rule 3: Larger amounts or supervised → MPP (better dispute resolution, fiat rails)
+    const mppRail = this.getRail("mpp");
+    if (mppRail?.status === "live" && amount >= (mppRail.minAmount ?? 0)) {
+      return {
+        rail: "mpp",
+        reason: `Amount $${(amount / 1_000_000).toFixed(2)} — MPP provides fiat rails and dispute resolution`,
+        estimatedOverheadBps: 290,
+        isLive: true,
+      };
+    }
+
+    // Default: x402 on Base
+    return {
+      rail: "x402",
+      reason: "Default rail — Base x402",
+      estimatedOverheadBps: 0,
+      isLive: this.getRail("x402")?.status === "live",
+    };
+  }
+
+  /**
+   * Get all available (live) rails.
+   */
+  getLiveRails(): RailConfig[] {
+    return this.rails.filter((r) => r.status === "live");
+  }
+
+  /**
+   * Check if a specific rail is available.
+   */
+  isRailLive(rail: PaymentRail): boolean {
+    return this.getRail(rail)?.status === "live";
+  }
+
+  private getRail(rail: PaymentRail): RailConfig | undefined {
+    return this.rails.find((r) => r.rail === rail);
+  }
+}

package/src/sdk/router/index.ts

@@ -0,0 +1,8 @@
+export type {
+  PaymentContext,
+  PaymentRail,
+  RailConfig,
+  RailStatus,
+  RoutingDecision,
+} from "./PaymentRouter.js";
+export { PaymentRouter } from "./PaymentRouter.js";

package/src/sdk/swap/SwapModule.ts

@@ -0,0 +1,310 @@
+/**
+ * @module swap/SwapModule
+ * SwapModule — multi-chain Uniswap V3 token swap aggregator with 0.875% protocol fee.
+ *
+ * Supports Base, Arbitrum, Optimism, and Polygon. Automatically selects the best
+ * Uniswap V3 fee tier (0.01%, 0.05%, 0.3%, 1%) by quoting all tiers and choosing
+ * the highest output. Applies slippage protection and an optional protocol fee.
+ *
+ * Usage: construct with `chain` param or use `attachSwap(wallet, { chain: 'arbitrum' })`.
+ */
+// SwapModule — Uniswap V3 token swap aggregator with 0.875% protocol fee
+import {
+  type Address,
+  encodeFunctionData,
+  type Hash,
+  type PublicClient,
+  type WalletClient,
+} from "viem";
+import { ERC20Abi, UniswapV3QuoterV2Abi, UniswapV3RouterAbi } from "./abi.js";
+import {
+  DEFAULT_SLIPPAGE_BPS,
+  PROTOCOL_FEE_BPS,
+  PROTOCOL_FEE_COLLECTOR,
+  type SwapChain,
+  type SwapModuleConfig,
+  type SwapOptions,
+  type SwapQuote,
+  type SwapResult,
+  UNISWAP_V3_ADDRESSES,
+  type UniswapFeeTier,
+} from "./types.js";
+
+const FEE_TIERS: UniswapFeeTier[] = [100, 500, 3000, 10000];
+
+/** Calculate protocol fee: floor(amount * feeBps / 100_000) */
+export function calcProtocolFee(amount: bigint, feeBps: number): bigint {
+  return (amount * BigInt(feeBps)) / 100000n;
+}
+
+/** Apply slippage: floor(amount * (10_000 - slippageBps) / 10_000) */
+export function applySlippage(amount: bigint, slippageBps: number): bigint {
+  return (amount * BigInt(10000 - slippageBps)) / 10000n;
+}
+
+/** Encode deadline: block.timestamp + deadlineSecs */
+export function calcDeadline(deadlineSecs: number): bigint {
+  return BigInt(Math.floor(Date.now() / 1000) + deadlineSecs);
+}
+
+export class SwapModule {
+  private readonly publicClient: PublicClient;
+  private readonly walletClient: WalletClient;
+  private readonly accountAddress: Address;
+  private readonly config: SwapModuleConfig;
+
+  constructor(
+    publicClient: PublicClient,
+    walletClient: WalletClient,
+    accountAddress: Address,
+    config?: Partial<SwapModuleConfig> & { chain?: SwapChain },
+  ) {
+    this.publicClient = publicClient;
+    this.walletClient = walletClient;
+    this.accountAddress = accountAddress;
+    const chain: SwapChain = config?.chain ?? "base";
+    const chainAddresses = UNISWAP_V3_ADDRESSES[chain];
+    this.config = {
+      routerAddress: chainAddresses.ROUTER,
+      quoterAddress: chainAddresses.QUOTER_V2,
+      feeBps: PROTOCOL_FEE_BPS,
+      feeWallet: PROTOCOL_FEE_COLLECTOR,
+      chain,
+      ...config,
+      // Re-apply chain-derived addresses if chain was specified but addresses were not
+      ...(config?.routerAddress
+        ? {}
+        : { routerAddress: chainAddresses.ROUTER }),
+      ...(config?.quoterAddress
+        ? {}
+        : { quoterAddress: chainAddresses.QUOTER_V2 }),
+    };
+  }
+
+  async getQuote(
+    tokenIn: Address,
+    tokenOut: Address,
+    amountIn: bigint,
+    options: Pick<SwapOptions, "slippageBps" | "feeTiers"> = {},
+  ): Promise<SwapQuote> {
+    const slippageBps = options.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+    const tiersToTry = options.feeTiers ?? FEE_TIERS;
+    const feeAmount = calcProtocolFee(amountIn, this.config.feeBps);
+    const amountInNet = amountIn - feeAmount;
+    if (amountInNet <= 0n) {
+      throw new Error(
+        `SwapModule: amountIn (${amountIn}) is too small — fee (${feeAmount}) exceeds input`,
+      );
+    }
+
+    let bestQuote: {
+      amountOut: bigint;
+      gasEstimate: bigint;
+      feeTier: UniswapFeeTier;
+    } | null = null;
+    for (const fee of tiersToTry) {
+      try {
+        const result = await this.publicClient.readContract({
+          address: this.config.quoterAddress,
+          abi: UniswapV3QuoterV2Abi,
+          functionName: "quoteExactInputSingle",
+          args: [
+            {
+              tokenIn,
+              tokenOut,
+              amount: amountInNet,
+              fee,
+              sqrtPriceLimitX96: 0n,
+            },
+          ],
+        });
+        const [amountOut, , , gasEstimate] = result as [
+          bigint,
+          bigint,
+          number,
+          bigint,
+        ];
+        if (!bestQuote || amountOut > bestQuote.amountOut) {
+          bestQuote = {
+            amountOut,
+            gasEstimate,
+            feeTier: fee as UniswapFeeTier,
+          };
+        }
+      } catch {
+        // Pool doesn't exist for this fee tier
+      }
+    }
+
+    if (!bestQuote) {
+      throw new Error(
+        `SwapModule: No Uniswap V3 pool found for ${tokenIn} → ${tokenOut} on ${this.config.chain}.`,
+      );
+    }
+
+    const amountOutMinimum = applySlippage(bestQuote.amountOut, slippageBps);
+    const effectiveRate =
+      amountInNet > 0n ? Number(bestQuote.amountOut) / Number(amountInNet) : 0;
+
+    return {
+      tokenIn,
+      tokenOut,
+      amountInRaw: amountIn,
+      amountInNet,
+      feeAmount,
+      amountOut: bestQuote.amountOut,
+      amountOutMinimum,
+      poolFeeTier: bestQuote.feeTier,
+      effectiveRate,
+      gasEstimate: bestQuote.gasEstimate,
+    };
+  }
+
+  async ensureApproval(
+    token: Address,
+    spender: Address,
+    amount: bigint,
+  ): Promise<Hash | undefined> {
+    const currentAllowance = (await this.publicClient.readContract({
+      address: token,
+      abi: ERC20Abi,
+      functionName: "allowance",
+      args: [this.accountAddress, spender],
+    })) as bigint;
+
+    if (currentAllowance >= amount) return undefined;
+
+    const MAX_UINT256 =
+      115792089237316195423570985008687907853269984665640564039457584007913129639935n;
+    const account = this.walletClient.account;
+    if (!account) throw new Error("SwapModule: walletClient has no account");
+
+    const approveData = encodeFunctionData({
+      abi: ERC20Abi,
+      functionName: "approve",
+      args: [spender, MAX_UINT256],
+    });
+
+    return this.walletClient.sendTransaction({
+      account,
+      to: token,
+      data: approveData,
+      chain: this.walletClient.chain ?? null,
+    });
+  }
+
+  private async transferFee(
+    token: Address,
+    feeAmount: bigint,
+    feeWallet: Address,
+  ): Promise<Hash> {
+    const account = this.walletClient.account;
+    if (!account) throw new Error("SwapModule: walletClient has no account");
+
+    const transferData = encodeFunctionData({
+      abi: ERC20Abi,
+      functionName: "transfer",
+      args: [feeWallet, feeAmount],
+    });
+
+    return this.walletClient.sendTransaction({
+      account,
+      to: token,
+      data: transferData,
+      chain: this.walletClient.chain ?? null,
+    });
+  }
+
+  async swap(
+    tokenIn: Address,
+    tokenOut: Address,
+    amountIn: bigint,
+    options: SwapOptions = {},
+  ): Promise<SwapResult> {
+    const slippageBps = options.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+    const deadlineSecs = options.deadlineSecs ?? 300;
+    const feeWallet = options.feeWallet ?? this.config.feeWallet;
+
+    const quote = await this.getQuote(tokenIn, tokenOut, amountIn, {
+      slippageBps,
+      feeTiers: options.feeTiers,
+    });
+
+    if (quote.gasEstimate > 2000000n) {
+      console.warn(
+        `SwapModule: High gas estimate (${quote.gasEstimate}). Pool may be illiquid.`,
+      );
+    }
+
+    const approvalTxHash = await this.ensureApproval(
+      tokenIn,
+      this.config.routerAddress,
+      amountIn,
+    );
+    const approvalRequired = approvalTxHash !== undefined;
+
+    let feeTxHash: Hash | undefined;
+    if (quote.feeAmount > 0n && feeWallet !== this.accountAddress) {
+      feeTxHash = await this.transferFee(tokenIn, quote.feeAmount, feeWallet);
+    }
+
+    const account = this.walletClient.account;
+    if (!account) throw new Error("SwapModule: walletClient has no account");
+
+    const _deadline = calcDeadline(deadlineSecs); // reserved for future router versions
+    const swapData = encodeFunctionData({
+      abi: UniswapV3RouterAbi,
+      functionName: "exactInputSingle",
+      args: [
+        {
+          tokenIn,
+          tokenOut,
+          fee: quote.poolFeeTier,
+          recipient: this.accountAddress,
+          amountIn: quote.amountInNet,
+          amountOutMinimum: quote.amountOutMinimum,
+          sqrtPriceLimitX96: 0n,
+        },
+      ],
+    });
+
+    const txHash = await this.walletClient.sendTransaction({
+      account,
+      to: this.config.routerAddress,
+      data: swapData,
+      chain: this.walletClient.chain ?? null,
+    });
+
+    return { txHash, feeTxHash, quote, approvalRequired, approvalTxHash };
+  }
+
+  getConfig(): SwapModuleConfig {
+    return { ...this.config };
+  }
+
+  setFeeWallet(address: Address): void {
+    this.config.feeWallet = address;
+  }
+}
+
+export function attachSwap(
+  wallet: {
+    address: Address;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+  },
+  config?: Partial<SwapModuleConfig> & { chain?: SwapChain },
+) {
+  const swapModule = new SwapModule(
+    wallet.publicClient,
+    wallet.walletClient,
+    wallet.address,
+    config,
+  );
+  return {
+    ...wallet,
+    swapModule,
+    swap: swapModule.swap.bind(swapModule),
+    getQuote: swapModule.getQuote.bind(swapModule),
+  };
+}

package/src/sdk/swap/abi.ts

@@ -0,0 +1,117 @@
+// [MAX-ADDED] ABIs for Uniswap V3 SwapRouter02 and QuoterV2 on Base Mainnet
+/** Uniswap V3 SwapRouter02 ABI — exactInputSingle */
+export const UniswapV3RouterAbi = [
+  {
+    name: "exactInputSingle",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "fee", type: "uint24" },
+          { name: "recipient", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "amountOutMinimum", type: "uint256" },
+          { name: "sqrtPriceLimitX96", type: "uint160" },
+        ],
+      },
+    ],
+    outputs: [{ name: "amountOut", type: "uint256" }],
+  },
+  {
+    name: "exactInput",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "path", type: "bytes" },
+          { name: "recipient", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "amountOutMinimum", type: "uint256" },
+        ],
+      },
+    ],
+    outputs: [{ name: "amountOut", type: "uint256" }],
+  },
+];
+/** Uniswap V3 QuoterV2 ABI — quoteExactInputSingle */
+export const UniswapV3QuoterV2Abi = [
+  {
+    name: "quoteExactInputSingle",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "amount", type: "uint256" },
+          { name: "fee", type: "uint24" },
+          { name: "sqrtPriceLimitX96", type: "uint160" },
+        ],
+      },
+    ],
+    outputs: [
+      { name: "amountOut", type: "uint256" },
+      { name: "sqrtPriceX96After", type: "uint160" },
+      { name: "initializedTicksCrossed", type: "uint32" },
+      { name: "gasEstimate", type: "uint256" },
+    ],
+  },
+];
+/** Minimal ERC-20 ABI for allowance, approve, transferFrom */
+export const ERC20Abi = [
+  {
+    name: "allowance",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+    ],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "approve",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+  {
+    name: "transfer",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+  {
+    name: "balanceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "decimals",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint8" }],
+  },
+];

package/src/sdk/swap/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @module swap
+ * Re-exports for the SwapModule: multi-chain Uniswap V3 swaps.
+ *
+ * Supported chains: base, arbitrum, optimism, polygon.
+ * Use SwapModule directly or attachSwap(wallet, { chain }) for a wallet-bound instance.
+ */
+
+export { ERC20Abi, UniswapV3QuoterV2Abi, UniswapV3RouterAbi } from "./abi.js";
+export {
+  applySlippage,
+  attachSwap,
+  calcDeadline,
+  calcProtocolFee,
+  SwapModule,
+} from "./SwapModule.js";
+export type {
+  SwapChain,
+  SwapModuleConfig,
+  SwapOptions,
+  SwapQuote,
+  SwapResult,
+  UniswapFeeTier,
+} from "./types.js";
+export {
+  ARBITRUM_TOKENS,
+  BASE_TOKENS,
+  DEFAULT_SLIPPAGE_BPS,
+  OPTIMISM_TOKENS,
+  POLYGON_TOKENS,
+  PROTOCOL_FEE_BPS,
+  PROTOCOL_FEE_COLLECTOR,
+  UNISWAP_V3_ADDRESSES,
+} from "./types.js";