@elizaos/plugin-wallet 2.0.0-beta.1

package/src/chains/wallet-router.test.ts

@@ -0,0 +1,296 @@
+import type { HandlerOptions, IAgentRuntime, Memory } from "@elizaos/core";
+import { describe, expect, it, vi } from "vitest";
+import { WalletBackendService } from "../services/wallet-backend-service";
+import type {
+  WalletChainHandler,
+  WalletRouterExecution,
+  WalletRouterParams,
+} from "../types/wallet-router";
+import { walletRouterAction } from "./wallet-action";
+
+function createRuntime(): IAgentRuntime {
+  const logger = {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    log: vi.fn(),
+    warn: vi.fn(),
+  };
+  const runtime = {
+    agentId: "test-agent",
+    character: { name: "Test Agent", settings: {} },
+    getService: vi.fn(() => null),
+    getServicesByType: vi.fn(() => []),
+    getSetting: vi.fn(() => null),
+    logger,
+  };
+
+  return runtime as IAgentRuntime;
+}
+
+function createService(): {
+  readonly runtime: IAgentRuntime;
+  readonly service: WalletBackendService;
+} {
+  const runtime = createRuntime();
+  const service = new WalletBackendService(runtime);
+  vi.mocked(runtime.getService).mockImplementation((name: string) =>
+    name === WalletBackendService.serviceType ? service : null,
+  );
+  return { runtime, service };
+}
+
+function handler(
+  chain: string,
+  name: string,
+  chainId: string,
+  kind: "evm" | "solana",
+  supportedActions: WalletChainHandler["supportedActions"] = [
+    "transfer",
+    "swap",
+  ],
+): WalletChainHandler {
+  const execute = vi.fn(
+    async (params: WalletRouterParams): Promise<WalletRouterExecution> => ({
+      status: "submitted",
+      chain,
+      chainId,
+      subaction: params.subaction,
+      dryRun: false,
+      mode: params.mode,
+      transactionHash: kind === "evm" ? "0xtest" : undefined,
+      signature: kind === "solana" ? "soltest" : undefined,
+      amount: params.amount,
+      fromToken: params.fromToken,
+      toToken: params.toToken,
+      to: params.recipient,
+    }),
+  );
+  return {
+    chain,
+    name,
+    chainId,
+    aliases:
+      kind === "solana"
+        ? [chain, name, chainId, "sol"]
+        : [chain, name, chainId],
+    supportedActions,
+    tokens: [
+      {
+        symbol: kind === "evm" ? "ETH" : "SOL",
+        address:
+          kind === "evm"
+            ? "0x0000000000000000000000000000000000000000"
+            : "So11111111111111111111111111111111111111112",
+        decimals: kind === "evm" ? 18 : 9,
+        native: true,
+      },
+    ],
+    signer: {
+      required: true,
+      kind,
+      source: "test",
+    },
+    dryRun: {
+      supported: true,
+      supportedActions,
+    },
+    execute,
+  };
+}
+
+function message(): Memory {
+  return {
+    id: "00000000-0000-0000-0000-000000000001",
+    entityId: "00000000-0000-0000-0000-000000000002",
+    agentId: "00000000-0000-0000-0000-000000000003",
+    roomId: "00000000-0000-0000-0000-000000000004",
+    content: { text: "wallet action" },
+    createdAt: Date.now(),
+  } as Memory;
+}
+
+async function run(
+  runtime: IAgentRuntime,
+  parameters: Record<string, unknown>,
+) {
+  return walletRouterAction.handler(runtime, message(), undefined, {
+    parameters,
+  } as HandlerOptions);
+}
+
+describe("wallet router action", () => {
+  it("routes EVM transfer through the selected chain handler", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    service.registerChainHandler(base);
+
+    const result = await run(runtime, {
+      subaction: "transfer",
+      chain: "base",
+      fromToken: "ETH",
+      amount: "0.5",
+      recipient: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(true);
+    expect(base.execute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        subaction: "transfer",
+        chain: "base",
+        amount: "0.5",
+      }),
+      expect.any(Object),
+    );
+    expect(result?.data?.chain).toBe("base");
+    expect(result?.data?.transactionHash).toBe("0xtest");
+  });
+
+  it("routes EVM swap through the selected chain handler", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    service.registerChainHandler(base);
+
+    const result = await run(runtime, {
+      subaction: "swap",
+      chain: "8453",
+      fromToken: "0x0000000000000000000000000000000000000000",
+      toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      amount: "1",
+      slippageBps: 100,
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(true);
+    expect(base.execute).toHaveBeenCalledWith(
+      expect.objectContaining({
+        subaction: "swap",
+        chain: "8453",
+        fromToken: "0x0000000000000000000000000000000000000000",
+        toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("routes Solana transfer and swap through the Solana handler", async () => {
+    const { runtime, service } = createService();
+    const solana = handler("solana", "Solana", "solana-mainnet", "solana");
+    service.registerChainHandler(solana);
+
+    const transfer = await run(runtime, {
+      subaction: "transfer",
+      chain: "sol",
+      fromToken: "SOL",
+      amount: "2",
+      recipient: "9xQeWvG816bUx9EPfWJXn4xHLh1BaK7Z7QXDXuGpS9SW",
+      mode: "execute",
+    });
+    const swap = await run(runtime, {
+      subaction: "swap",
+      chain: "solana",
+      fromToken: "SOL",
+      toToken: "USDC",
+      amount: "3",
+      mode: "execute",
+    });
+
+    expect(transfer?.success).toBe(true);
+    expect(swap?.success).toBe(true);
+    expect(solana.execute).toHaveBeenCalledTimes(2);
+    expect(solana.execute).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ subaction: "transfer" }),
+      expect.any(Object),
+    );
+    expect(solana.execute).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ subaction: "swap" }),
+      expect.any(Object),
+    );
+  });
+
+  it("returns unsupported chain details without executing", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    service.registerChainHandler(base);
+
+    const result = await run(runtime, {
+      subaction: "transfer",
+      chain: "doge",
+      amount: "1",
+      recipient: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(false);
+    expect(result?.data?.error).toBe("UNSUPPORTED_CHAIN");
+    expect(base.execute).not.toHaveBeenCalled();
+  });
+
+  it("clarifies ambiguous omitted chains", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    const solana = handler("solana", "Solana", "solana-mainnet", "solana");
+    service.registerChainHandler(base);
+    service.registerChainHandler(solana);
+
+    const result = await run(runtime, {
+      subaction: "transfer",
+      amount: "1",
+      recipient: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(false);
+    expect(result?.data?.error).toBe("AMBIGUOUS_CHAIN");
+    expect(String(result?.text)).toContain("Available chains");
+    expect(base.execute).not.toHaveBeenCalled();
+    expect(solana.execute).not.toHaveBeenCalled();
+  });
+
+  it("defaults omitted chain when only one handler supports subaction", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    service.registerChainHandler(base);
+
+    const result = await run(runtime, {
+      subaction: "swap",
+      fromToken: "ETH",
+      toToken: "USDC",
+      amount: "1",
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(true);
+    expect(base.execute).toHaveBeenCalledWith(
+      expect.objectContaining({ subaction: "swap" }),
+      expect.any(Object),
+    );
+    expect(result?.data?.chain).toBe("base");
+  });
+
+  it("prepares dry-run metadata without executing", async () => {
+    const { runtime, service } = createService();
+    const base = handler("base", "Base", "8453", "evm");
+    service.registerChainHandler(base);
+
+    const result = await run(runtime, {
+      subaction: "transfer",
+      chain: "base",
+      amount: "1",
+      recipient: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+      dryRun: true,
+      mode: "execute",
+    });
+
+    expect(result?.success).toBe(true);
+    expect(result?.data?.dryRun).toBe(true);
+    expect(result?.data?.metadata).toMatchObject({
+      signer: { kind: "evm", required: true },
+      dryRun: { supported: true },
+    });
+    expect(base.execute).not.toHaveBeenCalled();
+  });
+});

package/src/contracts.ts

@@ -0,0 +1,65 @@
+export interface WalletExportRequestBody {
+  confirm?: boolean;
+  exportToken?: string;
+}
+
+export interface WalletExportRejection {
+  status: 400 | 401 | 402 | 403 | 429;
+  reason: string;
+}
+
+export interface WalletMarketPriceSnapshot {
+  id: string;
+  symbol: string;
+  name: string;
+  priceUsd: number;
+  change24hPct: number;
+  imageUrl: string | null;
+}
+
+export interface WalletMarketMover {
+  id: string;
+  symbol: string;
+  name: string;
+  priceUsd: number;
+  change24hPct: number;
+  marketCapRank: number | null;
+  imageUrl: string | null;
+}
+
+export interface WalletMarketPrediction {
+  id: string;
+  slug: string | null;
+  question: string;
+  highlightedOutcomeLabel: string;
+  highlightedOutcomeProbability: number | null;
+  volume24hUsd: number;
+  totalVolumeUsd: number | null;
+  endsAt: string | null;
+  imageUrl: string | null;
+}
+
+export type WalletMarketOverviewProviderId = "coingecko" | "polymarket";
+
+export interface WalletMarketOverviewSource {
+  providerId: WalletMarketOverviewProviderId;
+  providerName: string;
+  providerUrl: string;
+  available: boolean;
+  stale: boolean;
+  error: string | null;
+}
+
+export interface WalletMarketOverviewResponse {
+  generatedAt: string;
+  cacheTtlSeconds: number;
+  stale: boolean;
+  sources: {
+    prices: WalletMarketOverviewSource;
+    movers: WalletMarketOverviewSource;
+    predictions: WalletMarketOverviewSource;
+  };
+  prices: WalletMarketPriceSnapshot[];
+  movers: WalletMarketMover[];
+  predictions: WalletMarketPrediction[];
+}

package/src/core-augmentation.ts

@@ -0,0 +1,10 @@
+/**
+ * Augment elizaOS service registry so `getService("wallet-backend")` is typed.
+ */
+declare module "@elizaos/core" {
+  interface ServiceTypeRegistry {
+    WALLET_BACKEND: "wallet-backend";
+  }
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,71 @@
+import "./core-augmentation.js";
+
+export * from "./actions/index.js";
+export { BirdeyeService } from "./analytics/birdeye/service.js";
+export { DexScreenerService } from "./analytics/dexscreener/index.js";
+// Consolidated analytics surface (formerly @elizaos/plugin-{lpinfo,dexscreener,defi-news,birdeye}).
+export {
+  kaminoPlugin,
+  lpinfoPlugin,
+  steerPlugin,
+} from "./analytics/lpinfo/index.js";
+export {
+  defiNewsPlugin,
+  defiNewsProvider,
+  NewsDataService,
+} from "./analytics/news/index.js";
+export {
+  TOKEN_INFO_SERVICE_TYPE,
+  TokenInfoService,
+  tokenInfoAction,
+} from "./analytics/token-info/index.js";
+export * from "./audit/audit-log.js";
+export { walletRouterAction } from "./chains/wallet-action.js";
+export * from "./contracts.js";
+export {
+  canUseLocalTradeExecution,
+  resolveTradePermissionMode,
+  resolveWalletExportRejection,
+} from "./lib/server-wallet-trade.js";
+export {
+  _resetForTesting,
+  getWalletExportAuditLog,
+} from "./lib/wallet-export-guard.js";
+// Consolidated LP management surface (formerly @elizaos/plugin-lp-manager).
+// Includes Solana DEX adapters (Raydium / Orca / Meteora) under
+// chains/solana/dex/* and EVM DEX adapters (Uniswap / PancakeSwap / Aerodrome)
+// under chains/evm/dex/*.
+export {
+  AerodromeLpService,
+  aerodromePlugin,
+  ConcentratedLiquidityService,
+  DexInteractionService,
+  default as lpManagerPlugin,
+  LP_MANAGER_PLUGIN_NAME,
+  LpManagementAgentAction,
+  orcaPlugin,
+  PancakeSwapV3LpService,
+  pancakeswapPlugin,
+  raydiumPlugin,
+  UniswapV3LpService,
+  UserLpProfileService,
+  uniswapPlugin,
+  VaultService,
+  YieldOptimizationService,
+} from "./lp/lp-manager-entry.js";
+export * from "./lp/types.js";
+export { default, walletPlugin } from "./plugin.js";
+export * from "./policy/policy.js";
+export * from "./providers/canonical-provider.js";
+export { unifiedWalletProvider } from "./providers/unified-wallet-provider.js";
+export * from "./register-routes.js";
+export * from "./routes/plugin.js";
+/** ERC-6551 / x402 / CCTP / swaps are available from the package barrel. */
+export * from "./sdk/index.js";
+export {
+  WALLET_BACKEND_SERVICE_TYPE,
+  WalletBackendService,
+} from "./services/wallet-backend-service.js";
+export * from "./types/wallet-router.js";
+export * from "./wallet/index.js";
+export * from "./wallet-action.js";

package/src/lib/server-wallet-trade.ts

@@ -0,0 +1,192 @@
+/**
+ * Wallet / trade compat helpers — trade permission modes, local execution
+ * guards, and wallet export rejection wrappers.
+ *
+ * Exported from the `@elizaos/plugin-wallet` barrel for package consumers.
+ */
+import crypto from "node:crypto";
+import type http from "node:http";
+import { syncAppEnvToEliza, syncElizaEnvAliases } from "@elizaos/core";
+
+import type { WalletExportRequestBody } from "../contracts.js";
+import {
+  type WalletExportRejection as CompatWalletExportRejection,
+  createHardenedExportGuard,
+} from "./wallet-export-guard";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function normalizeCompatReason(reason: string): string {
+  return reason;
+}
+
+function mirrorCompatHeaders(req: Pick<http.IncomingMessage, "headers">): void {
+  const HEADER_ALIASES = [
+    ["x-elizaos-token", "x-eliza-token"],
+    ["x-elizaos-export-token", "x-eliza-export-token"],
+    ["x-elizaos-client-id", "x-eliza-client-id"],
+    ["x-elizaos-terminal-token", "x-eliza-terminal-token"],
+    ["x-elizaos-ui-language", "x-eliza-ui-language"],
+    ["x-elizaos-agent-action", "x-eliza-agent-action"],
+  ] as const;
+
+  for (const [appHeader, elizaHeader] of HEADER_ALIASES) {
+    const appValue = req.headers[appHeader];
+    const elizaValue = req.headers[elizaHeader];
+
+    if (appValue != null && elizaValue == null) {
+      req.headers[elizaHeader] = appValue;
+    }
+
+    if (elizaValue != null && appValue == null) {
+      req.headers[appHeader] = elizaValue;
+    }
+  }
+}
+
+export function normalizeCompatRejection<
+  T extends { status: number; reason: string } | null,
+>(rejection: T): T {
+  if (!rejection) {
+    return rejection;
+  }
+
+  return {
+    ...rejection,
+    reason: normalizeCompatReason(rejection.reason),
+  } as T;
+}
+
+export function runWithCompatAuthContext<T>(
+  req: Pick<http.IncomingMessage, "headers">,
+  operation: () => T,
+): T {
+  syncElizaEnvAliases();
+  syncAppEnvToEliza();
+  mirrorCompatHeaders(req);
+
+  try {
+    return operation();
+  } finally {
+    syncAppEnvToEliza();
+    syncElizaEnvAliases();
+  }
+}
+
+function tokenMatches(expected: string, provided: string): boolean {
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(provided, "utf8");
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+function resolveBaseWalletExportRejection(
+  req: http.IncomingMessage,
+  body: WalletExportRequestBody,
+): CompatWalletExportRejection | null {
+  if (!body.confirm) {
+    return {
+      status: 403,
+      reason:
+        'Export requires explicit confirmation. Send { "confirm": true } in the request body.',
+    };
+  }
+
+  const expected = process.env.ELIZA_WALLET_EXPORT_TOKEN?.trim();
+  if (!expected) {
+    return {
+      status: 403,
+      reason:
+        "Wallet export is disabled. Set ELIZA_WALLET_EXPORT_TOKEN to enable secure exports.",
+    };
+  }
+
+  const headerToken =
+    typeof req.headers["x-eliza-export-token"] === "string"
+      ? req.headers["x-eliza-export-token"].trim()
+      : "";
+  const bodyToken =
+    typeof body.exportToken === "string" ? body.exportToken.trim() : "";
+  const provided = headerToken || bodyToken;
+
+  if (!provided) {
+    return {
+      status: 401,
+      reason:
+        "Missing export token. Provide X-Eliza-Export-Token header or exportToken in request body.",
+    };
+  }
+
+  if (!tokenMatches(expected, provided)) {
+    return { status: 401, reason: "Invalid export token." };
+  }
+
+  return null;
+}
+
+function resolveCompatWalletExportRejection(
+  req: http.IncomingMessage,
+  body: WalletExportRequestBody,
+): CompatWalletExportRejection | null {
+  return runWithCompatAuthContext(req, () =>
+    normalizeCompatRejection(resolveBaseWalletExportRejection(req, body)),
+  );
+}
+
+// Create the hardened guard with the compat rejection resolver
+const hardenedGuard = createHardenedExportGuard(
+  resolveCompatWalletExportRejection,
+);
+
+// ---------------------------------------------------------------------------
+// Exported types and functions
+// ---------------------------------------------------------------------------
+
+export type TradePermissionMode =
+  | "user-sign-only"
+  | "manual-local-key"
+  | "agent-auto";
+
+export function resolveTradePermissionMode(config: {
+  features?: { tradePermissionMode?: unknown } | null;
+}): TradePermissionMode {
+  const raw = config.features?.tradePermissionMode;
+  if (
+    raw === "user-sign-only" ||
+    raw === "manual-local-key" ||
+    raw === "agent-auto"
+  ) {
+    return raw;
+  }
+  return "user-sign-only";
+}
+
+export function canUseLocalTradeExecution(
+  mode: TradePermissionMode,
+  isAgent: boolean,
+): boolean {
+  if (mode === "agent-auto") {
+    return true;
+  }
+  if (mode === "manual-local-key") {
+    return !isAgent;
+  }
+  return false;
+}
+
+/**
+ * Hardened wallet export rejection function.
+ *
+ * Wraps the upstream token validation with per-IP rate limiting (1 per 10 min),
+ * audit logging (IP + UA), and a 10s confirmation delay via single-use nonces.
+ */
+export function resolveWalletExportRejection(
+  req: http.IncomingMessage,
+  body: WalletExportRequestBody,
+): CompatWalletExportRejection | null {
+  return runWithCompatAuthContext(req, () =>
+    normalizeCompatRejection(hardenedGuard(req, body)),
+  );
+}