avianlink is a Rust library for end-to-end encrypted text over packet links that lose half of what you send, deliver the rest hours later, and disappear for days. It treats the network as a postal service, not a connection.
Rust 1.82 · MIT ·
#![no_std] core with alloc · builds for
thumbv7em-none-eabihf and
aarch64-apple-ios at every commit
Say what is true, quietly.
That a message arrives in under a second, and that if it doesn't, something is wrong. Here a message may take an hour, a contact may be unreachable for days, and half the packets may never arrive. None of that is a fault — and an interface or protocol that treats it as one would be lying several times an hour.
send_text returns
once the message is committed to storage; delivery is a separate
event that may arrive much later.
The engine
The core does not own a socket, a clock, a thread or a filesystem. You hand it bytes, time and randomness; it hands you packets to transmit and events to show. The same code runs on a laptop, a phone and a microcontroller, because portability was a day-one constraint rather than a later port.
Inputs are handle_packet, send_text and
handle_timeout. Outputs are
poll_transmit, poll_event and
next_timeout. No async, no sockets, no hidden state —
so the whole protocol is testable in virtual time.
#![no_std] with alloc, integer math
only, no floating point in core logic. CI builds the core for
thumbv7em-none-eabihf and
aarch64-apple-ios on every commit, so the embedded
target can never quietly rot.
Every byte off the wire is untrusted. The core is
#![forbid(unsafe_code)] with no
unwrap, no panicking indexing and no unchecked
arithmetic on parsed values — enforced by lints, and checked by
cargo-fuzz targets on every parser.
Every packet is independently decryptable under ChaCha20-Poly1305, with keys derived from two static identities via HKDF and nonces derived from a per-direction counter. There is no handshake to complete and no session to lose.
A message ID is a truncated hash of its own encoded bytes, so duplicates are detected for free and a resend is idempotent. IDs are never put on the wire — both sides compute the same one from the content.
A Lamport clock per conversation, never wall-clock ordering. Messages are delivered to the host in arrival order together with their causal position, so a reply that shows up two hours late lands where it belongs instead of at the bottom.
Compact ACK bitmaps ride along with data whenever a packet is
going out anyway; receipts are the lowest-priority traffic.
A soft FRAG_ACK names which fragments landed, so a
25-fragment message under 50% loss converges in about 2× its size
instead of resending everything each round.
An RFC 6298-style estimator in integer milliseconds, sampled from packet counters rather than messages so retransmission ambiguity can't poison it. When a peer goes silent the contact drops to one probe packet per interval, capped at 30 s and never more than ~10% of a duty-cycled link's airtime.
The engine writes its own state through a Storage
trait you implement, in atomic batches committed
before the matching in-memory change. Restore mid-flight
and nothing is lost or duplicated; packet counters are reserved in
blocks so a nonce is never reused.
You register each link with its MTU, a rate or duty-cycle budget — airtime is often legally limited — and a relative cost. The engine fragments, paces and schedules per link. It never infers congestion from loss, because on these links loss isn't congestion.
Most messages fit one packet, so repair is coded across messages: a sliding window emits XOR parity packets — Reed–Solomon later — so one repair recovers any one loss in its window, at a rate that adapts to each link's measured loss.
A peer returning after a week offline reconciles what each side holds using compact per-conversation hash ranges, rather than "send everything since X" — and makes progress even when only a fraction of its sync packets arrive.
Security model
Identity is an Ed25519 keypair, used in its X25519 form for Diffie–Hellman. Contacts are added from a public key exchanged out of band — a QR code, a read-aloud fingerprint — and there is no handshake to intercept. The non-goals are stated as prominently as the goals, because a protocol that oversells itself is a hazard.
Storage, so encrypt it.
# pairwise key schedule, for contacts A and B
s = X25519(sk_A, PK_B) # reject all-zero output
prk = HKDF-SHA256-Extract(salt = "avianlink/v1/pair", ikm = s)
key A→B = HKDF-Expand(prk, "key" ‖ PK_A ‖ PK_B, 32)
tag A→B = HKDF-Expand(prk, "tag" ‖ PK_A ‖ PK_B, 3)
nonce = counter as u64 little-endian ‖ 00 00 00 00a1b2-c3d4-e5f6-7890-abcd
Wire format
The first byte is a version, because peers will run mismatched builds for years. Everything after it is varints, a three-byte routing tag and counter-derived nonces — because at a 48-byte MTU every header byte is text you didn't send.
Associated data: the header, authenticated but not encrypted Nonce: from the counter, never sent in full
| MTU | Text in one packet | Fragment payload | Efficiency |
|---|---|---|---|
| 48 B | 12 B | 18 B | 37% |
| 51 B · LoRa | 15 B | 21 B | 41% |
| 64 B | 28 B | 34 B | 53% |
| 128 B | 92 B | 98 B | 76% |
| 255 B | 218 B | 224 B | 87% |
| 512 B · EDGE | 475 B | 481 B | 93% |
| 1200 B | 1163 B | 1169 B | 97% |
At a 48-byte MTU the full 16-byte Poly1305 tag costs a third of the packet. It isn't truncated anyway: saving eight bytes would mean composing ChaCha20 and Poly1305 by hand instead of using an audited AEAD, and v1 declines that trade.
Simulator
You cannot debug a protocol like this on a real radio. So the simulator is held to the same standard as the engine: virtual time, a seeded RNG, and any failing run reproducible exactly from its seed. Impairments include heavy-tailed delay, Gilbert–Elliott bursty loss, bit flips, duplication, reordering, duty-cycle limits and scheduled outages.
Lab conditions. Measures the engine's own overhead.
GEO VSAT: ~550 ms round trip, 64 kbit/s, rain fade.
2G EDGE: slow, spiky, Pareto-tailed latency.
Overloaded, damaged cellular: corruption, duplication, reordering.
EU868 at SF9: a 51-byte packet costs ~0.37 s of airtime.
| Variant | p50 | p95 | p99 | Wire / payload |
|---|---|---|---|---|
| Fixed 4 s RTO, no backoff | 5.3 s | 6.5 m | 10.6 m | 23.9× |
| RFC 6298 as written, 120 s cap | 39.1 s | 13.2 m | 19.1 m | 3.65× |
| 2·rttvar, 30 s cap | 33.1 s | 13.1 m | 24.7 m | 3.87× |
| 2·rttvar, 30 s cap, 2 grace probes | 8.4 s | 7.5 m | 11.3 m | 4.75× |
| 1·rttvar, 10 s cap, 3 grace | 5.5 s | 6.5 m | 11.3 m | 7.04× |
The chosen point holds p95 and p99 within about 15% of the naive
fixed-timer build while spending a fifth of the bytes — and it is the
knee of the curve: pushing further buys little latency for a lot of
bandwidth. All three knobs are plain Config fields for
hosts that weigh latency and airtime differently.
Desktop app
A Tauri 2 app — Svelte 5 front end, Rust and SQLite behind it — built on one rule: tell the truth about what has and hasn't happened, and be calm about it. The user decides whether it's a problem. Private keys stay in the backend and in the OS keychain; the front end sees public keys and fingerprints only.
Each state differs in shape, not just tone, and the set still reads correctly in greyscale. Colour is a redundant second channel; only failed gets a hue, and it has its own glyph too.
Sending is a local durable write, so it always succeeds instantly and it never shows an error about a link. No spinners, no "reconnecting…", no red badge for a network doing exactly what it was designed for.
The thread is ordered by the library's causal order, not arrival time. A reply that arrives hours after the message it answers inserts into the right position with a subtle "arrived later" marker — and without yanking your scroll position.
Which links are up, recent loss, and time since the last packet from each contact. Informative, never alarming: being offline for a day is normal here, and the chrome says so without raising its voice.
Your own key as a QR code, a copyable string and five groups of four hex characters. Comparison is made easy and explained in one sentence, because out-of-band verification is the whole trust model.
A virtualized thread over backend pagination, on SQLite with versioned migrations. Writes the library treats as durable are durable before the engine is told they succeeded.
Status
Every phase ends with a report: what was built, test results, simulator metrics, open questions, and anything that deviated from the plan and why. Significant choices and the alternatives rejected are kept in a decision log.
handle_packet.
Done
tc netem profiles mirroring the simulator's.
Planned
cbindgen, an iOS XCFramework, and an
example on real microcontroller hardware.
Planned
Horizontal lines trace a gull in flight, each one a packet, fading from the wingtips toward the body like a signal tailing off. One wing line breaks in two — a nod to loss, and to recovery.