auramaxx 1.0.0-alpha.4

package/server/lib/defaults.ts

@@ -0,0 +1,366 @@
+/**
+ * Centralized System Defaults
+ * ===========================
+ * Key-value store for configurable limits, permissions, TTLs, rate limits, etc.
+ * Backed by Prisma SystemDefault table with in-memory cache for fast reads.
+ *
+ * Usage:
+ *   const limit = await getDefault('limits.fund', 0.1);
+ *   const perms = getDefaultSync('permissions.default', ['swap']);
+ *   await setDefault('limits.fund', 0.05);
+ */
+
+import { prisma } from './db';
+
+// ─── Seed Defaults ──────────────────────────────────────────────────
+// Canonical seed values — used for reset and as fallback when DB is empty.
+
+export interface SeedDefault {
+  key: string;
+  value: unknown;
+  type: string;
+  label: string;
+  description?: string;
+}
+
+export const SEED_DEFAULTS: SeedDefault[] = [
+  // Permissions
+  { key: 'permissions.default', value: ['wallet:create:hot', 'send:hot', 'swap', 'fund', 'action:create', 'secret:read', 'secret:write'], type: 'permissions', label: 'Default Agent Permissions', description: 'Permissions granted to new agent tokens by default' },
+  { key: 'permissions.agent_tier', value: 'admin', type: 'permissions', label: 'Default Agent Permission Tier', description: 'Agent-chat permission level: admin (full access) or restricted (approval required)' },
+
+  // Financial limits
+  { key: 'limits.fund', value: 0.1, type: 'financial', label: 'Default Fund Limit (ETH)', description: 'Default ETH limit for cold→hot transfers' },
+  { key: 'limits.send', value: 0.1, type: 'financial', label: 'Default Send Limit (ETH)', description: 'Default ETH limit for hot wallet sends' },
+  { key: 'limits.swap', value: 0.1, type: 'financial', label: 'Default Swap Limit (ETH)', description: 'Default ETH limit for token swaps' },
+  { key: 'gas.evm_buffer', value: 0.001, type: 'financial', label: 'EVM Gas Buffer (ETH)', description: 'Reserved ETH buffer for max-send in UI' },
+  { key: 'gas.sol_buffer', value: 0.000005, type: 'financial', label: 'Solana Gas Buffer (SOL)', description: 'Reserved SOL buffer for max-send in UI' },
+
+  // TTLs
+  { key: 'ttl.agent', value: 3600, type: 'ttl', label: 'Agent Token TTL (seconds)', description: 'Default time-to-live for agent tokens' },
+  { key: 'ttl.admin', value: 604800, type: 'ttl', label: 'Admin Token TTL (seconds)', description: 'Time-to-live for admin tokens (7 days)' },
+  { key: 'ttl.app', value: 86400, type: 'ttl', label: 'App Token TTL (seconds)', description: 'Time-to-live for app tokens (24h)' },
+  { key: 'ttl.action', value: 60, type: 'ttl', label: 'Action Token TTL (seconds)', description: 'Default time-to-live for action tokens' },
+
+  // Strategy runtime (cron-owned)
+  { key: 'strategy.cron_enabled', value: true, type: 'strategy', label: 'Enable Cron-Owned Strategy Runtime', description: 'When true, strategy ticks and message hooks are owned by the cron process only' },
+  { key: 'strategy.tick_interval', value: 1000, type: 'strategy', label: 'Strategy Scheduler Interval (ms)', description: 'Main cron loop interval for strategy ticks and queued messages' },
+  { key: 'strategy.message_batch_size', value: 20, type: 'strategy', label: 'Strategy Message Batch Size', description: 'Maximum queued app messages processed per strategy loop' },
+  { key: 'strategy.message_timeout_ms', value: 120000, type: 'strategy', label: 'App Message Timeout (ms)', description: 'How long API waits for cron-owned app message processing' },
+  { key: 'strategy.health_stale_ms', value: 30000, type: 'strategy', label: 'Strategy Runtime Health Stale Threshold (ms)', description: 'How long a cron heartbeat can be stale before strategy runtime is considered unhealthy' },
+
+  // Rate limits (format: "max,windowMs")
+  { key: 'rate.brute_force', value: '5,900000', type: 'rate_limit', label: 'Brute Force Limit', description: 'Max attempts per 15-minute window for auth endpoints' },
+  { key: 'rate.auth_request', value: '10,60000', type: 'rate_limit', label: 'Auth Request Limit', description: 'Max auth requests per 1-minute window' },
+  { key: 'rate.app_message', value: '10,60000', type: 'rate_limit', label: 'App Message Limit', description: 'Max messages per 1-minute window per app' },
+  { key: 'rate.app_fetch', value: '60,60000', type: 'rate_limit', label: 'App Fetch Limit', description: 'Max fetch proxy requests per 1-minute window per app' },
+  { key: 'rate.app_callback', value: '3,120000', type: 'rate_limit', label: 'App Callback Limit', description: 'Max auto-execute callbacks per 2-minute window per app' },
+
+  // Swap / slippage
+  { key: 'swap.max_slippage', value: 50, type: 'swap', label: 'Max Slippage (%)', description: 'Maximum allowed slippage percentage' },
+  { key: 'swap.min_slippage_admin', value: 0.5, type: 'swap', label: 'Min Slippage Admin (%)', description: 'Minimum slippage floor for admin tokens' },
+  { key: 'swap.min_slippage_agent', value: 1.0, type: 'swap', label: 'Min Slippage Agent (%)', description: 'Minimum slippage floor for agent tokens' },
+
+  // AI provider & model
+  { key: 'ai.provider', value: 'claude-cli', type: 'ai', label: 'AI provider mode', description: 'Which AI provider to use for hooks and ticks' },
+
+  // AI safety
+  { key: 'ai.max_tool_calls', value: 10, type: 'ai_safety', label: 'Max Tool Calls', description: 'Maximum tool calls per hook invocation' },
+  { key: 'ai.max_followup_depth', value: 3, type: 'ai_safety', label: 'Max Follow-up Depth', description: 'Maximum recursive intent follow-up depth' },
+
+  // Launch defaults
+  { key: 'launch.initial_supply', value: '1000000000', type: 'launch', label: 'Initial Token Supply', description: 'Default initial supply for token launches' },
+  { key: 'launch.sell_percent', value: 90, type: 'launch', label: 'Sell Percentage', description: 'Default percentage of supply to sell in auction' },
+  { key: 'launch.epoch_length', value: 3600, type: 'launch', label: 'Epoch Length (seconds)', description: 'Default epoch length for dynamic auctions' },
+
+  // Protocol
+  { key: 'protocol.fee_address', value: '0xa931533E0E0cCE34fc0FafB25ea2046d391eCAA5', type: 'protocol', label: 'Protocol Fee Address', description: 'Address that receives protocol fees from swaps and launches' },
+
+  // App constraints
+  { key: 'app.max_file_size_mb', value: 5, type: 'app', label: 'Max App File Size (MB)', description: 'Maximum file size for installed apps' },
+  { key: 'app.max_total_size_mb', value: 20, type: 'app', label: 'Max App Total Size (MB)', description: 'Maximum total size for installed apps' },
+
+  // Asset discovery
+  { key: 'discovery.enabled', value: true, type: 'discovery', label: 'Enable Asset Discovery', description: 'Master toggle for incoming asset auto-discovery' },
+  { key: 'discovery.scan_interval', value: 60000, type: 'discovery', label: 'Discovery Scan Interval (ms)', description: 'How often to scan for incoming transfers' },
+  { key: 'discovery.max_blocks_per_tick', value: 2000, type: 'discovery', label: 'Max Blocks Per Scan', description: 'Maximum blocks to scan per tick per chain' },
+  { key: 'discovery.min_value_usd', value: 0.5, type: 'discovery', label: 'Min Value USD', description: 'Minimum USD value to auto-track a discovered token' },
+  { key: 'discovery.min_liquidity_usd', value: 1000, type: 'discovery', label: 'Min Liquidity USD', description: 'Minimum pool liquidity to auto-track a discovered token' },
+  { key: 'discovery.safety_enabled', value: true, type: 'discovery', label: 'Enable Safety Check', description: 'Run honeypot/tax checks on discovered tokens' },
+  { key: 'discovery.max_initial_lookback', value: 302400, type: 'discovery', label: 'Max Initial Lookback (blocks)', description: 'How far back to scan on first run (~7 days on Base)' },
+
+  // Trust / auto-approve defaults
+  { key: 'trust.localAutoApprove', value: true, type: 'trust', label: 'Auto-Approve Local Socket Connections', description: 'Auto-approve auth requests from same-UID processes via Unix socket (0600 permission = same user = trusted)' },
+  { key: 'trust.localProfile', value: 'dev', type: 'trust', label: 'Local Socket Agent Profile', description: 'Built-in profile used for local socket-issued agent tokens (strict/dev/admin)' },
+  { key: 'trust.localProfileVersion', value: 'v1', type: 'trust', label: 'Local Socket Agent Profile Version', description: 'Version for local socket profile resolution' },
+  { key: 'trust.localProfileOverrides', value: null, type: 'trust', label: 'Local Socket Agent Profile Overrides', description: 'Optional tighten-only overrides for the local socket profile' },
+  { key: 'trust.localPermissions', value: ['extension:*'], type: 'trust', label: 'Auto-Approve Token Permissions', description: 'Permissions granted to auto-approved local tokens' },
+  { key: 'trust.localLimits', value: { fund: 0, send: 0, swap: 0 }, type: 'trust', label: 'Auto-Approve Token Limits', description: 'Spending limits for auto-approved local tokens (0 = no financial operations)' },
+  { key: 'trust.localTtl', value: 3600, type: 'trust', label: 'Auto-Approve Token TTL (seconds)', description: 'Time-to-live for auto-approved local tokens' },
+
+  // Credential vault defaults
+  { key: 'defaults.credential.access.read', value: ['*'], type: 'credential', label: 'Default Credential Read Scopes', description: 'Default scopes for credential read access on new tokens' },
+  { key: 'defaults.credential.access.write', value: ['*'], type: 'credential', label: 'Default Credential Write Scopes', description: 'Default scopes for credential write access on new tokens' },
+  { key: 'defaults.credential.excludeFields.card', value: ['cvv'], type: 'credential', label: 'Card Excluded Fields', description: 'Fields excluded by default when reading card credentials' },
+  { key: 'defaults.credential.excludeFields.login', value: ['password'], type: 'credential', label: 'Login Excluded Fields', description: 'Fields excluded by default when reading login credentials' },
+  { key: 'defaults.credential.excludeFields.note', value: [], type: 'credential', label: 'Note Excluded Fields', description: 'Fields excluded by default when reading note credentials' },
+
+  // Balance sync
+  { key: 'sync.active_interval', value: 15000, type: 'sync', label: 'Active Sync Interval (ms)', description: 'Interval for syncing active/cold wallets' },
+  { key: 'sync.background_interval', value: 120000, type: 'sync', label: 'Background Sync Interval (ms)', description: 'Interval for syncing background wallets' },
+  { key: 'sync.dormant_interval', value: 600000, type: 'sync', label: 'Dormant Sync Interval (ms)', description: 'Interval for syncing dormant wallets' },
+  { key: 'sync.active_ttl', value: 60000, type: 'sync', label: 'Active Tier TTL (ms)', description: 'How long a wallet stays in active tier after focus' },
+  { key: 'sync.enabled', value: true, type: 'sync', label: 'Enable Balance Sync', description: 'Master switch for the cron balance sync' },
+  { key: 'sync.max_assets_per_call', value: 200, type: 'sync', label: 'Max Assets Per Multicall', description: 'Maximum ERC-20 assets per multicall batch' },
+];
+
+// ─── In-Memory Cache ────────────────────────────────────────────────
+
+const cache = new Map<string, unknown>();
+let cacheLoaded = false;
+
+/**
+ * Invalidate one key or the entire defaults cache.
+ */
+export function invalidateCache(key?: string): void {
+  if (key) {
+    cache.delete(key);
+    return;
+  }
+  cache.clear();
+}
+
+// ─── Change Listeners ───────────────────────────────────────────────
+
+type ChangeListener = (key: string, value: unknown) => void;
+const listeners = new Map<string, Set<ChangeListener>>();
+
+/**
+ * Register a listener that fires when a specific key changes.
+ * Use '*' to listen to all changes.
+ */
+export function onDefaultChanged(key: string, callback: ChangeListener): () => void {
+  if (!listeners.has(key)) {
+    listeners.set(key, new Set());
+  }
+  listeners.get(key)!.add(callback);
+  return () => { listeners.get(key)?.delete(callback); };
+}
+
+function notifyListeners(key: string, value: unknown): void {
+  // Notify specific key listeners
+  listeners.get(key)?.forEach(cb => {
+    try { cb(key, value); } catch { /* listener errors don't propagate */ }
+  });
+  // Notify wildcard listeners
+  listeners.get('*')?.forEach(cb => {
+    try { cb(key, value); } catch { /* listener errors don't propagate */ }
+  });
+}
+
+// ─── Core API ───────────────────────────────────────────────────────
+
+/**
+ * Load all defaults from DB into cache. Call once at startup before app.listen().
+ */
+export async function preloadCache(): Promise<void> {
+  try {
+    const rows = await prisma.systemDefault.findMany();
+    for (const row of rows) {
+      cache.set(row.key, parseValue(row.value));
+    }
+    cacheLoaded = true;
+  } catch {
+    // DB may not have been migrated yet — seed defaults will be used as fallback
+    cacheLoaded = true;
+  }
+}
+
+/**
+ * Get a default value (async). Reads: cache → DB → fallback.
+ */
+export async function getDefault<T>(key: string, fallback: T): Promise<T> {
+  // Cache hit
+  if (cache.has(key)) {
+    return cache.get(key) as T;
+  }
+
+  // DB lookup
+  try {
+    const row = await prisma.systemDefault.findUnique({ where: { key } });
+    if (row) {
+      const val = parseValue(row.value);
+      cache.set(key, val);
+      return val as T;
+    }
+  } catch {
+    // DB error — fall through to seed/fallback
+  }
+
+  // Seed default
+  const seed = SEED_DEFAULTS.find(s => s.key === key);
+  if (seed !== undefined) {
+    cache.set(key, seed.value);
+    return seed.value as T;
+  }
+
+  return fallback;
+}
+
+/**
+ * Get a default value synchronously from cache only.
+ * Requires preloadCache() to have been called at startup.
+ * Falls back to seed default → provided fallback.
+ */
+export function getDefaultSync<T>(key: string, fallback: T): T {
+  if (cache.has(key)) {
+    return cache.get(key) as T;
+  }
+
+  // Seed default as fallback
+  const seed = SEED_DEFAULTS.find(s => s.key === key);
+  if (seed !== undefined) {
+    return seed.value as T;
+  }
+
+  return fallback;
+}
+
+/**
+ * Update a default value. Upserts to DB + updates cache + notifies listeners.
+ */
+export async function setDefault(key: string, value: unknown): Promise<void> {
+  const serialized = JSON.stringify(value);
+
+  // Look up metadata from seed or existing row
+  const seed = SEED_DEFAULTS.find(s => s.key === key);
+  const type = seed?.type || 'custom';
+  const label = seed?.label || key;
+
+  await prisma.systemDefault.upsert({
+    where: { key },
+    update: { value: serialized },
+    create: { key, value: serialized, type, label },
+  });
+
+  invalidateCache(key);
+  cache.set(key, value);
+  notifyListeners(key, value);
+}
+
+/**
+ * Get all defaults grouped by type. Used by GET /defaults endpoint.
+ */
+export async function getAllDefaults(): Promise<Record<string, Array<{
+  key: string;
+  value: unknown;
+  type: string;
+  label: string;
+  description: string | null;
+  updatedAt: string;
+}>>> {
+  const rows = await prisma.systemDefault.findMany({ orderBy: { key: 'asc' } });
+  const grouped: Record<string, Array<{
+    key: string;
+    value: unknown;
+    type: string;
+    label: string;
+    description: string | null;
+    updatedAt: string;
+  }>> = {};
+
+  for (const row of rows) {
+    if (!grouped[row.type]) {
+      grouped[row.type] = [];
+    }
+    grouped[row.type].push({
+      key: row.key,
+      value: parseValue(row.value),
+      type: row.type,
+      label: row.label,
+      description: row.description,
+      updatedAt: row.updatedAt.toISOString(),
+    });
+  }
+
+  return grouped;
+}
+
+/**
+ * Reset a default to its seed value. Pass '*' to reset all.
+ */
+export async function resetDefault(key: string): Promise<void> {
+  if (key === '*') {
+    // Reset all seed defaults
+    for (const seed of SEED_DEFAULTS) {
+      const serialized = JSON.stringify(seed.value);
+      await prisma.systemDefault.upsert({
+        where: { key: seed.key },
+        update: { value: serialized },
+        create: {
+          key: seed.key,
+          value: serialized,
+          type: seed.type,
+          label: seed.label,
+          description: seed.description,
+        },
+      });
+      invalidateCache(seed.key);
+      cache.set(seed.key, seed.value);
+      notifyListeners(seed.key, seed.value);
+    }
+    return;
+  }
+
+  const seed = SEED_DEFAULTS.find(s => s.key === key);
+  if (!seed) {
+    throw new Error(`No seed default for key: ${key}`);
+  }
+
+  const serialized = JSON.stringify(seed.value);
+  await prisma.systemDefault.upsert({
+    where: { key },
+    update: { value: serialized },
+    create: {
+      key: seed.key,
+      value: serialized,
+      type: seed.type,
+      label: seed.label,
+      description: seed.description,
+    },
+  });
+
+  invalidateCache(key);
+  cache.set(key, seed.value);
+  notifyListeners(key, seed.value);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+/** Parse a stored JSON string back to its value */
+function parseValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Parse a rate limit string "max,windowMs" into { max, windowMs }.
+ */
+export function parseRateLimit(value: unknown): { max: number; windowMs: number } {
+  if (typeof value === 'string') {
+    const [maxStr, windowStr] = value.split(',');
+    return { max: parseInt(maxStr, 10), windowMs: parseInt(windowStr, 10) };
+  }
+  return { max: 10, windowMs: 60000 };
+}
+
+// ─── Test Helpers ───────────────────────────────────────────────────
+
+/** Reset cache state (for tests only) */
+export function __resetCache(): void {
+  cache.clear();
+  listeners.clear();
+  cacheLoaded = false;
+}

package/server/lib/dex/index.ts

@@ -0,0 +1,80 @@
+import { ethers } from 'ethers';
+import { DexAdapter, PoolInfo } from './types';
+import { uniswapAdapter } from './uniswap';
+import { relayAdapter } from './relay';
+
+// Re-export types
+export * from './types';
+
+// Registry of available DEX adapters
+const adapters: Record<string, DexAdapter> = {
+  relay: relayAdapter,
+  uniswap: uniswapAdapter,
+};
+
+// Default DEX preference order for auto-detection
+// Relay is primary (aggregator with MEV protection), Uniswap is fallback
+const DEX_PRIORITY = ['relay', 'uniswap'] as const;
+
+/**
+ * Get a specific DEX adapter by name
+ */
+export function getDexAdapter(name: string): DexAdapter | null {
+  return adapters[name.toLowerCase()] || null;
+}
+
+/**
+ * Get all available DEX adapters
+ */
+export function getAllAdapters(): DexAdapter[] {
+  return Object.values(adapters);
+}
+
+/**
+ * Get adapters that support a specific chain
+ */
+export function getAdaptersForChain(chainId: number): DexAdapter[] {
+  return Object.values(adapters).filter(a => a.supportsChain(chainId));
+}
+
+/**
+ * Detect the best DEX and pool for a token
+ * Returns the first DEX that has liquidity for this token
+ */
+export async function detectBestDex(
+  token: string,
+  provider: ethers.Provider,
+  chainId: number
+): Promise<{ adapter: DexAdapter; pool: PoolInfo } | null> {
+  const supportedAdapters = getAdaptersForChain(chainId);
+
+  // Check in priority order
+  for (const dexName of DEX_PRIORITY) {
+    const adapter = adapters[dexName];
+    if (!adapter || !adapter.supportsChain(chainId)) continue;
+
+    const pool = await adapter.detectPool(token, provider);
+    if (pool) {
+      return { adapter, pool };
+    }
+  }
+
+  // Check any remaining adapters not in priority list
+  for (const adapter of supportedAdapters) {
+    if (DEX_PRIORITY.includes(adapter.name as typeof DEX_PRIORITY[number])) continue;
+
+    const pool = await adapter.detectPool(token, provider);
+    if (pool) {
+      return { adapter, pool };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * List available DEX names
+ */
+export function listDexes(): string[] {
+  return Object.keys(adapters);
+}

package/server/lib/dex/relay.ts

@@ -0,0 +1,235 @@
+import { ethers } from 'ethers';
+import { DexAdapter, PoolInfo, SwapParams, SwapTxData } from './types';
+import { getDefaultSync } from '../defaults';
+
+const RELAY_API = 'https://api.relay.link';
+
+// Native ETH address used by Relay
+const NATIVE_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+// App fee: 1% (100 bps). Relay keeps 25%, we keep 75%.
+const APP_FEE_BPS = '100';
+
+// Supported EVM chain IDs
+const SUPPORTED_CHAINS = new Set([
+  1,      // Ethereum
+  10,     // Optimism
+  137,    // Polygon
+  8453,   // Base
+  42161,  // Arbitrum
+  324,    // zkSync Era
+  43114,  // Avalanche
+  56,     // BNB Chain
+  250,    // Fantom
+  59144,  // Linea
+  534352, // Scroll
+  7777777, // Zora
+]);
+
+// Relay quote request
+interface RelayQuoteRequest {
+  user: string;
+  originChainId: number;
+  destinationChainId: number;
+  originCurrency: string;
+  destinationCurrency: string;
+  amount: string;
+  tradeType: 'EXACT_INPUT';
+  slippageTolerance?: string;
+  source?: string;
+  appFees?: { recipient: string; fee: string }[];
+}
+
+// Relay quote response types
+interface RelayTxData {
+  from: string;
+  to: string;
+  data: string;
+  value: string;
+  chainId: number;
+}
+
+interface RelayStepItem {
+  status: string;
+  data: RelayTxData;
+}
+
+interface RelayStep {
+  id: string;
+  kind: string;
+  items: RelayStepItem[];
+}
+
+interface RelayQuoteResponse {
+  steps: RelayStep[];
+}
+
+// Relay price response types
+export interface RelayPriceResponse {
+  fees: {
+    gas: { amount: string; amountUsd: string; currency: { symbol: string } };
+    relayer?: { amount: string; amountUsd: string };
+    app?: { amount: string; amountUsd: string };
+  };
+  details: {
+    sender: { amount: string; amountFormatted: string; amountUsd: string; currency: { symbol: string; decimals: number; address: string } };
+    recipient: { amount: string; amountFormatted: string; amountUsd: string; currency: { symbol: string; decimals: number; address: string } };
+    rate: string;
+    slippageTolerance: { origin: { percent: string } };
+  };
+}
+
+/**
+ * Get a lightweight price/quote from Relay.
+ * Uses /price endpoint (no calldata, lighter than /quote/v2).
+ * Returns amounts, fees, exchange rate, and impact.
+ */
+export async function getRelayPrice(params: {
+  user: string;
+  originChainId: number;
+  destinationChainId?: number;
+  originCurrency: string;
+  destinationCurrency: string;
+  amount: string;
+  slippageBps?: number;
+}): Promise<RelayPriceResponse> {
+  const body: RelayQuoteRequest = {
+    user: params.user,
+    originChainId: params.originChainId,
+    destinationChainId: params.destinationChainId ?? params.originChainId,
+    originCurrency: params.originCurrency,
+    destinationCurrency: params.destinationCurrency,
+    amount: params.amount,
+    tradeType: 'EXACT_INPUT',
+    source: 'aurawallet',
+    appFees: [{ recipient: getDefaultSync('protocol.fee_address', '0xa931533E0E0cCE34fc0FafB25ea2046d391eCAA5'), fee: APP_FEE_BPS }],
+  };
+
+  if (params.slippageBps !== undefined) {
+    body.slippageTolerance = params.slippageBps.toString();
+  }
+
+  const response = await fetch(`${RELAY_API}/price`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Relay price failed: ${response.status} ${text}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get a swap quote from Relay.
+ * Returns the raw transaction data for the first incomplete transaction step.
+ */
+async function getRelayQuote(params: {
+  user: string;
+  originChainId: number;
+  destinationChainId?: number;
+  originCurrency: string;
+  destinationCurrency: string;
+  amount: string;
+  slippageBps?: number;
+}): Promise<RelayTxData> {
+  const body: RelayQuoteRequest = {
+    user: params.user,
+    originChainId: params.originChainId,
+    destinationChainId: params.destinationChainId ?? params.originChainId,
+    originCurrency: params.originCurrency,
+    destinationCurrency: params.destinationCurrency,
+    amount: params.amount,
+    tradeType: 'EXACT_INPUT',
+    source: 'aurawallet',
+    appFees: [{ recipient: getDefaultSync('protocol.fee_address', '0xa931533E0E0cCE34fc0FafB25ea2046d391eCAA5'), fee: APP_FEE_BPS }],
+  };
+
+  if (params.slippageBps !== undefined) {
+    body.slippageTolerance = params.slippageBps.toString();
+  }
+
+  const response = await fetch(`${RELAY_API}/quote/v2`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Relay quote failed: ${response.status} ${text}`);
+  }
+
+  const data: RelayQuoteResponse = await response.json();
+
+  // Find the first incomplete transaction step
+  for (const step of data.steps) {
+    if (step.kind !== 'transaction') continue;
+    for (const item of step.items) {
+      if (item.status === 'incomplete' && item.data) {
+        return item.data;
+      }
+    }
+  }
+
+  throw new Error('Relay quote returned no executable transaction steps');
+}
+
+/**
+ * Relay adapter for same-chain swaps via Relay aggregator API.
+ * Supports all major EVM chains. No API key required.
+ */
+export const relayAdapter: DexAdapter = {
+  name: 'relay',
+
+  supportsChain(chainId: number): boolean {
+    return SUPPORTED_CHAINS.has(chainId);
+  },
+
+  async detectPool(
+    _token: string,
+    _provider: ethers.Provider
+  ): Promise<PoolInfo | null> {
+    // Relay is an aggregator -- it finds routes internally.
+    // Return a synthetic PoolInfo to indicate Relay can handle this token.
+    return { version: 'relay', poolAddress: 'relay' };
+  },
+
+  async buildSwapTx(params: SwapParams): Promise<SwapTxData> {
+    const { token, direction, amount, from, chainId, destinationChainId } = params;
+
+    // Determine origin/destination currencies
+    // buy: ETH -> token, sell: token -> ETH
+    const originCurrency = direction === 'buy' ? NATIVE_ADDRESS : token;
+    const destinationCurrency = direction === 'buy' ? token : NATIVE_ADDRESS;
+
+    // Amount is already in wei (EVM) or lamports (Solana)
+    const amountWei = amount;
+
+    const txData = await getRelayQuote({
+      user: from,
+      originChainId: chainId,
+      destinationChainId,
+      originCurrency,
+      destinationCurrency,
+      amount: amountWei,
+    });
+
+    return {
+      to: txData.to,
+      data: txData.data,
+      value: txData.value || '0',
+    };
+  },
+
+  getRouterAddress(): string {
+    // Relay uses different contract addresses per chain/tx.
+    // Return a descriptive placeholder; the actual `to` comes from buildSwapTx.
+    return 'relay';
+  },
+};
+
+export default relayAdapter;