@elizaos/plugin-wallet 2.0.0-beta.1 → 2.0.3-beta.5

package/dist/sdk/tokens/solana.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @module tokens/solana
+ * Solana SPL token support for AgentWallet v6.
+ *
+ * Uses @solana/web3.js as an optional peer dependency.
+ * All imports are done dynamically so EVM-only users pay zero overhead.
+ *
+ * Token addresses verified against:
+ *   - Solana SPL Token Registry: https://raw.githubusercontent.com/solana-labs/token-list/main/src/tokens/solana.tokenlist.json
+ *   - USDC on Solana: https://developers.circle.com/stablecoins/usdc-contract-addresses
+ *   - Raydium: https://docs.raydium.io/raydium/token-pairs-and-liquidity
+ */
+export declare const SOLANA_TOKENS: {
+    readonly SOL: null;
+    readonly USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    readonly USDT: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+    readonly RAY: "4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R";
+    readonly SRM: "SRMuApVNdxXokk5GT7XD5cUUgXMBCoAz2LHeuAoKWRt";
+    readonly BONK: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263";
+    readonly JITOSOL: "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn";
+    readonly MSOL: "mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So";
+    readonly WBTC: "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh";
+    readonly WETH: "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs";
+};
+export type SolanaTokenSymbol = keyof typeof SOLANA_TOKENS;
+export interface SolanaTokenInfo {
+    symbol: SolanaTokenSymbol;
+    mint: string | null;
+    decimals: number;
+    name: string;
+}
+/** Known decimals for Solana tokens */
+export declare const SOLANA_TOKEN_DECIMALS: Record<SolanaTokenSymbol, number>;
+export interface SolanaWalletConfig {
+    /** Solana RPC endpoint (default: mainnet) */
+    rpcUrl?: string;
+    /** Base-58 encoded private key for the signer */
+    privateKeyBase58?: string;
+    /** Keypair bytes (Uint8Array of 64 bytes) */
+    keypairBytes?: Uint8Array;
+}
+export interface SolBalanceResult {
+    rawBalance: bigint;
+    sol: string;
+}
+export interface SplBalanceResult {
+    mint: string;
+    rawBalance: bigint;
+    humanBalance: string;
+    decimals: number;
+}
+export interface SolanaTxResult {
+    signature: string;
+}
+/**
+ * Solana wallet for native SOL and SPL token operations.
+ * Uses @solana/web3.js (optional peer dependency, dynamically imported).
+ */
+export declare class SolanaWallet {
+    private readonly rpcUrl;
+    private readonly config;
+    private _connection;
+    private _keypair;
+    constructor(config?: SolanaWalletConfig);
+    private getConnection;
+    private getKeypair;
+    /** Get signer's public key as base-58 string */
+    getPublicKey(): Promise<string>;
+    /**
+     * Get native SOL balance.
+     * @param address - Optional base-58 public key to check (defaults to wallet's key)
+     */
+    getSolBalance(address?: string): Promise<SolBalanceResult>;
+    /**
+     * Get SPL token balance for a given mint.
+     * @param mintAddress - SPL token mint address (base-58)
+     * @param owner - Optional owner address (defaults to wallet's key)
+     */
+    getSplTokenBalance(mintAddress: string, owner?: string): Promise<SplBalanceResult>;
+    /**
+     * Send native SOL to a recipient.
+     * @param to - Recipient base-58 public key
+     * @param amount - Lamports (bigint) OR SOL amount as string (e.g. "1.5")
+     */
+    sendSol(to: string, amount: string | bigint): Promise<SolanaTxResult>;
+    /**
+     * Send SPL tokens to a recipient.
+     * Creates the recipient's associated token account if it doesn't exist.
+     *
+     * @param to - Recipient base-58 public key
+     * @param amount - Raw token units (bigint) OR human-readable string
+     * @param mintAddress - SPL token mint address (base-58)
+     */
+    sendSplToken(to: string, amount: string | bigint, mintAddress: string): Promise<SolanaTxResult>;
+    /**
+     * List all SPL token accounts for the wallet.
+     */
+    listSplTokenAccounts(): Promise<Array<{
+        mint: string;
+        amount: bigint;
+        decimals: number;
+    }>>;
+}
+/**
+ * Create a SolanaWallet instance.
+ */
+export declare function createSolanaWallet(config: SolanaWalletConfig): SolanaWallet;

package/dist/sdk/tokens/transfers.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @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 Hash, type PublicClient, type WalletClient } from "viem";
+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;
+}
+export interface TransferContext {
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /** Caller's address (used as from address) */
+    account: Address;
+    /** Chain ID for registry lookups */
+    chainId?: number;
+}
+/**
+ * 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 declare function sendToken(ctx: TransferContext, to: Address, amount: string | bigint, tokenAddress: Address, options?: TransferOptions): Promise<Hash>;
+/**
+ * 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 declare function sendNative(ctx: TransferContext, to: Address, amount: string | bigint, options?: TransferOptions): Promise<Hash>;
+/**
+ * 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 declare function getTokenBalance(ctx: TransferContext, tokenAddress: Address, holder?: Address): Promise<TokenBalanceResult>;
+/**
+ * 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 declare function getNativeBalance(ctx: TransferContext, holder?: Address): Promise<NativeBalanceResult>;
+/**
+ * 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 declare function getBalances(ctx: TransferContext, tokenAddresses?: Address[], holder?: Address): Promise<TokenBalanceResult[]>;
+/**
+ * Encode an ERC-20 transfer call as raw calldata.
+ * Useful for building calldata for agentExecute() or multicall.
+ */
+export declare function encodeERC20Transfer(to: Address, amount: bigint): `0x${string}`;

package/dist/sdk/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @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;
+    perTxLimit: bigint;
+    periodLimit: bigint;
+    periodLength: number;
+}
+/** 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;
+}
+/** 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;
+}
+/** 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 declare const CHAIN_IDS: {
+    readonly base: 8453;
+    readonly "base-sepolia": 84532;
+    readonly ethereum: 1;
+    readonly arbitrum: 42161;
+    readonly polygon: 137;
+    readonly optimism: 10;
+    readonly avalanche: 43114;
+    readonly unichain: 130;
+    readonly linea: 59144;
+    readonly sonic: 146;
+    readonly worldchain: 480;
+};
+/** Supported chain name type */
+export type SupportedChain = keyof typeof CHAIN_IDS;