@framers/agentos-ext-wallet 0.2.0

package/src/cards/MccCategoryMap.ts

@@ -0,0 +1,138 @@
+// @ts-nocheck
+/**
+ * @fileoverview Merchant Category Code (MCC) → SpendCategory mapping.
+ *
+ * Maps 4-digit MCC codes used by card networks to the wallet extension's
+ * SpendCategory enum. Uses range-based matching for efficient lookup.
+ *
+ * @module wallet/cards/MccCategoryMap
+ */
+
+import type { SpendCategory } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// MCC range definitions
+// ---------------------------------------------------------------------------
+
+interface MccRange {
+  min: number;
+  max: number;
+  category: SpendCategory;
+}
+
+/**
+ * Ordered list of MCC ranges → SpendCategory mappings.
+ * Ranges are inclusive on both ends.
+ */
+const MCC_RANGES: MccRange[] = [
+  // Travel: airlines, hotels, rental cars, travel agencies
+  { min: 3000, max: 3999, category: 'travel' },
+  { min: 4511, max: 4511, category: 'travel' },   // airlines
+  { min: 4722, max: 4722, category: 'travel' },   // travel agencies
+  { min: 7011, max: 7012, category: 'travel' },   // hotels, timeshares
+  { min: 7033, max: 7033, category: 'travel' },   // trailer parks
+  { min: 7512, max: 7519, category: 'travel' },   // car rental
+
+  // Utilities: telecom, electric, gas, water
+  { min: 4812, max: 4816, category: 'utilities' }, // telecom
+  { min: 4899, max: 4900, category: 'utilities' }, // cable, electric/gas/water
+
+  // Shopping: general retail
+  { min: 5200, max: 5499, category: 'shopping' },  // home supply, dept stores
+  { min: 5511, max: 5599, category: 'shopping' },  // auto dealers, auto parts
+  { min: 5600, max: 5699, category: 'shopping' },  // apparel
+  { min: 5700, max: 5799, category: 'shopping' },  // furniture, electronics
+  { min: 5900, max: 5999, category: 'shopping' },  // retail stores, misc
+
+  // Dining: restaurants, bars, fast food
+  { min: 5811, max: 5811, category: 'dining' },    // caterers
+  { min: 5812, max: 5812, category: 'dining' },    // eating places/restaurants
+  { min: 5813, max: 5813, category: 'dining' },    // bars/taverns
+  { min: 5814, max: 5814, category: 'dining' },    // fast food
+
+  // Subscriptions: digital goods/services
+  { min: 5815, max: 5818, category: 'subscriptions' }, // digital goods, games, apps, streaming
+
+  // Entertainment: movies, theaters, events, recreation
+  { min: 7832, max: 7833, category: 'entertainment' }, // movie theaters
+  { min: 7841, max: 7841, category: 'entertainment' }, // video tape rental
+  { min: 7911, max: 7911, category: 'entertainment' }, // dance halls/studios
+  { min: 7922, max: 7922, category: 'entertainment' }, // theatrical producers
+  { min: 7929, max: 7929, category: 'entertainment' }, // bands/orchestras
+  { min: 7932, max: 7933, category: 'entertainment' }, // billiards, bowling
+  { min: 7941, max: 7941, category: 'entertainment' }, // sports clubs/fields
+  { min: 7991, max: 7999, category: 'entertainment' }, // tourist attractions, recreation
+
+  // Web services: computer programming, data processing, IT
+  { min: 7372, max: 7379, category: 'web_services' }, // computer services
+  { min: 4816, max: 4816, category: 'web_services' }, // computer network/info services (re-mapped from utilities for precision)
+
+  // API costs: SaaS / cloud compute (commonly billed under computer services)
+  // Note: most SaaS bills under 7372 (web_services). If needed, specific
+  // merchant descriptors can override at the CardManager level.
+];
+
+// ---------------------------------------------------------------------------
+// Lookup class
+// ---------------------------------------------------------------------------
+
+export class MccCategoryMap {
+  private readonly ranges: MccRange[];
+
+  constructor() {
+    // Sort by min for binary-search-friendly access
+    this.ranges = [...MCC_RANGES].sort((a, b) => a.min - b.min);
+  }
+
+  /**
+   * Resolve a 4-digit MCC string to a SpendCategory.
+   * Returns 'other' if no matching range is found.
+   */
+  mccToCategory(mcc: string): SpendCategory {
+    const code = parseInt(mcc, 10);
+    if (isNaN(code)) return 'other';
+
+    for (const range of this.ranges) {
+      if (code >= range.min && code <= range.max) {
+        return range.category;
+      }
+    }
+    return 'other';
+  }
+
+  /**
+   * Get all MCC ranges that map to a given SpendCategory.
+   * Useful for building Lithic auth rules.
+   */
+  categoryToMccRanges(category: SpendCategory): Array<{ min: number; max: number }> {
+    return this.ranges
+      .filter(r => r.category === category)
+      .map(({ min, max }) => ({ min, max }));
+  }
+
+  /**
+   * Get all individual MCC codes for a category (expands ranges).
+   * Useful for Lithic's blocked_mcc list which expects individual codes.
+   */
+  categoryToMccCodes(category: SpendCategory): string[] {
+    const codes: string[] = [];
+    for (const range of this.ranges) {
+      if (range.category !== category) continue;
+      for (let code = range.min; code <= range.max; code++) {
+        codes.push(code.toString().padStart(4, '0'));
+      }
+    }
+    return codes;
+  }
+
+  /**
+   * Get all categories that have MCC mappings.
+   */
+  getMappedCategories(): SpendCategory[] {
+    const categories = new Set<SpendCategory>();
+    for (const range of this.ranges) {
+      categories.add(range.category);
+    }
+    return [...categories];
+  }
+}

package/src/cards/types.ts

@@ -0,0 +1,169 @@
+// @ts-nocheck
+/**
+ * @fileoverview Types for the virtual card subsystem (Lithic integration).
+ * @module wallet/cards/types
+ */
+
+import type { SpendCategory } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Card primitives
+// ---------------------------------------------------------------------------
+
+export type CardType = 'VIRTUAL' | 'PHYSICAL';
+export type CardState = 'OPEN' | 'PAUSED' | 'CLOSED' | 'PENDING_FULFILLMENT';
+export type CardNetwork = 'VISA' | 'MASTERCARD';
+export type CardTxStatus = 'PENDING' | 'SETTLED' | 'DECLINED' | 'VOIDED';
+export type SpendLimitDuration = 'TRANSACTION' | 'MONTHLY' | 'ANNUALLY' | 'FOREVER';
+
+// ---------------------------------------------------------------------------
+// Config (lives in WalletConfig.card)
+// ---------------------------------------------------------------------------
+
+export interface CardConfig {
+  enabled: boolean;
+  /** Card provider. Only 'lithic' is supported. */
+  provider: 'lithic';
+  /** Default per-card spending limit in USD. */
+  defaultSpendLimitUsd: number;
+  /** Whether physical card issuance is allowed. */
+  allowPhysical: boolean;
+}
+
+export const DEFAULT_CARD_CONFIG: CardConfig = {
+  enabled: false,
+  provider: 'lithic',
+  defaultSpendLimitUsd: 500,
+  allowPhysical: false,
+};
+
+// ---------------------------------------------------------------------------
+// Records (DB / runtime)
+// ---------------------------------------------------------------------------
+
+export interface AgentCardRecord {
+  id: string;
+  agentId: string;
+  /** Lithic's card token identifier. */
+  lithicCardToken: string;
+  last4: string;
+  cardType: CardType;
+  state: CardState;
+  spendLimitUsd: number;
+  spendLimitDuration: SpendLimitDuration;
+  network: CardNetwork;
+  /** Agent-assigned label for the card. */
+  memo?: string;
+  createdAt: number;
+}
+
+export interface CardTransactionRecord {
+  id: string;
+  /** FK to AgentCardRecord.id */
+  cardId: string;
+  /** Lithic's transaction token. */
+  lithicTxToken: string;
+  merchantName?: string;
+  /** 4-digit Merchant Category Code. */
+  merchantMcc: string;
+  /** Resolved spend category. */
+  category: SpendCategory;
+  amountUsd: number;
+  status: CardTxStatus;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Card store interface (agnostic — callers provide SQLite/memory impl)
+// ---------------------------------------------------------------------------
+
+export interface ICardStore {
+  getCard(agentId: string): Promise<AgentCardRecord | null>;
+  saveCard(record: AgentCardRecord): Promise<void>;
+  updateCardState(agentId: string, state: CardState): Promise<void>;
+  insertTransaction(record: CardTransactionRecord): Promise<void>;
+  updateTransactionStatus(id: string, status: CardTxStatus): Promise<void>;
+  getTransactions(cardId: string, limit?: number): Promise<CardTransactionRecord[]>;
+  getTransactionsByPeriod(cardId: string, since: number): Promise<CardTransactionRecord[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Lithic API types (subset we need)
+// ---------------------------------------------------------------------------
+
+export interface CreateCardParams {
+  type: CardType;
+  memo?: string;
+  spend_limit: number;
+  spend_limit_duration: SpendLimitDuration;
+  state?: CardState;
+}
+
+export interface UpdateCardParams {
+  state?: CardState;
+  spend_limit?: number;
+  spend_limit_duration?: SpendLimitDuration;
+  memo?: string;
+}
+
+export interface LithicCardResponse {
+  token: string;
+  last_four: string;
+  type: CardType;
+  state: CardState;
+  spend_limit: number;
+  spend_limit_duration: SpendLimitDuration;
+  pan?: string;
+  cvv?: string;
+  exp_month?: string;
+  exp_year?: string;
+  funding: { token: string; type: string };
+}
+
+export interface LithicTransaction {
+  token: string;
+  card_token: string;
+  amount: number;
+  merchant: {
+    descriptor: string;
+    mcc: string;
+    city?: string;
+    state?: string;
+    country?: string;
+  };
+  status: 'PENDING' | 'SETTLED' | 'DECLINED' | 'VOIDED';
+  created: string;
+}
+
+export interface ListTxOpts {
+  begin?: string;
+  end?: string;
+  page_size?: number;
+}
+
+export interface AuthRuleParams {
+  allowed_mcc?: string[];
+  blocked_mcc?: string[];
+}
+
+export interface ICardAdapter {
+  createCard(params: CreateCardParams): Promise<LithicCardResponse>;
+  getCard(cardToken: string): Promise<LithicCardResponse>;
+  updateCard(cardToken: string, updates: UpdateCardParams): Promise<LithicCardResponse>;
+  pauseCard(cardToken: string): Promise<void>;
+  resumeCard(cardToken: string): Promise<void>;
+  closeCard(cardToken: string): Promise<void>;
+  listTransactions(cardToken: string, opts?: ListTxOpts): Promise<LithicTransaction[]>;
+  createAuthRule(cardToken: string, rule: AuthRuleParams): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Spending summary
+// ---------------------------------------------------------------------------
+
+export interface SpendingSummary {
+  totalUsd: number;
+  period: 'day' | 'month';
+  byCategory: Array<{ category: SpendCategory; amountUsd: number }>;
+  transactionCount: number;
+}

package/src/chains/EvmWalletAdapter.ts

@@ -0,0 +1,170 @@
+// @ts-nocheck
+/**
+ * @fileoverview EVM chain adapter for the Agent Personal Wallet.
+ *
+ * Supports Ethereum, Base, and Polygon via ethers.js v6 (dynamic import).
+ *
+ * @module wunderland/wallet/chains/EvmWalletAdapter
+ */
+
+import type { ChainId, IChainWalletAdapter, WalletTxStatus } from '../types.js';
+
+// Lazily resolved ethers module (dynamic import — not a hard dependency)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _ethers: any = null;
+
+async function getEthers(): Promise<any> {
+  if (!_ethers) {
+    try {
+      _ethers = await import('ethers' as string);
+    } catch {
+      throw new Error(
+        'Missing dependency: ethers is required for EVM wallet support. '
+        + 'Install it with: npm install ethers',
+      );
+    }
+  }
+  return _ethers;
+}
+
+/** Default RPC endpoints per chain. */
+const DEFAULT_RPC: Record<string, string> = {
+  ethereum: 'https://eth.llamarpc.com',
+  base: 'https://mainnet.base.org',
+  polygon: 'https://polygon-rpc.com',
+};
+
+/** Well-known ERC-20 addresses per chain. */
+export const KNOWN_TOKENS: Record<string, Record<string, string>> = {
+  ethereum: {
+    USDC: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    USDT: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+  },
+  base: {
+    USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    USDT: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
+  },
+  polygon: {
+    USDC: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
+    USDT: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
+  },
+};
+
+/** Minimal ERC-20 ABI for balance + transfer. */
+const ERC20_ABI = [
+  'function balanceOf(address owner) view returns (uint256)',
+  'function transfer(address to, uint256 amount) returns (bool)',
+  'function decimals() view returns (uint8)',
+];
+
+export interface EvmWalletAdapterOptions {
+  chain: ChainId;
+  rpcUrl?: string;
+}
+
+export class EvmWalletAdapter implements IChainWalletAdapter {
+  readonly chain: ChainId;
+  private rpcUrl: string;
+
+  constructor(opts: EvmWalletAdapterOptions) {
+    this.chain = opts.chain;
+    this.rpcUrl = opts.rpcUrl || DEFAULT_RPC[opts.chain] || DEFAULT_RPC.ethereum;
+  }
+
+  async generateKeypair(): Promise<{ publicKey: string; secretKey: Uint8Array }> {
+    const { Wallet } = await getEthers();
+    const wallet = Wallet.createRandom();
+    // ethers v6 returns hex private key — convert to Uint8Array
+    const privKeyHex = wallet.privateKey.slice(2); // remove 0x
+    const secretKey = hexToBytes(privKeyHex);
+    return {
+      publicKey: wallet.address,
+      secretKey,
+    };
+  }
+
+  async getBalance(address: string): Promise<bigint> {
+    const { JsonRpcProvider } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    return await provider.getBalance(address);
+  }
+
+  async getTokenBalance(address: string, tokenAddress: string): Promise<bigint> {
+    const { JsonRpcProvider, Contract } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    const contract = new Contract(tokenAddress, ERC20_ABI, provider);
+    const balance: bigint = await contract.balanceOf(address);
+    return balance;
+  }
+
+  async signTransfer(
+    secretKey: Uint8Array,
+    to: string,
+    amountRaw: bigint,
+  ): Promise<Uint8Array> {
+    const { JsonRpcProvider, Wallet } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    const wallet = new Wallet(bytesToHex(secretKey), provider);
+
+    const tx = await wallet.populateTransaction({
+      to,
+      value: amountRaw,
+    });
+
+    const signed = await wallet.signTransaction(tx);
+    return hexToBytes(signed.slice(2));
+  }
+
+  async signTokenTransfer(
+    secretKey: Uint8Array,
+    to: string,
+    tokenAddress: string,
+    amountRaw: bigint,
+  ): Promise<Uint8Array> {
+    const { JsonRpcProvider, Wallet, Contract } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    const wallet = new Wallet(bytesToHex(secretKey), provider);
+    const contract = new Contract(tokenAddress, ERC20_ABI, wallet);
+
+    const tx = await contract.transfer.populateTransaction(to, amountRaw);
+    const populated = await wallet.populateTransaction(tx);
+    const signed = await wallet.signTransaction(populated);
+    return hexToBytes(signed.slice(2));
+  }
+
+  async broadcast(signedTx: Uint8Array): Promise<string> {
+    const { JsonRpcProvider } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    const txResponse = await provider.broadcastTransaction('0x' + bytesToHex(signedTx));
+    await txResponse.wait(1);
+    return txResponse.hash;
+  }
+
+  async getTransactionStatus(txHash: string): Promise<WalletTxStatus> {
+    const { JsonRpcProvider } = await getEthers();
+    const provider = new JsonRpcProvider(this.rpcUrl);
+    const receipt = await provider.getTransactionReceipt(txHash);
+
+    if (!receipt) return 'pending';
+    if (receipt.status === 1) return 'confirmed';
+    return 'failed';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hex <-> bytes helpers
+// ---------------------------------------------------------------------------
+
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

package/src/chains/SolanaWalletAdapter.ts

@@ -0,0 +1,184 @@
+// @ts-nocheck
+/**
+ * @fileoverview Solana chain adapter for the Agent Personal Wallet.
+ *
+ * Uses dynamic imports for @solana/web3.js so it remains an optional dependency.
+ * Patterns derived from the existing SolanaProvider in anchor-providers.
+ *
+ * @module wunderland/wallet/chains/SolanaWalletAdapter
+ */
+
+import type { IChainWalletAdapter, WalletTxStatus } from '../types.js';
+
+// Lazily resolved modules
+let _web3: typeof import('@solana/web3.js') | null = null;
+
+async function getWeb3() {
+  if (!_web3) {
+    try {
+      _web3 = await import('@solana/web3.js');
+    } catch {
+      throw new Error(
+        'Missing dependency: @solana/web3.js is required for Solana wallet support. '
+        + 'Install it with: npm install @solana/web3.js',
+      );
+    }
+  }
+  return _web3;
+}
+
+export interface SolanaWalletAdapterOptions {
+  /** RPC endpoint URL. Defaults to mainnet-beta. */
+  rpcUrl?: string;
+  /** Commitment level for queries. */
+  commitment?: 'processed' | 'confirmed' | 'finalized';
+}
+
+export class SolanaWalletAdapter implements IChainWalletAdapter {
+  readonly chain = 'solana' as const;
+  private rpcUrl: string;
+  private commitment: 'processed' | 'confirmed' | 'finalized';
+
+  constructor(opts: SolanaWalletAdapterOptions = {}) {
+    this.rpcUrl = opts.rpcUrl || 'https://api.mainnet-beta.solana.com';
+    this.commitment = opts.commitment || 'confirmed';
+  }
+
+  async generateKeypair(): Promise<{ publicKey: string; secretKey: Uint8Array }> {
+    const { Keypair } = await getWeb3();
+    const kp = Keypair.generate();
+    return {
+      publicKey: kp.publicKey.toBase58(),
+      secretKey: kp.secretKey,
+    };
+  }
+
+  async getBalance(address: string): Promise<bigint> {
+    const { Connection, PublicKey } = await getWeb3();
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const lamports = await conn.getBalance(new PublicKey(address));
+    return BigInt(lamports);
+  }
+
+  async getTokenBalance(address: string, tokenMint: string): Promise<bigint> {
+    const { Connection, PublicKey } = await getWeb3();
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const ownerPk = new PublicKey(address);
+    const mintPk = new PublicKey(tokenMint);
+
+    // Find the associated token account
+    const accounts = await conn.getTokenAccountsByOwner(ownerPk, { mint: mintPk });
+    if (accounts.value.length === 0) return 0n;
+
+    // Parse account data to get amount
+    const info = await conn.getTokenAccountBalance(accounts.value[0].pubkey);
+    return BigInt(info.value.amount);
+  }
+
+  async signTransfer(
+    secretKey: Uint8Array,
+    to: string,
+    amountRaw: bigint,
+  ): Promise<Uint8Array> {
+    const { Keypair, PublicKey, SystemProgram, Transaction, Connection } = await getWeb3();
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const signer = Keypair.fromSecretKey(secretKey);
+
+    const tx = new Transaction().add(
+      SystemProgram.transfer({
+        fromPubkey: signer.publicKey,
+        toPubkey: new PublicKey(to),
+        lamports: Number(amountRaw),
+      }),
+    );
+
+    tx.feePayer = signer.publicKey;
+    tx.recentBlockhash = (await conn.getLatestBlockhash()).blockhash;
+    tx.sign(signer);
+
+    return tx.serialize();
+  }
+
+  async signTokenTransfer(
+    secretKey: Uint8Array,
+    to: string,
+    tokenMint: string,
+    amountRaw: bigint,
+  ): Promise<Uint8Array> {
+    // SPL token transfers require @solana/spl-token — use dynamic import
+    const { Keypair, PublicKey, Transaction, Connection } = await getWeb3();
+    let splToken: any;
+    try {
+      splToken = await import('@solana/spl-token' as string);
+    } catch {
+      throw new Error(
+        'Missing dependency: @solana/spl-token is required for SPL token transfers. '
+        + 'Install it with: npm install @solana/spl-token',
+      );
+    }
+
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const signer = Keypair.fromSecretKey(secretKey);
+    const mintPk = new PublicKey(tokenMint);
+    const destPk = new PublicKey(to);
+
+    // Get or create associated token accounts
+    const sourceAta = splToken.getAssociatedTokenAddressSync(mintPk, signer.publicKey);
+    const destAta = splToken.getAssociatedTokenAddressSync(mintPk, destPk);
+
+    const tx = new Transaction();
+
+    // Create destination ATA if it doesn't exist
+    const destAccount = await conn.getAccountInfo(destAta);
+    if (!destAccount) {
+      tx.add(
+        splToken.createAssociatedTokenAccountInstruction(
+          signer.publicKey,
+          destAta,
+          destPk,
+          mintPk,
+        ),
+      );
+    }
+
+    tx.add(
+      splToken.createTransferInstruction(
+        sourceAta,
+        destAta,
+        signer.publicKey,
+        Number(amountRaw),
+      ),
+    );
+
+    tx.feePayer = signer.publicKey;
+    tx.recentBlockhash = (await conn.getLatestBlockhash()).blockhash;
+    tx.sign(signer);
+
+    return tx.serialize();
+  }
+
+  async broadcast(signedTx: Uint8Array): Promise<string> {
+    const { Connection } = await getWeb3();
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const sig = await conn.sendRawTransaction(signedTx, {
+      skipPreflight: false,
+      preflightCommitment: this.commitment,
+    });
+    // Wait for confirmation
+    await conn.confirmTransaction(sig, this.commitment);
+    return sig;
+  }
+
+  async getTransactionStatus(txHash: string): Promise<WalletTxStatus> {
+    const { Connection } = await getWeb3();
+    const conn = new Connection(this.rpcUrl, this.commitment);
+    const status = await conn.getSignatureStatus(txHash);
+
+    if (!status.value) return 'pending';
+    if (status.value.err) return 'failed';
+    if (status.value.confirmationStatus === 'finalized' || status.value.confirmationStatus === 'confirmed') {
+      return 'confirmed';
+    }
+    return 'pending';
+  }
+}