Architecture

How ICN works

ICN is a constraint engine. Apps translate cooperative governance into generic constraints. The kernel enforces those constraints without understanding their meaning. That separation is the architectural invariant of the entire system.

Foundations

Five design principles

Every architectural decision in ICN traces back to these five commitments.

Local-First

Nodes operate independently and reconcile via gossip. No central server to go down. No single point of failure. Maximum autonomy, maximum resilience.

Trust-Native

Security derives from social trust edges, not global consensus or proof-of-work. Trust is transitive, contextual, and computed from real relationships.

Deterministic Compute

Same inputs produce same outputs produce same journal state on all nodes. No nondeterminism. No surprises. Verifiable by any peer.

Capability-Based Security

Contracts cannot do anything they are not explicitly permitted to do. No ambient authority. Every action requires an explicit, revocable grant.

Human-Governed

Cooperative governance makes policy changes democratic and auditable. Code enforces constraints. People decide what those constraints should be.

Core Invariant

The Meaning Firewall

The architectural boundary that makes everything else possible. Apps live above it. The kernel lives below it. Nothing crosses without becoming a generic constraint.

Policy Oracles (Apps)
Apps and governance decide constraint values
Trust Oracle Journal Oracle Governance Oracle Membership Oracle
Meaning Firewall
ConstraintSet { rate_limit: 20/s, credit_ceiling: 1000, capabilities: [...] }
Constraint Enforcement (Kernel)
Kernel enforces constraints without knowing why
Transport Auth Replay Guard Rate Limiter Capability Gate Credit Gate

The critical property: Governance can change what the rate limit is (20/s vs 100/s). Governance cannot remove that rate limiting exists. The enforcement mechanism is fixed. The values are democratic.

Subsystems

Nine interlocking systems

ICN coordinates identity, trust, governance, economics, contracts, replication, compute, networking, and runtime supervision into a single coherent daemon.

Identity

Decentralized identifiers (DIDs) with Ed25519 signatures, X25519 encryption, Age-encrypted keystore. Multi-device support with capability-based permissions.

Trust Graph

Web-of-participation scoring with transitive propagation. Multi-graph support for different trust contexts. Informs access control and resource allocation.

Governance

Democratic policy-making through proposals and voting. Domain-specific rules, membership criteria, configurable thresholds. Consensus, majority, or consent.

Economic Journal

Append-only Merkle-DAG journal with mutual-credit semantics. Dynamic credit limits, safety rails, fork detection and resolution. The journal is the source of truth. Account state is a projection.

Contracts (CCL)

Cooperative Contract Language interpreter with fuel metering. Capability-based security model. Deterministic execution. YAML schema for entities, governance, economics.

Gossip & Sync

Push/pull replication with Bloom filter anti-entropy. Vector clocks for causal ordering. Topic-based dissemination. Eventual consistency across the network.

Network Transport

QUIC/TLS secure sessions with DID-TLS binding. mDNS discovery, NAT traversal, message authentication. Rate-limited, trust-gated connections.

Distributed Compute

Trust-gated task execution with intelligent scheduling based on trust, capacity, and economics. Result verification. Cooperative resource pooling.

Runtime & Supervision

Actor-based services on Tokio. App lifecycle management with prepare, install, start, stop, uninstall stages. Inter-actor communication via message passing.

Data Flow

How a message moves through ICN

From signed message to enforced constraint in six steps.

1

Receive

A node receives a signed message over QUIC/TLS transport

2

Validate

The kernel validates invariants: authentication, replay protection, rate limits, capability gates, credit gates

3

Replicate

State replication through gossip moves validated events across the network

4

Compute

Policy subsystems (trust, governance, journal) compute semantic meanings from events

5

Constrain

Meanings are expressed as constraints: rate limits, credit ceilings, capability grants

6

Enforce

The kernel enforces those constraints on subsequent actions without understanding their semantic origin

Comparison

ICN vs. the alternatives

ICN Blockchain Federation Server
Consensus Local-first gossip Global (PoW/PoS) Central authority
Trust Model Social trust graph Trustless / economic Institutional
Identity Self-sovereign DIDs Wallet addresses Server accounts
Economics Mutual credit Token/coin None / external
Governance Democratic primitives Token-weighted Admin decisions
Scalability Per-cooperative Global bottleneck Per-server
Offline Full operation Degraded No access
Crate Map

What lives where

ICN is organized into kernel crates (enforcement mechanisms) and app crates (domain semantics). The Meaning Firewall sits between them.

Kernel Crates

icn-kernel-apiTrait definitions, PolicyOracle, OracleRegistry
icn-identityDID + keystore + multi-device
icn-storePersistent storage abstraction
icn-protocolGossip + networking (facade)
icn-coreRuntime, supervisor, app lifecycle
icn-servicesAPI + RPC + gateway (facade)
icn-securitySecurity primitives
icn-cryptoCryptography (facade)
icn-obsObservability + metrics
icn-encodingSerialization
icn-timeTime primitives
icn-testkitTest utilities

App Crates (above the firewall)

icn-trustTrust graph computation + scoring
icn-ledgerEconomic journal + mutual credit semantics
icn-governanceProposals, voting, domains
icn-cclContract language + YAML schemas
icn-computeDistributed task execution
icn-communityCommunity + membership management
icn-federationInter-cooperative agreements

Ready to dig in?

The source is open. The architecture docs are in the repo. Read the code, run a node, break things.

View on GitHub → Get Started