archy/.claude/skills/mesh/SKILL.md

---
name: mesh
description: Mesh networking development for Archipelago — protocol, crypto, serial driver, transport abstraction, and LoRa chat. Use when working on mesh radio, Meshcore protocol, LoRa messaging, transport layers, peer discovery, or off-grid communication features.
---

# Mesh Networking Skill

## Architecture

The mesh subsystem enables offline peer discovery and end-to-end encrypted messaging between Archipelago nodes via Meshcore LoRa radio devices (Heltec V3, T-Beam, RAK WisBlock).

```
USB Meshcore Device (115200 baud)
    ↕ serial2-tokio
core/archipelago/src/mesh/
├── mod.rs         — MeshService: lifecycle, config, public API
├── types.rs       — MeshPeer, MeshMessage, MeshStatus, MeshEvent
├── protocol.rs    — Meshcore binary frame protocol (encode/decode)
├── serial.rs      — MeshcoreDevice: async serial driver
├── crypto.rs      — X25519 ECDH + ChaCha20-Poly1305 encryption
└── listener.rs    — Background tokio task: serial reader + dispatcher
    ↕ RPC
core/archipelago/src/api/rpc/mesh.rs — 6 endpoints
    ↕ HTTP
neode-ui/src/stores/mesh.ts     — Pinia store
neode-ui/src/views/Mesh.vue     — Two-column chat UI
```

## Key Files

### Backend (Rust)
- `core/archipelago/src/mesh/mod.rs` — MeshService (start/stop/status/peers/messages/send/configure)
- `core/archipelago/src/mesh/types.rs` — All shared types
- `core/archipelago/src/mesh/protocol.rs` — Binary frame format, command builders, response parsers (12 unit tests)
- `core/archipelago/src/mesh/serial.rs` — USB serial driver, handshake, device detection
- `core/archipelago/src/mesh/crypto.rs` — X25519 key agreement + ChaCha20-Poly1305 (7 unit tests)
- `core/archipelago/src/mesh/listener.rs` — Background event loop, auto-reconnect, peer cache
- `core/archipelago/src/api/rpc/mesh.rs` — RPC handlers (mesh.status/peers/messages/send/broadcast/configure)
- `core/archipelago/src/server.rs` — MeshService initialization (non-blocking)
- `core/archipelago/src/identity.rs` — Ed25519 keypair, DID, X25519 derivation

### Frontend (Vue 3 + TypeScript)
- `neode-ui/src/stores/mesh.ts` — Pinia store with unread tracking
- `neode-ui/src/views/Mesh.vue` — Full chat UI (~1000 lines)
- `neode-ui/src/router/index.ts` — Route: `/dashboard/mesh`

### Mock Backend
- `neode-ui/mock-backend.js` — Dev mode mesh RPC responses (mesh.status/peers/messages/send/broadcast/configure)

## Protocol Reference

### Meshcore Frame Format
- Outbound: `<` (0x3C) + 2-byte LE length + data
- Inbound: `>` (0x3E) + 2-byte LE length + data
- Max LoRa payload: 160 bytes
- Baud: 115200, 8N1

### Key Commands
| Byte | Command | Description |
|------|---------|-------------|
| 0x01 | APP_START | Init session with version negotiation |
| 0x02 | SEND_TXT_MSG | Direct message (6-byte pubkey prefix) |
| 0x03 | SEND_CHANNEL_TXT_MSG | Broadcast on channel |
| 0x04 | GET_CONTACTS | Fetch contact list |
| 0x06 | SET_DEVICE_TIME | Sync device clock |
| 0x07 | SEND_SELF_ADVERT | Broadcast identity |
| 0x0A | SYNC_NEXT_MESSAGE | Retrieve queued messages |

### Identity Wire Format
`ARCHY:2:{ed25519_hex_64}:{x25519_hex_64}` (137 bytes, fits 160)

### Encryption
- X25519 Diffie-Hellman from Ed25519 keys (RFC 7748 clamping)
- ChaCha20-Poly1305 AEAD with random 12-byte nonce
- Wire: `[nonce 12B] + [ciphertext + tag 16B]` — max 132B plaintext

## RPC Endpoints

| Method | Params | Returns |
|--------|--------|---------|
| `mesh.status` | — | MeshStatus |
| `mesh.peers` | — | `{peers, count}` |
| `mesh.messages` | `{limit?}` | `{messages, count}` |
| `mesh.send` | `{contact_id, message}` | `{sent, message_id, encrypted}` |
| `mesh.broadcast` | — | `{broadcast}` |
| `mesh.configure` | `{enabled?, device_path?, channel_name?, broadcast_identity?, advert_name?}` | `{configured}` |

## Development Workflow

### Building & Testing (on dev server, NOT macOS)
```bash
# Deploy mesh changes
./scripts/deploy-to-target.sh --live

# Run mesh unit tests on server
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'cd ~/archy/core && cargo test --all-features -- mesh'

# Check device is detected
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'ls -la /dev/ttyUSB* /dev/ttyACM* 2>/dev/null'

# Watch mesh logs
ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
  'sudo journalctl -u archipelago -f | grep -i mesh'
```

### Frontend Dev (local, mock backend)
```bash
cd neode-ui && npm start
# Mesh mock data at http://localhost:8100/dashboard/mesh
```

## Roadmap Phases

### Phase 1: Core Implementation (COMPLETE)
- Meshcore binary protocol, serial driver, crypto, listener, RPC, Vue UI

### Phase 2: Mesh as Federation Transport
- NodeTransport trait abstraction (mesh/tor/lan backends)
- Transport priority: Mesh (1) > LAN/mDNS (2) > Tor (3)
- Chunked message protocol for >160B payloads (Reed-Solomon FEC)
- CBOR delta sync instead of full JSON state
- Transport indicator per peer in federation UI
- "Mesh only" off-grid mode
- Dependencies: `ciborium` (CBOR), `reed-solomon-erasure` (FEC), `mdns-sd` (LAN discovery)

### Phase 3: Encrypted Mesh Messaging
- Double Ratchet (Signal protocol) over LoRa
- X3DH key agreement using existing Ed25519/X25519
- Store-and-forward relay for offline peers (24h TTL)
- Message types: TEXT, ALERT, INVOICE (bolt11), PSBT_HASH, COORDINATE
- Per-peer chat threads, delivery status, offline indicators

### Phase 4: Off-Grid Bitcoin Operations
- Compact block headers over mesh (SPV verification)
- Transaction relay via internet-connected mesh peer
- Lightning payment coordination over mesh
- Emergency alert system (signed alerts, GPS, dead man's switch)

### Phase 5: Mesh Network Intelligence
- Adaptive routing, signal strength mapping, spreading factor adjustment
- Multi-path routing for reliability
- Steganographic modes
- Additional hardware: T-Beam, RAK WisBlock, WiFi mesh (802.11s), BLE, Blockstream Satellite

## Conventions

- All crypto uses existing identity infrastructure (Ed25519 signing key → X25519 derivation)
- Mesh init is non-blocking — errors logged but don't crash server
- Config persists to `{data_dir}/mesh-config.json`
- Message buffer: circular, max 100 messages
- Never build Rust on macOS — always deploy to server
- USB device paths: `/dev/ttyUSB*` and `/dev/ttyACM*`
- `archipelago` user must be in `dialout` group for serial access