@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/tokens/transfers.ts

@@ -0,0 +1,327 @@
+/**
+ * @module tokens/transfers
+ * Multi-token transfer utilities for AgentWallet v6.
+ *
+ * Provides send/balance functions for any ERC-20 token or native gas token,
+ * with flexible amount input (raw bigint or human-readable string).
+ *
+ * All transfer functions go through viem's wallet client — they do NOT
+ * route through the AgentAccountV2 contract (use agentTransferToken for that).
+ * These are direct EOA/smart-wallet operations for wallets that hold the key.
+ */
+
+import {
+  type Address,
+  type Chain,
+  encodeFunctionData,
+  type Hash,
+  type PublicClient,
+  parseAbi,
+  type WalletClient,
+  zeroAddress,
+} from "viem";
+import { formatBalance, parseAmount, toHuman } from "./decimals.js";
+import { getGlobalRegistry } from "./registry.js";
+
+// ─── ERC20 ABI (minimal) ─────────────────────────────────────────────────────
+
+const ERC20_ABI = parseAbi([
+  "function transfer(address to, uint256 amount) returns (bool)",
+  "function balanceOf(address account) view returns (uint256)",
+  "function decimals() view returns (uint8)",
+  "function symbol() view returns (string)",
+  "function name() view returns (string)",
+]);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface TransferOptions {
+  /** Gas price override */
+  gasPrice?: bigint;
+  /** Max fee per gas (EIP-1559) */
+  maxFeePerGas?: bigint;
+  /** Max priority fee per gas (EIP-1559) */
+  maxPriorityFeePerGas?: bigint;
+  /** Gas limit override */
+  gas?: bigint;
+  /** Chain ID for multi-chain operations */
+  chainId?: number;
+}
+
+export interface TokenBalanceResult {
+  address: Address;
+  symbol: string;
+  name: string;
+  decimals: number;
+  rawBalance: bigint;
+  humanBalance: string;
+  formatted: string;
+}
+
+export interface NativeBalanceResult {
+  symbol: string;
+  decimals: number;
+  rawBalance: bigint;
+  humanBalance: string;
+}
+
+// ─── Transfer context ─────────────────────────────────────────────────────────
+
+export interface TransferContext {
+  publicClient: PublicClient;
+  walletClient: WalletClient;
+  /** Caller's address (used as from address) */
+  account: Address;
+  /** Chain ID for registry lookups */
+  chainId?: number;
+}
+
+// ─── Core transfer functions ──────────────────────────────────────────────────
+
+/**
+ * Send any ERC-20 token.
+ *
+ * @param ctx - Public + wallet clients and account
+ * @param to - Recipient address
+ * @param amount - Amount as raw bigint OR human-readable string (requires tokenAddress decimals lookup)
+ * @param tokenAddress - ERC-20 contract address
+ * @param options - Optional gas overrides
+ */
+export async function sendToken(
+  ctx: TransferContext,
+  to: Address,
+  amount: string | bigint,
+  tokenAddress: Address,
+  options: TransferOptions = {},
+): Promise<Hash> {
+  let rawAmount: bigint;
+
+  if (typeof amount === "string") {
+    // Need decimals to parse string amount
+    let decimals: number;
+
+    // Try registry first
+    if (ctx.chainId != null) {
+      const entry = getGlobalRegistry().getTokenByAddress(
+        tokenAddress,
+        ctx.chainId,
+      );
+      decimals =
+        entry?.decimals ??
+        (await fetchTokenDecimals(ctx.publicClient, tokenAddress));
+    } else {
+      decimals = await fetchTokenDecimals(ctx.publicClient, tokenAddress);
+    }
+
+    rawAmount = parseAmount(amount, decimals);
+  } else {
+    rawAmount = amount;
+  }
+
+  const data = encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: "transfer",
+    args: [to, rawAmount],
+  });
+
+  return ctx.walletClient.sendTransaction({
+    account: ctx.account,
+    chain: requirePublicClientChain(ctx),
+    to: tokenAddress,
+    data,
+    ...buildGasOptions(options),
+  });
+}
+
+/**
+ * Send native gas token (ETH, MATIC, AVAX, etc.).
+ *
+ * @param ctx - Transfer context
+ * @param to - Recipient address
+ * @param amount - Raw bigint OR human-readable string (18 decimals for ETH/MATIC/AVAX)
+ * @param options - Optional gas overrides
+ */
+export async function sendNative(
+  ctx: TransferContext,
+  to: Address,
+  amount: string | bigint,
+  options: TransferOptions = {},
+): Promise<Hash> {
+  const rawAmount = parseAmount(amount, 18);
+
+  return ctx.walletClient.sendTransaction({
+    account: ctx.account,
+    chain: requirePublicClientChain(ctx),
+    to,
+    value: rawAmount,
+    ...buildGasOptions(options),
+  });
+}
+
+/**
+ * Get the ERC-20 balance of the current account (or a specified address).
+ *
+ * @param ctx - Transfer context
+ * @param tokenAddress - ERC-20 contract address
+ * @param holder - Address to check (defaults to ctx.account)
+ */
+export async function getTokenBalance(
+  ctx: TransferContext,
+  tokenAddress: Address,
+  holder?: Address,
+): Promise<TokenBalanceResult> {
+  const target = holder ?? ctx.account;
+
+  // Batch read: balanceOf + decimals + symbol + name
+  const [rawBalance, decimals, symbol, name] = await Promise.all([
+    ctx.publicClient.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "balanceOf",
+      args: [target],
+    }) as Promise<bigint>,
+    ctx.publicClient.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "decimals",
+    }) as Promise<number>,
+    ctx.publicClient.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "symbol",
+    }) as Promise<string>,
+    ctx.publicClient.readContract({
+      address: tokenAddress,
+      abi: ERC20_ABI,
+      functionName: "name",
+    }) as Promise<string>,
+  ]);
+
+  const humanBalance = toHuman(rawBalance, decimals);
+  const formatted = formatBalance(rawBalance, { symbol, decimals });
+
+  return {
+    address: tokenAddress,
+    symbol,
+    name,
+    decimals,
+    rawBalance,
+    humanBalance,
+    formatted,
+  };
+}
+
+/**
+ * Get the native gas token balance of the current account (or a specified address).
+ *
+ * @param ctx - Transfer context
+ * @param holder - Address to check (defaults to ctx.account)
+ */
+export async function getNativeBalance(
+  ctx: TransferContext,
+  holder?: Address,
+): Promise<NativeBalanceResult> {
+  const target = holder ?? ctx.account;
+  const rawBalance = await ctx.publicClient.getBalance({ address: target });
+
+  // Determine native token symbol from registry if chainId is known
+  let symbol = "ETH";
+  if (ctx.chainId != null) {
+    const native = getGlobalRegistry().getTokenByAddress(
+      zeroAddress,
+      ctx.chainId,
+    );
+    symbol = native?.symbol ?? "ETH";
+  }
+
+  const humanBalance = toHuman(rawBalance, 18);
+
+  return { symbol, decimals: 18, rawBalance, humanBalance };
+}
+
+/**
+ * Batch query balances for multiple ERC-20 tokens.
+ *
+ * @param ctx - Transfer context
+ * @param tokenAddresses - List of ERC-20 addresses to query (or null/empty for all registry tokens)
+ * @param holder - Address to check (defaults to ctx.account)
+ */
+export async function getBalances(
+  ctx: TransferContext,
+  tokenAddresses?: Address[],
+  holder?: Address,
+): Promise<TokenBalanceResult[]> {
+  const target = holder ?? ctx.account;
+
+  let addresses = tokenAddresses;
+
+  // If no addresses provided and chainId is known, use all registry tokens
+  if (!addresses || addresses.length === 0) {
+    if (ctx.chainId != null) {
+      const tokens = getGlobalRegistry().listTokens(ctx.chainId);
+      addresses = tokens.filter((t) => !t.isNative).map((t) => t.address);
+    } else {
+      return [];
+    }
+  }
+
+  // Parallel balance fetches
+  const results = await Promise.allSettled(
+    addresses.map((addr) => getTokenBalance(ctx, addr, target)),
+  );
+
+  return results
+    .filter(
+      (r): r is PromiseFulfilledResult<TokenBalanceResult> =>
+        r.status === "fulfilled",
+    )
+    .map((r) => r.value);
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function fetchTokenDecimals(
+  publicClient: PublicClient,
+  tokenAddress: Address,
+): Promise<number> {
+  return publicClient.readContract({
+    address: tokenAddress,
+    abi: ERC20_ABI,
+    functionName: "decimals",
+  }) as Promise<number>;
+}
+
+function buildGasOptions(options: TransferOptions) {
+  const gas: Record<string, bigint> = {};
+  if (options.gas != null) gas.gas = options.gas;
+  if (options.gasPrice != null) gas.gasPrice = options.gasPrice;
+  if (options.maxFeePerGas != null) gas.maxFeePerGas = options.maxFeePerGas;
+  if (options.maxPriorityFeePerGas != null)
+    gas.maxPriorityFeePerGas = options.maxPriorityFeePerGas;
+  return gas;
+}
+
+function requirePublicClientChain(ctx: TransferContext): Chain {
+  const chain = ctx.publicClient.chain;
+  if (!chain) {
+    throw new Error(
+      "TransferContext.publicClient must be created with chain (required for walletClient.sendTransaction).",
+    );
+  }
+  return chain;
+}
+
+/**
+ * Encode an ERC-20 transfer call as raw calldata.
+ * Useful for building calldata for agentExecute() or multicall.
+ */
+export function encodeERC20Transfer(
+  to: Address,
+  amount: bigint,
+): `0x${string}` {
+  return encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: "transfer",
+    args: [to, amount],
+  });
+}

package/src/sdk/types.ts

@@ -0,0 +1,158 @@
+/**
+ * @module types
+ * Core type definitions for the AgentWallet SDK.
+ *
+ * Contains shared interfaces, constants, and type utilities used across all
+ * SDK modules: spending policies, wallet config, chain identifiers, and
+ * value-add diagnostic types (BudgetForecast, WalletHealth, ActivityEntry).
+ *
+ * Supported chains: Base, Ethereum, Arbitrum, Polygon, Optimism, Avalanche,
+ * Unichain, Linea, Sonic, Worldchain, and Base Sepolia (testnet).
+ */
+import type { JsonValue } from "@elizaos/core";
+import type { Address, Hash, Hex } from "viem";
+
+/** Spend policy for a single token */
+export interface SpendPolicy {
+  token: Address; // address(0) for native ETH
+  perTxLimit: bigint; // max single tx amount (0 = no autonomous spending)
+  periodLimit: bigint; // max total per rolling window (0 = no autonomous spending)
+  periodLength: number; // window duration in seconds (default 86400)
+}
+
+/** On-chain spend policy state (includes tracking fields) */
+export interface SpendPolicyState extends SpendPolicy {
+  periodSpent: bigint;
+  periodStart: number;
+}
+
+/** A pending over-limit transaction awaiting owner approval */
+export interface PendingTx {
+  txId: bigint;
+  to: Address;
+  value: bigint;
+  data: Hex;
+  token: Address;
+  amount: bigint;
+  createdAt: number;
+  executed: boolean;
+  cancelled: boolean;
+}
+
+/** Budget remaining for a token */
+export interface BudgetStatus {
+  token: Address;
+  perTxLimit: bigint;
+  remainingInPeriod: bigint;
+}
+
+/** Result of agentExecute — either executed or queued */
+export interface ExecuteResult {
+  executed: boolean;
+  txHash: Hash;
+  pendingTxId?: bigint; // set if queued
+}
+
+/** Config for creating an AgentWallet client */
+export interface AgentWalletConfig {
+  accountAddress: Address;
+  chain:
+    | "base"
+    | "base-sepolia"
+    | "ethereum"
+    | "arbitrum"
+    | "polygon"
+    | "optimism"
+    | "avalanche"
+    | "unichain"
+    | "linea"
+    | "sonic"
+    | "worldchain";
+  rpcUrl?: string;
+}
+
+/** Event emitted when a transaction exceeds spend limits */
+export interface QueuedEvent {
+  txId: bigint;
+  to: Address;
+  value: bigint;
+  token: Address;
+  amount: bigint;
+  blockNumber: bigint | null;
+  transactionHash: Hash | null;
+}
+
+// ─── [MAX-ADDED] Value-add types for agent customers ───
+
+/** Budget forecast with time-aware remaining capacity */
+export interface BudgetForecast {
+  token: Address;
+  perTxLimit: bigint;
+  remainingInPeriod: bigint;
+  periodLimit: bigint;
+  periodLength: number;
+  periodSpent: bigint;
+  periodStart: number;
+  /** Seconds until the current period resets (budget refills) */
+  secondsUntilReset: number;
+  /** Percentage of period budget already used (0-100) */
+  utilizationPercent: number;
+}
+
+/** Wallet health diagnostic snapshot */
+export interface WalletHealth {
+  /** Wallet contract address */
+  address: Address;
+  /** NFT token contract bound to this wallet */
+  tokenContract: Address;
+  /** NFT token ID */
+  tokenId: bigint;
+  /** Current operator epoch (increments on invalidateAll) */
+  operatorEpoch: bigint;
+  /** Which operators from the checklist are currently active */
+  activeOperators: { address: Address; active: boolean }[];
+  /** Number of pending (unexecuted, uncancelled) transactions in queue */
+  pendingQueueDepth: number;
+  /** Budget status for each requested token */
+  budgets: BudgetForecast[];
+}
+
+/** A decoded activity log entry from on-chain events */
+export interface ActivityEntry {
+  type:
+    | "execution"
+    | "queued"
+    | "approved"
+    | "cancelled"
+    | "policy_update"
+    | "operator_update";
+  blockNumber: bigint;
+  transactionHash: Hash;
+  /** Decoded event args (varies by type) */
+  args: Record<string, JsonValue>;
+}
+
+/** Params for a single transfer in a batch */
+export interface BatchTransfer {
+  token: Address;
+  to: Address;
+  amount: bigint;
+}
+
+/** Supported chain IDs */
+export const CHAIN_IDS = {
+  base: 8453,
+  "base-sepolia": 84532,
+  ethereum: 1,
+  arbitrum: 42161,
+  polygon: 137,
+  optimism: 10,
+  avalanche: 43114,
+  unichain: 130,
+  linea: 59144,
+  sonic: 146,
+  worldchain: 480,
+} as const;
+
+/** Supported chain name type */
+export type SupportedChain = keyof typeof CHAIN_IDS;

package/src/sdk/wallet-core.ts

@@ -0,0 +1,115 @@
+import {
+  type Address,
+  type Chain,
+  createPublicClient,
+  getContract,
+  type Hash,
+  http,
+  type WalletClient,
+  zeroAddress,
+} from "viem";
+import { arbitrum, base, baseSepolia, mainnet, polygon } from "viem/chains";
+import { AgentAccountV2Abi } from "./abi.js";
+import type { AgentWalletConfig, BudgetStatus, SpendPolicy } from "./types.js";
+
+const CHAINS: Record<string, Chain> = {
+  base,
+  "base-sepolia": baseSepolia,
+  ethereum: mainnet,
+  arbitrum,
+  polygon,
+};
+
+/** Asserts the viem wallet client has a selected account (required for writes). */
+export function requireWalletAccount(client: WalletClient) {
+  const { account } = client;
+  if (!account) {
+    throw new Error("WalletClient.account is required for this operation");
+  }
+  return account;
+}
+
+/** Native ETH token address (zero address) */
+export const NATIVE_TOKEN: Address = zeroAddress;
+
+/**
+ * Create a wallet client connected to an existing AgentAccountV2.
+ */
+export function createWallet(
+  config: AgentWalletConfig & { walletClient: WalletClient },
+) {
+  const chain = CHAINS[config.chain];
+  if (!chain) throw new Error(`Unsupported chain: ${config.chain}`);
+
+  const publicClient = createPublicClient({
+    chain,
+    transport: http(config.rpcUrl),
+  });
+
+  const contract = getContract({
+    address: config.accountAddress,
+    abi: AgentAccountV2Abi,
+    client: { public: publicClient, wallet: config.walletClient },
+  });
+
+  return {
+    address: config.accountAddress,
+    contract,
+    publicClient,
+    walletClient: config.walletClient,
+    chain,
+  };
+}
+
+export type AgentWallet = ReturnType<typeof createWallet>;
+
+/**
+ * Set a spend policy for a token. Only callable by the NFT owner.
+ * Use NATIVE_TOKEN (address(0)) for native ETH.
+ */
+export async function setSpendPolicy(
+  wallet: AgentWallet,
+  policy: SpendPolicy,
+): Promise<Hash> {
+  const periodLength = policy.periodLength || 86400;
+
+  const hash = await wallet.contract.write.setSpendPolicy(
+    [policy.token, policy.perTxLimit, policy.periodLimit, BigInt(periodLength)],
+    { account: requireWalletAccount(wallet.walletClient), chain: wallet.chain },
+  );
+
+  return hash;
+}
+
+/**
+ * Check remaining autonomous budget for a token.
+ */
+export async function checkBudget(
+  wallet: AgentWallet,
+  token: Address = NATIVE_TOKEN,
+): Promise<BudgetStatus> {
+  const [perTxLimit, remainingInPeriod] =
+    await wallet.contract.read.remainingBudget([token]);
+
+  return {
+    token,
+    perTxLimit,
+    remainingInPeriod,
+  };
+}
+
+/**
+ * Transfer ERC20 tokens as the agent, respecting spend limits.
+ */
+export async function agentTransferToken(
+  wallet: AgentWallet,
+  params: { token: Address; to: Address; amount: bigint },
+): Promise<Hash> {
+  return wallet.contract.write.agentTransferToken(
+    [params.token, params.to, params.amount],
+    {
+      account: requireWalletAccount(wallet.walletClient),
+      chain: wallet.chain,
+    },
+  );
+}