@elizaos/plugin-wallet 2.0.0-beta.1

package/src/utils/intent-trajectory.ts

@@ -0,0 +1,106 @@
+/**
+ * Intent-extraction trajectory helper for plugin-wallet.
+ *
+ * Wraps `runtime.useModel` calls used for financial-parameter extraction
+ * (transfer/swap/bridge/balance intent prompts) with the canonical
+ * `recordLlmCall` trajectory recorder so every intent LLM hop lands in
+ * the trajectories table for training and audit.
+ *
+ * Falls back to `logActiveTrajectoryLlmCall` if `recordLlmCall` is not
+ * exported by the linked `@elizaos/core` build.
+ */
+
+import {
+  buildCanonicalSystemPrompt,
+  getTrajectoryContext,
+  type IAgentRuntime,
+  logActiveTrajectoryLlmCall,
+  ModelType,
+  recordLlmCall,
+} from "@elizaos/core";
+
+export type IntentModelType =
+  | typeof ModelType.TEXT_LARGE
+  | typeof ModelType.TEXT_SMALL;
+
+export interface RunIntentModelParams {
+  runtime: IAgentRuntime;
+  /** Trajectory `actionType` label. Use a dotted call-site identifier. */
+  taskName: string;
+  /** Logical purpose; financial intent extraction is "action" by default. */
+  purpose?: string;
+  /** Composed prompt text passed to the model. */
+  template: string;
+  /** Defaults to TEXT_LARGE. */
+  modelType?: IntentModelType;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+/**
+ * Run an intent-extraction LLM call and record it on the active trajectory.
+ *
+ * Returns the raw model text so callers can continue parsing with their
+ * existing JSON pipeline. Uses `recordLlmCall` when available; otherwise
+ * runs the model and emits a `logActiveTrajectoryLlmCall` entry directly.
+ */
+export async function runIntentModel(
+  params: RunIntentModelParams,
+): Promise<string> {
+  const {
+    runtime,
+    taskName,
+    template,
+    purpose = "action",
+    modelType = ModelType.TEXT_LARGE,
+    maxTokens,
+    temperature,
+  } = params;
+
+  const systemPrompt = buildCanonicalSystemPrompt({
+    character: runtime.character,
+    userRole: getTrajectoryContext()?.userRole,
+  });
+  const modelLabel = String(modelType);
+  const modelParams = {
+    prompt: template,
+    system: systemPrompt,
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    ...(temperature !== undefined ? { temperature } : {}),
+  };
+
+  if (typeof recordLlmCall === "function") {
+    return recordLlmCall(
+      runtime,
+      {
+        model: modelLabel,
+        systemPrompt,
+        userPrompt: template,
+        temperature: temperature ?? 0,
+        maxTokens: maxTokens ?? 0,
+        purpose,
+        actionType: taskName,
+      },
+      async () => {
+        const response = await runtime.useModel(modelType, modelParams);
+        return typeof response === "string" ? response : String(response ?? "");
+      },
+    );
+  }
+
+  const startedAt = Date.now();
+  const response = await runtime.useModel(modelType, modelParams);
+  const text = typeof response === "string" ? response : String(response ?? "");
+  logActiveTrajectoryLlmCall(runtime, {
+    model: modelLabel,
+    systemPrompt,
+    userPrompt: template,
+    response: text,
+    temperature: temperature ?? 0,
+    maxTokens: maxTokens ?? 0,
+    purpose,
+    actionType: taskName,
+    latencyMs: Math.max(0, Date.now() - startedAt),
+  });
+  return text;
+}

package/src/wallet/backend.ts

@@ -0,0 +1,62 @@
+import type {
+  PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import type { Account, Hex, TypedDataDefinition } from "viem";
+import type { SignResult, SignScope } from "./pending.js";
+
+/**
+ * Narrow signing surface for Solana venues (swap, LP, transfers).
+ */
+export interface SolanaSigner {
+  readonly publicKey: PublicKey;
+  signTransaction(
+    tx: Transaction | VersionedTransaction,
+  ): Promise<Transaction | VersionedTransaction>;
+  signAllTransactions(
+    txs: ReadonlyArray<Transaction | VersionedTransaction>,
+  ): Promise<Array<Transaction | VersionedTransaction>>;
+  /**
+   * Detached Ed25519 signature of an opaque message. Returned bytes are 64
+   * bytes (raw signature). Used by Wallet-Standard `signMessage` and any
+   * non-transaction sign-in flows.
+   */
+  signMessage(message: Uint8Array): Promise<Uint8Array>;
+}
+
+export interface WalletAddresses {
+  readonly evm: `0x${string}` | null;
+  readonly solana: PublicKey | null;
+}
+
+export type WalletBackendKind = "local" | "steward";
+
+/**
+ * Canonical wallet abstraction. Providers and canonical actions reach signing
+ * only through this interface — never via raw env reads inside venue code.
+ *
+ * See docs/architecture/wallet-and-trading.md §A.
+ */
+export interface WalletBackend {
+  readonly kind: WalletBackendKind;
+
+  getAddresses(): WalletAddresses;
+
+  /**
+   * Returns true when this backend can satisfy signing for the given hint.
+   * Read-only QUERY_* flows may skip wallet checks per spec.
+   */
+  canSign(chainHint: "evm" | "solana" | "off-chain"): boolean;
+
+  getEvmAccount(chainId: number): Account;
+
+  getSolanaSigner(): SolanaSigner;
+
+  signMessage(scope: SignScope, message: Hex): Promise<SignResult>;
+
+  signTypedData(
+    scope: SignScope,
+    typedData: TypedDataDefinition,
+  ): Promise<SignResult>;
+}

package/src/wallet/errors.ts

@@ -0,0 +1,49 @@
+import type { PendingApproval } from "./pending.js";
+
+export type WalletBackendNotConfiguredCode =
+  | "EVM_PRIVATE_KEY_MISSING"
+  | "SOLANA_PRIVATE_KEY_MISSING"
+  | "NO_WALLET_CONFIGURED";
+
+export class WalletBackendNotConfiguredError extends Error {
+  readonly code: WalletBackendNotConfiguredCode;
+
+  constructor(code: WalletBackendNotConfiguredCode, message?: string) {
+    const defaults: Record<WalletBackendNotConfiguredCode, string> = {
+      EVM_PRIVATE_KEY_MISSING:
+        "EVM private key is not configured. Set EVM_PRIVATE_KEY (or hydrate from the OS keychain) before using EVM wallet actions.",
+      SOLANA_PRIVATE_KEY_MISSING:
+        "Solana private key is not configured. Set SOLANA_PRIVATE_KEY (base58; or hydrate from the OS keychain) before using Solana wallet actions.",
+      NO_WALLET_CONFIGURED:
+        "No wallet keys are configured. Set at least EVM_PRIVATE_KEY and/or SOLANA_PRIVATE_KEY (local), or use Steward (cloud).",
+    };
+    super(message ?? defaults[code]);
+    this.name = "WalletBackendNotConfiguredError";
+    this.code = code;
+  }
+}
+
+export class StewardUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StewardUnavailableError";
+  }
+}
+
+export class PendingApprovalError extends Error {
+  readonly kind = "pending_approval" as const;
+
+  constructor(readonly pending: PendingApproval) {
+    super(
+      `Wallet operation pending approval: ${pending.scope} (${pending.approvalId})`,
+    );
+    this.name = "PendingApprovalError";
+  }
+}
+
+export class SolanaPrivateKeyInvalidError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SolanaPrivateKeyInvalidError";
+  }
+}

package/src/wallet/index.ts

@@ -0,0 +1,27 @@
+export type {
+  SolanaSigner,
+  WalletAddresses,
+  WalletBackend,
+  WalletBackendKind,
+} from "./backend.js";
+export {
+  PendingApprovalError,
+  SolanaPrivateKeyInvalidError,
+  StewardUnavailableError,
+  WalletBackendNotConfiguredError,
+} from "./errors.js";
+export { LocalEoaBackend } from "./local-eoa-backend.js";
+export type {
+  ApprovalSummary,
+  CanonicalHandlerResult,
+  PendingApproval,
+  SignaturePayload,
+  SignResult,
+  SignScope,
+  ValidateOutcome,
+} from "./pending.js";
+export {
+  resolveWalletBackend,
+  type WalletBackendMode,
+} from "./select-backend.js";
+export { StewardBackend } from "./steward-backend.js";

package/src/wallet/local-eoa-backend.ts

@@ -0,0 +1,201 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import {
+  Keypair,
+  type PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import bs58 from "bs58";
+import type { Hex, TypedDataDefinition } from "viem";
+import { hexToBytes } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import type {
+  SolanaSigner,
+  WalletAddresses,
+  WalletBackend,
+} from "./backend.js";
+import {
+  SolanaPrivateKeyInvalidError,
+  WalletBackendNotConfiguredError,
+} from "./errors.js";
+import type { SignResult, SignScope } from "./pending.js";
+
+function readSetting(runtime: IAgentRuntime, key: string): string | undefined {
+  const v = runtime.getSetting(key);
+  if (typeof v === "string" && v.length > 0) {
+    return v;
+  }
+  return undefined;
+}
+
+function resolveEvmPrivateKey(runtime: IAgentRuntime): Hex | null {
+  const raw =
+    readSetting(runtime, "EVM_PRIVATE_KEY") ?? process.env.EVM_PRIVATE_KEY;
+  if (!raw) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (!/^0x[a-fA-F0-9]{64}$/.test(trimmed)) {
+    return null;
+  }
+  return trimmed as Hex;
+}
+
+function keypairFromSolanaSecret(raw: string): Keypair {
+  const trimmed = raw.trim();
+  let decoded: Uint8Array;
+  try {
+    decoded = bs58.decode(trimmed);
+  } catch {
+    throw new SolanaPrivateKeyInvalidError(
+      "SOLANA_PRIVATE_KEY must be base58-encoded.",
+    );
+  }
+  if (decoded.length === 64) {
+    return Keypair.fromSecretKey(decoded);
+  }
+  if (decoded.length === 32) {
+    return Keypair.fromSeed(decoded);
+  }
+  throw new SolanaPrivateKeyInvalidError(
+    "SOLANA_PRIVATE_KEY decodes to an unexpected length (expected 32-byte seed or 64-byte secret key).",
+  );
+}
+
+function resolveSolanaKeypair(runtime: IAgentRuntime): Keypair | null {
+  const raw =
+    readSetting(runtime, "SOLANA_PRIVATE_KEY") ??
+    process.env.SOLANA_PRIVATE_KEY ??
+    readSetting(runtime, "WALLET_PRIVATE_KEY") ??
+    process.env.WALLET_PRIVATE_KEY;
+  if (!raw) {
+    return null;
+  }
+  try {
+    return keypairFromSolanaSecret(raw);
+  } catch {
+    return null;
+  }
+}
+
+class LocalSolanaSigner implements SolanaSigner {
+  readonly publicKey: PublicKey;
+
+  constructor(private readonly keypair: Keypair) {
+    this.publicKey = keypair.publicKey;
+  }
+
+  async signTransaction(
+    tx: Transaction | VersionedTransaction,
+  ): Promise<Transaction | VersionedTransaction> {
+    if (tx instanceof Transaction) {
+      const serialized = tx.serialize({
+        requireAllSignatures: false,
+        verifySignatures: false,
+      });
+      const copy = Transaction.from(serialized);
+      copy.partialSign(this.keypair);
+      return copy;
+    }
+    const copy = VersionedTransaction.deserialize(tx.serialize());
+    copy.sign([this.keypair]);
+    return copy;
+  }
+
+  async signAllTransactions(
+    txs: ReadonlyArray<Transaction | VersionedTransaction>,
+  ): Promise<Array<Transaction | VersionedTransaction>> {
+    const out: Array<Transaction | VersionedTransaction> = [];
+    for (const tx of txs) {
+      out.push(await this.signTransaction(tx));
+    }
+    return out;
+  }
+
+  async signMessage(message: Uint8Array): Promise<Uint8Array> {
+    const nacl = await import("tweetnacl");
+    return nacl.default.sign.detached(message, this.keypair.secretKey);
+  }
+}
+
+/**
+ * Desktop default: local EOA / keypair signing. **Does not** autogenerate keys.
+ */
+export class LocalEoaBackend implements WalletBackend {
+  readonly kind = "local" as const;
+
+  private readonly evmAccount: ReturnType<typeof privateKeyToAccount> | null;
+
+  private readonly solanaSigner: SolanaSigner | null;
+
+  private constructor(evmHex: Hex | null, solanaKeypair: Keypair | null) {
+    this.evmAccount = evmHex ? privateKeyToAccount(evmHex) : null;
+    this.solanaSigner = solanaKeypair
+      ? new LocalSolanaSigner(solanaKeypair)
+      : null;
+  }
+
+  static async create(runtime: IAgentRuntime): Promise<LocalEoaBackend> {
+    const evm = resolveEvmPrivateKey(runtime);
+    const kp = resolveSolanaKeypair(runtime);
+    if (!evm && !kp) {
+      throw new WalletBackendNotConfiguredError("NO_WALLET_CONFIGURED");
+    }
+    return new LocalEoaBackend(evm, kp);
+  }
+
+  getAddresses(): WalletAddresses {
+    return {
+      evm: this.evmAccount?.address ?? null,
+      solana: this.solanaSigner?.publicKey ?? null,
+    };
+  }
+
+  canSign(chainHint: "evm" | "solana" | "off-chain"): boolean {
+    if (chainHint === "evm") {
+      return this.evmAccount !== null;
+    }
+    if (chainHint === "solana") {
+      return this.solanaSigner !== null;
+    }
+    return this.evmAccount !== null;
+  }
+
+  getEvmAccount(_chainId: number) {
+    void _chainId;
+    if (!this.evmAccount) {
+      throw new WalletBackendNotConfiguredError("EVM_PRIVATE_KEY_MISSING");
+    }
+    return this.evmAccount;
+  }
+
+  getSolanaSigner(): SolanaSigner {
+    if (!this.solanaSigner) {
+      throw new WalletBackendNotConfiguredError("SOLANA_PRIVATE_KEY_MISSING");
+    }
+    return this.solanaSigner;
+  }
+
+  async signMessage(scope: SignScope, message: Hex): Promise<SignResult> {
+    void scope;
+    if (!this.evmAccount) {
+      throw new WalletBackendNotConfiguredError("EVM_PRIVATE_KEY_MISSING");
+    }
+    const sig = await this.evmAccount.signMessage({
+      message: { raw: hexToBytes(message) },
+    });
+    return { kind: "signature", signature: sig };
+  }
+
+  async signTypedData(
+    scope: SignScope,
+    typedData: TypedDataDefinition,
+  ): Promise<SignResult> {
+    void scope;
+    if (!this.evmAccount) {
+      throw new WalletBackendNotConfiguredError("EVM_PRIVATE_KEY_MISSING");
+    }
+    const sig = await this.evmAccount.signTypedData(typedData);
+    return { kind: "signature", signature: sig };
+  }
+}

package/src/wallet/pending.ts

@@ -0,0 +1,60 @@
+import type {
+  ActionFailureCode,
+  ValidateFailureCode,
+} from "../actions/failure-codes.js";
+
+/**
+ * Stable identity for a signing operation. Used by the audit log and the
+ * policy module. Format: "<domain>.<operation>".
+ */
+export type SignScope =
+  | `hyperliquid.${string}`
+  | `polymarket.${string}`
+  | `lifi.${string}`
+  | `jupiter.${string}`
+  | `raydium.${string}`
+  | `orca.${string}`
+  | `meteora.${string}`
+  | `aave.${string}`
+  | `morpho.${string}`
+  | `lp.${string}`
+  | `lp-solana.${string}`
+  | `lp-evm.${string}`
+  | `clanker.${string}`
+  | `mint.${string}`
+  | `transfer.${string}`
+  | `automation.${string}`
+  | `x402.${string}`
+  | `cctp.${string}`;
+
+export interface ApprovalSummary {
+  readonly title: string;
+  readonly venue: string;
+  readonly chainHint: "evm" | "solana" | "off-chain";
+  readonly fields: ReadonlyArray<{ label: string; value: string }>;
+}
+
+export interface PendingApproval {
+  readonly kind: "pending_approval";
+  readonly approvalId: string;
+  readonly scope: SignScope;
+  readonly expiresAt: number;
+  readonly summary: ApprovalSummary;
+}
+
+export interface SignaturePayload {
+  readonly kind: "signature";
+  readonly signature: `0x${string}`;
+  readonly raw?: `0x${string}`;
+}
+
+export type SignResult = SignaturePayload | PendingApproval;
+
+export type ValidateOutcome =
+  | { ok: true }
+  | { ok: false; reason: ValidateFailureCode; detail: string };
+
+export type CanonicalHandlerResult<TData> =
+  | { ok: true; data: TData }
+  | { ok: false; error: ActionFailureCode; detail: string }
+  | { ok: false; error: "PENDING_APPROVAL"; pending: PendingApproval };

package/src/wallet/select-backend.ts

@@ -0,0 +1,47 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import type { WalletBackend } from "./backend.js";
+import { LocalEoaBackend } from "./local-eoa-backend.js";
+import { StewardBackend } from "./steward-backend.js";
+
+export type WalletBackendMode = "local" | "steward" | "auto";
+
+function readMode(runtime: IAgentRuntime): WalletBackendMode {
+  const raw =
+    runtime.getSetting("ELIZA_WALLET_BACKEND") ??
+    process.env.ELIZA_WALLET_BACKEND ??
+    "auto";
+  if (raw === "local" || raw === "steward" || raw === "auto") {
+    return raw;
+  }
+  return "auto";
+}
+
+function preferStewardInAuto(): boolean {
+  if (process.env.ELIZA_WALLET_STEWARD_AUTO === "1") {
+    return true;
+  }
+  return process.env.ELIZA_CLOUD_PROVISIONED === "1";
+}
+
+/**
+ * Resolves the active wallet backend.
+ *
+ * - `local` — env keys only ({@link LocalEoaBackend}).
+ * - `steward` — Steward API signing ({@link StewardBackend}).
+ * - `auto` — Steward when cloud-provisioned or `ELIZA_WALLET_STEWARD_AUTO=1`, otherwise local.
+ */
+export async function resolveWalletBackend(
+  runtime: IAgentRuntime,
+): Promise<WalletBackend> {
+  const mode = readMode(runtime);
+  if (mode === "steward") {
+    return StewardBackend.create(runtime);
+  }
+  if (mode === "local") {
+    return LocalEoaBackend.create(runtime);
+  }
+  if (preferStewardInAuto()) {
+    return StewardBackend.create(runtime);
+  }
+  return LocalEoaBackend.create(runtime);
+}