IFM Protocol Documentation

Internet Frequency Modulation — An open, decentralized communication protocol for peer-to-peer broadcast over a distributed mesh network.

Quick Links

Section	Description
Architecture	System architecture, layer model, and design principles
Protocol Specification	Wire protocol, packet formats, and message types
Station Discovery & Relay Protocol	Station/relay discovery, signed records, presence, relay selection
Frequency Model	Frequency naming, types, and resolution
Packet Format	Binary packet structure, payload types, and serialization
Identity & Crypto	Ed25519 identity, encryption, and authentication
Transport & Discovery	QUIC, WebRTC, Kademlia DHT, and peer discovery
Rendezvous	Headless peer-discovery service — build, run, deploy
Audio & Voice	Modular audio pipeline architecture, Opus codec, streaming, and voice
Plugin System	Plugin architecture and JavaScript SDK integration
SDK Reference	JavaScript/TypeScript SDK API
CLI Reference	Command-line interface commands
Deployment	Running nodes, bootstrap peers, and production setup
Demos	Public demos: Station System, Relay Station, Radio Listener
Developer Tools	Node UI (TUI), CLI, SDK — for developers and operators
Future Development	Long-term economic vision, relay tiers, phased rollout
Distribution	Packaging, release channels, and build pipeline for all IFM products

Vision

IFM (Internet Frequency Modulation) creates virtual broadcast frequencies over a distributed mesh network. Inspired by FM radio:

Anyone can transmit — no central authority
Anyone can listen — open participation
Nobody owns the spectrum — decentralized by design
Communication is peer-to-peer — no servers required
The network has no central authority — resilient and censorship-resistant

Instead of Connect(server), users simply Tune(91.700).

Design Principles

No Central Servers — Every participant is a peer; network survives mass peer loss
Open Protocol — Public spec, no patents, no vendor lock-in
Portable — Runs on Raspberry Pi, laptop, phone, USB stick, IoT, browser (WASM)
Stateless Communication — No accounts, emails, or passwords; identity is cryptographic
Radio Metaphor — Intuitive frequency tuning replaces connection-oriented paradigms

Architecture Overview

Repository Structure

ifm/
├── Cargo.toml
├── package.json
├── crates/
│   ├── core/          # Main API (Node, tune, broadcast)
│   ├── protocol/      # Packet, Frequency, Header, Serialization
│   ├── crypto/        # Ed25519, Noise, AES-GCM, ChaCha20, BLAKE3
│   ├── packet/        # Packet encoding/decoding
│   ├── frequency/     # Frequency model, resolution, types
│   ├── discovery/     # Kademlia, Bootstrap, Peer Discovery
│   ├── gossip/        # Packet cache, TTL, Duplicate removal, Forwarding
│   ├── transport/     # QUIC, WebRTC, TCP fallback
│   ├── audio/         # Opus, Microphone, Playback, Streaming
│   ├── storage/       # Identity, Config, Cache, Logs, Plugins
│   ├── node/          # High-level node orchestration
│   └── ffi/           # N-API / WASM bindings
├── packages/
│   ├── sdk/           # @ifm/sdk JavaScript/TypeScript package
│   ├── cli/           # ifm CLI tool
│   └── examples/      # Three demo apps: station/, relay/, listener/
└── docs/              # This documentation

Quick Start

JavaScript/TypeScript

typescript

import { IFM } from "@ifm/sdk"

const radio = await IFM.create()
await radio.tune("91.700")

radio.on("message", console.log)
await radio.broadcast("Hello, IFM!")

Rust

rust

let node = Node::new();
node.connect()?;
node.tune("91.700")?;
node.broadcast("Hello, IFM!")?;

CLI

bash

ifm init
ifm connect
ifm tune 91.700
ifm broadcast "Hello, IFM!"

Frequency Examples

Human Frequency	Type	Description
`91.700`	Public	Open broadcast frequency
`chat.general`	Public	Text chat channel
`music.lofi`	Public	Music streaming
`private.team`	Protected	Encrypted, shared key required
`team.alpha`	Hidden	Not advertised, invitation only
`sensor.temperature`	Public	IoT telemetry

Performance Goals

Metric	Target
Startup	< 500 ms
Memory (idle)	< 64 MB
Voice Latency	< 100 ms
Connections	100–500 peers
Binary Size (optimized)	< 30 MB

Roadmap

Phase 1 — Core Networking (Rust workspace, libp2p, QUIC, Kademlia, GossipSub, CLI)
Phase 2 — SDK (N-API bindings, @ifm/sdk, Bun/Node, Event-driven API)
Phase 3 — Real-Time Media (Opus voice, Presence, Frequency scanning, Encrypted frequencies)
Phase 4 — Ecosystem (WASM, Browser, Plugin system, React, Tauri, Mobile)

Future Development & Tokenomics

⚠️ Future Plan — Not Implemented
This section describes a long-term economic vision for the IFM network. No token exists today. No rewards are being distributed. The protocol is and will remain free and open. This is a research direction for post-mainnet sustainability.

The Core Insight: Listeners as Infrastructure

Traditional broadcast: more listeners = higher cost (CDN, bandwidth, servers).

IFM inverts this: more listeners = more relays = stronger network.

Every client that tunes in can optionally become a micro-relay, forwarding packets to nearby peers. The audience becomes the distribution infrastructure — similar to how BitTorrent turns downloaders into uploaders, but for real-time radio.

Why Not "Listen-to-Earn"?

Paying tokens merely for listening creates a Sybil attack vector:

This pattern has broken many "X-to-Earn" models (Move-to-Earn, Watch-to-Earn, Learn-to-Earn). Listening is not scarce; bandwidth relaying is.

What Has Value: Relay Work

The network should reward verified contribution to packet delivery:

Metric	Why It Matters
Bytes Relayed	Actual bandwidth contributed
Unique Peers Served	Diversity of reach (anti-Sybil)
Uptime	Reliability
Geographic Coverage	Mesh resilience (measured via latency hints)
Latency / Jitter	Quality of service

A node that relays 20 GB to 400 peers earns significantly more than one relaying 200 MB to 12 peers.

Relay Tiers (Progressive Commitment)

All tiers run the same software — no separate binaries.

Tier	Name	Requirements	Rewards
0	Listener	None	None (just listen)
1	Community Relay	Opt-in, ≤5% CPU, ≤X GB/mo	Small
2	Verified Relay	Stake + uptime SLA	Medium
3	Backbone Relay	Datacenter/ISP, high bandwidth	Large

Users choose their tier. Default = Tier 0 (listen only).

Phased Rollout

Phase	Focus	Token?
1	Core Protocol (current)	❌ No
2	Relay Scoring & Metrics	❌ No — observability only
3	Opt-in Listener Relays	❌ No — reputation scores
4	Distribution Marketplace	⚠️ Credits (stable, non-speculative)
5	IFM Token (if needed)	❓ Only if marketplace demands it

Phase 1–3 require no token. The protocol works purely on reputation and reciprocal peering (Tit-for-Tat). A token is only introduced if a genuine marketplace for bandwidth credits emerges organically.

Distribution Marketplace (Phase 4+)

Instead of inflationary rewards, broadcasters buy distribution credits:

Credits are stable (pegged to bandwidth cost, not speculative)
No pre-mine, no ICO — credits minted when broadcasters deposit
Relays cash out — credits → stablecoin / fiat via exchange

This aligns incentives: broadcasters pay for reach; relays earn for delivery. No "yield farming" on listening.

The Endgame: BitTorrent for Live Radio

If this works, IFM becomes a self-scaling broadcast primitive:

The network gets stronger the more popular it gets. That property — more than any token — is the economic moat.

Distribution

Document	Description
Overview	Distribution philosophy, product matrix, and release cadence
Packaging	Binary formats, installers, containers, and platform packages
Channels	Release channels (stable/beta/nightly), versioning, and promotion
Build Pipeline	CI/CD, cross-compilation, signing, attestation, and publishing

Quick Start

bash

# Install latest stable CLI
curl -fsSL https://ifm.sh/install.sh | bash

# Or via package managers
brew install ifm              # macOS
winget install IFM.IFM        # Windows
apt install ifm               # Debian/Ubuntu (via repo)
pacman -S ifm                # Arch Linux
cargo install ifm-cli        # Rust developers
bun add @ifm/sdk             # JS/TS developers

Open protocol. No patents. No vendor lock-in. Anyone can build clients, hardware, libraries, or extend the protocol.

IFM Protocol Documentation ​

Quick Links ​

Vision ​

Design Principles ​

Architecture Overview ​

Repository Structure ​

Quick Start ​

JavaScript/TypeScript ​

Rust ​

CLI ​

Frequency Examples ​

Performance Goals ​

Roadmap ​

Future Development & Tokenomics ​

The Core Insight: Listeners as Infrastructure ​

Why Not "Listen-to-Earn"? ​

What Has Value: Relay Work ​

Relay Tiers (Progressive Commitment) ​

Phased Rollout ​

Distribution Marketplace (Phase 4+) ​

The Endgame: BitTorrent for Live Radio ​

Distribution ​

Quick Start ​

IFM Protocol Documentation

Quick Links

Vision

Design Principles

Architecture Overview

Repository Structure

Quick Start

JavaScript/TypeScript

Rust

CLI

Frequency Examples

Performance Goals

Roadmap

Future Development & Tokenomics

The Core Insight: Listeners as Infrastructure

Why Not "Listen-to-Earn"?

What Has Value: Relay Work

Relay Tiers (Progressive Commitment)

Phased Rollout

Distribution Marketplace (Phase 4+)

The Endgame: BitTorrent for Live Radio

Distribution

Quick Start