- Kotlin 96%
- Rust 2%
- Shell 2%
iroh-aware #
Your iroh endpoint, announced from your pocket. An Android app that advertises an iroh endpoint over Wi-Fi Aware peer-to-peer discovery — no internet, no shared LAN, no server. Named Data Networking is the long-game successor to the announcement layer.
The idea: signaling, not a pipe #
iroh splits connection setup into two planes, and the split is the whole design:
| Plane | Job | In iroh |
|---|---|---|
| Discovery (control) | "where is node X reachable?" — given a NodeId, produce addressing data |
Pluggable Discovery trait; ships with DNS/pkarr, mainline DHT, mDNS backends |
| Transport (data) | actually move bytes | QUIC over UDP — hole-punched direct, relay fallback |
So this project is a rendezvous publication, not a tunnel. We write a small record — who we are, where to try us — into a local radio channel that peers can hear, and let iroh do everything hard about connecting. Wi-Fi Aware's service discovery maps onto this almost embarrassingly well:
publish()↔ announce our recordsubscribe()↔ discover peers' records- service-specific-info blob ↔ the record itself (44-byte fixed header + TLVs, 200-byte budget)
And one genuinely speculative idea keeps the door open: the Wi-Fi Aware NAN
datapath is a real IP interface pair between two nearby phones. If QUIC can
ride it (irhdn-datapath), then the discovery medium becomes a
transport and the whole stack works with zero infrastructure.
What works today vs what doesn't #
| ✅ Works | ⏳ Pending | ❌ Not yet |
|---|---|---|
| Compiles to debug APK, JVM tests green | On-device publish-session verification (irhdn-discovery-publish) |
Dialing discovered peers (needs embedded core, irhdn-discovery-dial) |
| Wire-format codec w/ full round-trip test matrix | Two-device resolve verification (irhdn-discovery-resolve) |
Real ed25519 identity — current NodeId is a persisted random placeholder (caveat) |
| Dual-role Aware link: publish and subscribe on one attach | Verifying the true NAN service-info cap (~255B cited, unconfirmed) | Embedded iroh core / JNI pipeline (irhdn-transport-jni) |
| Runtime permission flow for API 33+ and ≤32 | WebTransport gateway, NDN layer |
Roadmap #
Tracked in beads — bd list, prefix irhdn.
| Ver | Epic | Scope | Status |
|---|---|---|---|
| v0 | — | Compilable skeleton: mise toolchain, Gradle wrapper, Aware availability probe | ✅ done |
| v1 | irhdn-discovery |
Announce/resolve endpoint records over Wi-Fi Aware | ◐ code complete, device verification open |
| v2 | irhdn-transport |
Embedded iroh core via JNI/cargo-ndk; real dialing; QUIC over the NAN datapath; WebTransport spike | open |
| v3 | irhdn-ndn |
NDN-style named announcements, trust schema, forwarder evals, presence sync | open, speculative |
Dependency shape (from bd list): survey → record → {publish, resolve} → dial;
everything transport-shaped hangs off irhdn-transport-jni → -endpoint.
How it works #
app/src/main/java/com/superbfowle/iroh/aware/
├── MainActivity.kt permission flow, start button, peer list UI
└── aware/
├── EndpointRecord.kt wire format v1 codec — strict decode, tolerant TLVs
├── Identity.kt placeholder NodeId: SecureRandom 32B, prefs-persisted
└── AwareLink.kt ONE attach, BOTH roles (mirrors the bitchat reference)
Wire format v1 (full spec: .design/wifi-aware/wire-format.md):
offset size field
0 1 version = 0x01
1 32 node_id raw iroh NodeId (ed25519 pubkey)
33 2 quic_port u16 big-endian; 0 = unspecified until v2
35 8 timestamp_sec u64 big-endian unix seconds
43 1 flags bit 0: relay TLV follows
44 .. TLVs type u8, len u8, value — 0x01 = "host[:port]" relay
Decoders are strict about the header (version, truncation, unknown flags) and tolerant of unknown TLV types, so v2/v3 can extend without breaking v1 readers.
Design decisions worth knowing:
- No signature in v1. The NodeId is the identity; spoofing resistance arrives with iroh's own handshake when dialing lands. Signed envelopes (pkarr-style) are the NDN-era concern.
- There is no peer-lost callback on
DiscoverySessionCallback— peer expiry is a timestamp filter in the UI, not an event. - NAN beacons are immutable: a changed record means stop/start republish. Cheap enough for now; revisit when a live endpoint makes records change often.
Building #
Toolchain is mise-managed — Java 17 (Temurin), Gradle
8.14.5, AGP 8.13.2, KGP 2.3.21, compileSdk/targetSdk 35, minSdk 26 (the
Wi-Fi Aware baseline, matching n0's own Android demo). ANDROID_HOME resolves
through mise.toml; no emulator or device needed to build.
mise exec -- ./gradlew :app:assembleDebug # APK → app/build/outputs/apk/debug/
mise exec -- ./gradlew :app:testDebugUnitTest # wire-format test matrix (9 tests)
mise exec -- ./gradlew :app:assembleDebug :app:testDebugUnitTest
Provisioning details and every gotcha hit along the way (Debian's ancient system
Gradle, core-ktx↔AGP compatibility pins, SDK licensing) live in
.design/android-skeleton/setup-notes.md.
Running on hardware #
adb install -r app/build/outputs/apk/debug/app-debug.apk
Grant the nearby-devices prompt, hit Announce & browse. Two phones running the app should list each other within seconds of NAN discovery. First check a device supports Aware at all — OEM firmware routinely ships API 26+ with the feature disabled; Ditto's wifi-aware-checker app answers that in one tap.
Prior art & references #
Each of these earned its place by contributing something concrete:
n0-computer/iroh-liveAndroid demo — the template for v2: cargo-ndk → jniLibs pipeline, Kotlin JNI bridge, strip step, minSdk-26 rationale. Local checkout:~/archive/n0-computer/iroh-live.NodleCode/wifi-aware— research notes plusWifiAwareMeshServiceLatest.kt, a complete working dual-role mesh service. OurAwareLinkstructure follows its attach-once/publish+subscribe pattern. Not a library — prior art only.- Android Wi-Fi Aware overview — platform API surface, permission model, datapath mechanics.
getditto/wifi-aware-checker— documents the OEM-firmware lottery; its availability-probe pattern is in our stub.m1ga/ti.wifi-aware— Titanium module; clearest minimal publish/subscribe/message flow and theNEARBY_WIFI_DEVICESrequest order.- iroh
Discoverytrait — the upstream shapeirhdn-discovery-rust-traitwants to fill: NAN announce/resolve behind aDiscoveryimpl any RustEndpointcould use. - pkarr — signed DNS packets; iroh's existing announcement envelope and the natural bridge from our TLV records to named signed data.
- Named Data Networking ·
NFD-android— the v3 horizon: names instead of channels, interests as pull-based rendezvous.
Deeper dives live under .design/ — capability survey, wire-format
rationale, toolchain notes — each written against the tickets that consumed them.