@elizaos/plugin-wallet 2.0.0-beta.1

package/src/plugin.ts

@@ -0,0 +1,125 @@
+import { resolveCloudRoute, toRuntimeSettings } from "@elizaos/cloud-routing";
+import {
+  type IAgentRuntime,
+  type Plugin,
+  parseBooleanFromText,
+  type ServiceClass,
+} from "@elizaos/core";
+import { walletSearchAddressAction } from "./analytics/birdeye/actions/wallet-search-address.js";
+import { agentPortfolioProvider } from "./analytics/birdeye/providers/agent-portfolio-provider.js";
+import { marketProvider } from "./analytics/birdeye/providers/market.js";
+import { trendingProvider } from "./analytics/birdeye/providers/trending.js";
+import { registerBirdeyeSearchCategories } from "./analytics/birdeye/search-category.js";
+import {
+  BIRDEYE_ROUTE_SPEC,
+  BirdeyeService,
+} from "./analytics/birdeye/service.js";
+import { registerDexScreenerSearchCategory } from "./analytics/dexscreener/search-category.js";
+import { DexScreenerService } from "./analytics/dexscreener/service.js";
+import { tokenInfoAction } from "./analytics/token-info/action.js";
+import { TokenInfoService } from "./analytics/token-info/service.js";
+import evmPlugin from "./chains/evm/index.js";
+import solanaPlugin from "./chains/solana/index.js";
+import { unifiedWalletProvider } from "./providers/unified-wallet-provider.js";
+import { WalletBackendService } from "./services/wallet-backend-service.js";
+
+const coreWalletPlugin: Plugin = {
+  name: "wallet-backend",
+  description:
+    "Wallet backend service + unified wallet provider (Steward / local).",
+  services: [WalletBackendService],
+  providers: [unifiedWalletProvider],
+  actions: [],
+};
+
+function concatServices(
+  ...chunks: (readonly ServiceClass[] | undefined)[]
+): ServiceClass[] {
+  const out: ServiceClass[] = [];
+  for (const c of chunks) {
+    if (c) out.push(...c);
+  }
+  return out;
+}
+
+function concatPlugins<T>(...chunks: (readonly T[] | undefined)[]): T[] {
+  const out: T[] = [];
+  for (const c of chunks) {
+    if (c) out.push(...c);
+  }
+  return out;
+}
+
+async function initBirdeyeAnalytics(runtime: IAgentRuntime): Promise<void> {
+  const birdeyeRoute = resolveCloudRoute(
+    toRuntimeSettings(runtime),
+    BIRDEYE_ROUTE_SPEC,
+  );
+  registerBirdeyeSearchCategories(runtime, {
+    enabled: birdeyeRoute.source !== "disabled",
+    disabledReason:
+      birdeyeRoute.source === "disabled"
+        ? "BIRDEYE_API_KEY or Eliza Cloud route is not configured."
+        : undefined,
+  });
+  if (birdeyeRoute.source === "disabled") {
+    runtime.logger.log(
+      "birdeye: no BIRDEYE_API_KEY and Eliza Cloud not connected, skipping plugin-birdeye init",
+    );
+    return;
+  }
+
+  const walletAddr = runtime.getSetting("BIRDEYE_WALLET_ADDR");
+  if (walletAddr) {
+    runtime.registerProvider(agentPortfolioProvider);
+  }
+  runtime.registerProvider(marketProvider);
+
+  const beNoTrending = parseBooleanFromText(
+    String(runtime.getSetting("BIRDEYE_NO_TRENDING") ?? ""),
+  );
+  if (!beNoTrending) {
+    runtime.registerProvider(trendingProvider);
+  } else {
+    runtime.logger.log(
+      "BIRDEYE_NO_TRENDING is set, skipping trending provider",
+    );
+  }
+}
+
+const analyticsServices: ServiceClass[] = [
+  BirdeyeService,
+  DexScreenerService,
+  TokenInfoService,
+] as ServiceClass[];
+
+/**
+ * Single plugin surface: EVM + Solana wallet backend.
+ * Consumers should depend only on `@elizaos/plugin-wallet`.
+ */
+export const walletPlugin: Plugin = {
+  name: "wallet",
+  description:
+    "Unified non-custodial wallet for elizaOS — EVM + Solana, Steward/local backends, x402, CCTP, and venue routing.",
+  services: concatServices(
+    coreWalletPlugin.services,
+    evmPlugin.services as ServiceClass[] | undefined,
+    solanaPlugin.services as ServiceClass[] | undefined,
+    analyticsServices,
+  ),
+  providers: concatPlugins(coreWalletPlugin.providers, evmPlugin.providers),
+  actions: concatPlugins(coreWalletPlugin.actions, evmPlugin.actions, [
+    tokenInfoAction,
+    walletSearchAddressAction,
+  ]),
+  routes: concatPlugins(solanaPlugin.routes),
+  init: async (config, runtime) => {
+    await coreWalletPlugin.init?.(config, runtime);
+    await evmPlugin.init?.(config, runtime);
+    await solanaPlugin.init?.(config, runtime);
+    registerDexScreenerSearchCategory(runtime);
+    await initBirdeyeAnalytics(runtime);
+  },
+};
+
+export default walletPlugin;

package/src/policy/policy.ts

@@ -0,0 +1,19 @@
+import type { ApprovalSummary, SignScope } from "../wallet/pending.js";
+
+export interface PolicyEvaluation {
+  readonly kind: "ok" | "requires_approval" | "blocked";
+  readonly reason?: string;
+  readonly rule?: string;
+  readonly cooldownUntil?: number;
+}
+
+/**
+ * Business rules for size limits, allowlists, and cooldowns. Actions never
+ * inline policy checks — they delegate here after zod parse + plugin checks.
+ */
+export interface PolicyModule {
+  evaluate(
+    scope: SignScope,
+    summary: ApprovalSummary,
+  ): Promise<PolicyEvaluation>;
+}

package/src/providers/canonical-provider.ts

@@ -0,0 +1,27 @@
+import type {
+  IAgentRuntime,
+  Memory,
+  ProviderResult,
+  State,
+} from "@elizaos/core";
+
+export type HealthStatus = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Typed venue / data-source adapter. Canonical actions dispatch into concrete
+ * provider classes registered on the runtime provider registry (Phase 2 wiring).
+ *
+ * See docs/architecture/wallet-and-trading.md §B.3.
+ */
+export interface CanonicalProvider {
+  readonly name: string;
+  readonly contextBudgetTokens: number;
+
+  getContext(
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State,
+  ): Promise<ProviderResult>;
+
+  healthcheck(runtime: IAgentRuntime): Promise<HealthStatus>;
+}

package/src/providers/unified-wallet-provider.ts

@@ -0,0 +1,79 @@
+import type { IAgentRuntime, Memory, Provider, State } from "@elizaos/core";
+import type { WalletBackendService } from "../services/wallet-backend-service.js";
+import {
+  StewardUnavailableError,
+  WalletBackendNotConfiguredError,
+} from "../wallet/errors.js";
+
+const MAX_WALLET_TEXT_CHARS = 1000;
+
+/**
+ * Injects live addresses into planner context. Always-on (200-token budget in spec).
+ */
+export const unifiedWalletProvider: Provider = {
+  name: "wallet",
+  description:
+    "Unified non-custodial wallet — EVM + Solana addresses (@elizaos/plugin-wallet).",
+  descriptionCompressed:
+    "unifi non-custodial wallet EVM + Solana address (elizaos/plugin-wallet)",
+  contexts: ["finance", "crypto", "wallet"],
+  contextGate: { anyOf: ["finance", "crypto", "wallet"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  roleGate: { minRole: "OWNER" },
+  position: -5,
+  dynamic: true,
+  get: async (runtime: IAgentRuntime, _message: Memory, _state: State) => {
+    void _message;
+    void _state;
+    const svc = runtime.getService(
+      "wallet-backend",
+    ) as WalletBackendService | null;
+    if (!svc) {
+      return {
+        text: "## Wallet\nWallet backend service is not running.",
+        values: { walletReady: false },
+      };
+    }
+    try {
+      const w = svc.getWalletBackend();
+      const { evm, solana } = w.getAddresses();
+      const evmLine = evm ? `- EVM: ${evm}` : "- EVM: (not configured)";
+      const solLine = solana
+        ? `- Solana: ${solana.toBase58()}`
+        : "- Solana: (not configured)";
+      const text = `## Wallet\n${evmLine}\n${solLine}`.slice(
+        0,
+        MAX_WALLET_TEXT_CHARS,
+      );
+      return {
+        text,
+        values: {
+          walletReady: evm !== null || solana !== null,
+          evmAddress: evm ?? null,
+          solanaAddress: solana?.toBase58() ?? null,
+          backendKind: w.kind,
+        },
+      };
+    } catch (e) {
+      if (
+        e instanceof WalletBackendNotConfiguredError ||
+        e instanceof StewardUnavailableError
+      ) {
+        return {
+          text: `## Wallet\n${e.message}`,
+          values: { walletReady: false, walletError: e.name },
+        };
+      }
+      return {
+        text: `## Wallet\nWallet backend error: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        values: {
+          walletReady: false,
+          walletError: e instanceof Error ? e.name : "WalletBackendError",
+        },
+      };
+    }
+  },
+};

package/src/register-routes.ts

@@ -0,0 +1,11 @@
+/**
+ * Side-effect import: registers the @elizaos/plugin-wallet route plugin
+ * with the runtime app-route plugin registry. Imported by the API server
+ * at startup so wallet HTTP routes are dispatched via Plugin.routes.
+ */
+import { registerAppRoutePluginLoader } from "@elizaos/core";
+
+registerAppRoutePluginLoader("@elizaos/plugin-wallet:routes", async () => {
+  const { walletRoutePlugin } = await import("./routes/plugin");
+  return walletRoutePlugin;
+});

package/src/routes/plugin.ts

@@ -0,0 +1,47 @@
+/**
+ * Wallet route plugin — registers wallet HTTP route handlers with the
+ * elizaOS runtime plugin route system.
+ *
+ * All routes use `rawPath: true` to preserve the legacy `/api/wallet/*`
+ * paths without a plugin-name prefix. This module is node-only — the main
+ * runtime plugin (services, actions, providers) lives in `../plugin.ts`
+ * and is browser-safe; this `plugin.ts` is loaded only on the server via
+ * `../register-routes.ts`.
+ *
+ * Migrated from packages/app-core/src/api/wallet-market-overview-route.ts.
+ */
+
+import type http from "node:http";
+import type { Plugin, Route } from "@elizaos/core";
+import { handleWalletMarketOverviewRoute } from "./wallet-market-overview-route";
+
+async function marketOverviewHandler(
+  req: unknown,
+  res: unknown,
+  _runtime: unknown,
+): Promise<void> {
+  const httpReq = req as http.IncomingMessage;
+  const httpRes = res as http.ServerResponse;
+  await handleWalletMarketOverviewRoute(httpReq, httpRes);
+}
+
+const walletHttpRoutes: Route[] = [
+  // GET /api/wallet/market-overview — public cached market overview for
+  // wallet empty states and cloud feeds. The handler also responds to
+  // OPTIONS preflight with 204 and rejects other methods with 405.
+  {
+    type: "GET",
+    path: "/api/wallet/market-overview",
+    rawPath: true,
+    public: true,
+    name: "wallet-market-overview",
+    handler: marketOverviewHandler,
+  },
+];
+
+export const walletRoutePlugin: Plugin = {
+  name: "@elizaos/plugin-wallet:routes",
+  description:
+    "Wallet HTTP route handlers (market overview, etc.) — extracted from packages/app-core/src/api.",
+  routes: walletHttpRoutes,
+};