Skip to content

phase8-meshcore-research.md

Latest commit

 

History

History
67 lines (54 loc) · 3 KB

phase8-meshcore-research.md

File metadata and controls

67 lines (54 loc) · 3 KB
Raw

Phase 8: MeshCore Foundation — Research Summary

Date: 2025-12-10
Branch: experimental/brainz
Scope: T-1032..T-1038

Goals

  • Define the decentralized MeshCore foundations: DHT, identity, routing, storage, bootstrap, overlay, NAT traversal.
  • Establish guardrails and defaults for future implementation work.

Decisions & Findings

DHT Architecture & Keys (T-1032, T-1035)

  • Use Kademlia-style DHT with SHA1-derived 160-bit IDs.
  • Namespaced keys:
    • mesh:peer:<peerId> → peer descriptors (addr/port/transports, signed).
    • mesh:content:<contentId> → content descriptors (hashes, sizes, codecs, owner), signed.
    • mesh:scene:<sceneId> → scene membership/metadata (consistent with Phase 6 scenes).
  • Values are MessagePack blobs, signed by Ed25519 (see identity).
  • TTL: default 1 hour; publishers refresh at 30 minutes; consumers treat >1h as stale.
  • Size cap per value: 8–10 KB; shard if larger.

Identity (T-1033)

  • Ed25519 keypairs for mesh identities.
  • PeerId = peer:mesh:<base32(sha256(pubkey))[0:16]>.
  • All DHT values and overlay control messages are signed; include pubkey, sig, ts fields.
  • Rotation: support key rotation via prev_pubkey link; keep last 2 keys accepted for overlap.

Routing (T-1034)

  • Kademlia routing table with k-buckets (k=20).
  • Prefer IPv6, but keep dual-stack descriptors.
  • Store transport hints (DHT, overlay, mirrored) to bias selection.
  • NAT awareness flag in descriptors to decide relay vs direct attempts.

Storage & TTL (T-1035)

  • Values: soft cap 8–10 KB; shard large payloads (e.g., multiple peer hints).
  • TTL 1h; publisher refresh 30m; reader treats >1h as stale; eviction after 2h.
  • Reject unsigned or expired (ts older than TTL) values.

Bootstrap & Discovery (T-1036)

  • Bootstrap nodes list in config (later replaceable with DNS seeds).
  • On start: join bootstrap peers, perform self-announce, fetch closest peers.
  • Periodic FIND_NODE for own ID to keep table warm.

Overlay Protocol Design (T-1037)

  • Control plane: small signed messages over QUIC/WebRTC data channels (future).
  • Data plane: leverage existing multi-swarm overlay (Phase 6) as mirrored path; optional.
  • Message envelope: {type, payload, pubkey, sig, ts}.

NAT Traversal (T-1038)

  • Prefer direct: UDP hole punching (STUN); fallback to TURN/relay when available.
  • If NAT type symmetric → mark descriptor as relay-required; prefer mirrored transport.
  • Keep-alive pings to maintain NAT bindings where applicable.

Risks & Guardrails

  • Signature verification on all DHT and overlay control messages.
  • Size limits to prevent DHT spam.
  • Conservative TTL to reduce stale data.
  • NAT detection to avoid futile direct attempts.
  • No PII in DHT values; use pseudonymous PeerIds only.

Next Steps (implementation)

  • Build DHT client abstraction with signed put/get and TTL enforcement.
  • Implement peer descriptor publisher/refresh worker.
  • Integrate MeshTransportService preference with DHT vs overlay selection.
  • Add NAT detection utility and descriptor flagging.