CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BlueWallet is a Bitcoin & Lightning Network wallet built with React Native and Electrum. Cross-platform mobile app (iOS/Android/macOS via Catalyst).

Common Commands

# Development
npm start                    # Start Metro bundler
npm run ios                  # Run on iOS
npm run android              # Run on Android

# Testing
npm test                     # Full suite (lint + unit + integration)
npm run lint                 # ESLint + TypeScript check + unused loc keys
npm run lint:fix             # Auto-fix linting issues
npm run unit                 # Jest unit tests only

# E2E Testing (Detox)
npm run e2e:debug            # Debug build and test on Android
npm run e2e:release-test     # Release build test

# Clean builds
npm run clean                # Full clean (gradle, cache, node_modules)
npm run clean:ios            # iOS clean (Pods + node_modules)
npm run android:clean        # Android clean

Architecture

Directory Structure:

components/ - React components and Context providers (SettingsProvider, StorageProvider)
class/ - Core business logic including wallet implementations in class/wallets/
blue_modules/ - Utility modules (BlueElectrum, currency, encryption, etc.)
screen/ - Navigation screens organized by feature (wallets, send, receive, settings, lnd)
navigation/ - React Navigation setup with typed param lists
hooks/ - Custom React hooks (useStorage, useSettings, useBiometrics, etc.)
loc/ - Localization files (en.json as source, 55+ languages)
models/ - Type definitions for units, fiat, block explorers
tests/unit/, tests/integration/, tests/e2e/ - Test suites

Wallet System: Multiple wallet implementations in class/wallets/: Legacy, SegWit (P2SH, Bech32), Taproot, HD variants, Lightning (Custodian, Ark), Multisig, Watch-only. Types defined in class/wallets/types.ts.

State Management: React Context providers wrap the app. Custom hooks expose state logic. Realm for database, AsyncStorage for persistence, Keychain for secrets.

Navigation: React Navigation 7.x with native stack. Typed params in navigation/DetailViewStackParamList.ts and other param list files.

Code Conventions

Commit Prefixes: REL, FIX, ADD, REF, TST, OPS, DOC (e.g., "ADD: new feature")

TypeScript: All new files must be TypeScript. Strict mode enabled.

Dependencies: Do not add new dependencies without strong justification. Bonus for removing dependencies.

Patches: Local fixes to node_modules live in patches/ and are applied by patch-package on postinstall. Each patch is documented in patches/README.md (what/why + upstream issue link); update it when adding or removing a patch.

Components: New components go in components/, not legacy BlueComponents.js.

Linting Rules:

No inline styles in React Native (react-native/no-inline-styles: error)
No unused styles (react-native/no-unused-styles: error)
Prettier: single quotes, 140 char width, trailing commas

Localization: Keys in loc/en.json. Run find-unused-loc.js to detect unused keys. See loc/vocabulary.md for the canonical glossary of Bitcoin/Lightning terms and their per-language renderings — use it as ground truth when translating or generating translations with LLMs.

Testing

Unit tests in tests/unit/ use Jest with assert. Test setup mocks React Native modules (Clipboard, Push Notifications, Keychain, etc.). Integration tests require environment variables for test mnemonics (HD_MNEMONIC, HD_MNEMONIC_BIP84, etc.).

3.6 KiB Raw Permalink Blame History