Fix syncing: trigger header sync when peers connect

The SPV client's syncHeaders() was never called. The peer manager
started connections but never notified the SPV client when a peer
completed the handshake.

Changes:
- Added onPeerReady callback to PeerManager (dispatches to subscribers)
- SPV client registers for onPeerReady, triggers syncHeaders() on
  first ready peer, and sends Bloom filter to each new peer
- Made BloomFilter.numHashFuncs and .tweak public (needed by SPV client
  to serialize filterload messages for new peers)
- Wallet store no longer sets isSyncing:true prematurely - the SPV
  client's onSyncProgress event drives the syncing state
- Updated README with current architecture and features

Author: NateIsern

README.md

@@ -6,36 +6,39 @@ Built with Expo SDK 55, React Native 0.83, and pure TypeScript cryptography.
 
 ## Features
 
-- **True SPV wallet** — connects directly to the FairCoin P2P network, no server dependency
+- **True SPV wallet** — connects directly to the FairCoin P2P network via DNS seeds, no server dependency
 - **HD wallet** — BIP39 (24-word mnemonic) + BIP32 + BIP44 (`m/44'/119'/0'/...`)
 - **Multi-wallet** — create, import, switch between, and manage multiple wallets
-- **QR code** — scan to send, show to receive
-- **Deep links** — handles `faircoin:` URIs (BIP21-style)
-- **PIN & biometrics** — 6-digit PIN with fingerprint/face unlock
+- **QR code** — camera scanner to send, QR display to receive
+- **Deep links** — handles `faircoin:` URIs (BIP21-style), opens Send pre-filled
+- **PIN & biometrics** — 6-digit PIN with fingerprint/face unlock on app open
+- **Address book** — save and manage contacts
+- **Coin control** — select specific UTXOs for transactions
 - **Masternode** — detect 5,000 FAIR collateral UTXOs, start masternodes
 - **FastSend** — instant confirmation via masternode quorum (SwiftTX)
-- **Secure** — keys stored in OS keychain (Keychain/EncryptedSharedPreferences), per-wallet SQLite databases
+- **BIP38** — encrypted private key export/import
+- **Secure** — keys in OS keychain, per-wallet SQLite databases, edge-to-edge UI
 
 ## Platforms
 
-| Platform | Status | How |
-|----------|--------|-----|
-| Android | Ready | Expo Go / APK build |
-| iOS | Ready | Expo Go / IPA build |
-| Desktop | Ready | Electron wrapping Expo web export |
+| Platform | Status | Build |
+|----------|--------|-------|
+| Android | Production | APK via GitHub Actions |
+| iOS | Production | Expo prebuild + Xcode |
+| Desktop | Production | Electron (Windows, macOS, Linux) |
 
 ## Tech Stack
 
 | Layer | Technology |
 |-------|-----------|
 | Framework | Expo SDK 55, React Native 0.83 |
-| Navigation | expo-router (native tabs on Android/iOS) |
-| Styling | NativeWind (Tailwind CSS) |
-| State | Zustand |
-| Crypto | `@noble/secp256k1`, `@noble/hashes`, `@scure/bip32`, `@scure/bip39` |
-| Storage | expo-secure-store (keys), expo-sqlite (chain data) |
-| P2P | Custom SPV client (TCP via react-native-tcp-socket / Node.js net) |
-| Desktop | Electron (IPC bridge for TCP + secure storage) |
+| Navigation | expo-router with native tabs (NativeTabs on Android/iOS, headless on web) |
+| Styling | NativeWind 4.x (Tailwind CSS) |
+| State | Zustand 5 |
+| Crypto | `@noble/secp256k1` 2.x, `@noble/hashes` 1.8, `@scure/bip32` 1.7, `@scure/bip39` 1.6 |
+| Storage | expo-secure-store (native keychain), expo-sqlite (chain data) |
+| P2P | Custom SPV client over TCP (react-native-tcp-socket on mobile, Node.js net on Electron) |
+| Desktop | Electron with custom `app://` protocol for proper SPA routing |
 
 ## FairCoin Protocol
 
@@ -51,14 +54,16 @@ Built with Expo SDK 55, React Native 0.83, and pure TypeScript cryptography.
 | Tx hash | Double SHA-256 |
 | Signing curve | secp256k1 |
 | Masternode collateral | 5,000 FAIR |
+| DNS seeds | `seed1.fairco.in`, `seed2.fairco.in` |
 
 ## Getting Started
 
 ### Prerequisites
 
 - [Node.js](https://nodejs.org/) 22+
 - [Bun](https://bun.sh/) (package manager)
-- [Expo Go](https://expo.dev/go) on your phone/emulator
+- JDK 17+ (for Android builds)
+- Android SDK (for Android builds)
 
 ### Install
 
@@ -71,46 +76,55 @@ bun install
 ### Development
 
 ```bash
-# Start Expo dev server
+# Start Expo dev server (requires Expo Go or dev client)
 bun start
 
-# Android
+# Build and run on Android (requires Android SDK + JDK)
 bun run android
 
-# iOS
+# Build and run on iOS (requires Xcode)
 bun run ios
 
-# Web (for Electron)
+# Web (for Electron development)
 bun run web
 ```
 
 ### Desktop (Electron)
 
 ```bash
-# Development
+# Build web export + launch Electron
 bun run export:web
-bun run electron -- --dev
+bun run electron
 
-# Production
-bun run electron:build
+# Development mode (connects to Expo dev server)
+bun run electron -- --dev
 ```
 
-### Build APK
+### Build APK Locally
 
 ```bash
-# Local build
 npx expo prebuild --platform android
 cd android && ./gradlew assembleRelease
 ```
 
-Or push a release tag — GitHub Actions will automatically build and attach the APK.
-
 ### Type Check
 
 ```bash
 bun run typecheck
 ```
 
+## CI/CD
+
+GitHub Actions automatically build and attach release artifacts when you create a GitHub release:
+
+- **Android**: APK built with Gradle, attached to release
+- **Desktop**: Windows (.exe), macOS (.dmg), Linux (.deb, .AppImage) via electron-builder
+
+```bash
+# Create a release (triggers builds)
+gh release create v1.0.1 --title "v1.0.1" --notes "Release notes..."
+```
+
 ## Project Structure
 
 ```
@@ -121,6 +135,10 @@ FAIRWallet/
 │   ├── lock.tsx            # PIN/biometric lock screen
 │   ├── masternode.tsx      # Masternode management
 │   ├── wallets.tsx         # Multi-wallet manager
+│   ├── contacts.tsx        # Address book
+│   ├── coin-control.tsx    # UTXO selection
+│   ├── export-key.tsx      # BIP38 key export
+│   ├── transaction/        # Transaction detail
 │   ├── onboarding/         # Welcome, create, restore, PIN setup
 │   └── (tabs)/             # Main app (wallet, send, receive, settings)
 ├── src/
@@ -138,50 +156,58 @@ FAIRWallet/
 │   ├── p2p/                # SPV P2P client
 │   │   ├── messages.ts     # Wire protocol serialization
 │   │   ├── bloom-filter.ts # BIP37 Bloom filter
-│   │   ├── peer.ts         # TCP peer connection
-│   │   ├── peer-manager.ts # Multi-peer pool
+│   │   ├── peer.ts         # TCP peer connection + handshake
+│   │   ├── peer-manager.ts # Multi-peer pool + discovery
 │   │   ├── spv-client.ts   # Header sync + Merkle validation
+│   │   ├── dns-seeds.ts    # DNS-over-HTTPS seed resolution
 │   │   ├── masternode.ts   # Masternode broadcast/ping
-│   │   └── fastsend.ts     # SwiftTX instant confirmations
+│   │   ├── fastsend.ts     # SwiftTX instant confirmations
+│   │   ├── socket-provider.ts # Platform TCP adapter
+│   │   └── header-store.ts # SQLite ↔ SPV bridge
 │   ├── wallet/             # Wallet state
 │   │   ├── key-manager.ts  # HD key derivation + gap limit
 │   │   ├── utxo-set.ts     # UTXO tracking + coin selection
-│   │   └── wallet-store.ts # Zustand store (multi-wallet)
+│   │   └── wallet-store.ts # Zustand store (multi-wallet, P2P)
 │   ├── storage/            # Persistence
 │   │   ├── database.ts     # SQLite (per-wallet)
-│   │   └── secure-store.ts # Keychain (mnemonics, PIN, biometrics)
+│   │   ├── secure-store.ts # Keychain (mnemonics, PIN, biometrics)
+│   │   └── kv-store.ts     # Platform adapter (native keychain / localStorage)
 │   └── ui/components/      # Reusable UI
-│       ├── Button.tsx       # Multi-variant button
+│       ├── Button.tsx
 │       ├── TransactionItem.tsx
 │       ├── SyncStatus.tsx
-│       └── QRScanner.tsx    # Camera-based QR scanner
+│       └── QRScanner.tsx
 ├── electron/               # Desktop wrapper
-│   ├── main.js             # TCP P2P + safeStorage via IPC
+│   ├── main.js             # Custom app:// protocol + TCP P2P + safeStorage
 │   └── preload.js          # contextBridge API
+├── plugins/
+│   └── withGradle813.js    # Expo config plugin: Gradle 9→8.13 downgrade
 ├── .github/workflows/
-│   └── build-android.yml   # Auto-build APK on GitHub releases
+│   ├── build-android.yml   # APK build on release
+│   └── build-desktop.yml   # Electron builds on release
 └── app.json                # Expo config
 ```
 
 ## Deep Links
 
-FAIRWallet handles `faircoin:` URIs:
+FAIRWallet handles `faircoin:` URIs following BIP21 conventions:
 
 ```
 faircoin:FxxxxAddress
 faircoin:FxxxxAddress?amount=10.5
 faircoin:FxxxxAddress?amount=10.5&label=Donation&message=Thanks
 ```
 
-Clicking a `faircoin:` link opens FAIRWallet and pre-fills the Send screen.
+Tapping a `faircoin:` link opens FAIRWallet and navigates to the Send screen with address and amount pre-filled.
 
 ## Security
 
-- Private keys and mnemonics are stored in the OS keychain (iOS Keychain / Android EncryptedSharedPreferences)
-- PIN is hashed with SHA-256 before storage
+- Private keys and mnemonics stored in OS keychain (iOS Keychain / Android EncryptedSharedPreferences)
+- PIN hashed with SHA-256 before storage
 - Each wallet has its own isolated SQLite database
 - All cryptography uses audited libraries (`@noble/*`, `@scure/*`)
 - No external servers — SPV client connects directly to FairCoin nodes
+- BIP38 encrypted key export for backups
 
 ## License
 

src/p2p/bloom-filter.ts

@@ -92,8 +92,8 @@ function murmurHash3(data: Uint8Array, seed: number): number {
 
 export class BloomFilter {
   private readonly data: Uint8Array;
-  private readonly numHashFuncs: number;
-  private readonly tweak: number;
+  readonly numHashFuncs: number;
+  readonly tweak: number;
   private readonly flags: number;
 
   constructor(size: number, numHashFuncs: number, tweak: number, flags: number) {

src/p2p/peer-manager.ts

@@ -22,6 +22,7 @@ export interface PeerManagerConfig {
 }
 
 export type MessageHandler = (peer: Peer, command: string, payload: Uint8Array) => void;
+export type PeerReadyHandler = (peer: Peer) => void;
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -48,6 +49,7 @@ export class PeerManager {
   private readonly failedAddresses: Map<string, number> = new Map(); // address -> fail count
 
   private messageHandlers: MessageHandler[] = [];
+  private peerReadyHandlers: PeerReadyHandler[] = [];
   private reconnectTimer: ReturnType<typeof setInterval> | undefined;
   private discoveryTimer: ReturnType<typeof setInterval> | undefined;
   private running = false;
@@ -175,6 +177,13 @@ export class PeerManager {
     this.messageHandlers.push(handler);
   }
 
+  /**
+   * Register a handler called when a peer completes the version handshake.
+   */
+  onPeerReady(handler: PeerReadyHandler): void {
+    this.peerReadyHandlers.push(handler);
+  }
+
   /**
    * Remove a previously registered message handler.
    */
@@ -262,6 +271,10 @@ export class PeerManager {
       onReady: (peer: Peer) => {
         // Reset fail count on successful connection
         this.failedAddresses.delete(peer.host);
+        // Notify subscribers
+        for (const handler of this.peerReadyHandlers) {
+          handler(peer);
+        }
       },
       onMessage: (peer: Peer, command: string, payload: Uint8Array) => {
         this.dispatchMessage(peer, command, payload);

src/p2p/spv-client.ts

@@ -259,6 +259,7 @@ export class SPVClient {
 
     this.peerManager = new PeerManager(peerManagerConfig);
     this.peerManager.onMessage(this.handlePeerMessage.bind(this));
+    this.peerManager.onPeerReady(this.handlePeerReady.bind(this));
   }
 
   // -----------------------------------------------------------------------
@@ -289,6 +290,28 @@ export class SPVClient {
     this.peerManager.stop();
   }
 
+  /**
+   * Called when a peer completes the version/verack handshake.
+   * Sends our Bloom filter and begins header sync if not already syncing.
+   */
+  private handlePeerReady(peer: Peer): void {
+    // Send Bloom filter to the newly connected peer
+    if (this.bloomFilter) {
+      const filterPayload = serializeFilterLoad(
+        this.bloomFilter.toBytes(),
+        this.bloomFilter.numHashFuncs,
+        this.bloomFilter.tweak,
+        1, // BLOOM_UPDATE_ALL
+      );
+      peer.sendMessage("filterload", filterPayload);
+    }
+
+    // Begin header sync on first ready peer
+    if (this.running && !this.syncing) {
+      void this.syncHeaders();
+    }
+  }
+
   /**
    * Register event handlers.
    */

src/wallet/wallet-store.ts

@@ -375,17 +375,12 @@ export const useWalletStore = create<WalletState>((set, get) => ({
         set({ networkStatus: "Connecting to peers..." });
         await spvClient.start();
 
-        const peerCount = spvClient.getPeerManager().getReadyPeers().length;
         set({
-          connectedPeers: peerCount,
           chainHeight: spvClient.getChainHeight(),
-          isSyncing: true,
-          networkStatus: peerCount > 0
-            ? `Connected to ${peerCount} peer${peerCount === 1 ? "" : "s"}`
-            : "Waiting for peers...",
+          networkStatus: "Waiting for peers...",
         });
 
-        // Start a periodic peer count updater
+        // Periodic peer count updater
         const peerUpdateInterval = setInterval(() => {
           if (!spvClient) {
             clearInterval(peerUpdateInterval);