Introduction to Calimero

What is Calimero?

Calimero is a peer-to-peer framework for building self-sovereign, local-first applications with automatic, conflict-free synchronization. It enables developers to create distributed apps where users own their data, operate offline, and sync with peers when connectivity is available—without relying on centralized servers.

At the application layer, Calimero provides a shared environment for collaboration, computation, and coordination between peers. Instead of relying on global consensus like blockchains do, it achieves distributed consistency through CRDTs (Conflict-free Replicated Data Types)—allowing independent nodes to converge on the same state without coordination, leaders, or ordering guarantees.

Core Value Proposition

Feature	What it means
CRDT-based Sync	Automatic conflict resolution without coordination
Offline-first	Works without connectivity, syncs when online
Event-driven	Real-time notifications across nodes
WASM Runtime	Write apps in Rust or TypeScript, run in sandboxed environment
Multi-chain	Integrates with NEAR, ICP, Ethereum, Stellar

Key Design Principles

Data Ownership - Your data on your devices, you control access
Privacy by Default - End-to-end encryption
Distributed by Design - P2P architecture, no single point of failure
Developer-Friendly - Simple API with powerful CRDT primitives

What Makes Calimero Unique?

Calimero combines several powerful technologies to deliver a unique distributed computing platform:

Automatic conflict resolution via CRDTs — no manual merge code needed. Write natural code with nested data structures; the storage layer handles synchronization automatically.
Causal ordering via DAG — handles out-of-order network delivery gracefully. Deltas can arrive in any order; the system buffers and applies them in correct causal sequence.
Dual sync strategy — fast broadcast (~100-200ms) + reliable catch-up. Gossipsub provides real-time propagation, while periodic P2P sync ensures eventual consistency even after network issues.
Event-driven architecture — real-time updates without polling. Applications emit events that automatically propagate to all peers and trigger handlers.
Local-first — data owned by users, no central authority required. Your data lives on your devices; you control access and sharing.

Use Cases

Calimero enables a wide range of decentralized applications:

Use Case	Why Calimero?
Collaborative Editing	Real-time document collaboration without servers. Multiple users edit simultaneously; conflicts resolve automatically via CRDTs.
Decentralized Social	User-controlled social networks. Each user runs their own node; data ownership and privacy by default.
P2P Gaming	Multiplayer games with automatic state sync. Game state synchronizes across players even with network interruptions.
IoT Networks	Decentralized device coordination. Devices coordinate without central servers; works offline and syncs when online.
Supply Chain	Transparent, multi-party tracking. All participants maintain their own copy; automatic conflict resolution handles concurrent updates.
Healthcare	Private, patient-controlled medical records. Patients own their data; selective sharing with healthcare providers via encrypted contexts.

See Example Applications for working implementations.

Performance Characteristics

Latency: 100-200ms delta propagation (Gossipsub)
Throughput: 100-1000 deltas/sec per context
Memory: ~10MB per context (1000 deltas)
Scalability: Horizontal (more contexts = more throughput)

Where to Start

If you are…	Start here
Building apps	Getting Started → `core/crates/sdk/README.md`
Running nodes	Run a Local Network → `core/crates/node/README.md`
Understanding sync	Architecture Overview → `core/crates/dag/README.md`
Debugging issues	Monitor & Debug → `core/crates/node/readme/troubleshooting.md`

Core Architecture Layers

Calimero’s architecture consists of four main layers:

1. Application Layer

WASM apps using the Calimero SDK
CRDT collections: UnorderedMap, Vector, Counter, LwwRegister
Event emission for real-time updates

Documentation: Applications → core/crates/sdk/README.md

2. Node Layer

Orchestrates synchronization and execution
Dual sync paths: Gossipsub (~100-200ms) + Periodic P2P (every 10-30s)
Event handler execution across the network
Blob distribution for file sharing

Documentation: Nodes → core/crates/node/README.md

3. Storage Layer

CRDT storage with automatic merging
DAG (Directed Acyclic Graph) for causal ordering
Handles out-of-order delivery with dependency resolution
Merkle trees for efficient state comparison

Documentation: Architecture Overview → core/crates/storage/README.md

4. Network Layer

libp2p-based P2P (Gossipsub, reliable streams, DHT discovery)
JSON-RPC server for client interaction
WebSocket/SSE for real-time subscriptions
Authentication and authorization

Documentation: Reference → core/crates/network/README.md

How It Works (Transaction Flow)

Client calls WASM method via JSON-RPC
WASM executes, generates CRDT actions (inserts, increments, etc.)
Actions committed as DAG delta with causal parents
Delta broadcast via Gossipsub to all peers (~100-200ms)
Peers receive delta, check if parents are ready
If ready: apply immediately and execute event handlers
If not ready: buffer until parents arrive (DAG handles this automatically)
Periodic P2P sync ensures eventual consistency

For detailed flow diagrams, see Architecture Overview.

Core Repository Structure

The Calimero Core repository (calimero-network/core) contains the runtime and all supporting infrastructure:

core/
├── crates/          # Core Rust libraries (30+ crates)
│   ├── sdk/         # Application SDK - macros, CRDT collections, event emission
│   ├── runtime/    # WASM execution engine (Wasmer), sandboxing, resource limits
│   ├── storage/    # CRDT storage layer - collections with merge semantics
│   ├── dag/        # DAG logic (pure) - causal delta tracking, dependency resolution
│   ├── node/       # Node runtime - orchestrates sync, events, blob sharing
│   ├── network/     # P2P networking - libp2p integration (Gossipsub, streams, DHT)
│   ├── server/     # JSON-RPC server - API, WebSocket/SSE subscriptions, admin endpoints
│   ├── auth/       # Authentication - identity management, JWT tokens
│   ├── store/      # Persistent storage backend (RocksDB)
│   ├── context/    # Context lifecycle management (application instances)
│   ├── merod/      # Node binary (coordinator or peer)
│   └── meroctl/    # CLI tool - node operations, app installation, method calls
├── apps/            # Example applications
│   ├── kv-store/    # Simple key-value store
│   ├── blobs/       # Blob sharing example
│   └── ...          # More examples
├── contracts/       # Cross-chain smart contracts
│   ├── near/        # NEAR Protocol contracts
│   ├── icp/         # Internet Computer Protocol canisters
│   ├── ethereum/    # Solidity contracts
│   └── stellar/     # Stellar contracts
└── e2e-tests/       # End-to-end test suite

For detailed component explanations, see Architecture Overview.

Next Steps

New to Calimero? → Getting Started
Ready to build? → Builder Directory
Want to learn? → Core Concepts
Need to operate? → Operator Track

Built by the Calimero Network team

For questions, reach out on Discord, GitHub Issues, or email support@calimero.network.