amped-defi 1.0.0

package/src/wallet/providers/LocalKeyBackend.ts

@@ -0,0 +1,184 @@
+/**
+ * Local Key Backend
+ * 
+ * Wallet backend implementation using local private keys.
+ * Compatible with evm-wallet-skill's key storage.
+ * 
+ * Uses viem for transaction signing and submission.
+ */
+
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Hash,
+  type Address,
+  type Chain,
+} from 'viem';
+import { privateKeyToAccount, type PrivateKeyAccount } from 'viem/accounts';
+import type { 
+  IWalletBackend, 
+  LocalKeyBackendConfig, 
+  TransactionRequest, 
+  TransactionReceipt 
+} from './types';
+import { getViemChain, getDefaultRpcUrl, resolveChainId } from './chainConfig';
+
+/**
+ * Local private key wallet backend
+ * 
+ * Signs transactions locally using the provided private key.
+ * This is the standard backend for self-custody wallets.
+ */
+export class LocalKeyBackend implements IWalletBackend {
+  readonly type = 'localKey' as const;
+  
+  private readonly account: PrivateKeyAccount;
+  private readonly walletClient: ReturnType<typeof createWalletClient>;
+  private readonly _publicClient: ReturnType<typeof createPublicClient>;
+  private readonly chainId: number;
+  private readonly chain: Chain;
+
+  constructor(config: LocalKeyBackendConfig) {
+    // Resolve chain configuration
+    this.chainId = resolveChainId(config.chainId);
+    this.chain = getViemChain(this.chainId);
+    
+    // Get RPC URL (custom or default)
+    const rpcUrl = config.rpcUrl || getDefaultRpcUrl(this.chainId);
+    
+    // Create account from private key
+    this.account = privateKeyToAccount(config.privateKey);
+    
+    // Create viem clients
+    this._publicClient = createPublicClient({
+      chain: this.chain,
+      transport: http(rpcUrl),
+    });
+    
+    this.walletClient = createWalletClient({
+      account: this.account,
+      chain: this.chain,
+      transport: http(rpcUrl),
+    });
+    
+    console.log(`[LocalKeyBackend] Initialized for chain ${this.chain.name} (${this.chainId})`);
+    console.log(`[LocalKeyBackend] Address: ${this.account.address}`);
+  }
+
+  /**
+   * Get the wallet address
+   */
+  async getAddress(): Promise<Address> {
+    return this.account.address;
+  }
+
+  /**
+   * Send a transaction
+   * 
+   * Signs locally and submits via RPC.
+   */
+  async sendTransaction(tx: TransactionRequest): Promise<Hash> {
+    console.log(`[LocalKeyBackend] Sending transaction to ${tx.to}`);
+    
+    // Build transaction params
+    const txParams: any = {
+      account: this.account,
+      chain: this.chain,
+      to: tx.to,
+      value: tx.value || 0n,
+      data: tx.data,
+    };
+    
+    // Add optional gas parameters
+    if (tx.gasLimit) txParams.gas = tx.gasLimit;
+    if (tx.gasPrice) txParams.gasPrice = tx.gasPrice;
+    if (tx.maxFeePerGas) txParams.maxFeePerGas = tx.maxFeePerGas;
+    if (tx.maxPriorityFeePerGas) txParams.maxPriorityFeePerGas = tx.maxPriorityFeePerGas;
+    if (tx.nonce !== undefined) txParams.nonce = tx.nonce;
+    
+    const hash = await this.walletClient.sendTransaction(txParams);
+    
+    console.log(`[LocalKeyBackend] Transaction sent: ${hash}`);
+    return hash;
+  }
+
+  /**
+   * Wait for transaction confirmation
+   */
+  async waitForTransaction(txHash: Hash): Promise<TransactionReceipt> {
+    console.log(`[LocalKeyBackend] Waiting for transaction: ${txHash}`);
+    
+    const receipt = await this._publicClient.waitForTransactionReceipt({
+      hash: txHash,
+    });
+    
+    console.log(`[LocalKeyBackend] Transaction confirmed in block ${receipt.blockNumber}`);
+    
+    return {
+      transactionHash: receipt.transactionHash,
+      blockNumber: receipt.blockNumber,
+      blockHash: receipt.blockHash,
+      from: receipt.from,
+      to: receipt.to,
+      gasUsed: receipt.gasUsed,
+      status: receipt.status === 'success' ? 'success' : 'reverted',
+      logs: receipt.logs.map((log: any) => ({
+        address: log.address,
+        topics: [...(log.topics || [])] as `0x${string}`[],
+        data: log.data,
+      })),
+    };
+  }
+
+  /**
+   * Check if backend is ready
+   * 
+   * For local key backend, we verify RPC connectivity.
+   */
+  async isReady(): Promise<boolean> {
+    try {
+      await this._publicClient.getChainId();
+      return true;
+    } catch (error) {
+      console.error('[LocalKeyBackend] RPC connectivity check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get the chain ID
+   */
+  getChainId(): number {
+    return this.chainId;
+  }
+
+  /**
+   * Get the public client (for external use)
+   */
+  getPublicClient(): ReturnType<typeof createPublicClient> {
+    return this._publicClient;
+  }
+
+  /**
+   * Get the wallet client (for advanced use cases)
+   */
+  getWalletClient(): ReturnType<typeof createWalletClient> {
+    return this.walletClient;
+  }
+}
+
+/**
+ * Create a LocalKeyBackend from configuration
+ */
+export async function createLocalKeyBackend(config: LocalKeyBackendConfig): Promise<LocalKeyBackend> {
+  const backend = new LocalKeyBackend(config);
+  
+  // Verify connectivity
+  const ready = await backend.isReady();
+  if (!ready) {
+    console.warn('[LocalKeyBackend] Backend created but RPC connectivity check failed');
+  }
+  
+  return backend;
+}

package/src/wallet/providers/chainConfig.ts

@@ -0,0 +1,194 @@
+/**
+ * Chain Configuration for Amped Wallet Provider
+ *
+ * Complete chain configuration for all SODAX-supported EVM chains.
+ * 
+ * Note: We maintain our own chain definitions to avoid viem version
+ * mismatches with @sodax/wallet-sdk-core. The SDK's getEvmViemChain()
+ * is used as a fallback for future chain additions.
+ */
+
+import { defineChain, type Chain } from 'viem';
+import {
+  mainnet,
+  arbitrum,
+  optimism,
+  base,
+  polygon,
+  bsc,
+  avalanche,
+  sonic,
+  lightlinkPhoenix,
+} from 'viem/chains';
+
+/**
+ * Chain ID constants matching @sodax/types
+ */
+export const CHAIN_IDS = {
+  ETHEREUM: 1,
+  ARBITRUM: 42161,
+  OPTIMISM: 10,
+  BASE: 8453,
+  POLYGON: 137,
+  BSC: 56,
+  AVALANCHE: 43114,
+  SONIC: 146,
+  LIGHTLINK: 1890,
+  HYPEREVM: 999,
+  KAIA: 8217,
+} as const;
+
+/**
+ * SDK chain ID format mapping (e.g., 'ethereum', '0x2105.base')
+ */
+export const SDK_CHAIN_ID_MAP: Record<string, number> = {
+  'ethereum': CHAIN_IDS.ETHEREUM,
+  'arbitrum': CHAIN_IDS.ARBITRUM,
+  '0xa4b1.arbitrum': CHAIN_IDS.ARBITRUM,
+  'optimism': CHAIN_IDS.OPTIMISM,
+  '0xa.optimism': CHAIN_IDS.OPTIMISM,
+  'base': CHAIN_IDS.BASE,
+  '0x2105.base': CHAIN_IDS.BASE,
+  'polygon': CHAIN_IDS.POLYGON,
+  '0x89.polygon': CHAIN_IDS.POLYGON,
+  'bsc': CHAIN_IDS.BSC,
+  '0x38.bsc': CHAIN_IDS.BSC,
+  'avalanche': CHAIN_IDS.AVALANCHE,
+  'avax': CHAIN_IDS.AVALANCHE,
+  '0xa86a.avax': CHAIN_IDS.AVALANCHE,
+  'sonic': CHAIN_IDS.SONIC,
+  'lightlink': CHAIN_IDS.LIGHTLINK,
+  'hyperevm': CHAIN_IDS.HYPEREVM,
+  'hyper': CHAIN_IDS.HYPEREVM,
+  'kaia': CHAIN_IDS.KAIA,
+  '0x2019.kaia': CHAIN_IDS.KAIA,
+};
+
+/**
+ * HyperEVM chain definition
+ * Matches @sodax/wallet-sdk-core hyper definition
+ */
+export const hyper = defineChain({
+  id: CHAIN_IDS.HYPEREVM,
+  name: 'HyperEVM',
+  nativeCurrency: { decimals: 18, name: 'HYPE', symbol: 'HYPE' },
+  rpcUrls: { default: { http: ['https://rpc.hyperliquid.xyz/evm'] } },
+  blockExplorers: { default: { name: 'HyperEVMScan', url: 'https://hyperevmscan.io/' } },
+  contracts: { multicall3: { address: '0xcA11bde05977b3631167028862bE2a173976CA11', blockCreated: 13051 } },
+});
+
+/**
+ * Kaia chain definition
+ */
+export const kaia = defineChain({
+  id: CHAIN_IDS.KAIA,
+  name: 'Kaia',
+  nativeCurrency: { decimals: 18, name: 'KAIA', symbol: 'KAIA' },
+  rpcUrls: { default: { http: ['https://public-en.node.kaia.io'] } },
+  blockExplorers: { default: { name: 'KaiaScan', url: 'https://kaiascan.io/' } },
+});
+
+/**
+ * Chain configuration by numeric ID
+ */
+const CHAIN_CONFIG: Record<number, Chain> = {
+  [CHAIN_IDS.ETHEREUM]: mainnet,
+  [CHAIN_IDS.ARBITRUM]: arbitrum,
+  [CHAIN_IDS.OPTIMISM]: optimism,
+  [CHAIN_IDS.BASE]: base,
+  [CHAIN_IDS.POLYGON]: polygon,
+  [CHAIN_IDS.BSC]: bsc,
+  [CHAIN_IDS.AVALANCHE]: avalanche,
+  [CHAIN_IDS.SONIC]: sonic,
+  [CHAIN_IDS.LIGHTLINK]: lightlinkPhoenix,
+  [CHAIN_IDS.HYPEREVM]: hyper,
+  [CHAIN_IDS.KAIA]: kaia,
+};
+
+/**
+ * Default RPC URLs for all supported chains
+ */
+/**
+ * FALLBACK RPC URLs for all supported chains
+ * Primary RPCs should come from evm-wallet-skill (chains.js)
+ * @see https://github.com/amped-finance/evm-wallet-skill
+ */
+export const DEFAULT_RPC_URLS: Record<number, string> = {
+  [CHAIN_IDS.ETHEREUM]: 'https://ethereum.publicnode.com',
+  [CHAIN_IDS.ARBITRUM]: 'https://arb1.arbitrum.io/rpc',
+  [CHAIN_IDS.OPTIMISM]: 'https://mainnet.optimism.io',
+  [CHAIN_IDS.BASE]: 'https://mainnet.base.org',
+  [CHAIN_IDS.POLYGON]: 'https://polygon-bor-rpc.publicnode.com',
+  [CHAIN_IDS.BSC]: 'https://bsc-dataseed.binance.org',
+  [CHAIN_IDS.AVALANCHE]: 'https://api.avax.network/ext/bc/C/rpc',
+  [CHAIN_IDS.SONIC]: 'https://rpc.soniclabs.com',
+  [CHAIN_IDS.LIGHTLINK]: 'https://replicator.phoenix.lightlink.io/rpc/v1',
+  [CHAIN_IDS.HYPEREVM]: 'https://rpc.hyperliquid.xyz/evm',
+  [CHAIN_IDS.KAIA]: 'https://public-en.node.kaia.io',
+};
+
+/**
+ * Resolve SDK chain ID format to numeric chain ID
+ */
+export function resolveChainId(sdkChainId: string | number): number {
+  if (typeof sdkChainId === 'number') return sdkChainId;
+
+  const lower = sdkChainId.toLowerCase();
+  if (SDK_CHAIN_ID_MAP[lower] !== undefined) return SDK_CHAIN_ID_MAP[lower];
+
+  if (lower.startsWith('0x')) {
+    const parsed = parseInt(lower, 16);
+    if (!isNaN(parsed)) return parsed;
+  }
+
+  const parsed = parseInt(sdkChainId, 10);
+  if (!isNaN(parsed)) return parsed;
+
+  throw new Error(`Unable to resolve chain ID: ${sdkChainId}`);
+}
+
+/**
+ * Get viem Chain configuration for a chain ID
+ */
+export function getViemChain(chainId: string | number): Chain {
+  const numericId = resolveChainId(chainId);
+  const chain = CHAIN_CONFIG[numericId];
+  if (!chain) throw new Error(`Unsupported chain ID: ${chainId} (resolved to ${numericId})`);
+  return chain;
+}
+
+/**
+ * Get default RPC URL for a chain
+ */
+export function getDefaultRpcUrl(chainId: string | number): string {
+  const numericId = resolveChainId(chainId);
+  const rpcUrl = DEFAULT_RPC_URLS[numericId];
+  if (!rpcUrl) throw new Error(`No default RPC URL for chain ID: ${chainId}`);
+  return rpcUrl;
+}
+
+/**
+ * Check if a chain is supported
+ */
+export function isChainSupported(chainId: string | number): boolean {
+  try {
+    getViemChain(chainId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all supported chain IDs
+ */
+export function getSupportedChainIds(): number[] {
+  return Object.keys(CHAIN_CONFIG).map(Number);
+}
+
+/**
+ * Get chain name
+ */
+export function getChainName(chainId: string | number): string {
+  return getViemChain(chainId).name;
+}

package/src/wallet/providers/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Wallet Providers
+ * 
+ * Pluggable wallet backend architecture for Amped DeFi plugin.
+ * 
+ * @example
+ * ```typescript
+ * import { AmpedWalletProvider } from './wallet/providers';
+ * 
+ * // Create with local private key (evm-wallet-skill compatible)
+ * const provider = await AmpedWalletProvider.fromPrivateKey({
+ *   privateKey: '0x...',
+ *   chainId: 'lightlink',
+ * });
+ * 
+ * // Or create with Bankr backend
+ * const bankrProvider = await AmpedWalletProvider.fromBankr({
+ *   bankrApiUrl: 'https://api.bankr.xyz',
+ *   bankrApiKey: 'your-api-key',
+ *   userAddress: '0x...',
+ *   chainId: 'base',
+ * });
+ * ```
+ */
+
+// Main provider
+export { AmpedWalletProvider } from './AmpedWalletProvider';
+
+// Backends
+export { LocalKeyBackend, createLocalKeyBackend } from './LocalKeyBackend';
+export { BankrBackend, createBankrBackend } from './BankrBackend';
+
+// Chain configuration
+export {
+  CHAIN_IDS,
+  SDK_CHAIN_ID_MAP,
+  DEFAULT_RPC_URLS,
+  hyper,
+  resolveChainId,
+  getViemChain,
+  getDefaultRpcUrl,
+  isChainSupported,
+  getSupportedChainIds,
+  getChainName,
+} from './chainConfig';
+
+// Types
+export type {
+  WalletBackendType,
+  WalletBackendBaseConfig,
+  LocalKeyBackendConfig,
+  BankrBackendConfig,
+  PrivyBackendConfig,
+  SmartWalletBackendConfig,
+  WalletBackendConfig,
+  TransactionRequest,
+  TransactionReceipt,
+  IWalletBackend,
+  WalletBackendFactory,
+  AmpedWalletProviderConfig,
+  IAmpedWalletProvider,
+} from './types';

package/src/wallet/providers/types.ts

@@ -0,0 +1,186 @@
+/**
+ * Wallet Provider Types
+ * 
+ * Interfaces for the pluggable wallet backend architecture.
+ * Allows the same AmpedWalletProvider to work with:
+ * - Local private keys (evm-wallet-skill)
+ * - Bankr execution API
+ * - Future: Privy, smart contract wallets, etc.
+ */
+
+import type { Hash, Address } from 'viem';
+import { createPublicClient } from 'viem';
+import type { 
+  EvmRawTransaction, 
+  EvmRawTransactionReceipt,
+  IEvmWalletProvider 
+} from '@sodax/types';
+
+/**
+ * Wallet backend type identifiers
+ */
+export type WalletBackendType = 'localKey' | 'bankr' | 'privy' | 'smartWallet';
+
+/**
+ * Base configuration for all backends
+ */
+export interface WalletBackendBaseConfig {
+  type: WalletBackendType;
+  chainId: string | number;
+  rpcUrl?: string;
+}
+
+/**
+ * Configuration for local private key backend
+ */
+export interface LocalKeyBackendConfig extends WalletBackendBaseConfig {
+  type: 'localKey';
+  privateKey: `0x${string}`;
+}
+
+/**
+ * Configuration for Bankr execution backend
+ */
+export interface BankrBackendConfig extends WalletBackendBaseConfig {
+  type: 'bankr';
+  bankrApiUrl: string;
+  bankrApiKey: string;
+  userAddress: Address;
+  /** Optional: policy limits for transactions */
+  policy?: {
+    maxValuePerTx?: bigint;
+    maxDailyVolume?: bigint;
+    allowedContracts?: Address[];
+  };
+}
+
+/**
+ * Configuration for Privy server wallet backend (future)
+ */
+export interface PrivyBackendConfig extends WalletBackendBaseConfig {
+  type: 'privy';
+  appId: string;
+  appSecret: string;
+  walletId: string;
+}
+
+/**
+ * Configuration for smart contract wallet backend (future)
+ */
+export interface SmartWalletBackendConfig extends WalletBackendBaseConfig {
+  type: 'smartWallet';
+  walletAddress: Address;
+  sessionKey: `0x${string}`;
+  entryPointAddress: Address;
+}
+
+/**
+ * Union of all backend configurations
+ */
+export type WalletBackendConfig = 
+  | LocalKeyBackendConfig 
+  | BankrBackendConfig
+  | PrivyBackendConfig
+  | SmartWalletBackendConfig;
+
+/**
+ * Transaction request (simplified)
+ */
+export interface TransactionRequest {
+  to: Address;
+  value?: bigint;
+  data?: `0x${string}`;
+  gasLimit?: bigint;
+  gasPrice?: bigint;
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  nonce?: number;
+}
+
+/**
+ * Transaction receipt (simplified)
+ */
+export interface TransactionReceipt {
+  transactionHash: Hash;
+  blockNumber: bigint;
+  blockHash: Hash;
+  from: Address;
+  to: Address | null;
+  gasUsed: bigint;
+  status: 'success' | 'reverted';
+  logs: Array<{
+    address: Address;
+    topics: `0x${string}`[];
+    data: `0x${string}`;
+  }>;
+}
+
+/**
+ * Wallet backend interface
+ * 
+ * All wallet backends must implement this interface.
+ * This allows AmpedWalletProvider to delegate to different backends
+ * without changing its own implementation.
+ */
+export interface IWalletBackend {
+  /** Backend type identifier */
+  readonly type: WalletBackendType;
+  
+  /** Get the wallet address */
+  getAddress(): Promise<Address>;
+  
+  /** 
+   * Send a transaction and return the transaction hash
+   * The backend is responsible for signing and submitting the transaction.
+   */
+  sendTransaction(tx: TransactionRequest): Promise<Hash>;
+  
+  /**
+   * Wait for a transaction to be confirmed
+   * Returns when the transaction is included in a block.
+   */
+  waitForTransaction(txHash: Hash): Promise<TransactionReceipt>;
+  
+  /**
+   * Check if the backend can execute transactions
+   * (e.g., Bankr backend may need API connectivity)
+   */
+  isReady(): Promise<boolean>;
+  
+  /**
+   * Get the numeric chain ID this backend is configured for
+   */
+  getChainId(): number;
+}
+
+/**
+ * Factory function type for creating backends
+ */
+export type WalletBackendFactory = (config: WalletBackendConfig) => Promise<IWalletBackend>;
+
+/**
+ * Amped Wallet Provider configuration
+ */
+export interface AmpedWalletProviderConfig {
+  /** Backend configuration */
+  backend: WalletBackendConfig;
+  /** Optional custom RPC URL (overrides chain default) */
+  rpcUrl?: string;
+}
+
+/**
+ * Extended IEvmWalletProvider with Amped-specific methods
+ */
+export interface IAmpedWalletProvider extends IEvmWalletProvider {
+  /** Get the underlying backend */
+  getBackend(): IWalletBackend;
+  
+  /** Get the backend type */
+  getBackendType(): WalletBackendType;
+  
+  /** Check if ready for transactions */
+  isReady(): Promise<boolean>;
+  
+  /** Get chain ID */
+  getChainId(): number;
+}