How koniverse/subwallet-mobile works
Project Type and Purpose
• This is a cross-platform mobile application (iOS & Android) built with React Native that surfaces the functionality of the SubWallet browser extension in a mobile context.
• To overcome React Native’s lack of WebAssembly support and to share the same Polkadot crypto libraries with the extension, most blockchain logic runs inside a hidden WebView (“WebRunner”), and React Native communicates with it via message passing.
High-Level File Structure Overview
• android/ / ios/ – Native platform projects (build.gradle, Xcode).
• html/ – Prebuilt WebRunner bundles (WASM + JS) loaded in WebView.
• src/ – React Native code: screens, components, hooks, providers, stores, utils.
• scripts/ – Build & CI/CD scripts (build-android, build-ios, upload).
• stores/ & reducers/ – State management layer.
• providers/ – React Context providers wrapping UI and WebRunner.
• messaging/ – Message-passing definitions between React Native host and WebRunner guest.
• nativeModules/ – Custom native bridges (e.g., RCTMinimizer).
Architecture Overview from README
• React Native hosts a hidden WebView (“app runner” / WebRunner) that loads Polkadot/WebRunner assets.
• UI layer dispatches commands and listens for events over a bidirectional messaging channel to perform crypto operations, network calls, transaction signing, etc.
• This maintains one codebase for shared logic (extension vs mobile).
Key Components
a. UI Layer (React Native App):
• Screens & Components (src/screens/, src/components/)
• Navigation (src/AppNavigator.tsx)
• Context Providers (AppModalContext, TransactionContext, WebRunnerProvider)
• State Management (stores/, reducers/)
b. WebRunner (Hidden WebView):
• Loads pre-compiled HTML/JS/WASM bundles from html/Web.bundle
• Holds Polkadot JS and WASM modules (@polkadot packages)
• Exposes an RPC-style message API to React Native
c. Native Modules & Services:
• RCTMinimizer, StaticServer (custom native bridges)
• Secure storage (AsyncStorage or Keychain)
• Camera / QR scanner modules
d. External Services:
• Dotsama node RPC endpoints (Polkadot/Substrate networks)
• 3rd-party buy providers (Banxa, Coinbase, Transak)
Interactions & Data Flow
1. User Action → UI
• User taps UI → React Native event handler → dispatches action (via context or store).
2. UI → WebRunner
• Host posts a message to WebView containing the JSON-RPC request (e.g., fetch balance, sign transaction).
3. WebRunner Processing
• WebRunner JS/WASM executes Polkadot logic, fetches data from chain RPC, signs payload.
4. WebRunner → UI
• WebRunner posts a response message back to React Native with the result or error.
5. UI Updates State & Renders
• Message handler in providers updates stores/reducers, React re-renders components.
6. Native Services
• For camera/QR or local file storage, React Native calls custom native modules directly.
Architectural Patterns & Principles
• Flux-style state management: centralized stores + reducers, accessed via React Context.
• Message-passing boundary: explicit separation of crypto logic into WebView.
• Component hierarchy: Presentation (screens/components) ←→ Context/Providers ←→ Stores ←→ WebRunner/Native Modules.
• Separation of concerns: UI, business logic (hooks/services), state management, external communication.
Technologies & Frameworks
• React Native (JS/TS)
• React Navigation
• React Context & Hooks
• Custom state layer (stores + reducers)
• WebRunner (hidden WebView + WASM bundles)
• Native Modules (Java/Objective-C bridges)
• Yarn, Metro, Babel, CMake (for WASM build)