Feature: Bull Mesh Offline Transaction Relay

[atomauro]

Fix the money Fix the world

Overview

This Pull Request integrates Bull Mesh, a resilient offline communication layer allowing signed Bitcoin transactions to be broadcast without an Internet connection. The system leverages Bluetooth Low Energy (BLE) to propagate transactions to nearby peers (Relays), who then forward them to the Bitcoin Mempool.

Technical Architecture

The implementation utilizes a three-tier architecture designed to overcome standard BLE data limitations and OS-level background execution constraints.

1. Fragmentation Protocol (MeshProtocol)

To bypass the standard BLE MTU limit (~23-512 bytes), a custom application-layer fragmentation protocol has been implemented in lib/core/mesh/mesh_protocol.dart.

• Payload Segmentation: Transactions are serialized into raw Hex and split into chunks of 500 bytes.
• Header Structure: Each chunk is prefixed with a 2-byte header [TotalChunks (1B) | ChunkIndex (1B)].
• Capacity: Supports payloads up to ~127KB (255 chunks), sufficient for large CoinJoin or Multisig transactions.
• Reassembly: The receiver utilizes a buffer map Map<int, Uint8List> to accumulate chunks out-of-order, reassembling the full payload only when map.length == totalChunks.

2. Persistent Background Services (MeshBackgroundService)

To ensure high availability of Relays, the system implements OS-specific background persistence strategies.

• Android (Foreground Service):
  • Utilizes flutter_background_service to spawn a dedicated Isolate.
  • Promotes the process to a Foreground Service with a pinned notification ("Sentinel Mode").
  • Ensures the BLE scanning process is not terminated by the Android Low Memory Killer (LMK).
• iOS (Background Modes):
  • Configured with bluetooth-central, bluetooth-peripheral, and fetch capabilities in Info.plist.
  • Operates on a "Best Effort" execution model compliant with iOS BGAppRefresh policies.
• Isolate Communication Bridge:
  • Implements a bi-directional event channel to safely marshal data between the Background Isolate (Scanner) and the Main UI Isolate.
  • Methods injectIncomingTx and injectDownloadProgress in MeshService handle the safe ingestion of background events.

3. Transmission Strategy: "Looping Beacon"

The Sender implements a cyclic transmission strategy to maximize connection probability without strict handshakes:

• Cyclic Advertising: The sender iterates through the transaction chunks indefinitely (1->2->3...1->2->3).
• Asynchronous Connection: Receivers can initiate connection at any point in the cycle.
• Latency Tolerance: Duplicate chunks are discarded; missing chunks are awaited in the next cycle.

---

User Interface Implementation

Sender: Adaptive Radar (MeshSignalAnimation)

• State Machine: Visualizes three distinct states:
  1. Scanning: Low-frequency pulse animation.
  2. Handshake: High-frequency "Lock-on" animation upon peer connection.
  3. Transmission: Deterministic progress ring driven by the uploadProgressNotifier.

Receiver: Reactive Dashboard (MeshRelayDashboard)

• Event-Driven UI: The dashboard is triggered automatically via downloadProgressNotifier (start of transmission) or incomingTransactions stream (completion).
• Progress Visualization: Displays real-time byte reassembly status.
• Verification: Shows the computed TxID only after the reassembled payload passes Hex validation.

---

Security & Validation

• Input Sanitization: Incoming payloads undergo strict RegEx validation (^[0-9a-fA-F]+$) before any interaction with the BDK (Bitcoin Dev Kit).
• Sandboxing: The Mesh service operates completely independently of the wallet's key storage. It acts strictly as a data transport layer for pre-signed raw transactions.

---

Verification

Unit Testing

• test/core/mesh/mesh_protocol_test.dart:
  • Logic: Validates the splitting and rejoining of Uint8List payloads.
  • Edge Cases: Verifies handling of out-of-order chunk arrival and partial datasets.

Manual Verification

• Throughput: Verified successful transmission of 2KB+ transaction payloads.
• Persistence: Confirmed Android Service persistence across app minimization and device sleep states.
• Interoperability: Validated communication between Android and iOS devices.

---

File Manifest

• Protocol: lib/core/mesh/mesh_protocol.dart
• Service: lib/core/mesh/mesh_service.dart, lib/core/mesh/mesh_background_service.dart
• UI: lib/features/broadcast_signed_tx/presentation/widgets/
• Config: android/app/src/main/AndroidManifest.xml, pubspec.yaml

[atomauro]

Hey guys, I'm attending your talk at the Medellín Bitcoin conference. Great stuff, thanks and keep building!

[ethicnology]

Hello @atomauro and thanks for your interest in improving BULL wallet

I have remarks/questions:

1. I'm familiar with mesh networks in the case of messaging when an oppressive authority cut internet (and does not jam bluetooth) with apps like briar. Since Bitcoin transactions eventually need to hit the mempool via internet or satellite, how do you envision that final hop happening? Does the mesh look for a peer with an active connection?
2. Is your protocol compatible with existing mesh protocol ?
3. The wallet already use the workmanager package to schedule background tasks, it's better to re-use it rather than importing extra package to limit the supply chain attacks.
4. Android supports foreground tasks, but iOS foreground are mostly background tasks. Do you think you can tweak the implementation to make it work only with background tasks (and the current implementation of workmanager)?

[i5hi]

Awesome effort! This sounds very interesting!! Thank you!

You will have to give us some time to review and test this since its not part of our scope and we are in the middle of 2 huge releases back to back till March.

How did you test this? Will be great if you give us some screenshares or videos so we get an idea.

[ethicnology]

This PR seems stale with no answers from the maintainer in two months.

If we do implement a mesh networks, we will likely follow an existing standardized protocol like FIPS.

I'm closing this PR, but author can re-open it, if wants to follow up