View source on GitHub →

Phase 6: Crate Consolidation

Status: Complete ✅
Date: 2026-02-02

Summary

Phase 6 defined a clear 12-crate kernel facade structure for the ICN API surface using the facade pattern, without removing or merging existing crates. Three new "unified" crates were created that re-export existing crates under cleaner namespaces.

Changes

New Unified Crates

1. icn-protocol (Gossip + Networking)

pub use icn_gossip as gossip;
pub use icn_net as net;
  • Unifies protocol layer (gossip replication + network transport)
  • Usage: use icn_protocol::{gossip::GossipActor, net::NetworkActor};

2. icn-services (API + RPC + Gateway)

pub use icn_api as api;
pub use icn_rpc as rpc;
pub use icn_gateway as gateway;
  • Unifies service layer (API types, RPC server, REST/WebSocket gateway)
  • Usage: use icn_services::{gateway, rpc, api};

3. icn-crypto (Post-Quantum Cryptography)

pub use icn_crypto_pq::*;
  • Unifies cryptography layer
  • Usage: use icn_crypto::HybridKeypair;

Final Kernel Structure (12 Crates)

  1. icn-kernel-api - Trait definitions for kernel extensibility
  2. icn-identity - DID generation, keystore, identity management
  3. icn-store - Generic persistent storage (Sled)
  4. icn-protocol ⭐ NEW - Gossip + networking unified
  5. icn-core - Actor runtime, supervisor, lifecycle management
  6. icn-services ⭐ NEW - API + RPC + Gateway unified
  7. icn-security - Byzantine detection, misbehavior tracking
  8. icn-crypto ⭐ NEW - Post-quantum hybrid cryptography
  9. icn-obs - Prometheus metrics, tracing, observability
  10. icn-encoding - Serialization utilities (bincode, postcard)
  11. icn-time - Clock synchronization (Rough Time Protocol)
  12. icn-testkit - Test utilities for multi-node scenarios

Approach: Facade Pattern

Rather than merging source code (which would be disruptive), we used the "facade pattern":

  • New crates re-export existing crates
  • Maintains backward compatibility
  • Allows gradual migration
  • Keeps git history clean
  • Minimal code changes

Verification

  • ✅ All 12 kernel crates compile
  • ✅ Test suite: 221/222 tests pass (1 DNS resolution failure unrelated to changes)
  • ✅ No circular dependencies verified with cargo tree
  • ✅ Full workspace builds successfully

Future Work

Optional Migrations (Phase 6.1)

  • Mark old crates as deprecated in Cargo.toml
  • Update dependents to use new unified crates
  • Eventually remove old crates (Phase 7+)

App-Level Crates (Future Phase)

These crates should potentially move to apps/ in future phases:

  • icn-ledger (mutual credit)
  • icn-ccl (contract language)
  • icn-trust (trust graph)
  • icn-governance (proposals, voting)
  • icn-compute (distributed compute)
  • icn-federation (inter-cooperative)
  • icn-steward, icn-zkp (SDIS)
  • icn-coop, icn-community, icn-entity
  • icn-privacy, icn-snapshot

Implementation Details

Workspace Updates

  • Added 3 new crate entries to Cargo.toml members
  • Added workspace dependencies for the new crates
  • No changes to existing crates (backward compatible)

Testing

# Build all new crates
cargo build -p icn-protocol -p icn-services -p icn-crypto

# Build entire workspace
cargo build --workspace

# Run tests
cargo test --workspace --lib

Benefits

  1. Clear Kernel Boundary: 12 well-defined kernel crates
  2. Simplified Dependencies: Easier to reason about kernel vs apps
  3. Better Organization: Related functionality grouped logically
  4. Backward Compatible: Old crates still work
  5. Migration Path: Can gradually move to new crates

References

  • Issue: #861 (Phase 6: Crate Consolidation)
  • Parent: #856 (Kernel Separation)
  • Depends on: Phase 5 (Membership consolidation - completed)
← Back to Docs