Skip to content

Core Concepts

Understanding Calimero's core concepts is essential for building and operating applications. This section covers the fundamental building blocks of the platform.

  • Contexts - Isolated application instances with their own state and members
  • Identity - Cryptographic identities for access control and authentication
  • Applications - WASM modules that run inside contexts
  • Nodes - Runtime that orchestrates synchronization and execution
  • Architecture Overview - How all components work together

Contexts

Contexts are isolated instances of applications running on the Calimero network. Each context has:

  • Isolated State: Own CRDT-backed state, completely separate from other contexts
  • Member Management: Invite-only access control with cryptographic identities
  • Lifecycle: Create, invite, join, and manage independently

Key concepts: - State isolation model (shared CRDT state vs private storage) - Invitation and membership flow - Multi-chain integration (NEAR, Ethereum, ICP, etc.)

Learn more →

Identity

Identity in Calimero uses cryptographic keys for access control:

  • Root Keys: Master identities (typically from blockchain wallets)
  • Client Keys: Derived keys for specific contexts
  • Authentication: Wallet-based authentication (NEAR, Ethereum, ICP, etc.)

Key concepts: - Hierarchical key management - Wallet adapters and integration - JWT tokens for API authentication

Learn more →

Applications

Applications are WASM modules that run inside contexts:

  • WASM Runtime: Sandboxed execution environment
  • CRDT State: Conflict-free data types for automatic synchronization
  • Event System: Real-time event emission and handling
  • Private Storage: Node-local data that never leaves the node

Key concepts: - SDK macros (#[app::state], #[app::logic]) - CRDT collections (UnorderedMap, Vector, Counter, etc.) - Views vs mutations - ABI generation for client bindings

Learn more →

Nodes

Nodes (merod) orchestrate synchronization and execution:

  • Node Types: Coordinator (first node) or Peer (joins network)
  • Synchronization: Dual-path sync (Gossipsub + periodic P2P)
  • Event Handling: Automatic event handler execution
  • Blob Distribution: Content-addressed file sharing

Key concepts: - NodeManager architecture - Delta propagation and application - Admin surfaces (JSON-RPC, WebSocket, SSE)

Learn more →

Architecture Overview

The Architecture Overview explains how all components work together:

  • Four-Layer Architecture: Application, Node, Storage, Network layers
  • Transaction Flow: How requests flow through the system
  • Synchronization Flow: Dual-path sync strategy
  • DAG-Based Ordering: Causal ordering for out-of-order delivery
  • Component Map: Detailed breakdown of each crate

Learn more →

How Concepts Relate

flowchart LR
    NODE[Node<br/>merod]
    CTX1[Context A<br/>App + State]
    CTX2[Context B<br/>App + State]
    ID1[Identity A<br/>alice.near]
    ID2[Identity B<br/>bob.near]

    NODE --> CTX1
    NODE --> CTX2
    ID1 --> CTX1
    ID2 --> CTX2
    CTX1 -.->|isolated| CTX2

    style NODE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff
    style CTX1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style CTX2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style ID1 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style ID2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff

Learning Path

New to Calimero? Start here:

  1. Architecture Overview - Understand the big picture
  2. Applications - Learn how to build apps
  3. Contexts - Understand application instances
  4. Identity - Learn about access control
  5. Nodes - Understand the runtime

Ready to build? Check out:

Need to operate? See:

Next: Start with Architecture Overview to understand how everything fits together.