@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/x402/types.ts

@@ -0,0 +1,156 @@
+/**
+ * @module x402/types
+ * x402 protocol type definitions and well-known asset constants.
+ *
+ * Implements the x402 HTTP payment protocol spec (coinbase/x402) for
+ * multi-chain USDC payments. Covers 10 mainnet chains: Base, Ethereum,
+ * Arbitrum, Polygon, Optimism, Avalanche, Unichain, Linea, Sonic, Worldchain.
+ *
+ * USDC addresses are sourced from Circle's official registry:
+ * https://developers.circle.com/stablecoins/usdc-contract-addresses
+ */
+// x402 protocol types — compatible with @x402/core spec
+import type { Address, Hash } from "viem";
+
+// ─── x402 Protocol Types (from coinbase/x402 spec) ───
+
+/** Resource information included in x402 responses */
+export interface X402ResourceInfo {
+  url: string;
+  description: string;
+  mimeType: string;
+}
+
+/** Payment requirements returned in 402 response PAYMENT-REQUIRED header */
+export interface X402PaymentRequirements {
+  scheme: string; // e.g. "exact"
+  network: string; // e.g. "base:8453"
+  asset: string; // token contract address (e.g. USDC on Base)
+  amount: string; // amount in smallest unit (e.g. "1000000" = 1 USDC)
+  payTo: string; // recipient address
+  maxTimeoutSeconds: number;
+  extra: Record<string, unknown>;
+}
+
+/** Full 402 response payload (base64-decoded from PAYMENT-REQUIRED header) */
+export interface X402PaymentRequired {
+  x402Version: number;
+  error?: string;
+  resource: X402ResourceInfo;
+  accepts: X402PaymentRequirements[];
+  extensions?: Record<string, unknown>;
+}
+
+/** Payment payload sent back with PAYMENT-SIGNATURE header */
+export interface X402PaymentPayload {
+  x402Version: number;
+  resource: X402ResourceInfo;
+  accepted: X402PaymentRequirements;
+  payload: Record<string, unknown>; // scheme-specific (e.g. tx hash, signature)
+  extensions?: Record<string, unknown>;
+}
+
+/** Settlement response returned in PAYMENT-RESPONSE header */
+export interface X402SettlementResponse {
+  success: boolean;
+  txHash?: string;
+  network?: string;
+  error?: string;
+}
+
+// ─── AgentWallet x402 Client Types ───
+
+/** Per-service spending cap configuration */
+export interface X402ServiceBudget {
+  /** Domain or URL pattern (e.g. "api.example.com" or "*") */
+  service: string;
+  /** Max spend per single request in token base units */
+  maxPerRequest: bigint;
+  /** Max total spend per day in token base units */
+  dailyLimit: bigint;
+}
+
+/** Transaction log entry for x402 payments */
+export interface X402TransactionLog {
+  timestamp: number;
+  service: string;
+  url: string;
+  amount: bigint;
+  token: Address;
+  recipient: Address;
+  txHash: Hash;
+  network: string;
+  scheme: string;
+  success: boolean;
+  error?: string;
+}
+
+/** Configuration for the x402 client */
+export interface X402ClientConfig {
+  /** Service-level budget controls */
+  serviceBudgets?: X402ServiceBudget[];
+  /** Global daily spending limit (token base units, default: unlimited) */
+  globalDailyLimit?: bigint;
+  /** Global per-request max (token base units, default: unlimited) */
+  globalPerRequestMax?: bigint;
+  /** Supported networks (default: ["base:8453"]) */
+  supportedNetworks?: string[];
+  /** Supported assets by network (default: USDC on Base) */
+  supportedAssets?: Record<string, Address[]>;
+  /** Max retries after payment (default: 1) */
+  maxRetries?: number;
+  /** Custom facilitator URL (optional, for verify/settle) */
+  facilitatorUrl?: string;
+  /** Whether to auto-pay 402 responses (default: true) */
+  autoPay?: boolean;
+  /** Callback before payment — return false to reject */
+  onBeforePayment?: (
+    req: X402PaymentRequirements,
+    url: string,
+  ) => Promise<boolean> | boolean;
+  /** Callback after payment */
+  onPaymentComplete?: (log: X402TransactionLog) => void;
+}
+
+// ─── Well-known Assets ───
+
+/**
+ * USDC contract addresses by network (chain-name:chainId format).
+ * Sources:
+ *   - EVM chains: https://developers.circle.com/cctp/references/contract-addresses
+ *   - Linea: https://linea.build/ecosystem/usdc
+ *   - Unichain: https://docs.unichain.org/docs/technical-information/token-addresses
+ *   - Sonic: https://docs.soniclabs.com/build/useful-addresses
+ *   - Worldchain: https://docs.worldcoin.org/world-chain/addresses/usdc
+ */
+export const USDC_ADDRESSES: Record<string, Address> = {
+  // Testnets
+  "base-sepolia:84532": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  // Mainnets
+  "base:8453": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  "ethereum:1": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "arbitrum:42161": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  "polygon:137": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+  "bsc:56": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+  "optimism:10": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+  "avalanche:43114": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+  "unichain:130": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
+  "linea:59144": "0x176211869cA2b568f2A7D4EE941E073a821EE1ff",
+  "sonic:146": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
+  "worldchain:480": "0x79A02482A880bCE3B13e09Da970dC34db4CD24d1",
+} as const;
+
+/** Default supported networks (all mainnet chains) */
+export const DEFAULT_SUPPORTED_NETWORKS = [
+  "base:8453",
+  "ethereum:1",
+  "arbitrum:42161",
+  "polygon:137",
+  "bsc:56",
+  "optimism:10",
+  "avalanche:43114",
+  "unichain:130",
+  "linea:59144",
+  "sonic:146",
+  "worldchain:480",
+] as const;

package/src/services/wallet-backend-service.ts

@@ -0,0 +1,328 @@
+import {
+  type IAgentRuntime,
+  type ITokenDataService,
+  type IWalletService,
+  Service,
+  ServiceType,
+} from "@elizaos/core";
+import { validateWalletBridgeParams } from "../chains/evm/bridge-router.js";
+import { registerDefaultWalletChainHandlers } from "../chains/registry.js";
+import type {
+  WalletChainHandler,
+  WalletChainHandlerMetadata,
+  WalletRouterContext,
+  WalletRouterFailure,
+  WalletRouterParams,
+  WalletRouterResult,
+  WalletRouterSubaction,
+} from "../types/wallet-router.js";
+import { normalizeWalletChainKey } from "../types/wallet-router.js";
+import type { WalletBackend } from "../wallet/backend.js";
+import { resolveWalletBackend } from "../wallet/select-backend.js";
+import "../core-augmentation.js";
+
+export const WALLET_BACKEND_SERVICE_TYPE = "wallet-backend" as const;
+
+/**
+ * Runtime service exposing {@link WalletBackend}. Retrieve via
+ * `runtime.getService("wallet-backend")`.
+ */
+export class WalletBackendService extends Service {
+  static override serviceType = WALLET_BACKEND_SERVICE_TYPE;
+
+  override capabilityDescription =
+    "Unified wallet backend and chain router (EVM + Solana, local or Steward)";
+
+  private backend: WalletBackend | null = null;
+  private backendLoadError: unknown = null;
+  private readonly handlers = new Map<string, WalletChainHandler>();
+  private readonly aliases = new Map<string, string>();
+
+  static override async start(
+    runtime: IAgentRuntime,
+  ): Promise<WalletBackendService> {
+    const svc = new WalletBackendService(runtime);
+    try {
+      svc.backend = await resolveWalletBackend(runtime);
+    } catch (error) {
+      svc.backend = null;
+      svc.backendLoadError = error;
+      runtime.logger.warn(
+        {
+          error: error instanceof Error ? error.message : String(error),
+        },
+        "Wallet backend unavailable; wallet router will expose metadata and dry-run only until signing is configured",
+      );
+    }
+    registerDefaultWalletChainHandlers(svc, runtime);
+    return svc;
+  }
+
+  getWalletBackend(): WalletBackend {
+    if (!this.backend) {
+      if (this.backendLoadError instanceof Error) {
+        throw this.backendLoadError;
+      }
+      throw new Error("Wallet backend is not configured");
+    }
+    return this.backend;
+  }
+
+  getWalletBackendOrNull(): WalletBackend | null {
+    return this.backend;
+  }
+
+  registerChainHandler(handler: WalletChainHandler): void {
+    const key = normalizeWalletChainKey(handler.chain);
+    this.handlers.set(key, handler);
+
+    const aliases = new Set<string>([
+      handler.chain,
+      handler.chainId,
+      handler.name,
+      ...handler.aliases,
+    ]);
+    for (const alias of aliases) {
+      this.aliases.set(normalizeWalletChainKey(alias), key);
+    }
+  }
+
+  listChainHandlers(): WalletChainHandlerMetadata[] {
+    return [...this.handlers.values()].map((handler) =>
+      this.toMetadata(handler),
+    );
+  }
+
+  listChainHandlersForSubaction(
+    subaction: WalletRouterSubaction,
+  ): WalletChainHandlerMetadata[] {
+    return [...this.handlers.values()]
+      .filter((handler) => handler.supportedActions.includes(subaction))
+      .map((handler) => this.toMetadata(handler));
+  }
+
+  getCapabilities(): {
+    readonly chains: readonly WalletChainHandlerMetadata[];
+  } {
+    return {
+      chains: this.listChainHandlers(),
+    };
+  }
+
+  async routeWalletAction(
+    params: WalletRouterParams,
+  ): Promise<WalletRouterResult> {
+    const handlerResult = this.resolveHandler(params);
+    if (!handlerResult.ok) {
+      return handlerResult;
+    }
+
+    const { handler } = handlerResult;
+    const required = this.validateRequiredParams(params);
+    if (required) {
+      return required;
+    }
+
+    if (params.dryRun || params.mode === "prepare") {
+      if (
+        params.dryRun &&
+        (!handler.dryRun.supported ||
+          !handler.dryRun.supportedActions.includes(params.subaction))
+      ) {
+        return {
+          ok: false,
+          error: "DRY_RUN_UNSUPPORTED",
+          detail: `${handler.name} does not support dry-run for ${params.subaction}.`,
+        };
+      }
+
+      if (params.subaction === "bridge") {
+        try {
+          const result = await handler.execute(params, this.createContext());
+          return {
+            ok: true,
+            handler: this.toMetadata(handler),
+            result,
+          };
+        } catch (error) {
+          return {
+            ok: false,
+            error: "EXECUTION_FAILED",
+            detail: error instanceof Error ? error.message : String(error),
+          };
+        }
+      }
+
+      return {
+        ok: true,
+        handler: this.toMetadata(handler),
+        result: {
+          status: "prepared",
+          chain: handler.chain,
+          chainId: handler.chainId,
+          subaction: params.subaction,
+          dryRun: params.dryRun,
+          mode: params.mode,
+          amount: params.amount,
+          fromToken: params.fromToken,
+          toToken: params.toToken,
+          to: params.recipient,
+          metadata: {
+            signer: handler.signer,
+            dryRun: handler.dryRun,
+            supportedActions: handler.supportedActions,
+            tokens: handler.tokens,
+          },
+        },
+      };
+    }
+
+    try {
+      const result = await handler.execute(params, this.createContext());
+      return {
+        ok: true,
+        handler: this.toMetadata(handler),
+        result,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: "EXECUTION_FAILED",
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  override async stop(): Promise<void> {
+    // No persistent connections for local / Steward HTTP clients today.
+  }
+
+  private resolveHandler(
+    params: WalletRouterParams,
+  ):
+    | { readonly ok: true; readonly handler: WalletChainHandler }
+    | WalletRouterFailure {
+    if (params.chain) {
+      const alias = this.aliases.get(normalizeWalletChainKey(params.chain));
+      const handler = alias ? this.handlers.get(alias) : null;
+      if (!handler) {
+        return {
+          ok: false,
+          error: "UNSUPPORTED_CHAIN",
+          detail: `Unsupported wallet chain "${params.chain}".`,
+          candidates: this.listChainHandlers(),
+        };
+      }
+      if (!handler.supportedActions.includes(params.subaction)) {
+        return {
+          ok: false,
+          error: "UNSUPPORTED_SUBACTION",
+          detail: `${handler.name} does not support ${params.subaction}.`,
+          candidates: [this.toMetadata(handler)],
+        };
+      }
+      return { ok: true, handler };
+    }
+
+    const candidates = [...this.handlers.values()].filter((handler) =>
+      handler.supportedActions.includes(params.subaction),
+    );
+    if (candidates.length === 0) {
+      return {
+        ok: false,
+        error: "UNSUPPORTED_SUBACTION",
+        detail: `No wallet chain supports ${params.subaction}.`,
+      };
+    }
+    if (candidates.length > 1) {
+      return {
+        ok: false,
+        error: "AMBIGUOUS_CHAIN",
+        detail: `Choose a chain for wallet ${params.subaction}.`,
+        candidates: candidates.map((handler) => this.toMetadata(handler)),
+      };
+    }
+
+    const handler = candidates[0];
+    return { ok: true, handler };
+  }
+
+  private validateRequiredParams(
+    params: WalletRouterParams,
+  ): WalletRouterFailure | null {
+    if (params.subaction === "bridge") {
+      const detail = validateWalletBridgeParams(params);
+      return detail ? { ok: false, error: "INVALID_PARAMS", detail } : null;
+    }
+    if (!params.amount) {
+      return {
+        ok: false,
+        error: "INVALID_PARAMS",
+        detail: "amount is required.",
+      };
+    }
+    if (params.subaction === "transfer" && !params.recipient) {
+      return {
+        ok: false,
+        error: "INVALID_PARAMS",
+        detail: "recipient is required for transfer.",
+      };
+    }
+    if (params.subaction === "swap") {
+      if (!params.fromToken) {
+        return {
+          ok: false,
+          error: "INVALID_PARAMS",
+          detail: "fromToken is required for swap.",
+        };
+      }
+      if (!params.toToken) {
+        return {
+          ok: false,
+          error: "INVALID_PARAMS",
+          detail: "toToken is required for swap.",
+        };
+      }
+    }
+    return null;
+  }
+
+  private createContext(): WalletRouterContext {
+    return {
+      runtime: this.runtime,
+      walletBackend: this.backend,
+      walletServices: this.getWalletServices(),
+      tokenDataService: this.getTokenDataService(),
+    };
+  }
+
+  private getWalletServices(): IWalletService[] {
+    const runtime = this.runtime as IAgentRuntime & {
+      getServicesByType?: <T>(serviceName: string) => T[];
+    };
+    if (typeof runtime.getServicesByType !== "function") {
+      return [];
+    }
+    return runtime.getServicesByType<IWalletService>(ServiceType.WALLET);
+  }
+
+  private getTokenDataService(): ITokenDataService | null {
+    return this.runtime.getService<ITokenDataService>(ServiceType.TOKEN_DATA);
+  }
+
+  private toMetadata(handler: WalletChainHandler): WalletChainHandlerMetadata {
+    return {
+      chainId: handler.chainId,
+      chain: handler.chain,
+      name: handler.name,
+      aliases: [...handler.aliases],
+      supportedActions: [...handler.supportedActions],
+      tokens: handler.tokens.map((token) => ({ ...token })),
+      signer: { ...handler.signer },
+      dryRun: {
+        ...handler.dryRun,
+        supportedActions: [...handler.dryRun.supportedActions],
+      },
+    };
+  }
+}

package/src/types/wallet-router.ts

@@ -0,0 +1,227 @@
+import type {
+  IAgentRuntime,
+  ITokenDataService,
+  IWalletService,
+} from "@elizaos/core";
+import { z } from "zod";
+import type { WalletBackend } from "../wallet/backend.js";
+
+export const WALLET_ROUTER_SUBACTIONS = [
+  "transfer",
+  "swap",
+  "bridge",
+  "gov",
+] as const;
+
+export type WalletRouterSubaction = (typeof WALLET_ROUTER_SUBACTIONS)[number];
+
+export const WALLET_ROUTER_MODES = ["prepare", "execute"] as const;
+
+export type WalletRouterMode = (typeof WALLET_ROUTER_MODES)[number];
+
+export const WALLET_GOV_OPS = ["propose", "vote", "queue", "execute"] as const;
+
+export type WalletGovOp = (typeof WALLET_GOV_OPS)[number];
+
+export interface WalletRouterParams {
+  readonly subaction: WalletRouterSubaction;
+  readonly chain?: string;
+  readonly toChain?: string;
+  readonly fromToken?: string;
+  readonly toToken?: string;
+  readonly amount?: string;
+  readonly recipient?: string;
+  readonly slippageBps?: number;
+  readonly mode: WalletRouterMode;
+  readonly dryRun: boolean;
+  readonly op?: WalletGovOp;
+  readonly governor?: string;
+  readonly proposalId?: string;
+  readonly support?: number;
+  readonly targets?: readonly string[];
+  readonly values?: readonly string[];
+  readonly calldatas?: readonly string[];
+  readonly description?: string;
+}
+
+export interface WalletTokenMetadata {
+  readonly symbol: string;
+  readonly address: string;
+  readonly decimals?: number;
+  readonly native?: boolean;
+}
+
+export interface WalletSignerMetadata {
+  readonly required: boolean;
+  readonly kind: "evm" | "solana" | "off-chain";
+  readonly source?: string;
+  readonly description?: string;
+}
+
+export interface WalletDryRunMetadata {
+  readonly supported: boolean;
+  readonly supportedActions: readonly WalletRouterSubaction[];
+  readonly description?: string;
+}
+
+export interface WalletChainHandlerMetadata {
+  readonly chainId: string;
+  readonly chain: string;
+  readonly name: string;
+  readonly aliases: readonly string[];
+  readonly supportedActions: readonly WalletRouterSubaction[];
+  readonly tokens: readonly WalletTokenMetadata[];
+  readonly signer: WalletSignerMetadata;
+  readonly dryRun: WalletDryRunMetadata;
+}
+
+export interface WalletRouterContext {
+  readonly runtime: IAgentRuntime;
+  readonly walletBackend: WalletBackend | null;
+  readonly walletServices: readonly IWalletService[];
+  readonly tokenDataService: ITokenDataService | null;
+}
+
+export interface WalletRouterExecution {
+  readonly status: "prepared" | "submitted";
+  readonly chain: string;
+  readonly chainId: string;
+  readonly subaction: WalletRouterSubaction;
+  readonly dryRun: boolean;
+  readonly mode: WalletRouterMode;
+  readonly transactionHash?: string;
+  readonly signature?: string;
+  readonly from?: string;
+  readonly to?: string;
+  readonly amount?: string;
+  readonly fromToken?: string;
+  readonly toToken?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface WalletChainHandler extends WalletChainHandlerMetadata {
+  execute(
+    params: WalletRouterParams,
+    context: WalletRouterContext,
+  ): Promise<WalletRouterExecution>;
+}
+
+export type WalletRouterErrorCode =
+  | "INVALID_PARAMS"
+  | "UNSUPPORTED_CHAIN"
+  | "UNSUPPORTED_SUBACTION"
+  | "AMBIGUOUS_CHAIN"
+  | "DRY_RUN_UNSUPPORTED"
+  | "EXECUTION_FAILED";
+
+export interface WalletRouterFailure {
+  readonly ok: false;
+  readonly error: WalletRouterErrorCode;
+  readonly detail: string;
+  readonly candidates?: readonly WalletChainHandlerMetadata[];
+}
+
+export interface WalletRouterSuccess {
+  readonly ok: true;
+  readonly result: WalletRouterExecution;
+  readonly handler: WalletChainHandlerMetadata;
+}
+
+export type WalletRouterResult = WalletRouterSuccess | WalletRouterFailure;
+
+const optionalString = z
+  .union([z.string(), z.number()])
+  .optional()
+  .nullable()
+  .transform((value) => {
+    if (value === null || value === undefined) return undefined;
+    const out = String(value).trim();
+    return out.length > 0 ? out : undefined;
+  });
+
+const optionalPositiveAmount = optionalString.refine(
+  (value) => {
+    if (value === undefined) return true;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0;
+  },
+  { message: "amount must be a positive number" },
+);
+
+const optionalStringArray = z.preprocess((value) => {
+  if (value === null || value === undefined) return undefined;
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => String(item).trim())
+      .filter((item) => item.length > 0);
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0);
+  }
+  return undefined;
+}, z.array(z.string()).optional());
+
+export const WalletRouterParamsSchema = z.object({
+  subaction: z.enum(WALLET_ROUTER_SUBACTIONS),
+  chain: optionalString,
+  toChain: optionalString,
+  fromToken: optionalString,
+  toToken: optionalString,
+  amount: optionalPositiveAmount,
+  recipient: optionalString,
+  slippageBps: z.coerce.number().int().min(0).max(10_000).optional(),
+  mode: z.enum(WALLET_ROUTER_MODES).default("prepare"),
+  dryRun: z
+    .preprocess((value) => {
+      if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (
+          normalized === "true" ||
+          normalized === "1" ||
+          normalized === "yes"
+        ) {
+          return true;
+        }
+        if (
+          normalized === "false" ||
+          normalized === "0" ||
+          normalized === "no"
+        ) {
+          return false;
+        }
+      }
+      return value;
+    }, z.boolean())
+    .default(false),
+  op: z.enum(WALLET_GOV_OPS).optional(),
+  governor: optionalString,
+  proposalId: optionalString,
+  support: z.coerce.number().int().min(0).max(2).optional(),
+  targets: optionalStringArray,
+  values: optionalStringArray,
+  calldatas: optionalStringArray,
+  description: optionalString,
+});
+
+export function parseWalletRouterParams(input: unknown): WalletRouterParams {
+  return WalletRouterParamsSchema.parse(input) as WalletRouterParams;
+}
+
+export function isWalletRouterSubaction(
+  value: unknown,
+): value is WalletRouterSubaction {
+  return (
+    typeof value === "string" &&
+    WALLET_ROUTER_SUBACTIONS.includes(value as WalletRouterSubaction)
+  );
+}
+
+export function normalizeWalletChainKey(value: string | number): string {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "");
+}