A self-custodial Ethereum wallet for iOS and Android that sends transactions over a BLE mesh network, enabling offline-first transfers without internet access.

• What is MeshWallet?
• Architecture Overview
• Transaction Flow
• Tech Stack
• Project Structure
• Quick Start
• Environment Variables
• Why @offline-protocol/mesh-sdk?
• Why @noble/* cryptography?
• Contributing
• License

MeshWallet is a self-custodial Ethereum mobile wallet that routes signed transactions through a BLE (Bluetooth Low Energy) device mesh when no internet is available. Any phone running the app acts as a relay node; when a node gains connectivity it flushes buffered transactions to an Ethereum RPC endpoint (Sepolia testnet) and polls for confirmation.

The wallet generates secp256k1 key pairs natively, stores private keys in the OS secure enclave (via expo-secure-store), and signs transactions locally using @noble/curves. WalletConnect v2 integration allows dApp pairing. The design assumes an adversarial environment: every packet is AES-256-GCM encrypted, carries a TTL, and is deduplicated before relay.

graph TB
    subgraph Device["Mobile Device (iOS / Android)"]
        UI["Expo Router UI\n(app/ screens)"]
        WS["walletStore\nZustand"]
        MS["meshStore\nZustand"]
        KM["KeyManager\nexpo-secure-store + secp256k1"]
        SG["Signer\n@noble/curves"]
        EN["Encryptor\nAES-256-GCM"]
        DB[(SQLite\nexpo-sqlite)]
        GW["GatewaySync\nBackgroundFetch"]
    end

    subgraph BLE["BLE Mesh Layer"]
        BM["BLEManager\n@offline-protocol/mesh-sdk"]
        MR["MeshRouter\nTTL · dedup · relay buffer"]
        PS["PairingService\nneighbor discovery"]
        PC["PacketCodec\nJSON encode/decode"]
    end

    subgraph External["External"]
        RPC["Ethereum RPC\nSepolia (multi-endpoint)"]
        ES["Etherscan API\nSepolia"]
        WC["WalletConnect v2\nCloud relay"]
    end

    UI --> WS
    UI --> MS
    UI --> KM
    UI --> SG
    UI --> EN
    SG --> DB
    GW --> DB
    GW --> RPC
    GW --> ES
    MR --> DB
    MR --> BM
    BM --> PC
    MR --> GW
    PS --> BM
    UI --> PS
    UI --> WC
    WS --> UI
    MS --> UI

sequenceDiagram
    participant User
    participant UI as Expo Router UI
    participant Signer
    participant Encryptor
    participant DB as SQLite
    participant MeshRouter
    participant BLEMesh as BLE Mesh (peers)
    participant GatewaySync
    participant RPC as Ethereum RPC (Sepolia)

    User->>UI: Enter recipient + amount, tap Send
    UI->>Signer: signTransaction(unsignedTx)
    Signer->>DB: insertTransaction(status=QUEUED_LOCAL)
    UI->>Encryptor: encryptForSender(signedTx, privKey)
    UI->>MeshRouter: enqueue MeshPacket (TTL=12)
    MeshRouter->>DB: insertRelayPacket + status→IN_MESH
    MeshRouter->>BLEMesh: writePacketToDevice (per peer)
    BLEMesh-->>MeshRouter: neighbor relays packet onwards

    alt Device has internet
        MeshRouter->>GatewaySync: flushPendingToGateway()
        GatewaySync->>DB: read relay_buffer (forwarded=0)
        GatewaySync->>Encryptor: decryptFromSender(packet)
        GatewaySync->>RPC: ethers.Wallet.sendTransaction (EIP-1559)
        RPC-->>GatewaySync: txHash
        GatewaySync->>DB: status→BROADCAST + tx_hash
        loop Poll every 5 s (max 10 min)
            GatewaySync->>RPC: getTransactionReceipt(txHash)
            RPC-->>GatewaySync: receipt
            GatewaySync->>DB: status→CONFIRMED or FAILED
        end
    else No internet (pure mesh relay)
        BLEMesh-->>BLEMesh: packet hops until a node with internet flushes it
    end

MeshWallet/
├── app/                        # Expo Router file-based screens
│   ├── (tabs)/                 # Bottom-tab group
│   │   ├── wallet.tsx          # Main balance + recent txs
│   │   ├── history.tsx         # Full transaction history
│   │   ├── network.tsx         # BLE mesh peer view + relay events
│   │   └── profile.tsx         # Address, QR code, settings
│   ├── send/                   # Multi-step send flow (stack)
│   │   ├── index.tsx           # Amount + recipient entry
│   │   ├── scan.tsx            # QR camera scanner
│   │   ├── pairing.tsx         # BLE peer picker
│   │   ├── confirm.tsx         # Review + sign
│   │   └── success.tsx         # Broadcast confirmation
│   ├── transaction/[id].tsx    # Transaction detail
│   ├── onboarding.tsx          # First-run key generation
│   ├── ledger.tsx              # On-chain balance reconciliation
│   ├── receive.tsx             # QR receive address
│   └── _layout.tsx             # Root navigator + WalletContext init
├── src/
│   ├── ble/
│   │   ├── BLEManager.ts       # Wraps @offline-protocol/mesh-sdk singleton
│   │   ├── MeshRouter.ts       # TTL, dedup, relay buffer, gateway trigger
│   │   ├── PacketCodec.ts      # MeshPacket type + JSON encode/decode
│   │   └── PairingService.ts   # Neighbor discovery for send pairing
│   ├── crypto/
│   │   ├── KeyManager.ts       # secp256k1 keygen, SecureStore persistence
│   │   ├── Signer.ts           # keccak256 + secp256k1 tx signing/verify
│   │   └── Encryptor.ts        # AES-256-GCM encrypt/decrypt per packet
│   ├── db/
│   │   ├── schema.ts           # SQLite table definitions (transactions, relay_buffer, ledger)
│   │   ├── TransactionRepo.ts  # CRUD for transactions + relay_buffer rows
│   │   └── LedgerRepo.ts       # Balance + nonce cache
│   ├── gateway/
│   │   └── GatewaySync.ts      # Relay buffer → RPC flush, confirmation poll, reconcile
│   ├── store/
│   │   ├── walletStore.ts      # Zustand: address, balance, pendingOutgoing
│   │   └── meshStore.ts        # Zustand: peers, relay buffer, mesh events
│   ├── hooks/
│   │   ├── useWallet.ts        # Wallet init, balance refresh
│   │   ├── useMesh.ts          # Mesh start/stop lifecycle
│   │   └── useTransactionQueue.ts # Outbox management
│   ├── context/
│   │   └── WalletContext.tsx   # Root context: key init, background task reg
│   ├── components/             # Shared UI primitives
│   └── constants/
│       ├── colors.ts           # Design tokens
│       └── config.ts           # WalletConnect project ID, Sepolia RPC
├── constants/
│   ├── ble.ts                  # BLE UUIDs, TTL, packet size, relay buffer cap
│   └── chain.ts                # Chain ID, RPC endpoints + fallbacks
├── plugins/
│   └── withBLEAdvertiserCompat.js  # Expo config plugin: Android BLE advertiser compat patch
├── scripts/
│   └── patch-native.js         # Post-install native patching
├── app.json                    # Expo config: permissions, bundle IDs, plugins
├── eas.json                    # EAS Build profiles (development, preview, production)
├── babel.config.js
├── metro.config.js
├── tailwind.config.js
├── tsconfig.json
└── vitest.config.ts            # Unit test config (crypto + BLE codec tests)

1. Clone and install dependencies

   git clone https://github.com/mkwallet/MeshWallet.git
   cd MeshWallet
   npm install

2. Set your WalletConnect Project ID

   Create a .env file in the repo root:

   echo "EXPO_PUBLIC_WC_PROJECT_ID=your_project_id_here" > .env

   Get a free project ID at https://cloud.walletconnect.com.

3. Install iOS native dependencies

   npx expo prebuild --platform ios
   cd ios && pod install && cd ..

4. Run on iOS simulator

   npm run ios

5. Run on Android emulator / device

   npm run android

6. Run unit tests

   npx vitest run

Note: BLE scanning and advertising require a physical device. Simulators will not discover peers.

To run native modules (BLE, SecureStore) that require a custom dev client:

npm run devbuild:android   # EAS cloud build → install APK on device

All other configuration is static in source:

1. Abstracts BLE central + peripheral simultaneously. Managing ble-plx (central) and react-native-ble-advertiser (peripheral) as separate libraries requires platform-specific glue code for Android API level splits and MIUI scan-filter bugs. The SDK collapses both roles into a single OfflineProtocol instance.
2. Native mesh routing. The SDK handles multi-hop relay internally; MeshRouter only needs to deduplicate and TTL-gate packets at the application layer, not implement flooding logic itself.
3. Stable public-key–based addressing. neighbor_discovered events expose peer_id which maps directly to the wallet's secp256k1 public key hex, enabling computeAddress() to derive the Ethereum address of a discovered peer with no extra handshake.
4. Transport-agnostic. The SDK can fall back to Wi-Fi Direct or other transports without API changes to BLEManager.ts.

1. Audited pure-TypeScript. No native bindings means the same code runs on iOS, Android, and in Vitest unit tests without mocking.
2. Explicit primitives. @noble/curves/secp256k1 exposes sign, verify, and getPublicKey directly; there is no hidden key-derivation abstraction that could silently weaken security.
3. Minimal bundle footprint. Tree-shaking eliminates unused cipher suites; only secp256k1, keccak_256, and aes/gcm are included in the final bundle.
4. @noble/ciphers AES-256-GCM. Authenticated encryption with per-packet 24-byte random nonces prevents replay attacks on the BLE mesh layer.

1. Fork the repository and create a feature branch from main:

   git checkout -b feat/your-feature

2. Make changes. Run lint and tests before committing:

   npm run lint
   npx vitest run

3. Commit with a conventional message (feat:, fix:, chore:, etc.).
4. Open a pull request against main. Describe the motivation and include relevant test output.

Code style: TypeScript strict mode, Prettier (config in prettier.config.js), ESLint (eslint.config.js). Run npm run format to auto-fix.

Private — all rights reserved.