@elizaos/plugin-wallet 2.0.0-beta.1

package/src/sdk/bridge/types.ts

@@ -0,0 +1,202 @@
+/**
+ * @module bridge/types
+ * Type definitions and constants for the CCTP V2 cross-chain USDC bridge.
+ *
+ * Supports 10 EVM chains + Solana via Circle's Cross-Chain Transfer Protocol V2.
+ * EVM chains: Ethereum, Avalanche, Optimism, Arbitrum, Base, Polygon,
+ *             Unichain, Linea, Sonic, Worldchain.
+ * Non-EVM: Solana (via bridge/solana.ts — uses separate CCTP V2 programs).
+ *
+ * Contract addresses verified against:
+ * - CCTP V2 EVM: https://developers.circle.com/cctp/references/contract-addresses
+ * - Solana V2 programs: https://developers.circle.com/cctp/references/solana-programs
+ * - USDC addresses: https://developers.circle.com/stablecoins/usdc-contract-addresses
+ */
+import type { Address, Hash, Hex } from "viem";
+
+/** Supported bridge destination chains */
+export type BridgeChain =
+  | "ethereum"
+  | "avalanche"
+  | "optimism"
+  | "arbitrum"
+  | "base"
+  | "polygon"
+  | "unichain"
+  | "linea"
+  | "sonic"
+  | "worldchain"
+  | "solana";
+
+/** EVM-only bridge chains (excludes non-EVM like Solana) */
+export type EVMBridgeChain = Exclude<BridgeChain, "solana">;
+
+/**
+ * CCTP V2 domain IDs — official Circle domain identifiers.
+ * Source: https://developers.circle.com/cctp/references/contract-addresses
+ * Solana domain: 5 — https://developers.circle.com/cctp/docs/solana
+ */
+export const CCTP_DOMAIN_IDS: Record<BridgeChain, number> = {
+  ethereum: 0,
+  avalanche: 1,
+  optimism: 2,
+  arbitrum: 3,
+  base: 6,
+  polygon: 7,
+  unichain: 10,
+  linea: 11,
+  sonic: 13,
+  worldchain: 14,
+  solana: 5,
+};
+
+/**
+ * EVM chain IDs for EVM-compatible bridge chains.
+ * Solana is excluded — use solana.ts for Solana-specific operations.
+ */
+export const BRIDGE_CHAIN_IDS: Record<EVMBridgeChain, number> = {
+  ethereum: 1,
+  avalanche: 43114,
+  optimism: 10,
+  arbitrum: 42161,
+  base: 8453,
+  polygon: 137,
+  unichain: 130,
+  linea: 59144,
+  sonic: 146,
+  worldchain: 480,
+};
+
+/**
+ * USDC contract addresses per chain (native Circle USDC, not bridged variants).
+ * Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (stored as string, not Address/Hex)
+ */
+export const USDC_CONTRACT: Record<EVMBridgeChain, Address> = {
+  ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  avalanche: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+  optimism: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+  arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  polygon: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+  unichain: "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
+  linea: "0x176211869cA2b568f2A7D4EE941E073a821EE1ff",
+  sonic: "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
+  worldchain: "0x79A02482A880bCE3B13e09Da970dC34db4CD24d1",
+};
+
+/** Solana USDC mint address */
+export const SOLANA_USDC_MINT =
+  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" as const;
+
+/**
+ * CCTP V2 TokenMessengerV2 — deterministic CREATE2 deployment, same address on all EVM chains.
+ * Source: https://developers.circle.com/cctp/references/contract-addresses
+ * Verified on-chain: BaseScan, Etherscan, Arbiscan (active transactions as of 2026-03-10)
+ * Solana uses a different program — see bridge/solana.ts
+ */
+const CCTP_V2_TOKEN_MESSENGER: Address =
+  "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d";
+
+export const TOKEN_MESSENGER_V2: Record<EVMBridgeChain, Address> = {
+  ethereum: CCTP_V2_TOKEN_MESSENGER,
+  avalanche: CCTP_V2_TOKEN_MESSENGER,
+  optimism: CCTP_V2_TOKEN_MESSENGER,
+  arbitrum: CCTP_V2_TOKEN_MESSENGER,
+  base: CCTP_V2_TOKEN_MESSENGER,
+  polygon: CCTP_V2_TOKEN_MESSENGER,
+  unichain: CCTP_V2_TOKEN_MESSENGER,
+  linea: CCTP_V2_TOKEN_MESSENGER,
+  sonic: CCTP_V2_TOKEN_MESSENGER,
+  worldchain: CCTP_V2_TOKEN_MESSENGER,
+};
+
+/**
+ * CCTP V2 MessageTransmitterV2 — deterministic CREATE2 deployment, same address on all EVM chains.
+ * Source: https://developers.circle.com/cctp/references/contract-addresses
+ * Solana uses a different program — see bridge/solana.ts
+ */
+const CCTP_V2_MESSAGE_TRANSMITTER: Address =
+  "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64";
+
+export const MESSAGE_TRANSMITTER_V2: Record<EVMBridgeChain, Address> = {
+  ethereum: CCTP_V2_MESSAGE_TRANSMITTER,
+  avalanche: CCTP_V2_MESSAGE_TRANSMITTER,
+  optimism: CCTP_V2_MESSAGE_TRANSMITTER,
+  arbitrum: CCTP_V2_MESSAGE_TRANSMITTER,
+  base: CCTP_V2_MESSAGE_TRANSMITTER,
+  polygon: CCTP_V2_MESSAGE_TRANSMITTER,
+  unichain: CCTP_V2_MESSAGE_TRANSMITTER,
+  linea: CCTP_V2_MESSAGE_TRANSMITTER,
+  sonic: CCTP_V2_MESSAGE_TRANSMITTER,
+  worldchain: CCTP_V2_MESSAGE_TRANSMITTER,
+};
+
+/**
+ * CCTP V2 minFinalityThreshold values.
+ * - FAST (0): ~12 seconds. Circle fast attestation.
+ * - FINALIZED (1000): Full on-chain finality.
+ */
+export const FINALITY_THRESHOLD = {
+  FAST: 0,
+  FINALIZED: 1000,
+} as const;
+
+/** Circle IRIS attestation API base URL */
+export const CIRCLE_ATTESTATION_API = "https://iris-api.circle.com";
+/** Max attestation polling attempts before timeout */
+export const MAX_ATTESTATION_POLLS = 60;
+/** Polling interval for attestation (milliseconds) */
+export const ATTESTATION_POLL_INTERVAL_MS = 5000;
+
+/** Options for a bridge operation */
+export interface BridgeOptions {
+  minFinalityThreshold?: number;
+  maxFee?: bigint;
+  destinationAddress?: Address;
+  destinationRpcUrl?: string;
+  attestationApiUrl?: string;
+}
+
+/** Result of a bridge.burn() operation */
+export interface BurnResult {
+  burnTxHash: Hash;
+  nonce: bigint;
+  messageHash: Hex;
+  messageBytes: Hex;
+  sourceDomain: number;
+  destinationDomain: number;
+}
+
+/** Circle attestation status */
+export type AttestationStatus = "pending_confirmations" | "complete" | "error";
+
+/** Circle IRIS API response for an attestation */
+export interface AttestationResponse {
+  status: AttestationStatus;
+  attestation: Hex | null;
+  error?: string;
+}
+
+/** Result of the full EVM↔EVM bridge() operation */
+export interface BridgeResult {
+  burnTxHash: Hash;
+  mintTxHash: Hash;
+  amount: bigint;
+  fromChain: EVMBridgeChain;
+  toChain: EVMBridgeChain;
+  recipient: Address;
+  nonce: bigint;
+  elapsedMs: number;
+}
+
+/** Error codes for actionable bridge error messages */
+export type BridgeErrorCode =
+  | "UNSUPPORTED_CHAIN"
+  | "INSUFFICIENT_ALLOWANCE"
+  | "INSUFFICIENT_BALANCE"
+  | "BURN_FAILED"
+  | "ATTESTATION_TIMEOUT"
+  | "ATTESTATION_ERROR"
+  | "MINT_FAILED"
+  | "INVALID_AMOUNT"
+  | "NO_WALLET_CLIENT";

package/src/sdk/convenience.ts

@@ -0,0 +1,347 @@
+/**
+ * @module convenience
+ * Environment-variable-driven wallet bootstrap helpers.
+ *
+ * Provides three dead-simple factory functions that read all configuration
+ * from process environment variables so that any agent can set up a fully
+ * functional wallet in 3 lines without touching viem directly:
+ *
+ * ```typescript
+ * import { walletFromEnv, setPolicyFromEnv, x402FromEnv } from 'agentwallet-sdk';
+ *
+ * const wallet = walletFromEnv();
+ * await setPolicyFromEnv(wallet);
+ * const client = x402FromEnv(wallet);
+ * ```
+ *
+ * ### Environment variables
+ *
+ * | Variable              | Required | Default        | Description                                      |
+ * |-----------------------|----------|----------------|--------------------------------------------------|
+ * | AGENT_PRIVATE_KEY     | ✅ yes   | —              | EOA private key (0x-prefixed hex, 32 bytes)      |
+ * | AGENT_WALLET_ADDRESS  | ✅ yes   | —              | AgentAccountV2 smart-wallet address              |
+ * | CHAIN_NAME            | no       | base           | Chain name (base, mainnet, arbitrum, …)          |
+ * | CHAIN_ID              | no       | —              | Alternative to CHAIN_NAME — numeric chain id     |
+ * | RPC_URL               | no       | chain default  | Custom JSON-RPC endpoint                         |
+ * | SPEND_LIMIT_PER_TX    | no       | —              | Per-tx USDC limit (decimal, e.g. "1.00")         |
+ * | SPEND_LIMIT_DAILY     | no       | —              | Daily USDC limit  (decimal, e.g. "10.00")        |
+ * | SPEND_ALLOWLIST       | no       | —              | Comma-separated recipient addresses              |
+ * | X402_SUPPORTED_NETWORKS | no     | (all mainnet)  | Comma-separated "chain:chainId" network strings  |
+ * | X402_GLOBAL_DAILY_LIMIT | no     | —              | Global daily x402 USDC limit (decimal)           |
+ * | X402_PER_REQUEST_MAX  | no       | —              | Per-request max USDC spend (decimal)             |
+ */
+
+import type { Address, Chain, Hex } from "viem";
+import { createWalletClient, http, parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  arbitrum,
+  base,
+  baseSepolia,
+  mainnet,
+  optimism,
+  polygon,
+} from "viem/chains";
+import type { AgentWalletConfig } from "./types.js";
+import { createWallet, NATIVE_TOKEN, setSpendPolicy } from "./wallet-core.js";
+import { createX402Client } from "./x402/middleware.js";
+import { DEFAULT_SUPPORTED_NETWORKS, USDC_ADDRESSES } from "./x402/types.js";
+
+// ─── Chain registry ────────────────────────────────────────────────────────
+
+/**
+ * Well-known chains, keyed by name (lower-case) or numeric id.
+ * Extend this map if you need additional L2s.
+ */
+const CHAIN_MAP: Record<string, Chain> = {
+  base,
+  "base-sepolia": baseSepolia,
+  basesepolia: baseSepolia,
+  mainnet,
+  ethereum: mainnet,
+  eth: mainnet,
+  arbitrum,
+  arb: arbitrum,
+  optimism,
+  op: optimism,
+  polygon,
+  matic: polygon,
+};
+
+/** Fallback RPC endpoints for chains that have no public default in viem. */
+const DEFAULT_RPC: Record<string, string> = {
+  base: "https://mainnet.base.org",
+  "base-sepolia": "https://sepolia.base.org",
+  mainnet: "https://cloudflare-eth.com",
+  ethereum: "https://cloudflare-eth.com",
+  arbitrum: "https://arb1.arbitrum.io/rpc",
+  optimism: "https://mainnet.optimism.io",
+  polygon: "https://polygon-rpc.com",
+};
+
+/**
+ * Resolve a chain object from either a name string or a numeric chain id.
+ * Tries CHAIN_MAP by name, then falls back to scanning by chainId.
+ *
+ * @param nameOrId - Chain name ("base", "arbitrum", …) or numeric id (8453, …).
+ * @returns The viem Chain object, or `base` as the default.
+ */
+function resolveChain(nameOrId: string | number): Chain {
+  if (typeof nameOrId === "number") {
+    const found = Object.values(CHAIN_MAP).find((c) => c.id === nameOrId);
+    return found ?? base;
+  }
+  const key = nameOrId.toLowerCase().trim();
+  return CHAIN_MAP[key] ?? base;
+}
+
+/** Maps a viem chain to the string key expected by `createWallet` (subset of networks). */
+function chainToCreateWalletKey(chain: Chain): AgentWalletConfig["chain"] {
+  switch (chain.id) {
+    case 8453:
+      return "base";
+    case 84532:
+      return "base-sepolia";
+    case 1:
+      return "ethereum";
+    case 42161:
+      return "arbitrum";
+    case 137:
+      return "polygon";
+    default:
+      throw new Error(
+        `[walletFromEnv] Unsupported chain for AgentWallet (${chain.name}, id ${chain.id}). ` +
+          `Use base, base-sepolia, ethereum, arbitrum, or polygon.`,
+      );
+  }
+}
+
+// ─── USDC scaling ──────────────────────────────────────────────────────────
+
+const USDC_DECIMALS = 6;
+
+/**
+ * Parse a human-readable USDC amount (e.g. "1.50") into base units (bigint).
+ * Returns `undefined` if the string is falsy or not a valid number.
+ *
+ * @param value - Decimal string such as "0.50" or "100".
+ */
+function parseUsdc(value: string | undefined): bigint | undefined {
+  if (!value || value.trim() === "") return undefined;
+  try {
+    return parseUnits(value.trim(), USDC_DECIMALS);
+  } catch {
+    console.warn(`[walletFromEnv] Could not parse USDC amount: "${value}"`);
+    return undefined;
+  }
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Create a fully configured AgentWallet from environment variables.
+ *
+ * Reads:
+ * - **AGENT_PRIVATE_KEY** — EOA signing key (required; 0x-prefixed 32-byte hex)
+ * - **AGENT_WALLET_ADDRESS** — AgentAccountV2 contract address (required)
+ * - **CHAIN_NAME** or **CHAIN_ID** — target chain (optional; defaults to Base mainnet)
+ * - **RPC_URL** — custom RPC endpoint (optional; uses chain default if omitted)
+ *
+ * @param options - Optional overrides for chain and rpcUrl.
+ * @param options.chain  - Chain name that takes precedence over the env var.
+ * @param options.rpcUrl - RPC endpoint that takes precedence over the env var.
+ * @returns A fully configured wallet object (same shape as `createWallet()`).
+ *
+ * @throws {Error} If AGENT_PRIVATE_KEY is missing or not a valid hex key.
+ * @throws {Error} If AGENT_WALLET_ADDRESS is missing.
+ *
+ * @example
+ * ```typescript
+ * const wallet = walletFromEnv({ chain: 'base-sepolia' });
+ * ```
+ */
+export function walletFromEnv(options?: {
+  chain?: string;
+  rpcUrl?: string;
+}): ReturnType<typeof createWallet> {
+  // ── Private key ────────────────────────────────────────────────────────
+  const rawKey = process.env.AGENT_PRIVATE_KEY;
+  if (!rawKey || rawKey.trim() === "") {
+    throw new Error(
+      "[walletFromEnv] AGENT_PRIVATE_KEY environment variable is required. " +
+        "Set it to the 0x-prefixed 32-byte hex private key of your agent EOA.",
+    );
+  }
+  const privateKey = (rawKey.startsWith("0x") ? rawKey : `0x${rawKey}`) as Hex;
+
+  // ── Wallet (smart-contract) address ────────────────────────────────────
+  const walletAddress = process.env.AGENT_WALLET_ADDRESS;
+  if (!walletAddress || walletAddress.trim() === "") {
+    throw new Error(
+      "[walletFromEnv] AGENT_WALLET_ADDRESS environment variable is required. " +
+        "Set it to the address of your deployed AgentAccountV2 smart wallet.",
+    );
+  }
+
+  // ── Chain resolution ────────────────────────────────────────────────────
+  const chainSource =
+    options?.chain ??
+    process.env.CHAIN_NAME ??
+    (process.env.CHAIN_ID ? process.env.CHAIN_ID : undefined);
+
+  const chain = chainSource
+    ? resolveChain(
+        /^\d+$/.test(String(chainSource))
+          ? parseInt(chainSource, 10)
+          : String(chainSource),
+      )
+    : base;
+
+  // ── RPC URL ─────────────────────────────────────────────────────────────
+  const rpcUrl =
+    options?.rpcUrl ??
+    process.env.RPC_URL ??
+    DEFAULT_RPC[chain.name.toLowerCase()] ??
+    DEFAULT_RPC.base;
+
+  // ── Build viem walletClient ──────────────────────────────────────────────
+  const account = privateKeyToAccount(privateKey);
+  const walletClient = createWalletClient({
+    account,
+    chain,
+    transport: http(rpcUrl),
+  });
+
+  // ── Delegate to core createWallet ────────────────────────────────────────
+  return createWallet({
+    accountAddress: walletAddress as Address,
+    chain: chainToCreateWalletKey(chain),
+    rpcUrl,
+    walletClient,
+  });
+}
+
+/**
+ * Apply a spending policy to a wallet from environment variables.
+ *
+ * Reads:
+ * - **SPEND_LIMIT_PER_TX** — maximum USDC per single transaction (e.g. "1.00")
+ * - **SPEND_LIMIT_DAILY**  — maximum USDC per 24-hour period (e.g. "10.00")
+ * - **SPEND_ALLOWLIST**    — comma-separated ERC-20 token addresses to restrict
+ *
+ * If neither limit is set, logs a warning and falls back to queue-for-approval
+ * mode (perTxLimit = 0, periodLimit = 0) so all agent transactions must be
+ * manually approved. This is the safest default.
+ *
+ * @param wallet - Wallet returned by `walletFromEnv()` (or `createWallet()`).
+ * @returns Promise that resolves to the on-chain tx hash of the policy update.
+ *
+ * @example
+ * ```typescript
+ * await setPolicyFromEnv(wallet);
+ * ```
+ */
+export async function setPolicyFromEnv(
+  wallet: ReturnType<typeof createWallet>,
+): Promise<string> {
+  const perTxLimit = parseUsdc(process.env.SPEND_LIMIT_PER_TX);
+  const periodLimit = parseUsdc(process.env.SPEND_LIMIT_DAILY);
+
+  // Determine which USDC token address to use for this chain
+  const chainId = wallet.chain.id;
+  const networkKey = Object.keys(USDC_ADDRESSES).find((k) => {
+    const parts = k.split(":");
+    return parts.length === 2 && parseInt(parts[1], 10) === chainId;
+  });
+  // Use USDC if found for this chain, otherwise fall back to native ETH (zero address)
+  const token: Address = networkKey
+    ? (USDC_ADDRESSES[networkKey] as Address)
+    : NATIVE_TOKEN;
+
+  // Warn and use safe defaults when no limits are configured
+  if (perTxLimit === undefined && periodLimit === undefined) {
+    console.warn(
+      "[setPolicyFromEnv] Neither SPEND_LIMIT_PER_TX nor SPEND_LIMIT_DAILY is set. " +
+        "Defaulting to queue-for-approval mode (all agent transactions require owner sign-off). " +
+        "Set these env vars to enable autonomous spending.",
+    );
+    const hash = await setSpendPolicy(wallet, {
+      token,
+      perTxLimit: 0n,
+      periodLimit: 0n,
+      periodLength: 86400, // 24 h
+    });
+    console.info(
+      `[setPolicyFromEnv] Queue-for-approval policy set. tx: ${hash}`,
+    );
+    return hash;
+  }
+
+  const resolvedPerTxLimit = perTxLimit ?? 0n;
+  const resolvedPeriodLimit = periodLimit ?? 0n;
+
+  const hash = await setSpendPolicy(wallet, {
+    token,
+    perTxLimit: resolvedPerTxLimit,
+    periodLimit: resolvedPeriodLimit,
+    periodLength: 86400, // 24 h
+  });
+
+  console.info(
+    `[setPolicyFromEnv] Policy set — perTx: ${resolvedPerTxLimit} base units, ` +
+      `daily: ${resolvedPeriodLimit} base units on ${wallet.chain.name}. tx: ${hash}`,
+  );
+
+  return hash;
+}
+
+/**
+ * Create an x402 payment client from environment variables.
+ *
+ * Reads:
+ * - **X402_SUPPORTED_NETWORKS**   — comma-separated "chain:chainId" strings
+ *   (e.g. "base:8453,arbitrum:42161"); defaults to all supported mainnets
+ * - **X402_GLOBAL_DAILY_LIMIT**   — total daily USDC budget across all x402
+ *   services (decimal, e.g. "5.00")
+ * - **X402_PER_REQUEST_MAX**      — per-request USDC ceiling (decimal)
+ *
+ * Sensible defaults: supports all 10 mainnet x402 chains, unlimited daily spend
+ * (rely on the agent's on-chain spend policy as the hard limit), 1 auto-retry.
+ *
+ * @param wallet - Wallet returned by `walletFromEnv()` (or `createWallet()`).
+ * @returns A configured X402Client instance.
+ *
+ * @example
+ * ```typescript
+ * const client = x402FromEnv(wallet);
+ * const data = await client.fetch('https://api.example.com/premium-endpoint');
+ * ```
+ */
+export function x402FromEnv(
+  wallet: ReturnType<typeof createWallet>,
+): ReturnType<typeof createX402Client> {
+  // Supported networks — override with comma-separated list or use all defaults
+  const networksEnv = process.env.X402_SUPPORTED_NETWORKS;
+  const supportedNetworks: string[] = networksEnv
+    ? networksEnv
+        .split(",")
+        .map((s: string) => s.trim())
+        .filter(Boolean)
+    : [...DEFAULT_SUPPORTED_NETWORKS];
+
+  // Global daily limit
+  const globalDailyLimitUsdc = parseUsdc(process.env.X402_GLOBAL_DAILY_LIMIT);
+  const globalPerRequestMaxUsdc = parseUsdc(process.env.X402_PER_REQUEST_MAX);
+
+  return createX402Client(wallet, {
+    supportedNetworks,
+    ...(globalDailyLimitUsdc !== undefined && {
+      globalDailyLimit: globalDailyLimitUsdc,
+    }),
+    ...(globalPerRequestMaxUsdc !== undefined && {
+      globalPerRequestMax: globalPerRequestMaxUsdc,
+    }),
+    autoPay: true,
+    maxRetries: 1,
+  });
+}