IICP Protocol Specification
The spec is the rulebook for implementers. Read it when you are building a client, node, directory, or compatibility layer and need exact behaviour instead of a high-level explanation.
IICP protocol-suite release v1.10.17 is organised into focused canonical documents. Its wire compatibility baseline remains v1.9.0. Releases v1.10.0 and v1.10.1 added the normative replica lifecycle and then pinned its structured release metadata. The core wire format document is v1.3.2 and remains backward-compatible; Phase 5 CIP (S.12) is in active draft, Phase 6 Federated Directory (S.13) and the binary framing sub-spec add normative extensions without changing the base protocol.
Which document should I read?
Message shapes, required fields, errors, and basic security rules.
Registration, heartbeat, discovery, public node views, and stats.
Cooperative work, billing, telemetry, federation, and optional features.
Specification documents
Wire format, message types, required fields, error codes, and security minimums. Every conformant implementation MUST satisfy this document.
Directory sub-protocol: REGISTER, HEARTBEAT, DISCOVER, NODELIST, node policy manifests, audit-report, public stats, credit endpoints, free-credit allocation, directory-initiated node probing (§3.9c DIR-PROBE-NODE-01), bootstrap, peer exchange, Phase 6 event log (replica federation), and the signed compliance attestation extension (IICP-DIR-EXT-ATTEST).
Intent routing, prohibited-practice intent guardrails, QoS, node scoring formula, retry policy, circuit-breaker, and reputation security rules (§11.2 delta cap, §11.5 griefing cap, §11.6 velocity ceiling, §11.7 quorum independence, §11.8 reporter eligibility).
Payload confidentiality for key-ready nodes: canonical cx_public_key discovery, default keyless-node refusal, relay opacity, Tier-1 request encryption, and Tier-2 targets for forward secrecy and response encryption.
Fan-out inference across multiple nodes: Best-of-N, majority vote, and map-reduce modes. Defines CIP-Consumer, CIP-Provider, and CIP-Full conformance levels. Credit settlement and reputation-aware routing.
OpenTelemetry span naming (TRACE-01..TRACE-21), Sybil quorum resistance (T4.2), outlier weight validation (T4.3), and proxy token authentication (T4.1).
Evolves the directory from a single authority into a Genesis Seed with cryptographically verifiable replicas. Defines signed event log, 307 redirect, replica registration handshake (DIR-FED-11..14), and health polling.
Formal translation between Anthropic's Model Context Protocol and IICP. Allows any MCP server to participate in the IICP mesh without protocol rewrites.
Credit fields, pricing declarations, CipWorkerReceipt HMAC structure, and canonical billing message format.
Native TCP/UDP wire framing on port 9484: 12-byte header (magic + version + msg_type + flags + length) + CBOR payload. Message types: INIT/ACK, DISCOVER, CALL/RESPONSE, CLOSE, PING/PONG. HTTP fallback preserved.
Machine-verifiable test IDs mapped to spec requirements. The live REACH evidence and current implementation results are available from the stats page and the conformance materials. Phase 5 covers cooperative inference, node tasks, privacy boundaries and independently observed reachability.
Registry of optional protocol extensions: reputation, billing, post-quantum readiness, and future sub-protocols.
JSON schema for capability objects in REGISTER and NODELIST. Defines intent, models, max_tokens, limits, and availability windows.
Architecture decisions referenced by the live site
Defines the privacy boundary for public node listings, including ID-prefix exposure and the rule that full node IDs and provider endpoints are not published.
Read ADR-017 on GitHub ↗Defines the endpoint-liveness health vector and the aggregate mesh-health signal displayed by the node directory and status pages.
Read ADR-044 on GitHub ↗CIP conformance levels (Phase 5)
| Level | Who |
|---|---|
| CIP-Provider | Adapter / Rust nodes |
| CIP-Consumer | Proxy nodes |
| CIP-Full | Hybrid nodes |
| CIP-None | Phase 1–4 nodes |
Protocol version history
| Version | What changed |
|---|---|
| v1.9.0 | Security-hardening normative content: per-heartbeat reputation delta cap (§11.2) and audit-report griefing cap (§11.5). Directory drift closeout: AUDIT_REPORT endpoint (§3.9), Public Stats schema (§3.9b), free-credit allocation rules (§3.10), NODELIST health_label / exposure_mode / public_key + transport fields (§3.4); credit-endpoint, SCORE_UPDATE snapshot-model, and tier-enum reconciliations. |
| v1.8.0 | S.13 ephemeral-by-design federation (ADR-033): HEARTBEAT/SCORE_UPDATE/REPUTATION_UPDATE removed from the federated event log; snapshot+event-tail bootstrap via GET /v1/snapshot; replica registration handshake (POST /v1/replicas/register) |
| v1.6.0–v1.7.0 | CIP (S.12) normative; telemetry spec (TRACE-01..21); identity slot (ADR-021); §5.1.1 tier structure + §5.1.2 bootstrap floor ratified; federated directory prerequisites; SSRF guard on /v1/probe; all 13 Phase-5 research tracks closed |
| v1.5.0 | Spec reorganised into 11 focused documents; IICP-DIR sub-protocol; MCP binding; node capability format; billing extension; conformance test suite v1.0; wire format unchanged |
| v1.4.2 | Single Internet-Draft format; Phase 1 wire format + scoring formula baseline |
This is a living specification. All changes are tracked in the IICP spec repo on GitHub. To propose normative changes, email [email protected].