MeshbellMeshbell Documentation
Meshbell is a neighborhood-scale emergency instrument. Its design principle is unusual for a consumer app: verification is the substrate, not a feature. This is how that works.
Overview
A hazard warning in Meshbell is a small, signed record — an assertion. Assertions are content-addressed (named by the hash of their own bytes), signed with a device key, and never altered: a correction is a new assertion that references the old one. That immutability is what lets a warning and its correction travel together across a mesh, and what lets any device re-check any message it receives.
Everything above the network is designed so that losing a connection, a server, or a model costs you an annotation, never the alert.
The trust model
Meshbell keeps two questions apart, because they are different facts and blurring them is how misinformation spreads:
| Question | What answers it | What it can say |
|---|---|---|
| Which record is this, and is it intact? | Content-address + signature check on your device | bound / preview / tampered |
| Who signed it, and can I check? | The on-device keyring | verified · could-not-check · forged |
The second axis is deliberately three-valued. A forgery (checked against a known key, failed) is not the same as an unknown key (no way to check yet) — collapsing them into one "invalid" would hide exactly the distinction a person needs. A message is stored as trusted only when the keyring says verified.
Verified off the air, with no prior copy
A short radio frame is a preview — a pointer at a record. But a record can also be sent in full as a self-authenticating envelope, split across several frames and reassembled on the far side. A device that has never seen the record before can then reconstruct it, re-derive its content address, and verify its signature — reaching a verified verdict on a pure-radio neighborhood with no internet anywhere in the loop.
The instruction firewall
The one thing an emergency app must never do is turn a rumor into an order. Meshbell enforces this structurally, not by review discipline:
- The screen that renders an instruction ("what to do") cannot even be constructed from an unverified message — the type system refuses it.
- Guidance text comes from a bundled, versioned playbook keyed by id, never from free text on the wire and never from a language model. A model can summarize a situation, in prose, labeled as inferred — it has no field in which to place a command.
- A relayed official alert is shown as a neighbor vouching, not as official, unless it proves a credential to an authoritative endpoint.
The promise, in one line: the app never launders a rumor into an instruction — and that sentence is a property of the code, not a mission statement.
Working offline
Degradation is the expected state, not an error. When a data path is down, Meshbell serves the last known good data labeled with its age ("as of 40 minutes ago") rather than a confident-looking blank. The zero-ML tier — an old phone with no on-device model — is a first-class product tier: an emergency app that only works on the newest hardware fails the people most likely to need it.
Radios & hardware
Meshbell runs on your phone alone. Radios extend its reach when the network is down. A neighborhood mesh is built from inexpensive, off-the-shelf LoRa hardware running open MeshCore firmware:
| Piece | Role |
|---|---|
| A companion LoRa radio (e.g. a Heltec node) | Your phone pairs with it over Bluetooth to send and hear bulletins on the mesh. |
| More radios around the neighborhood | Each one is a hop. Three or more begin to form real multi-hop reach across blocks and ridgelines. |
| An optional always-on node (e.g. a Raspberry Pi) | Bridges the mesh to the wider internet whenever any uplink is available, and keeps a durable log — "the phone is the head, the mesh is the body." |
Architecture
The domain logic is pure and portable — it builds and tests on a Raspberry Pi with no Apple hardware in the loop, so the parts that decide whether a message is trustworthy are verified continuously, not just at release. The iOS app is a thin renderer over it.
- Canonical JSON (sorted keys, ASCII-pinned) gives every device a byte-identical pre-image, so a content address computed on a phone matches one computed on a node.
- Ed25519 signing and verification, one implementation across Apple and Linux.
- An append-only, insert-only log: records are never updated or deleted, so history — including corrections — is preserved and re-verifiable.
- A cross-language conformance gate: the same frames are decoded by the app and by an independent Python node and asserted byte-for-byte, so the two can never silently drift.
Honest limits
Stated plainly, because an emergency tool that oversells itself is dangerous:
- Meshbell is an early beta. It has carried a signed bulletin across real LoRa radios and verified it on a phone — but it is not yet a substitute for official emergency channels. Keep your existing alerts on.
- Key distribution — how your device learns which public key belongs to whom — is an area of active work; a signature proves key-holding, and binding a key to a real identity is a separate, deliberate problem.
- On-device signing keys live in the device keychain and are extractable by anything that can already read the app's keychain; we do not claim hardware-enclave protection we cannot deliver.