# Nighthawk Wallet (DarkFi Edition) — Android

Nighthawk Android — DarkFi chat connected on testnet

Privacy-preserving wallet (work-in-progress) by [Nighthawk Apps](https://nighthawkapps.com). This tree ships as a **new Android application id** on the DarkFi network (DRK). The app integrates a native DarkFi wallet API via **UniFFI** (`rust/darkfi-mobile-ffi` → generated Kotlin + `DarkfiMobileFfiApi`) for chain sync, broadcast, and chat. **3.00.010** (`WALLET_VERSION_CODE=30001810`) toolchain: Gradle **9.7.1**, AGP **9.3.1**, Kotlin **2.2.10**, Compose UI **1.12.1**, Material3 **1.4.0**, Material icons **1.7.8**, AndroidX Lifecycle **2.11.0**, Navigation Compose **2.9.8**, JNA **5.19.1**, UniFFI **0.32**, NDK **26.1.10909125**, minSdk **27**, compile/target SDK **37**. Native sent-tx session cache is FIFO-capped (10,000). Reorg “transactions affected” is counted from `drk.get_txs_history()` (`block_height > rewind`), not from CLI log lines. ## Contents - [Download](#download) - [Quick start](#quick-start) - [Prerequisites](#prerequisites) - [Build](#build) - [Chat (DarkIRC)](#chat-darkirc--eventgraph) - [Nighthawk Mesh](#nighthawk-mesh-encrypted-eventgraph-hop) - [Architecture](#architecture) - [Privacy & security](#privacy--security) - [Verification](#verification) - [Known issues](#known-issues) - [Contributing & support](#contributing--support) - [Disclaimers](#disclaimers) --- ## Download Store listings are **not finalized** for `com.nighthawkwallet.android`. Placeholder targets until publishing completes: - **F-Droid:** DarkFi **testnet** package `com.nighthawkwallet.android.testnet` / flavor `darkfitestnet` (see [docs/fdroid.md](docs/fdroid.md); listing pending fdroiddata merge). **3.00.010** (`WALLET_VERSION_CODE=30001810`) — Fastlane changelog `fastlane/metadata/android/en-US/changelogs/30001810.txt`, tag `v3.00.010`. Local unsigned APK: `bundle exec fastlane fdroid`. Legacy Zcash: [com.nighthawkapps.wallet.android](https://f-droid.org/packages/com.nighthawkapps.wallet.android/) - **Google Play:** `https://PLACEHOLDER_PLAY_STORE_LISTING_URL` Replace these URLs when production listings exist—do not invent live links prematurely. --- ## Quick start From the repository root (first-time or after vendored DarkFi / native code changes): ```bash # 1) Pin upstream DarkFi ./scripts/vendor-darkfi.sh # 2) Android SDK + NDK export ANDROID_HOME="$HOME/Library/Android/sdk" export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/26.1.10909125" export PATH="$PATH:$ANDROID_HOME/platform-tools" # 3) UniFFI wallet native lib + Kotlin bindings ./scripts/build-darkfi-mobile-ffi-android.sh # Mesh C ABI only (keep committed UniFFI Kotlin): # SKIP_UNIFFI_BINDGEN=1 MOBILE_FFI_ABIS=arm64-v8a ./scripts/build-darkfi-mobile-ffi-android.sh # Emulator-only ABIs (faster): # MOBILE_FFI_ABIS="arm64-v8a x86_64" ./scripts/build-darkfi-mobile-ffi-android.sh # 4) Install ./gradlew :app:installDarkfimainnetDebug # Testnet (side-by-side .testnet package): # ./gradlew :app:installDarkfitestnetDebug # 5) Quick checks ./gradlew :darkfi-android-sdk:testDebugUnitTest ``` **Local lightwalletd:** run sibling [`darkfi-lightwalletd`](../darkfi-lightwalletd) on `127.0.0.1:9067` (cleartext loopback OK without pin). Public servers need TLS + pin — see [Privacy & security](#privacy--security) and [`../darkfi-lightwalletd/docs/TLS_PINNING.md`](../darkfi-lightwalletd/docs/TLS_PINNING.md). **Chat:** open the **Chat** tab — DarkIRC runs **in-process** via UniFFI (`start_darkirc`), not a desktop IRC server. First P2P/DAG sync can take several minutes. Watch `adb logcat -s darkfi-mobile-ffi darkfi-net`. Enable **Tor** in chat settings for SOCKS-routed P2P. **After editing `darkfi_mobile_ffi.udl`:** re-run `./scripts/build-darkfi-mobile-ffi-android.sh` (do **not** set `SKIP_UNIFFI_BINDGEN`). A UDL mismatch often shows as `Unresolved reference 'SyncMethod'`. After mesh-engine C ABI changes only, use `SKIP_UNIFFI_BINDGEN=1`. **Disk:** `third_party/darkfi/target/` and `rust/target/` grow large. Delete a finished NDK triple (`rust/target/aarch64-linux-android`) after copying `.so` files. Do not `make clean` / `distclean` the vendored DarkFi proofs tree to “fix” a build. **Optional binaries:** `./scripts/build-darkirc-android.sh` (legacy `darkirc_exec`), `./scripts/build-darkfid-android.sh`. IDE setup, emulators, signing, and troubleshooting: **[Setup Documentation](docs/Setup.md)**. ## Repository layout ```text parent/ darkfi/ # optional; app vendors into third_party/darkfi darkfi-lightwalletd/ # gRPC lightwalletd (local sync target) darkfi-mobile-ffi/ # optional sibling symlink of rust/darkfi-mobile-ffi nighthawk-android-wallet/ # this repo (GitHub: nighthawk-apps/nighthawk-android-wallet) nighthawk-ios-wallet/ nighthawk-desktop/ moonshine/ ``` Vendored DarkFi and RandomX are **git submodules** (`third_party/darkfi`, `third_party/RandomX`). Clone with `--recurse-submodules`, or run `./scripts/vendor-darkfi.sh` after clone. The shared UniFFI crate lives at `rust/darkfi-mobile-ffi`. Other clients (desktop, etc.) may symlink or copy it to a sibling directory named `darkfi-mobile-ffi`. --- ## Prerequisites | Requirement | Notes | |-------------|--------| | **JDK 17+** | Temurin common; Gradle may use toolchains — see [Setup](docs/Setup.md) | | **Android SDK** | SDK Manager → set `ANDROID_HOME`; add `platform-tools` to `PATH` for `adb` | | **Android NDK** | **Exactly `26.1.10909125`** (`gradle.properties` `ANDROID_NDK_VERSION`). NDK 27/30 will not satisfy Gradle. `sdkmanager --install "ndk;26.1.10909125"` then `export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/26.1.10909125"` | | **Rust + Cargo** | [rustup](https://rustup.rs/) stable | | **`cargo-ndk`** | Pin `4.1.2` (F-Droid). The FFI script defaults `CARGO_HOME` to the repo `.cargo-home`, so `cargo install cargo-ndk@4.1.2` into `~/.cargo` is easy to miss. Either `CARGO_HOME=$PWD/.cargo-home cargo install cargo-ndk@4.1.2` or keep `~/.cargo/bin` on `PATH` (the script now searches both). | | **Android Rust targets** | See command below | | **Vendored DarkFi** | git submodule at `docs/upstream/darkfi-revision.txt`; `./scripts/vendor-darkfi.sh` | ```bash rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android ``` --- ## Build ### UniFFI native libraries Produces `libdarkfi_mobile_ffi.so` per ABI, copies into `artifacts/mobile-ffi/` and `darkfi-android-sdk/src/main/jniLibs/`, and regenerates Kotlin bindings from `rust/darkfi-mobile-ffi/src/darkfi_mobile_ffi.udl`. ```bash export ANDROID_NDK_HOME=/path/to/ndk # e.g. ~/Library/Android/sdk/ndk/26.1.10909125 ./scripts/build-darkfi-mobile-ffi-android.sh # Emulator + device only: # MOBILE_FFI_ABIS="arm64-v8a x86_64" ./scripts/build-darkfi-mobile-ffi-android.sh ``` Re-run whenever Rust sources or the UDL change. If matching `.so` files already exist in `artifacts/mobile-ffi` / `jniLibs`, Gradle alone is enough until the next Rust/UDL change.
Manual cargo-ndk copy (equivalent to the script) ```bash export ANDROID_NDK_HOME cd rust cargo ndk \ -t arm64-v8a -t armeabi-v7a -t x86 -t x86_64 \ build --release -p darkfi-mobile-ffi JNILIBS=../darkfi-android-sdk/src/main/jniLibs T=target mkdir -p "$JNILIBS/arm64-v8a" "$JNILIBS/armeabi-v7a" "$JNILIBS/x86" "$JNILIBS/x86_64" cp "$T/aarch64-linux-android/release/libdarkfi_mobile_ffi.so" "$JNILIBS/arm64-v8a/" cp "$T/armv7-linux-androideabi/release/libdarkfi_mobile_ffi.so" "$JNILIBS/armeabi-v7a/" cp "$T/i686-linux-android/release/libdarkfi_mobile_ffi.so" "$JNILIBS/x86/" cp "$T/x86_64-linux-android/release/libdarkfi_mobile_ffi.so" "$JNILIBS/x86_64/" cd .. ```
Crate details: [`rust/darkfi-mobile-ffi/README.md`](rust/darkfi-mobile-ffi/README.md). Feature catalog: [`docs/app-features.md`](docs/app-features.md) · Plan: [`docs/implementation-plan.md`](docs/implementation-plan.md). ### Android app ```bash # Mainnet debug ./gradlew :app:assembleDarkfimainnetDebug # Testnet debug (distinct applicationId `.testnet`) ./gradlew :app:assembleDarkfitestnetDebug ./gradlew assembleDebug # Release (keystore required — see docs/Setup.md) # ./gradlew :app:assembleDarkfimainnetRelease # Remote HTTPS requires TLS pin: # ./gradlew :app:assembleDarkfimainnetRelease -PLIGHTWALLET_TLS_PIN_SHA256=<64hex> ``` APKs under `app/build/outputs/apk/`. Install: ```bash ./gradlew :app:installDarkfimainnetDebug # or: adb install -r app/build/outputs/apk/darkfimainnet/debug/app-darkfimainnet-debug.apk ``` --- ## Chat (DarkIRC / EventGraph) In-app **Chat** uses a **native in-process DarkIRC daemon** over UniFFI (`start_darkirc` + `DarkircEventCallback`). Same model as iOS. See [DarkFi integration](docs/darkfi-integration.md) and [Nighthawk Mesh](docs/nighthawk-mesh.md). Optional packaged `darkirc_exec` remains a **legacy IRC subprocess** ([packaging notes](docs/darkirc-embedded-android.md)); desktop reverse-port IRC is [android-darkirc-chat.md](docs/android-darkirc-chat.md). | Capability | Behavior | |------------|----------| | Transport | EventGraph P2P via `libdarkfi_mobile_ffi.so` (clearnet `tcp+tls` seeds by default) | | Nearby hop | Optional BLE **Nighthawk Mesh** — encrypted EventGraph only (no share-internet this pass) | | Tor | Chat settings → P2P via embedded Guardian **`tor-android`** SOCKS5; UI **Connected (Tor)** only after a real handshake | | Public channels | `#dev`, `#random`, `#lunardao`, `#hackers` | | E2E DMs | ChaCha via `chacha_encrypt_dm` / `chacha_decrypt_dm`; daemon refuses plaintext DMs | | Status | `darkirc_status()` → `ConnectedDirect` or `ConnectedViaTor` | | DAG history | First P2P connect can take several minutes | | Settings | **Settings → Chat** — identity, Tor/SOCKS, DAG hours | ```bash ./scripts/build-darkfi-mobile-ffi-android.sh ./gradlew :darkfi-android-sdk:testDebugUnitTest ./gradlew :app:installDarkfimainnetDebug ``` --- ## Nighthawk Mesh (encrypted EventGraph hop) Optional nearby BLE hop for **encrypted DarkIRC DAG** frames (Noise per GATT neighbor). Chat still goes through EventGraph → `event_pub` → UI. Share-internet / SoftAP / BLE LWD are **off**. Rebuild with `SKIP_UNIFFI_BINDGEN=1` after mesh C ABI changes. Full write-up: [docs/nighthawk-mesh.md](docs/nighthawk-mesh.md). --- ## Architecture - **UI:** `ui-lib` Compose — onboarding, backup, restore, send, receive, settings, chat. Bottom nav: **Chat → Wallet → Transfer → Settings** (opens on Chat). - **Themes:** Stealth (default), Light, Midnight (`APP_THEME_VARIANT`). - **Settings:** identity (IRC nickname / chat public ID / gated secret), Tor, chat, server, security, about. - **Wallet SDK:** `darkfi-android-sdk` — `PersistableDarkfiWallet`, `DarkfiMnemonic` (22-word), `DarkfiWalletCoordinator`, `DarkfiSynchronizer`. - **Balance:** single confirmed/spendable DRK tally (no transparent/shielded split). - **RPC presets:** `DarkfiEndpoint` defaults to lightwalletd **`tcp://127.0.0.1:9067`** (both networks). Network identity is enforced via `GetLightInfo.chain_name`. - **Native:** UniFFI + JNA → `libdarkfi_mobile_ffi.so` in `jniLibs//`. Mesh C ABI: `SKIP_UNIFFI_BINDGEN=1`. **arm64-v8a** includes neighbor mesh symbols; **x86_64** emulator `.so` is older until rebuilt. ### UniFFI & native bridge | Piece | Role | |-------|------| | **`rust/darkfi-mobile-ffi`** | UniFFI **0.32** `cdylib` (`darkfi_mobile_ffi.udl`) + mesh C ABI — [crate README](rust/darkfi-mobile-ffi/README.md) | | **Generated Kotlin** | `com.nighthawkapps.lib.uniffi.darkfi_mobile_ffi` (via build script) | | **`DarkfiMobileFfiApi`** | Stable façade so UI avoids importing generated symbols | | **`rust/darkfi-android-bridge`** | Legacy minimal bridge — prefer `darkfi-mobile-ffi` | | **JNA** | UniFFI **0.32** Kotlin bindings (`net.java.dev.jna:jna` **5.19.1**) | | **`jniLibs/`** | Per-ABI `.so` — Gradle does **not** invoke Cargo automatically | --- ## Privacy & security The wallet talks only to **`darkfi-lightwalletd`** (never production `darkfid`). Sibling docs: [`darkfi-lightwalletd`](../darkfi-lightwalletd) · TLS pin: [`docs/TLS_PINNING.md`](../darkfi-lightwalletd/docs/TLS_PINNING.md). ### TLS pin (remote HTTPS) ```bash openssl x509 -in lightwalletd.crt -outform DER | openssl dgst -sha256 -hex # → 64 hex chars ./gradlew :app:assembleDarkfimainnetRelease -PLIGHTWALLET_TLS_PIN_SHA256=<64hex> # or gradle.properties: LIGHTWALLET_TLS_PIN_SHA256=<64hex> ``` - Manifest meta: `com.nighthawkapps.lightwallet_tls_pin_sha256` - Runtime override: SharedPreferences `darkfi_lightwallet_security` / `lightwallet_tls_pin_sha256` - Loopback `http://127.0.0.1:9067` may omit the pin; remote `https://` / `tcp+tls://` **fail closed** without it ### Tor (SOCKS5) Enable Tor in settings. The SDK rewrites the lightwallet URL to `socks5://proxy/dest`; Rust dials via SOCKS5. Remote cleartext is only allowed through SOCKS; remote HTTPS still needs a TLS pin. ### Sync & network | # | Feature | Status | Description | |---|---------|--------|-------------| | 1 | **No direct darkfid** | ✅ | `direct-darkfid` off in production | | 2 | **Block range padding** | ✅ | Power-of-2 buckets (min 1024) | | 3 | **Polling jitter** | ✅ | ±30% sync intervals | | 4 | **TLS pin (S8)** | ✅ | Leaf-cert SHA-256 | | 5 | **Cleartext loopback only** | ✅ | Non-loopback `http://` refused | | 6 | **OMR-first + backoff (S15)** | ✅ | Exponential backoff; trial at max failures | | 7 | **Tor SOCKS5 dial** | ✅ | `socks5://` for lightwallet gRPC | | 8 | **Reorg recovery (R1)** | ✅ | `rewind_to_height()`; UI count is history rows with `block_height > rewind` | | 9 | **Tip regression (R4)** | ✅ | `new_tip < prev_tip` triggers reorg | | 10 | **Server switch reset** | ✅ | Clears tip / OMR counters | | 11 | **Instant Sync & Checkpoints** | ✅ | Instant restore from authenticated `TreeState` / `CheckpointSnapshot` | | 12 | **Real Birthday Clamping** | ✅ | Strict scan bounds; never trial-decrypt below birthday | | 13 | **UnifOMR Pipelining** | ✅ | Window N+1 prefetch concurrent with window N application; in-order buffer | | 14 | **ZKAS & Key Cache** | ✅ | In-memory LRU + disk cache for contract bincodes and proving keys | | 15 | **Proto Version Lockstep** | ✅ | Major-version semver check on `LightInfo.proto_version` | See [docs/instant-sync-strategy.md](docs/instant-sync-strategy.md) for full instant sync architecture and implementation details. ### Data-at-rest & logging | # | Feature | Status | Description | |---|---------|--------|-------------| | 8 | **Wallet pass** | ✅ | Encrypted DataStore (`DrkWalletPassStore`) | | 9 | **Encrypted memo (RAM)** | ✅ | Session keystream; not on disk | | 10 | **Log redaction** | ✅ | `redact_sync_error()` | ### UnifOMR (scheme 0x05) - Requires **darkfi-lightwalletd** with `fhe-omr` - Crypto parity: RLWE `n=1024`, signed AHE, `CLUE_ERROR_BOUND=2`, length-prefixed SealPIR limbs - Flow: RegisterCluePublicKey → GetClue → SendTransaction(omr_clue) → GetUnifOmrDigest → FetchPirBatch - Sync fail-closed if clue PK registration fails; send uses LWD `SendTransaction` only (24h clue hint) - **Trial-decrypt fallback (default on):** when UnifOMR returns no matches (or large gaps), the wallet supplemental trial-decrypts compact blocks so you can receive from non-UnifOMR wallets such as upstream `drk`. Toggle **Strict UnifOMR sync** under Advanced settings to disable this (UnifOMR-only, more private / faster when counterparties also use UnifOMR). - Default local endpoint: `http://127.0.0.1:9067` - Limits: [`doc/unifomr_mvp_limits.md`](doc/unifomr_mvp_limits.md) | # | Feature | Status | |---|---------|--------| | 11 | UnifOMR only (`0x05`; no PerfOMR) | ✅ | | 12 | FHE any-match client path | ✅ | | 13 | Multi-pubkey (cap 16) | ✅ | | 14 | BFV query LRU (cap 16) | ✅ | | 15 | Hard-fail digest (S11) | ✅ | | 16 | Tip completeness (S24) | ✅ | | 17 | Nullifiers all blocks (S25) | ✅ | | 18 | SendTransaction + clue | ✅ | | 19 | Domain-separated KDF | ✅ | | 20 | Pool-based key delivery | ❌ | | 21 | Cross-wallet trial fallback | ✅ | | 22 | `SyncFallbackReason` via UniFFI | ✅ | | 23 | Inter-match gap scanning | ✅ | | 24 | Reorg callback | ✅ | | 25 | LWD-only (`darkfidRpcUrl` default null) | ✅ | | 26 | Wallet Tor bootstrap flag | ✅ | | 27 | DM keypair UniFFI | ✅ | | 28 | `chain_name` network guard | ✅ | ### What the server learns | Sync mode | Learns | Does not learn | |-----------|--------|----------------| | **UnifOMR** | Encrypted digest + PIR window; clue-PK lookups | Which notes decrypt, spend keys | | **Trial / gap** | Padded / gap ranges | Which notes decrypt | | **Direct darkfid** ⚠️ | Everything | *(disabled — leave `darkfidRpcUrl` unset)* | ### Sync modes | Mode | When | Privacy | Bandwidth | |------|------|---------|-----------| | **UnifOMR (0x05)** | Server advertises `unifomr` | Best (MVP limits) | Low–medium | | **Trial (LWD)** | After OMR failure / empty match | Degraded | Higher | | **Direct darkfid** | Dev feature only | Poor | Highest | Code: `rust/darkfi-mobile-ffi/src/{sync,lightwallet_client,lightwallet_sync,omr,unifomr,transactions,block_cache}.rs` Checklist: [`docs/verification-checklist.md`](docs/verification-checklist.md). --- ## Verification Mirrors [.github/workflows/pull-request.yml](.github/workflows/pull-request.yml) where tooling resolves: | Step | Command | |------|---------| | JVM libraries | `./gradlew :configuration-api-lib:check :preference-api-lib:check :spackle-lib:check` | | Wallet SDK unit tests | `./gradlew :darkfi-android-sdk:testDebugUnitTest` | | UI library unit tests | `./gradlew :ui-lib:testDebugUnitTest` | | UniFFI crate tests | `cd rust && cargo test -p darkfi-mobile-ffi --lib` | | Repo JVM tests | `./gradlew test` | | Mainnet debug APK | `./gradlew :app:assembleDarkfimainnetDebug` | | Android Lint | `ORG_GRADLE_PROJECT_IS_MINIFY_ENABLED=false ./gradlew :app:lintDarkfimainnetRelease` | | ktlint | `./gradlew ktlint` / `./gradlew ktlintFormat` | Notes: - `./gradlew checkProperties` validates signing-related props (CI/release defaults). - ktlint uses `com.pinterest.ktlint:ktlint-cli` (`KTLINT_VERSION` in `gradle.properties`). - `./gradlew detektAll` runs in CI; a clean pass needs backlog clearance. --- ## Known issues 1. Intel machines may need `WALLET_IS_DEPENDENCY_LOCKING_ENABLED=false` in `~/.gradle/gradle.properties` if locking flakes during IDE sync. 2. Gradle may warn about mixed AGP detection for composite builds—safe when versions match under `build-conventions-*`. 3. `IS_ANDROID_INSTRUMENTATION_TEST_COVERAGE_ENABLED` prevents interactive debugging of the debug APK (CI-only). 4. Compose + Jacoco coverage remains limited upstream. ### Install & shortcuts - This tree does **not** migrate data from older package IDs—restore from seed if needed. - `shortcuts.xml` hard-codes `android:targetPackage="com.nighthawkwallet.android"` (no `${applicationId}` substitution). Avoid shipping mismatched testnet shortcuts silently. --- ## Related projects | Sibling directory | Role | |-------------------|------| | `../darkfi-lightwalletd` | Compact-block / UnifOMR gRPC server | | `../darkfi-mobile-ffi` | Optional sibling name for the UniFFI crate (`rust/darkfi-mobile-ffi`) | | `../nighthawk-ios-wallet` | iOS wallet | | `../nighthawk-desktop` | Desktop wallet (Tauri) | | `../moonshine` | CLI light wallet | ## Contributing & support - Guidelines: [Contributing](docs/CONTRIBUTING.md) - Translations: [Crowdin](https://crowdin.com/project/nighthawk-wallet/) [![Crowdin](https://badges.crowdin.net/nighthawk-wallet/localized.svg)](https://crowdin.com/project/nighthawk-wallet) - Security: [GitHub Security Advisories](https://github.com/nighthawk-apps/nighthawk-android-wallet/security) or maintainer channels. Do not disclose publicly before coordinated disclosure. - Issues / features: GitHub issues on this repository - Support: [DM @NighthawkWallet on X](https://x.com/nighthawkwallet) - Email: `nighthawkwallet@protonmail.com` --- ## Disclaimers - Funding/on-ramp and third-party exchange shortcuts were removed; acquire DRK through channels you trust. - Chat uses an in-process EventGraph daemon via UniFFI; optional Tor routes P2P through embedded **`tor-android`** SOCKS5. - Fiat hints depend on public APIs (`COIN_GECKO_ASSET_ID`) and may be unavailable.