Architecture
System Overview
Section titled “System Overview”┌─────────────────────────────────────────────────────┐│ Host Application ││ ││ ┌────────────────────────────────────────────────┐ ││ │ TokenFlight SDK (Web Component) │ ││ │ │ ││ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ ││ │ │ Swap UI │ │Receive UI│ │ Token Selector│ │ ││ │ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │ ││ │ │ │ │ │ ││ │ ┌────▼──────────────▼───────────────▼───────┐ │ ││ │ │ State Machine │ │ ││ │ │ idle → quoting → quoted → building → │ │ ││ │ │ awaiting-wallet → submitting → tracking │ │ ││ │ └────────────────┬──────────────────────────┘ │ ││ │ │ │ ││ │ ┌────────────────▼───────────────────────────┐ │ ││ │ │ TanStack Solid Query │ │ ││ │ │ (caching, deduplication, polling) │ │ ││ │ └────────────────┬───────────────────────────┘ │ ││ └───────────────────┼─────────────────────────────┘ ││ │ │└──────────────────────┼─────────────────────────────────┘ │ HTTPS ┌────────────▼────────────┐ │ Hyperstream API │ │ (your API endpoint) │ │ │ │ POST /v1/quotes │ │ POST /v1/deposit/build │ │ PUT /v1/deposit/submit│ │ GET /v1/orders/:addr │ │ GET /v1/tokens/search │ │ GET /v1/chains │ └────────────┬────────────┘ │ ┌────────────▼────────────┐ │ Routing Layer │ │ Intent Settlement │ │ │ │ Route Providers: │ │ • Multiple bridge │ │ protocols │ └────────────┬────────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │┌────▼────┐ ┌────▼────┐ ┌─────▼────┐│ Source │ │ Bridge │ │ Dest ││ Chain │ │ Network │ │ Chain ││(Ethereum)│ │ │ │ (Base) │└─────────┘ └─────────┘ └──────────┘Data Flow
Section titled “Data Flow”1. User Interaction → Quote
Section titled “1. User Interaction → Quote”User selects tokens and amount → SDK sends POST /v1/quotes to the API → API returns route options from available providers → SDK displays routes in the UI → onQuoteReceived callback fires2. Route Selection → Build
Section titled “2. Route Selection → Build”User selects a route → SDK sends POST /v1/deposit/build → API returns wallet actions (approve + transfer) → SDK prepares transaction for wallet signing3. Wallet Signing → Submit
Section titled “3. Wallet Signing → Submit”SDK passes transaction to Wallet Adapter → Adapter calls wallet (MetaMask, Phantom, etc.) → User signs in wallet popup → SDK receives txHash → SDK sends PUT /v1/deposit/submit with txHash → API creates order and begins tracking4. Order Tracking → Completion
Section titled “4. Order Tracking → Completion”SDK polls GET /v1/orders/:address → Progressive polling: 1s → 2s → 3s → 5s → 10s intervals → API returns order status updates → SDK updates UI (tracking progress bar) → Order reaches "filled" status → onSwapSuccess callback firesWallet Adapter Layer
Section titled “Wallet Adapter Layer”┌──────────────────────────────────────────────┐│ IWalletAdapter ││ ││ connect() getAddress() executeWalletAction()││ disconnect() isConnected() on() / off() │└──────────┬──────────┬──────────┬─────────────┘ │ │ │ ┌──────▼──┐ ┌────▼─────┐ ┌─▼──────────┐ │ AppKit │ │ wagmi │ │ ethers │ │ Adapter │ │ Adapter │ │ Adapter │ │ │ │ │ │ │ │EVM+Sol │ │ EVM only │ │ EVM only │ └────┬────┘ └────┬─────┘ └─────┬──────┘ │ │ │ ┌────▼────┐ ┌────▼─────┐ ┌────▼──────┐ │Reown │ │ wagmi │ │window. │ │AppKit │ │ Core │ │ethereum │ └─────────┘ └──────────┘ └───────────┘Shadow DOM Isolation
Section titled “Shadow DOM Isolation”Each widget instance creates its own Shadow DOM:
<div id="swap-widget"> ← Host element (your DOM) └── <div> ← Shadow host (created by SDK) └── #shadow-root (open) ← Shadow boundary ├── <style> ← Scoped CSS (theme + base styles) └── <div> ← Solid.js mount point └── ... ← Widget UI componentsStyles inside the Shadow DOM don’t leak out, and page styles don’t leak in. The supported customization paths are CSS custom properties (--tf-*) and the setCustomColors() runtime method.
Caching Architecture
Section titled “Caching Architecture”┌──────────────────────────────────┐│ TanStack Solid Query ││ (shared QueryClient) ││ ││ Cached: ││ • Chain list (GET /v1/chains) ││ • Token metadata ││ • Wallet balances ││ • Quote responses ││ ││ Shared across widget instances ││ Cleared on destroy() │└──────────────────────────────────┘Multiple widget instances on the same page share the same QueryClient, deduplicating API requests automatically.