MESHTASTIC

Meshtastic path (air-first)

MeshChain is designed for Meshtastic. The public cloud testnet still finalizes on TCP PoA so faucet/scanner stay reliable. This doc is the real radio path (items 1–5).

Architecture

[ mesh CLI --air ] ──MCHEX/tx_air──► [ mesh_radio_relay :9199 ]
                                            │
                         ┌──────────────────┼──────────────────┐
                         ▼                  ▼                  ▼
                   Meshtastic LoRa    TCP :9100–9102      tip gossip
                   (MC frames)        validators         (height/hash)

Path	Use
Air (LoRa)	Everyday Transfer (compact MC Tx), tip ads, 0–1 tx blocks if they fit
TCP	Multi-tx blocks, catch-up, multi-host, signed ACKs bulk
Internet HTTP	Faucet, scanner, Solana vault only

1. Air-first tx submit

# Local validator + mock radio (no hardware)
python3 tools/mesh_radio_relay.py --mock --tcp 127.0.0.1:9100 --listen 127.0.0.1:9199 &

# Sign + inject MC frame into relay → validator mempool
mesh send MXXXX-… 1 --wallet me.json --air --relay 127.0.0.1:9199

# Or two-step
mesh send MXXXX-… 1 --wallet me.json          # writes last_payment.json
mesh air-submit --relay 127.0.0.1:9199

Under the hood:

1. Tx signed (ed25519)
2. Encoded as MC binary frame (MsgType::Tx = 1)
3. Sent as tx_air JSON + MCHEX <hex> + normal tx for TCP peers
4. Validator accepts tx_air → mempool → leader includes → finality

2. Radio relay as first-class service

# Lab mock
python3 tools/mesh_radio_relay.py --mock --tcp 127.0.0.1:9100

# Hardware (private channel MeshChain-Testnet-1)
python3 tools/mesh_radio_relay.py \
  --port /dev/ttyUSB0 --channel-index 0 \
  --tcp 127.0.0.1:9100 --listen 127.0.0.1:9199

# systemd (on seed / operator host)
sudo cp deploy/meshchain-radio-relay.service /etc/systemd/system/
sudo cp deploy/radio-relay.env.example /etc/meshchain/radio-relay.env
# edit MESH_RADIO_FLAGS=--port /dev/ttyUSB0 ...
sudo systemctl enable --now meshchain-radio-relay

3. Air block policy (1 tx)

Medium	Max txs / block
TCP gossip	up to 16
LoRa / air inject	1 (AIR_MAX_TXS_PER_BLOCK)

Full multi-tx blocks are not pushed over LoRa. Relay sends block_hint + tip instead.
block_air inject is rejected if tx_count > 1.

4. Mesh tip gossip

Every MESH_RADIO_TIP_SECS (default 30s) the relay advertises:

{ "chain_id", "height", "tip_hash_hex" }

as an MC Tip frame (type 7). Validators log air tips and request block catch-up if behind.

5. Internet optional (spend path)

Action	Needs internet?
Transfer over local validator + radio	No (same mesh / LAN)
Observer catch-up via LoRa tip + local peer	Prefer local TCP
Faucet drip	Yes (HTTP)
Scanner UI	Yes (HTTP)
Solana vault deposit/withdraw	Yes

Public seed 34.172.103.125 remains the internet hub for join/faucet.
Mesh-native spend = local meshchain-node + mesh_radio_relay + radio.

Frame types (MC magic)

Type	Name	Payload
1	Tx	bincode Tx
2	Block	bincode Block (≤1 tx, fits MTU)
3	BlockAck	ack fields
7	Tip	height + tip hash
8	BlockHint	height + hash when block too big
20	GossipJson	small JSON hello/tx/ack

Max payload 200 bytes (+ 6-byte header).

Mock e2e (no hardware)

cargo build -p mesh -p meshchain-node
./scripts/e2e_air_path.sh

Channel safety

• Use private channel MeshChain-Testnet-1
• Do not put funds traffic on public LongFast
• Never send seed phrases over mesh

Honesty

• Live public multi-host finality is still TCP PoA on GCE.
• This path makes Meshtastic first-class for submit + tip + multi-hop relay.
• Full offline village finality (validators only on LoRa, no TCP) is the next milestone after this air path is boring.