@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/swap/types.ts

@@ -0,0 +1,135 @@
+/**
+ * @module swap/types
+ * Type definitions and constants for the multi-chain Uniswap V3 SwapModule.
+ *
+ * Supported swap chains: Base, Arbitrum, Optimism, Polygon.
+ * All router/quoter addresses verified against official Uniswap V3 deployment docs:
+ * - Base: https://docs.uniswap.org/contracts/v3/reference/deployments/base-deployments
+ * - Arbitrum: https://docs.uniswap.org/contracts/v3/reference/deployments/arbitrum-deployments
+ * - Optimism: https://docs.uniswap.org/contracts/v3/reference/deployments/optimism-deployments
+ * - Polygon: https://docs.uniswap.org/contracts/v3/reference/deployments/polygon-deployments
+ *
+ * Note: Base uses a unique SwapRouter02 address; Arbitrum, Optimism, and Polygon
+ * share the same universal SwapRouter02 deployment address.
+ */
+import type { Address, Hash } from "viem";
+
+/** Uniswap V3 fee tier options */
+export type UniswapFeeTier = 100 | 500 | 3000 | 10000;
+
+/** Chains supported for Uniswap V3 swap */
+export type SwapChain = "base" | "arbitrum" | "optimism" | "polygon";
+
+export interface SwapQuote {
+  tokenIn: Address;
+  tokenOut: Address;
+  amountInRaw: bigint;
+  amountInNet: bigint;
+  feeAmount: bigint;
+  amountOut: bigint;
+  amountOutMinimum: bigint;
+  poolFeeTier: UniswapFeeTier;
+  effectiveRate: number;
+  gasEstimate: bigint;
+}
+
+export interface SwapOptions {
+  slippageBps?: number;
+  feeTiers?: UniswapFeeTier[];
+  deadlineSecs?: number;
+  feeWallet?: Address;
+}
+
+export interface SwapResult {
+  txHash: Hash;
+  feeTxHash?: Hash;
+  quote: SwapQuote;
+  approvalRequired: boolean;
+  approvalTxHash?: Hash;
+}
+
+export interface SwapModuleConfig {
+  routerAddress: Address;
+  quoterAddress: Address;
+  feeBps: number;
+  feeWallet: Address;
+  /** Chain this SwapModule is configured for */
+  chain: SwapChain;
+}
+
+// ─── Token Addresses ───
+
+/** Well-known Base Mainnet token addresses */
+export const BASE_TOKENS = {
+  USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const,
+  WETH: "0x4200000000000000000000000000000000000006" as const,
+  cbETH: "0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22" as const,
+  WNATIVE: "0x4200000000000000000000000000000000000006" as const,
+};
+
+/** Well-known Arbitrum token addresses */
+export const ARBITRUM_TOKENS = {
+  USDC: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" as const,
+  WETH: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" as const,
+  WNATIVE: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1" as const,
+};
+
+/** Well-known Optimism token addresses */
+export const OPTIMISM_TOKENS = {
+  USDC: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" as const,
+  WETH: "0x4200000000000000000000000000000000000006" as const,
+  OP: "0x4200000000000000000000000000000000000042" as const,
+  WNATIVE: "0x4200000000000000000000000000000000000006" as const,
+};
+
+/** Well-known Polygon token addresses */
+export const POLYGON_TOKENS = {
+  USDC: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" as const,
+  WETH: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619" as const,
+  WMATIC: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270" as const,
+  WNATIVE: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270" as const,
+};
+
+// ─── Uniswap V3 Contract Addresses ───
+
+/**
+ * Uniswap V3 router and quoter addresses.
+ *
+ * Base has a different router (SwapRouter02 deployed at a unique address due to BASE chain launch).
+ * Arbitrum, Optimism, and Polygon use the same universal SwapRouter02 address.
+ *
+ * Sources:
+ *   - Base: https://docs.uniswap.org/contracts/v3/reference/deployments/base-deployments
+ *   - Arbitrum: https://docs.uniswap.org/contracts/v3/reference/deployments/arbitrum-deployments
+ *   - Optimism: https://docs.uniswap.org/contracts/v3/reference/deployments/optimism-deployments
+ *   - Polygon: https://docs.uniswap.org/contracts/v3/reference/deployments/polygon-deployments
+ */
+export const UNISWAP_V3_ADDRESSES: Record<
+  SwapChain,
+  { ROUTER: Address; QUOTER_V2: Address }
+> = {
+  base: {
+    ROUTER: "0x2626664c2603336E57B271c5C0b26F421741e481",
+    QUOTER_V2: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+  },
+  arbitrum: {
+    ROUTER: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    QUOTER_V2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+  },
+  optimism: {
+    ROUTER: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    QUOTER_V2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+  },
+  polygon: {
+    ROUTER: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+    QUOTER_V2: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+  },
+};
+
+/** Protocol fee in bps — 0.875% */
+export const PROTOCOL_FEE_BPS = 875;
+/** Protocol fee collector address (all EVM chains) */
+export const PROTOCOL_FEE_COLLECTOR =
+  "0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD" as const;
+/** Default slippage in bps — 0.5% */
+export const DEFAULT_SLIPPAGE_BPS = 50;

package/src/sdk/tokens/decimals.ts

@@ -0,0 +1,140 @@
+/**
+ * @module tokens/decimals
+ * Token decimal normalization utilities for multi-token agent wallets.
+ *
+ * Handles safe conversion between human-readable amounts ("1.5") and raw
+ * on-chain bigint amounts (1500000n for USDC with 6 decimals). All arithmetic
+ * is done in integer domain to avoid floating point precision errors.
+ */
+
+import type { Address } from "viem";
+
+/** Minimal token info required for formatting */
+export interface TokenInfo {
+  symbol: string;
+  decimals: number;
+  address: Address;
+  name?: string;
+  chainId?: number;
+}
+
+/**
+ * Convert a human-readable amount string to raw bigint (on-chain units).
+ *
+ * @param amount - Human-readable amount, e.g. "1.5" or "1000"
+ * @param decimals - Token decimal places (e.g. 6 for USDC, 18 for WETH)
+ * @returns Raw on-chain amount as bigint
+ *
+ * @example
+ * toRaw("1.5", 6)   // → 1500000n  (1.5 USDC)
+ * toRaw("1.0", 18)  // → 1000000000000000000n  (1 WETH)
+ * toRaw("0.001", 8) // → 100000n  (0.001 WBTC)
+ */
+export function toRaw(amount: string | bigint, decimals: number): bigint {
+  if (typeof amount === "bigint") return amount;
+
+  const str = amount.trim();
+  if (!str || str === "0") return 0n;
+
+  // Validate: only digits and one optional decimal point, optional leading minus
+  if (!/^-?\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`toRaw: invalid amount string "${amount}"`);
+  }
+
+  const negative = str.startsWith("-");
+  const abs = negative ? str.slice(1) : str;
+
+  const dotIndex = abs.indexOf(".");
+  if (dotIndex === -1) {
+    // Integer amount
+    const result = BigInt(abs) * 10n ** BigInt(decimals);
+    return negative ? -result : result;
+  }
+
+  const intPart = abs.slice(0, dotIndex);
+  let fracPart = abs.slice(dotIndex + 1);
+
+  // Truncate or pad fractional part to `decimals` digits
+  if (fracPart.length > decimals) {
+    fracPart = fracPart.slice(0, decimals); // truncate (floor for positive amounts)
+  } else {
+    fracPart = fracPart.padEnd(decimals, "0");
+  }
+
+  const raw =
+    BigInt(intPart || "0") * 10n ** BigInt(decimals) + BigInt(fracPart);
+
+  return negative ? -raw : raw;
+}
+
+/**
+ * Convert a raw bigint on-chain amount to a human-readable string.
+ *
+ * @param amount - Raw on-chain amount
+ * @param decimals - Token decimal places
+ * @returns Human-readable string, trimmed trailing zeros
+ *
+ * @example
+ * toHuman(1500000n, 6)               // → "1.5"
+ * toHuman(1000000000000000000n, 18)  // → "1.0"
+ * toHuman(0n, 6)                     // → "0.0"
+ */
+export function toHuman(amount: bigint, decimals: number): string {
+  if (decimals === 0) return amount.toString();
+
+  const negative = amount < 0n;
+  const abs = negative ? -amount : amount;
+
+  const divisor = 10n ** BigInt(decimals);
+  const intPart = abs / divisor;
+  const fracRaw = abs % divisor;
+
+  // Pad fractional part to `decimals` digits
+  const fracStr = fracRaw.toString().padStart(decimals, "0");
+
+  // Trim trailing zeros but keep at least one decimal digit
+  const trimmed = fracStr.replace(/0+$/, "") || "0";
+
+  const result = `${intPart}.${trimmed}`;
+  return negative ? `-${result}` : result;
+}
+
+/**
+ * Format a raw bigint amount with token symbol for display.
+ *
+ * @param amount - Raw on-chain amount
+ * @param token - Token info (symbol + decimals required)
+ * @param displayDecimals - Max decimal places to show (default: 4 for high-precision, 2 for stablecoins)
+ * @returns Formatted string e.g. "1.50 USDC" or "0.0023 WETH"
+ *
+ * @example
+ * formatBalance(1500000n, { symbol: 'USDC', decimals: 6, address: '0x...' })
+ * // → "1.50 USDC"
+ */
+export function formatBalance(
+  amount: bigint,
+  token: Pick<TokenInfo, "symbol" | "decimals">,
+  displayDecimals?: number,
+): string {
+  const human = toHuman(amount, token.decimals);
+  const maxDisplay = displayDecimals ?? (token.decimals <= 6 ? 2 : 4);
+
+  // Parse the human string and reformat to maxDisplay decimal places
+  const [intPart, fracPart = ""] = human.split(".");
+  const padded = fracPart.padEnd(maxDisplay, "0").slice(0, maxDisplay);
+
+  // If all fraction digits are zero, still show them for consistent formatting
+  return `${intPart}.${padded} ${token.symbol}`;
+}
+
+/**
+ * Parse amount that may be either a string (human-readable) or bigint (raw).
+ * Returns raw bigint. Used in transfer functions to accept flexible input.
+ *
+ * @param amount - Either a human-readable string "1.5" or a raw bigint
+ * @param decimals - Required only when amount is a string
+ */
+export function parseAmount(amount: string | bigint, decimals: number): bigint {
+  if (typeof amount === "bigint") return amount;
+  return toRaw(amount, decimals);
+}