How ethereum/kohaku-extension works
Project type and purpose
• This is a full-stack, multi-platform Web3 wallet with these outputs:
• Browser extensions (Chrome/WebKit, Gecko, Safari)
• Web applications (Ambire Wallet web, Benzin explorer, Legends rewards)
• Mobile apps (Android, iOS via React Native bare + Expo modules)
• It integrates on-chain wallet functionality (EIP-1193 provider), hardware wallets (Ledger, Trezor, Lattice), an ERC-4337 transaction explorer (Benzin), and a gamified rewards portal (Legends).
High-level components
a. UI layers (React/React Native/React Native Web)
– Mobile app (Android/iOS, Expo + native modules)
– Web wallet UI (React Native Web / webpack)
– Browser extension popup UI (React Native Web)
– Benzin explorer (Standalone React web)
– Legends rewards portal (Standalone React web)
b. Shared core
– ambire-common submodule: shared React components, hooks, contexts, services, utilities, theming
c. State & controller layer
– Web extension controllers (background script, message buses, provider)
– React contexts & hooks (account, networks, theme, toast, storage, etc.)
d. Native modules & hardware wallets
– Android native host, JSI / TurboModules, Flipper integration
– iOS AppDelegate, native modules
– Hardware-wallet libs and controllers (Ledger/Trezor/Lattice)
e. External interactions
– Ethereum JSON-RPC nodes / relayer services
– Ethers.js / custom fetch service
– Hardware-wallet connectors via USB/BLE
– Browser storage (IndexedDB, chrome.storage)
– Analytics / CrashReporting
f. Build & deployment
– Metro bundler (mobile)
– Webpack (web, extensions)
– Buck / Gradle (Android)
– Xcode projects (iOS / Safari extension)
– CI workflows (GitHub Actions)
Relationships & data flows
• UI triggers React Context → dispatches actions to controller hooks → controller calls services (fetch, hardware) → updates state → UI re-renders
• Browser popup ↔ background script via port messages (messenger modules) to handle signing, network requests, storage
• In-page injection: content script injects provider into DApp, calls background via RPC flow
• Mobile UI ↔ native modules via TurboModule / JSI layer (new architecture registry in android/app/src/main/jni)
• Shared core modules imported by all UIs for consistency
Architectural patterns & principles
– Modular layers: UI / contexts/hooks / services / native connectors
– Dependency injection via React Contexts
– Message-bus pattern for extension background ↔ popup ↔ in-page
– Shared monorepo submodule (ambire-common) for cross-platform code reuse
– Separation between “presentation” (React components) and “business logic” (services, controllers)
– Build-time configuration via env files, Metro/webpack configs
• Full-stack wallet (browser + web):
– Show shared core imported by both UI and background
– Label hardware wallet connectors as external services
• Mobile app:
– Show Expo modules as plug-ins
– Show external RPC calls to Ethereum node
• Benzin & Legends: