@elizaos/plugin-wallet 2.0.0-beta.1

package/src/chains/evm/gov-router.ts

@@ -0,0 +1,250 @@
+import type { Chain, Hex } from "viem";
+import {
+  type Address,
+  encodeFunctionData,
+  keccak256,
+  stringToHex,
+} from "viem";
+import governorArtifacts from "./contracts/artifacts/OZGovernor.json";
+import { buildSendTxParams } from "./actions/helpers";
+import { initWalletProvider, type WalletProvider } from "./providers/wallet";
+import type {
+  WalletRouterContext,
+  WalletRouterExecution,
+  WalletRouterParams,
+} from "../../types/wallet-router.js";
+import type { SupportedChain } from "./types";
+
+function isEvmAddress(value: string | undefined): value is Address {
+  return typeof value === "string" && /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+
+function requireGovernor(params: WalletRouterParams): Address {
+  if (!isEvmAddress(params.governor)) {
+    throw new Error("governor must be a valid EVM address.");
+  }
+  return params.governor;
+}
+
+function requireArray(
+  params: WalletRouterParams,
+  key: "targets" | "values" | "calldatas",
+): readonly string[] {
+  const value = params[key];
+  if (!value || value.length === 0) {
+    throw new Error(`${key} is required for governance ${params.op}.`);
+  }
+  return value;
+}
+
+function requireDescription(params: WalletRouterParams): string {
+  if (!params.description) {
+    throw new Error(`description is required for governance ${params.op}.`);
+  }
+  return params.description;
+}
+
+function requireProposalId(params: WalletRouterParams): string {
+  if (!params.proposalId) {
+    throw new Error(`proposalId is required for governance ${params.op}.`);
+  }
+  return params.proposalId;
+}
+
+function asAddressArray(values: readonly string[], key: string): Address[] {
+  return values.map((value) => {
+    if (!isEvmAddress(value)) {
+      throw new Error(`${key} must contain only valid EVM addresses.`);
+    }
+    return value;
+  });
+}
+
+function asHexArray(values: readonly string[], key: string): Hex[] {
+  return values.map((value) => {
+    if (!/^0x[0-9a-fA-F]*$/.test(value)) {
+      throw new Error(`${key} must contain only hex calldata values.`);
+    }
+    return value as Hex;
+  });
+}
+
+function asBigIntArray(values: readonly string[]): bigint[] {
+  return values.map((value) => BigInt(value));
+}
+
+function descriptionHash(description: string): Hex {
+  return keccak256(stringToHex(description));
+}
+
+export function validateWalletGovParams(
+  params: WalletRouterParams,
+): string | null {
+  try {
+    if (!params.op) {
+      return "op is required for governance actions.";
+    }
+    requireGovernor(params);
+    switch (params.op) {
+      case "propose":
+        requireArray(params, "targets");
+        requireArray(params, "values");
+        requireArray(params, "calldatas");
+        requireDescription(params);
+        break;
+      case "vote":
+        requireProposalId(params);
+        if (params.support === undefined) {
+          return "support is required for governance vote.";
+        }
+        break;
+      case "queue":
+        requireArray(params, "targets");
+        requireArray(params, "values");
+        requireArray(params, "calldatas");
+        requireDescription(params);
+        break;
+      case "execute":
+        requireProposalId(params);
+        requireArray(params, "targets");
+        requireArray(params, "values");
+        requireArray(params, "calldatas");
+        requireDescription(params);
+        break;
+    }
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+export function encodeWalletGovData(params: WalletRouterParams): Hex {
+  const governor = requireGovernor(params);
+  void governor;
+
+  switch (params.op) {
+    case "propose":
+      return encodeFunctionData({
+        abi: governorArtifacts.abi,
+        functionName: "propose",
+        args: [
+          asAddressArray(requireArray(params, "targets"), "targets"),
+          asBigIntArray(requireArray(params, "values")),
+          asHexArray(requireArray(params, "calldatas"), "calldatas"),
+          requireDescription(params),
+        ],
+      }) as Hex;
+    case "vote":
+      return encodeFunctionData({
+        abi: governorArtifacts.abi,
+        functionName: "castVote",
+        args: [BigInt(requireProposalId(params)), BigInt(params.support ?? 0)],
+      }) as Hex;
+    case "queue": {
+      const description = requireDescription(params);
+      return encodeFunctionData({
+        abi: governorArtifacts.abi,
+        functionName: "queue",
+        args: [
+          asAddressArray(requireArray(params, "targets"), "targets"),
+          asBigIntArray(requireArray(params, "values")),
+          asHexArray(requireArray(params, "calldatas"), "calldatas"),
+          descriptionHash(description),
+        ],
+      }) as Hex;
+    }
+    case "execute": {
+      requireProposalId(params);
+      const description = requireDescription(params);
+      return encodeFunctionData({
+        abi: governorArtifacts.abi,
+        functionName: "execute",
+        args: [
+          asAddressArray(requireArray(params, "targets"), "targets"),
+          asBigIntArray(requireArray(params, "values")),
+          asHexArray(requireArray(params, "calldatas"), "calldatas"),
+          descriptionHash(description),
+        ],
+      }) as Hex;
+    }
+    default:
+      throw new Error(
+        "Missing or invalid op (expected propose | vote | queue | execute).",
+      );
+  }
+}
+
+export async function routeEvmGovernance(
+  params: WalletRouterParams,
+  context: WalletRouterContext,
+  chainKey: string,
+  chain: Chain,
+  walletProvider?: WalletProvider,
+): Promise<WalletRouterExecution> {
+  const governor = requireGovernor(params);
+  const data = encodeWalletGovData(params);
+
+  if (params.mode === "prepare" || params.dryRun) {
+    return {
+      status: "prepared",
+      chain: chainKey,
+      chainId: String(chain.id),
+      subaction: "gov",
+      dryRun: params.dryRun,
+      mode: params.mode,
+      to: governor,
+      metadata: {
+        op: params.op,
+        governor,
+        proposalId: params.proposalId,
+        support: params.support,
+        targets: params.targets,
+        values: params.values,
+        calldatas: params.calldatas,
+        description: params.description,
+        transactionRequest: {
+          to: governor,
+          value: "0",
+          data,
+          chainId: chain.id,
+        },
+        requiresConfirmation: true,
+      },
+    };
+  }
+
+  const provider = walletProvider ?? (await initWalletProvider(context.runtime));
+  const walletClient = provider.getWalletClient(chainKey as SupportedChain);
+  const account = walletClient.account;
+  if (!account) {
+    throw new Error("Wallet account is not available.");
+  }
+
+  const hash = await walletClient.sendTransaction(
+    buildSendTxParams({
+      account,
+      to: governor,
+      value: 0n,
+      data,
+      chain,
+    }),
+  );
+
+  return {
+    status: "submitted",
+    chain: chainKey,
+    chainId: String(chain.id),
+    subaction: "gov",
+    dryRun: false,
+    mode: params.mode,
+    transactionHash: hash,
+    from: account.address,
+    to: governor,
+    metadata: {
+      op: params.op,
+      proposalId: params.proposalId,
+      support: params.support,
+      data,
+    },
+  };
+}

package/src/chains/evm/index.browser.ts

@@ -0,0 +1,16 @@
+import type { IAgentRuntime, Plugin } from "@elizaos/core";
+import { logger } from "@elizaos/core";
+
+const pluginName = "evm";
+
+export const evmPlugin: Plugin = {
+  name: pluginName,
+  description: "EVM plugin (browser stub; use a server proxy)",
+  async init(_config, _runtime: IAgentRuntime): Promise<void> {
+    logger.warn(
+      `[plugin-${pluginName}] This plugin is not supported directly in browsers. Use a server proxy.`
+    );
+  },
+};
+
+export default evmPlugin;

package/src/chains/evm/index.ts

@@ -0,0 +1,31 @@
+import type { Action, Plugin, ServiceClass } from "@elizaos/core";
+import { promoteSubactionsToActions } from "@elizaos/core";
+import { walletRouterAction } from "../wallet-action";
+import { tokenBalanceProvider } from "./providers/get-balance";
+import { evmWalletProvider } from "./providers/wallet";
+import { evmSignRoutes } from "./routes/sign";
+import { EVMService } from "./service";
+
+export {
+  createEvmWalletChainHandler,
+  type EvmExecutedTransaction,
+  type EvmPreparedResult,
+  type EvmRouterResult,
+  EvmWalletChainHandler,
+  type EvmWalletChainHandlerOptions,
+  type EvmWalletMode,
+  type EvmWalletSubaction,
+} from "./chain-handler";
+export { initWalletProvider, WalletProvider } from "./providers/wallet";
+export type { SupportedChain } from "./types";
+
+export const evmPlugin: Plugin = {
+  name: "evm",
+  description: "EVM blockchain integration plugin",
+  providers: [evmWalletProvider, tokenBalanceProvider],
+  services: [EVMService] as ServiceClass[],
+  actions: promoteSubactionsToActions(walletRouterAction as Action) as Action[],
+  routes: evmSignRoutes,
+};
+
+export default evmPlugin;

package/src/chains/evm/prompts.ts

@@ -0,0 +1,193 @@
+/**
+ * Prompt templates for plugin-wallet EVM actions and providers.
+ *
+ * These prompts use Handlebars-style template syntax:
+ * - {{variableName}} for simple substitution
+ * - {{#each items}}...{{/each}} for iteration
+ * - {{#if condition}}...{{/if}} for conditionals
+ */
+
+export const bridgeTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{chainBalances}}
+
+Extract the following information about the requested token bridge:
+- Token symbol or address to bridge
+- Source chain
+- Destination chain
+- Amount to bridge: Must be a string representing the amount in ether (only number without coin symbol, e.g., "0.1")
+- Destination address (if specified)
+
+Respond using plain key/value text like this:
+token: token symbol or address, or empty if unknown
+fromChain: source chain from {{supportedChains}}, or empty
+toChain: destination chain from {{supportedChains}}, or empty
+amount: amount as string (e.g. 0.1), or empty
+toAddress: destination address, or empty
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const BRIDGE_TEMPLATE = bridgeTemplate;
+
+export const executeProposalTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{walletInfo}}
+
+Extract the following information about the requested proposal:
+- Targets
+- Values
+- Calldatas
+- Description
+- Governor address
+- Chain to execute on
+
+Respond using plain key/value text like this. Use null for any scalar value that cannot be determined, and use empty arrays when no array values can be determined:
+targets[2]: 0xTargetAddress1,0xTargetAddress2
+values[2]: 0,1000000000000000000
+calldatas[2]: 0xCalldata1,0xCalldata2
+description: proposal description, or null
+governor: governor contract address, or null
+chain: chain to execute on, or null
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const EXECUTE_PROPOSAL_TEMPLATE = executeProposalTemplate;
+
+export const proposeTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{walletInfo}}
+
+Extract the following information about the requested proposal:
+- Targets
+- Values
+- Calldatas
+- Description
+- Governor address
+- Chain to execute on
+
+Respond using plain key/value text like this. Use null for any scalar value that cannot be determined, and use empty arrays when no array values can be determined:
+targets[2]: 0xTargetAddress1,0xTargetAddress2
+values[2]: 0,1000000000000000000
+calldatas[2]: 0xCalldata1,0xCalldata2
+description: proposal description, or null
+governor: governor contract address, or null
+chain: chain to execute on, or null
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const PROPOSE_TEMPLATE = proposeTemplate;
+
+export const queueProposalTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{walletInfo}}
+
+Extract the following information about the requested proposal:
+- Targets
+- Values
+- Calldatas
+- Description
+- Governor address
+- Chain to execute on
+
+Respond using plain key/value text like this. Use null for any scalar value that cannot be determined, and use empty arrays when no array values can be determined:
+targets[2]: 0xTargetAddress1,0xTargetAddress2
+values[2]: 0,1000000000000000000
+calldatas[2]: 0xCalldata1,0xCalldata2
+description: proposal description, or null
+governor: governor contract address, or null
+chain: chain to execute on, or null
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const QUEUE_PROPOSAL_TEMPLATE = queueProposalTemplate;
+
+export const swapTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{chainBalances}}
+
+Extract the following information about the requested token swap:
+- Input token symbol or address (the token being sold)
+- Output token symbol or address (the token being bought)
+- Amount to swap: Must be a string representing the amount in ether (only number without coin symbol, e.g., "0.1")
+- Chain to execute on
+
+Respond using plain key/value text like this:
+inputToken: token symbol or address being sold, or empty
+outputToken: token symbol or address being bought, or empty
+amount: amount as string (e.g. 0.1), or empty
+chain: chain from {{supportedChains}}, or empty
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const SWAP_TEMPLATE = swapTemplate;
+
+export const tokenBalanceTemplate = `Extract the token ticker and blockchain from the user's message.
+
+User message: "{{userMessage}}"
+
+Respond using plain key/value text like this:
+token: TOKEN_SYMBOL
+chain: CHAIN_NAME
+
+If no token is mentioned or it's not a balance inquiry, return:
+error: Not a token balance request
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const TOKEN_BALANCE_TEMPLATE = tokenBalanceTemplate;
+
+export const transferTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{chainBalances}}
+
+Extract the following information about the requested token transfer:
+- Chain to execute on (must be one of the supported chains)
+- Amount to transfer (only number without coin symbol, e.g., "0.1")
+- Recipient address (must be a valid Ethereum address)
+- Token symbol or address (if not a native token transfer)
+- Additional data/calldata (if any is included)
+
+Respond using plain key/value text like this:
+fromChain: chain from {{supportedChains}}, or empty
+amount: amount as string (e.g. 0.1), or empty
+toAddress: recipient Ethereum address, or empty
+token: token symbol or address (empty for native transfer)
+data: additional calldata hex string, or empty
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const TRANSFER_TEMPLATE = transferTemplate;
+
+export const voteTemplate = `Given the recent messages and wallet information below:
+
+{{recentMessages}}
+
+{{walletInfo}}
+
+Extract the following information about the requested vote:
+- Proposal ID
+- Support (0 for against, 1 for yes, 2 for abstain)
+- Governor address
+- Chain to execute on
+
+Respond using plain key/value text like this. Use null for any value that cannot be determined:
+proposalId: proposal ID, or null
+support: 0 for against, 1 for yes, 2 for abstain, or null
+governor: governor contract address, or null
+chain: chain to execute on, or null
+
+IMPORTANT: Your response must ONLY contain the key/value fields above. No preamble or explanation.`;
+
+export const VOTE_TEMPLATE = voteTemplate;

package/src/chains/evm/providers/get-balance.ts

@@ -0,0 +1,123 @@
+import {
+  type IAgentRuntime,
+  type Memory,
+  ModelType,
+  type Provider,
+  type ProviderResult,
+  parseJSONObjectFromText,
+} from "@elizaos/core";
+import { getToken } from "@lifi/sdk";
+import { type Address, formatUnits, parseAbi } from "viem";
+import { runIntentModel } from "../../../utils/intent-trajectory";
+import { requireProviderSpec } from "../generated/specs/spec-helpers";
+import { tokenBalanceTemplate } from "../prompts";
+import { EVMError, EVMErrorCode, type SupportedChain } from "../types";
+import { initWalletProvider } from "./wallet";
+
+const spec = requireProviderSpec("get-balance");
+
+export const tokenBalanceProvider: Provider = {
+  name: spec.name,
+  description: "Token balance for ERC20 tokens when onchain actions are requested",
+  descriptionCompressed: "ERC20 token balance for onchain actions.",
+  contexts: ["finance", "crypto", "wallet"],
+  contextGate: { anyOf: ["finance", "crypto", "wallet"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  roleGate: { minRole: "OWNER" },
+  dynamic: true,
+  get: async (runtime: IAgentRuntime, message: Memory): Promise<ProviderResult> => {
+    const inputText =
+      typeof message.content === "string"
+        ? message.content
+        : typeof message.content?.text === "string"
+          ? message.content.text
+          : "";
+    const normalizedText = inputText.toLowerCase();
+    const keywordMatch =
+      normalizedText.includes("balance") ||
+      normalizedText.includes("token") ||
+      normalizedText.includes("erc20") ||
+      normalizedText.includes("wallet");
+    const regexMatch = /\b(?:balance|token|erc20|wallet|chain)\b/i.test(inputText);
+    if (!keywordMatch || !regexMatch) {
+      return { text: "", data: {}, values: {} };
+    }
+
+    try {
+      const prompt = tokenBalanceTemplate.replace("{{userMessage}}", inputText);
+
+      const response = await runIntentModel({
+        runtime,
+        taskName: "evm.token-balance.intent",
+        purpose: "provider",
+        template: prompt,
+        modelType: ModelType.TEXT_SMALL,
+        maxTokens: 100,
+      });
+
+      const parsed = parseJSONObjectFromText(response) as Record<string, unknown> | null;
+
+      if (!parsed || parsed.error || !parsed.token || !parsed.chain) {
+        return { text: "", data: {}, values: {} };
+      }
+
+      const token = String(parsed.token).toUpperCase();
+      const chain = String(parsed.chain).toLowerCase();
+
+      const walletProvider = await initWalletProvider(runtime);
+
+      if (!walletProvider.chains[chain]) {
+        throw new EVMError(EVMErrorCode.CHAIN_NOT_CONFIGURED, `Chain ${chain} is not configured`);
+      }
+
+      const chainConfig = walletProvider.getChainConfigs(chain as SupportedChain);
+      const address = walletProvider.getAddress();
+      const tokenData = await getToken(chainConfig.id, token);
+      const publicClient = walletProvider.getPublicClient(chain as SupportedChain);
+      const balanceAbi = parseAbi(["function balanceOf(address) view returns (uint256)"]);
+
+      const balance = BigInt(
+        await publicClient.readContract({
+          address: tokenData.address as Address,
+          abi: balanceAbi,
+          functionName: "balanceOf",
+          args: [address],
+          authorizationList: undefined,
+        })
+      );
+
+      const formattedBalance = formatUnits(balance, tokenData.decimals);
+      const hasBalance = parseFloat(formattedBalance) > 0;
+
+      return {
+        text: `${token} balance on ${chain} for ${address}: ${formattedBalance}`,
+        data: {
+          token: tokenData.symbol,
+          chain,
+          balance: formattedBalance,
+          decimals: tokenData.decimals,
+          address: tokenData.address,
+          hasBalance,
+        },
+        values: {
+          token: tokenData.symbol,
+          chain,
+          balance: formattedBalance,
+          hasBalance: String(hasBalance),
+        },
+      };
+    } catch (error) {
+      return {
+        text: `Token balance unavailable: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        data: {},
+        values: {
+          tokenBalanceAvailable: false,
+          tokenBalanceError: error instanceof Error ? error.name : "TokenBalanceProviderError",
+        },
+      };
+    }
+  },
+};