DOCSEARCHbyAlgolia
Submit Docs

Blink Mobile

repository·main·Indexed 41 days ago

https://github.com/blinkbitcoin/blink-mobile

A React Native application compatible with the Galoy backend, designed for customizable mobile Bitcoin and Lightning services. The project includes a provider-pattern architecture for managing global state, wallet providers (custodial and self-custodial), and a GraphQL client via GaloyClient.

Tokens
17.6K
Snippets
51
Records
88
Agent score
49%

What's inside Blink Mobile

  1. Overview of the blink-mobile technology stack

    main

    The blink-mobile (GaloyApp) project is a cross-platform mobile application built with React Native and TypeScript. It utilizes a robust frontend stack including React Navigation for routing, Apollo Client for GraphQL data management, and Firebase for core services like analytics, crash reporting, and push notifications.

    Bitcoin and Lightning capabilities are integrated via specialized libraries like @blinkbitcoin/blink-client, bitcoinjs-lib, and lnurl-pay. The project supports 28 languages using typesafe-i18n.

  2. Overview of blink-mobile (GaloyApp) GraphQL API

    main

    The blink-mobile application communicates with the Blink backend using GraphQL. All TypeScript types and React hooks for data fetching and modification are auto-generated and located in app/graphql/generated.ts.

    The API surface includes:

    • 192 Query hooks for fetching data.
    • 50 Mutation hooks for modifying data.
    • 1 Subscription hook for real-time updates.

    Developers should use the generated hooks rather than writing raw GraphQL queries to ensure type safety and consistency with the auto-generated schema.

  3. Understand the blink-mobile project structure

    main

    The blink-mobile (GaloyApp) project is a React Native application organized into several key layers:

    • app/: The main application source code.
      • app/graphql/: The API layer containing Apollo Client setup and auto-generated types/hooks.
      • app/screens/: User interface organized by feature (e.g., authentication, bitcoin operations, social).
      • app/components/: Reusable UI elements (e.g., inputs, modals, navigation).
      • app/i18n/: Internationalization support for 28 languages.
      • app/navigation/: React Navigation configuration and route definitions.
      • app/hooks/: Custom React hooks for app logic.
    • ios/ & android/: Native platform-specific code and build configurations.
    • __tests__/: Unit tests using Jest.
    • e2e/: End-to-end tests using Detox and WebDriverIO/Appium.

  5. How the Merchant Map (BTC Map) works

    main

    The map feature uses community-maintained data from BTC Map rather than the Galoy backend.

    Data Handling

    • Cold Start: Loads a single gzipped ~550 KB CDN snapshot from cdn.static.btcmap.org.
    • Updates: Performs an updated_since delta check against api.btcmap.org/v4 (at most hourly) on app focus or resume.
    • Offline Cache: Stores ~2.4 MB of places in chunked AsyncStorage (5k rows per chunk).
    • Search & Filtering: Search is performed via a places/search call on a ~1.1 km grid. Category filtering is done on-device using icon names defined in btcmap/categories.ts.
    • Clustering: Uses supercluster indexed over a box 3× the viewport to maintain performance.

    Adding a Place

    Users can propose new places if they meet these criteria:

    1. Account Type: Must be a level-two custodial account (useIsAuthed() returns isAtLeastLevelTwo and activeAccount?.type is not SelfCustodial).
    2. Feature Flag: The btcMapPlacesEnabled Remote Config kill switch must be ON.
    3. Submission: Uses btcmap/use-place-submission.ts to fire the btcMapPlaceSubmit mutation. A client-minted submissionId acts as an idempotency key to prevent duplicate submissions during retries.

  6. Icon usage and limitations

    main

    The project uses react-native-vector-icons. The react-native-elements component library is also used, which relies on this icon set.

    Note: Custom icons from the Ionicons set have been added to existing components. If you import a new component from react-native-elements that uses an icon set other than Ionicons, it may fail to render on the screen.

  7. Understand the Data Flow and GraphQL hooks

    main

    The application uses GraphQL for all data operations, organized into three categories of hooks:

    • Queries: Used for data fetching. Examples include useWalletOverviewScreenQuery (dashboard), useRealtimePriceQuery (Bitcoin price), useTransactionsQuery (history), useContactsQuery (contacts), and useAnalyticsQuery (analytics).
    • Mutations: Used for data modifications. Examples include useIntraLedgerPaymentSendMutation (internal transfers), useLnInvoicePaymentSendMutation (Lightning), useOnChainPaymentSendMutation (on-chain), useUserUpdateUsernameMutation (profile), and useDeviceNotificationTokenCreateMutation (push notifications).
    • Subscriptions: Used for real-time updates, specifically for price updates via WebSocket.

  8. Navigation Structure and Flow

    main

    The app uses a RootStack (Stack Navigator) to manage the user journey. The navigation is divided into several key segments:

    • Unauthenticated/Initial Flow: getStarted $\rightarrow$ authenticationCheck $\rightarrow$ authentication (Login/PIN) $\rightarrow$ login $\rightarrow$ pin.
    • Primary App (Tab Navigator): The main authenticated experience, containing:
      • Home: Dashboard with balances.
      • People: Contact management (includes peopleHome, contactDetail, allContacts, and circlesDashboard).
      • Map: Merchant map.
      • Earn: Educational content.
    • Feature Flows:
      • sendBitcoin: A 5-screen flow.
      • receiveBitcoin: Receiving flow.
      • conversion: A 3-screen currency conversion flow.
      • onboarding: A Stack Navigator for new users (welcomeLevel1, emailBenefits, lightningBenefits, supportScreen).
    • Utility/Settings: scanningQRCode, settings, transaction*, and various authentication method screens (phone*, email*, totp*).

  9. Apollo Client Configuration details

    main

    The Apollo Client in app/graphql/client.tsx is configured with the following features:

    1. Persisted Queries: Uses SHA-256 hashed queries to optimize bandwidth.
    2. Cache Persistence: The Apollo cache is persisted using AsyncStorage.
    3. Retry Logic: Automatically retries failed requests with backoff, but excludes payment operations to prevent accidental double-spending.
    4. WebSocket: Supports real-time subscriptions (e.g., for price updates).
    5. App Check: Includes a Firebase device attestation header in requests.
    6. Auth: Automatically includes the Bearer token in the Authorization header.

  10. Understand the Provider Tree in app/app.tsx

    main

    The application uses a deeply nested provider tree to manage global concerns. When adding new features or components, you must understand where they sit in this hierarchy to access the correct context or state:

    • GestureHandlerRootView: Root wrapper for gesture handling.
    • PersistentStateProvider: Manages local persistent state.
    • TypesafeI18n: Handles internationalization.
    • GaloyClient: The Apollo GraphQL client instance.
    • GaloyThemeProvider: Provides UI theming.
    • FeatureFlagContextProvider: Manages feature flags.
    • ActionsProvider: Manages application actions.
    • NavigationContainerWrapper: Wraps the navigation logic.
    • ErrorBoundary: Catches component errors.
    • RootSiblingParent: Manages sibling components.
    • NotificationsProvider: Handles notifications.
    • AppStateWrapper: Monitors application state (active/background).
    • PushNotificationComponent: Handles incoming push notifications.
    • RootStack: The main navigation stack.
    • NetworkErrorComponent: Displays network error states.
    • ActionModals: Manages modal overlays.

  11. Understand Wallet and Transaction Types

    main

    Wallet Types

    • BTC Wallet: Handles Bitcoin (sats) for Lightning and on-chain transactions.
    • USD Wallet: Handles Stablesats (USD) for dollar-denominated balances.

    Transaction Types

    • Lightning Network: Includes invoice creation/payment, LNURL support (pay, withdraw, auth), and no-amount invoices.
    • On-Chain Bitcoin: Includes address generation, fee estimation, and transaction broadcasting.
    • Internal (Intra-Ledger): Includes user-to-user transfers and wallet-to-wallet conversion.

  12. Understand BTC Map merchant data integration

    main

    The app integrates with BTC Map to display bitcoin-accepting merchants.

    Key behaviors:

    • Data Source: The app reads from a CDN snapshot and performs incremental updated_since syncs (at most hourly).
    • Storage: The place list (~29k rows) is stored in AsyncStorage in 5k-place chunks to avoid Android's 2MB CursorWindow limit.
    • Read/Write: The app is primarily read-only for existing data. It only sends proposals for missing places via the btcMapPlaceSubmit mutation.
    • Search: Uses accent-folded name matching and nearest-first ranking.

    Core Files in app/btcmap/:

    • api.ts: Handles CDN snapshots and incremental sync.
    • storage.ts: Manages chunked AsyncStorage persistence.
    • use-places.ts: Provides a cache-first place list (gated by btcMapPlacesEnabled).
    • submission.ts: Defines the shape and validation for adding new places.
    • use-place-submission.ts: Handles the btcMapPlaceSubmit mutation with retry logic per submissionId.