msgp2p_flutter library
Flutter plugin and high-level SDK facade for msgp2p delay-tolerant group sync.
Classes
- AdaptiveScanScheduler
-
Adaptive radio scan duty-cycle scheduler (
NFR-PWR-01). - AndroidBlePeerLink
- Concrete PeerLink representing an active Android BLE connection (L2CAP CoC or GATT).
- AndroidBleTransport
-
Android BLE implementation of P2PTransport supporting Extended Advertising,
L2CAP CoC / GATT byte links, and adaptive PHY switching (
FR-SDK-03,FR-SYNC-06). - AttachmentRef
- Reference to an external bulk attachment (image, telemetry, etc.).
- AuthorState
- The held sequence state for a single author.
- AuthorWant
- Request for specific missing sequence ranges from an author.
- BeaconTokenGenerator
- Rotating anonymous BLE beacon discovery token generator and verifier as specified in protocol/wire-format.md §5.
- BleRadioBridge
- Thin byte-level bridge interface to native platform BLE hardware (FR-SDK-02).
- BleRadioEvent
- Sealed hierarchy of low-level radio events emitted by native BLE adapter (FR-SDK-02).
- BlobData
- Session BLOB_DATA payload (Type 0x18) carrying a hash-addressed attachment blob.
- BlobWant
- Session BLOB_WANT payload (Type 0x17) for requesting hash-addressed attachments over bulk links.
- BroadcastChunkPacket
- A discrete MTU-sized chunk packet formatted for broadcast transmissions (e.g. LoRa / Meshtastic).
- BroadcastChunkReassembler
- Reassembles broadcast chunks into complete BroadcastFrames.
- BroadcastChunkSlicer
- Slices a BroadcastFrame into MTU-sized BroadcastChunkPackets.
- BroadcastEngine
- Coordinator for unacknowledged 0-RTT broadcast push mode across packet radios (e.g. LoRa / Meshtastic).
- BroadcastFrame
- Self-contained asynchronous 0-RTT broadcast message wrapper for low-bandwidth packet radios.
- BroadcastPacket
- A raw radio packet received over an unacknowledged broadcast medium (e.g. LoRa / Meshtastic).
- BroadcastTransport
- Abstract radio transport supporting unacknowledged broadcast transmissions.
- ByeMessage
- Session BYE payload (Type 0x1F).
- ByeReason
- Disconnect reasons for BYE frame (0x1F).
- CanonicalCbor
- Deterministic Canonical CBOR encoder implementing RFC 8949 Section 4.2.
- CertReq
- Session CERT_REQ payload (Type 0x15).
- ChunkPacket
- A discrete radio-layer chunk packet as specified in protocol/wire-format.md ?6.2.
- ChunkReassembler
- Collects chunk packets and reassembles complete protocol frames.
- ChunkReceivedRadioEvent
- Emitted when a raw byte chunk arrives from a connected peer.
- ChunkSlicer
- Slices frames into MTU-sized chunk packets.
- ChurnTraceAnalyzer
- Trace analyzer computing amplification, flap-resilience, and data-structure metrics (IT-OBS-02).
- Clock
- Clock interface to allow deterministic virtual-time simulation and test injection.
- ClockRules
- Clock validation rules and tolerance constants per protocol/wire-format.md §4.4 & §8.
- Crc16
- CRC-16/IBM (also known as CRC-16/ARC or CRC-16/ANSI). Polynomial: 0x8005 (reversed/reflected: 0xA001), Init: 0x0000, XorOut: 0x0000. Check value for ASCII "123456789": 0xBB3D.
- DecryptedMessage
- Decrypted application-level message emitted by MsgP2PNode (FR-SDK-04).
- DeterministicRandomSource
- Deterministic, reproducible pseudorandom source for simulation and tests.
- DiscoveredPeerInfo
- Diagnostic peer entry displayed on the Peer Radar screen (FR-APP-03).
- Envelope
- Full envelope relayed across the P2P mesh and central server gateway.
- EnvelopeCore
- Immutable core of a message envelope (hashed for messageId and signed by author).
- FakeMedium
-
Simulates a shared radio environment connecting multiple FakeTransport instances.
Supports dynamic topology graphs, runtime partitions, seeded loss/latency,
mid-transfer link cutting (
IT-FI-02), half-open links (IT-FI-04), silent stalls (IT-FI-05), and directional asymmetric links (IT-FI-09). - FakePeerLink
- In-memory bidirectional link implementation for FakeTransport.
- FakeTransport
- Pure Dart in-memory P2PTransport implementation for unit tests and simulation.
- FlappingConfig
- Frame
- Discrete protocol frame as specified in protocol/wire-format.md ?6.1.
- FrameParser
- Accumulates streaming byte chunks and extracts complete Frames.
- GatewayClient
- Gateway HTTP client connecting a mobile mule node with the reference server (FR-SRV-02).
- GroupKeyDto
- Symmetrically shared group key epoch info.
- GroupMembership
- Active group membership context on a multi-tenant device.
- GroupStorePool
- Manages a pool of isolated MessageStore instances implementing the Store-per-Group pattern.
- IdentitySeeds
-
The long-lived identity of this device (
FR-ID-01): the seeds of its Ed25519 signing key and its X25519 Noise key. Proposal 0001, step 2; decisions in Discussion #10. - IosBlePeerLink
- Concrete PeerLink representing an active iOS CoreBluetooth connection (L2CAP CoC or GATT).
- IosBleTransport
-
iOS CoreBluetooth implementation of P2PTransport supporting Central/Peripheral roles,
L2CAP CoC / GATT fallback, foreground participation, and best-effort background state restoration (
v0.2). - KeyVault
-
Keeps this device's identity across restarts (
FR-ID-01). The SDK never stores seeds itself. - LinkClosed
- Emitted when the link is closed by either peer or a radio drop.
- LinkEvent
- Events emitted during the lifecycle of an active PeerLink.
- LoginResult
- Result of user authentication.
- LoopbackBleMedium
- Shared virtual radio medium connecting multiple LoopbackBleRadioBridge instances for deterministic contract testing and emulator-free UI testing (FR-TEST-03).
- LoopbackBleRadioBridge
-
In-memory BleRadioBridge implementation for testing AndroidBleTransport
against the
P2PTransportcontract suite without physical Bluetooth hardware. - LoopbackWifiAwareMedium
-
Shared virtual Wi-Fi Aware medium connecting multiple LoopbackWifiAwareRadioBridge
instances for deterministic contract testing and BLE -> Wi-Fi Aware upgrade tests (
FR-TEST-03). - LoopbackWifiAwareRadioBridge
- In-memory WifiAwareRadioBridge for testing WifiAwareTransport and session upgrades.
- MembershipCert
- Server-issued membership certificate granting access to a group.
- MemoryKeyVault
- In-memory vault for tests and short-lived nodes: an identity that lasts as long as the object.
- MemoryMessageStore
- In-memory implementation of MessageStore designed for fast unit testing, simulator runs, and memory-only mesh relay configurations.
- MeshHarness
- Orchestrates an in-process multi-node mesh test environment (FR-TEST-08).
- MeshNode
- Represents an active in-process mesh node running pure Dart protocol components.
- MeshTraceEvent
- A structured event recorded during multi-node mesh execution (JSONL trace schema).
- MessageStore
- Abstract contract for local message storage, receipts, certs, peer history, and vector indexing.
- MethodChannelBleRadioBridge
-
Production BleRadioBridge backed by Flutter
MethodChannelandEventChannel. - MethodChannelWifiAwareRadioBridge
-
Production WifiAwareRadioBridge backed by Flutter
MethodChannelandEventChannel. - MsgP2PConfig
- Configuration for initializing a MsgP2PNode (FR-SDK-04).
- MsgP2PCrypto
- Cryptographic services for msgp2p.
- MsgP2PNode
-
High-level payload-agnostic Flutter SDK facade for
msgp2p(FR-SDK-04). - MultiGroupBeaconManager
- Manages multi-group rotating beacon advertising and token matching for multi-tenant nodes.
- MultiGroupSyncCoordinator
- Orchestrates sequential group synchronization sessions over a persistent PeerLink.
- MutableClock
- Mutable virtual clock supporting deterministic advances and jumps (IT-FI-11).
- NodeClock
- Per-node clock wrapper applying a deterministic clock skew (IT-FI-08).
- NoiseCipherState
- Cipher state using ChaCha20-Poly1305 with uint64 little-endian nonce.
- NoiseHandshake
- Implements the Noise-XX mutually authenticated handshake bound to server-signed membership certificates per protocol/wire-format.md §7.1 and FR-SEC-06.
- NoiseHkdf
- RFC 5869 HKDF using SHA-256 for Noise protocol key derivation.
- NoiseInitiatorState
- Initiator side of Noise-XX handshake.
- NoiseInitiatorStepResult
- NoiseResponderState
- Responder side of Noise-XX handshake.
- NoiseSession
- Established authenticated Noise session holding symmetric transport ciphers.
- P2PTransport
- Abstract radio transport interface per architecture.md ?5.1 and FR-SDK-03.
- PeerAdvert
- Advertisement discovered from a nearby peer.
- PeerConnectedRadioEvent
- Emitted when a BLE L2CAP CoC or GATT link is established with a peer.
- PeerCooldownState
-
Ephemeral in-memory (Tier 3) per-peer reconnect cooldown and rate-limit tracker
(
FR-SYNC-07,IT-FLAP-03,IT-DS-05c,architecture.md §4). - PeerCooldownTracker
- PeerDailyStat
-
Tier 2 authenticated per-member daily summary (
FR-SYNC-08,IT-DS-05b,architecture.md §6). Keyed by(memberPubkey, dayDate)wheredayDateis UTC midnight in milliseconds. Retained for 90 days by default. - PeerDisconnectedRadioEvent
- Emitted when a peer connection closes or drops.
- PeerDiscoveredRadioEvent
- Emitted when a BLE advertisement carrying a group beacon token is scanned.
- PeerLink
- Bidirectional communication pipe between two connected peers.
- PeerSighting
-
Tier 1 anonymous rotating beacon sighting (
FR-SYNC-08,IT-DS-05a,architecture.md §6). Retained for <= 24 hours with at most one row per(token, rotationWindow). - PhyChanged
- Emitted when radio PHY changes (e.g. 1M -> Coded PHY on Android BLE).
- PhyChangedRadioEvent
- Emitted when the controller updates TX/RX PHY for a peer connection.
- PlatformKeyVault
-
A KeyVault in the platform keystore (
FR-ID-01; proposal 0001, step 2b; Discussion #10): - PullResult
- Result of envelope delta pull.
- PushResult
- Result of envelope ingestion push.
- RandomSource
- Abstraction for random byte generation.
- RegisterResult
- Result of user registration.
- RejectedItem
- Rejected envelope item with specific failure reason.
- RevocationNotice
- Server-signed member revocation notice.
- RevokeMemberResult
- Result of revoking a group member and rotating the group key epoch (FR-SEC-02).
- RssiChanged
- Emitted when signal strength changes on an active link.
- RssiUpdatedRadioEvent
- Emitted when a connected peer's RSSI is sampled.
- ScanPolicy
- Scanning policy configuration.
- Scenario
-
Unified YAML Scenario definition shared across in-process MeshHarness,
discrete-event simulator (
msgp2p_sim), and emulator test runners (FR-TEST-08). - ScenarioAssertion
- ScenarioContact
- ScenarioGateway
- ScenarioNode
- ScenarioWorkload
- SeqRange
-
An inclusive range of message sequence numbers:
fromSeq, toSeq. - ServerReceipt
- Server-signed batch receipt (anti-packet) confirming message sequence numbers stored on cloud.
- SessionFrameType
- Protocol frame type codes per protocol/wire-format.md §7.
- SessionStateMachine
- Orchestrates peer-to-peer session synchronization over PeerLink.
- SessionSummary
- Session SUMMARY payload (Type 0x10).
- SessionSyncResult
- Statistics and outcome of a completed or terminated session.
- SessionUpgradeCoordinator
-
Coordinates automatic session upgrade from BLE (
AndroidBleTransport/IosBleTransport) toWifiAwareTransportwhen pending transfer exceeds upgradeThresholdBytes or when hash-addressed attachment blobs need to be synced, followed by immediate teardown (v0.2). - SessionWant
- Session WANT payload (Type 0x11).
- SqliteMessageStore
-
Persistent SQLite implementation of MessageStore using WAL mode and
atomic batch transactions (
NFR-REL-01,FR-SYNC-05,FR-SYNC-08). - StoredAttachmentBlob
- Metadata wrapper for a hash-addressed attachment blob stored locally.
- StoredEnvelope
- Metadata wrapper for an envelope stored locally on this node.
- SyncResult
- Summary of an automated bidirectional sync operation with gateway.
- SystemClock
- System wall-clock implementation for production runtime.
- SystemRandomSource
- System CSPRNG implementation using math.Random.secure.
- TransportCapabilities
- Capabilities and limits of a specific P2PTransport radio.
- UpgradeAccept
- Session UPGRADE_ACCEPT payload (Type 0x1A) responding to an upgrade offer.
- UpgradeOffer
- Session UPGRADE_OFFER payload (Type 0x19) proposing BLE -> Wi-Fi Aware upgrade.
- UpgradeSyncOutcome
-
Combined outcome of a BLE session that optionally upgraded to Wi-Fi Aware (
v0.2). - VersionVector
- Version vector representing the state of all authors known to a node.
- VirtualClock
- Controllable virtual clock for deterministic multi-node simulation (FR-TEST-08).
- WifiAwareChunkReceivedEvent
- Emitted when a raw byte chunk arrives over a Wi-Fi Aware data path.
- WifiAwareConnectedEvent
- Emitted when a Wi-Fi Aware high-throughput data path is established with a peer.
- WifiAwareDisconnectedEvent
- Emitted when a Wi-Fi Aware data path closes or is torn down.
- WifiAwarePeerDiscoveredEvent
- Emitted when a Wi-Fi Aware (NAN) peer publishing the group service is discovered.
- WifiAwarePeerLink
- Concrete PeerLink representing an active Wi-Fi Aware (NAN) high-throughput data path.
- WifiAwareRadioBridge
-
Thin byte-level bridge to native Wi-Fi Aware hardware:
Android
WifiAwareManager(API 26+) and iOS 26+WiFiAwareframework (FR-SDK-02). - WifiAwareRadioEvent
- Sealed hierarchy of low-level radio events emitted by the native Wi-Fi Aware adapter (FR-SDK-02).
- WifiAwareTransport
-
High-throughput Wi-Fi Aware (Neighbor Awareness Networking) implementation of P2PTransport
for Android 8+ (
WifiAwareManager) and iOS 26+ (WiFiAwareframework, iPhone 12+) (v0.2).
Enums
- BlePhyMode
- Supported BLE PHY modes on Android 8.0+ (API 26+) (FR-SYNC-06).
- MeshEventType
- Event categories for structured multi-node trace logging (FR-TEST-08, IT-OBS-01).
- MessageDeliveryStatus
- Per-message delivery status badge states (FR-APP-02).
- Priority
- Priority levels for published messages (FR-SYNC-03).
- SessionPhase
- Phase states of an active synchronization session.
- UnsynchronizedIdentityReason
- Why guardStoreIdentity refused to let this node author.
Constants
- broadcastMagicByte → const int
- Magic byte identifying a 0-RTT broadcast chunk packet.
- maxChunksPerFrame → const int
- Maximum allowable chunks per fragmented frame per protocol/wire-format.md ?8.
- noiseXxProtocolName → const String
- Constant protocol identifier for Noise_XX pattern over Curve25519, ChaCha20-Poly1305 and SHA-256.
Functions
-
guardStoreIdentity(
{required MessageStore store, required Uint8List ownerPubkey, required bool created}) → Future< int> -
Checks that
storebelongs to the identityownerPubkeybefore the node authors, and returns the last sequence number this identity used (0 for none).createdsays whether the vault created the identity just now.
Typedefs
-
GroupStoreFactory
= Future<
MessageStore> Function(Uint8List groupId) - Factory signature for initializing a MessageStore for a specific group.
- KeyVaultLoad = ({bool created, IdentitySeeds seeds})
- What KeyVault.loadOrCreate returns: the seeds, and whether this call created them.
Exceptions / Errors
- EnvelopeSizeLimitException
-
Thrown when an envelope core exceeds the 4 KB (4096-byte) protocol hard limit (
requirements.md §3). - GatewayException
- Exception thrown when the gateway server returns an error.
- KeyVaultCorruptedError
- The stored seeds cannot be read or are malformed (truncated, wrong length, unknown version).
- The stored seeds exist but cannot be decrypted on this device, typically because a backup carried the encrypted file to another device while the keystore key stayed behind. The host should call KeyVault.erase and start with a new identity (Discussion #10).
- SecurityException
- Exception thrown when cryptographic or certificate verification fails during handshake.
- UnsynchronizedIdentityException
-
The vault and the store disagree about who this node is. Authoring now could reuse
(author, seq)pairs that peers already hold with different content. The host either restores the store that belongs to this identity, or callsKeyVault.erase()for a new identity (new certificate,seqfrom 1). Discussion #10.