dgb-wallet/packages/mobile/README.md

# @dgb-wallet/mobile

DigiByte.X Wallet — React Native (Expo) app. Ports the same recovery-first UI as `@dgb-wallet/web-ui` using React Native primitives (`View`/`Text`/`Pressable` instead of `div`/`button`).

Shares the same crypto core via the monorepo workspace — no re-implementation of address derivation or PSBT signing.

## Prerequisites

- Node 20+ (already installed)
- **Android Studio** with:
  - Android SDK (API 34+ recommended)
  - An Android emulator device (e.g., Pixel 6 running Android 14)
  - `ANDROID_HOME` env var set (usually `%LOCALAPPDATA%\Android\Sdk`)
- Java JDK 17 (Android Studio bundles one)

## First run

```powershell
cd "D:\Dev\SilentCode\Digibyte"

# 1. Install (installs Expo + RN + polyfills in packages/mobile)
npm install

# 2. Start Android emulator from Android Studio (Device Manager > play)

# 3. Boot the app
npm run android -w @dgb-wallet/mobile
```

First launch takes ~5 min: Metro bundles ~2000 modules, Expo compiles the dev client, APK installs on emulator. Subsequent launches are seconds.

## What's in the box (v0.0.2)

- **Three tabs**, bottom navigation via `@react-navigation/bottom-tabs`:
  - **Import** — paste seed, live BIP39 validation, derive all 5 descriptor paths, show first 5 addresses per path.
  - **Balance** — derive BIP84 xpub, POST to the wallet daemon at `http://10.0.2.2:5174/balance` (Android emulator alias for host localhost), show totalSats + UTXO list + filter/block/timing stats.
  - **Send** — build & sign a BIP84 P2WPKH tx, broadcast via daemon; toggle between Dandelion++ (default) and direct fan-out.

Balance and Send both talk to `@dgb-wallet/p2p`'s daemon over HTTP — run it in a separate terminal before opening those tabs:

```powershell
npm run daemon -w @dgb-wallet/p2p
```

For an iOS simulator, edit `src/rpc-native.ts` and switch `DAEMON_URL` to `http://127.0.0.1:5174` — the `10.0.2.2` alias is Android-emulator-only.

## Verified state

- `tsc --noEmit` passes cleanly on `packages/mobile` (once `npm install` has run at the repo root — the `@react-navigation/*`, `react-native-screens`, and `react-native-safe-area-context` deps hoist into `packages/mobile/node_modules`).
- The daemon HTTP contract that `src/rpc-native.ts` calls (`POST /balance` with `{xpub, purpose, account, gapLimit}`, `POST /broadcast` with `{hex}`) is verified end-to-end via the `@dgb-wallet/web-ui` package, which hits the same daemon endpoints with the same crypto core. The mobile screens are a straight React Native port of those flows.
- **Emulator boot is blocked on Intel VT-x being disabled in BIOS** on the current dev machine — see next section.

## Requires: hardware virtualization

Android x86 emulators need a hypervisor. On Windows that means either **AEHD** (Android Emulator Hypervisor Driver, HAXM's successor) or **WHPX** (Windows Hypervisor Platform). Both silently fall over if Intel VT-x / AMD-V is off in firmware.

**Check first:**

```powershell
Get-CimInstance Win32_Processor | Select-Object Name, VirtualizationFirmwareEnabled, SecondLevelAddressTranslationExtensions
```

If `VirtualizationFirmwareEnabled` is `False`, no software fix will work — reboot into BIOS/UEFI, find "Intel Virtualization Technology" / "VT-x" (typically under Advanced → CPU Configuration or Security), enable it, save, boot back to Windows.

**Then install AEHD (already downloaded with the SDK):**

```powershell
cd "$env:LOCALAPPDATA\Android\Sdk\extras\google\Android_Emulator_Hypervisor_Driver"
.\silent_install.bat        # runs elevated via UAC
sc query aehd               # STATE should say RUNNING
```

If AEHD's service is already registered but stops with `sc start aehd` returning `error 4294967201` (`ERROR_NOT_SUPPORTED`), that's the VT-x-off symptom — driver installed fine, but the CPU refuses to enter root mode. Fix in BIOS.

**Then boot the emulator normally:**

```powershell
& "$env:LOCALAPPDATA\Android\Sdk\emulator\emulator.exe" -avd Pixel_3a_API_30_x86
```

## Crypto polyfills — the non-obvious bit

React Native has no `crypto` or `Buffer` globals like Node/browser. This app plugs those gaps via:

- `react-native-quick-crypto` — implements Node's `crypto` API using native code (fast, correct)
- `buffer` npm package — Buffer polyfill
- `react-native-get-random-values` — polyfills `crypto.getRandomValues` used by `bip39.generateMnemonic`

All wired up in `index.js` (loads BEFORE any app code) and `metro.config.js` (aliases so bitcoinjs-lib et al find them).

## Layout

```
packages/mobile/
├── app.json                  Expo config (name, package, orientation)
├── babel.config.js           babel-preset-expo
├── index.js                  Entry — installs crypto polyfill THEN app
├── metro.config.js           Monorepo + Node-shim resolution
├── src/
│   ├── App.tsx               Root (header + bottom-tab navigation)
│   ├── ImportScreen.tsx      Recovery UX in RN primitives
│   ├── BalanceScreen.tsx     P2P daemon /balance client
│   ├── SendScreen.tsx        P2P build+sign+broadcast (Dandelion default)
│   ├── derive.ts             Same as web-ui/src/derive.ts (kept parallel for now)
│   ├── rpc-native.ts         Fetch helpers pointed at 10.0.2.2:5174
│   └── styles.ts             Shared StyleSheet across screens
└── tsconfig.json             extends expo's base config
```

## Known limitations at this scaffold stage

- **No on-device run yet.** Balance/Send tabs are wired against the daemon HTTP contract that the browser web-ui exercises today, but they haven't run on an actual Android surface — that's blocked by VT-x on this workstation (see previous section). A physical Android phone with USB debugging would unblock the same verification without touching BIOS.
- No secure keystore integration yet — imported seeds live in component state only. Production will use `expo-secure-store` (Android Keystore / iOS Keychain).
- Send tab uses BIP84 only, single account, flat 5000-sat fee (same demo scope as web-ui).