How leather-io/extension works
Project type and purpose
• Leather is a browser extension (Web Extension) implementing a crypto wallet for Bitcoin, Bitcoin L2s, and the Stacks blockchain. It offers a popup UI, in-page injection, background processing, messaging APIs (RPC), and integrates with hardware wallets (Ledger).
File structure
• Top-level “src” children define extension contexts:
• src/app – React/TypeScript UI for popup/extension pages (popup, dev-tool, onboarding, send/receive, swap, settings, etc.). Uses Redux for state, React Query (via src/query) for external data.
• src/background – background service worker handling long-running tasks: message routing, RPC method handlers, monitors (address updates, websockets).
• src/content-scripts – injected script for page context to hook dapps.
• src/inpage – small script injected into the page to define the window?.leather API, forwarding calls to the background.
• src/shared – code shared across contexts (RPC schemas, crypto, storage helpers, message types, utilities).
• Other key folders:
• public – static assets and HTML entrypoints for each extension page.
• test-app – standalone React app to test extension RPC APIs.
• tests – Playwright integration tests for extension UI + test-app, plus unit tests (Vitest).
• scripts, config, webpack, package.json, CI workflows for building, linting, testing, publishing.
README for additional insights
• Confirms it’s a Web Extension (MV3) targeting Chrome/Firefox.
• Describes contexts cannot run standalone – must be loaded as an extension.
• Mentions test-app for quick API tests.
• Outlines development commands, build targets, and testing.
Main components
a. Extension UI (src/app)
• Popup & React pages
• Redux store
• Query clients (REST/fetch to external Bitcoin/Stacks/market-data/compliance APIs)
b. Background Service Worker (src/background)
• RPC message handler
• Internal message broker
• Address monitors (mempool WebSocket)
• Chrome.storage persistence
c. Content Script (src/content-scripts)
• Injected into dapp pages to listen for hook calls
d. Inpage Script (src/inpage)
• Injected before page loads, exposes window API to dapps, forwards to background
e. Shared Modules (src/shared)
• RPC schemas & types
• Crypto & encryption utilities
• Message-type definitions
• Storage & persistence logic
f. External Services
• Bitcoin node or explorer APIs (UTXOs, broadcast, fee estimates)
• Stacks node or explorer APIs (transactions, contracts, mempool)
• Market data vendors (Binance, Coingecko, Coincap)
• Compliance checker, remote configs, sponsored transactions API, bitflow SDK
g. Hardware Wallet Integration
• Ledger flows (USB/HID) via background and UI
Relationships and interactions
• Dapp → (inpage) → window.leather API → chrome.runtime.sendMessage → background → UI/data/store or RPC → background calls external API → background returns result → UI or inpage
• UI ↔ background via chrome.runtime messaging for state changes, transaction signing, key requests.
• Background monitors chain updates (WebSocket), updates Redux store via messaging to UI or triggers notifications.
• Content script detects dapp contexts, optionally shows UI cues or intercepts calls.
• Test-app communicates via same RPC channels to background service.
Architectural patterns and design principles
• Single-page React apps for each extension page (popup, dev-tool, debug).
• Unidirectional data flow: UI dispatches actions → Redux → side effects via thunks/hooks → background/external.
• Messaging bus pattern for cross-context communication.
• Context isolation: UI vs. background vs. content vs. inpage.
• Modular “shared” layer to prevent duplication and maintain type safety across bundles.
Detail
• Every context as a separate “service” node
• Internal RPC bus and shared schemas
• Interactions with both Bitcoin and Stacks networks, plus ancillary APIs