Why crdt-kit?

Traditional sync solutions break when devices go offline. CRDTs solve this at the data structure level — every replica can be updated independently, and merges always converge to the same result, guaranteed by math, not by servers.

crdt-kit is built specifically for resource-constrained, latency-sensitive environments where existing solutions (Automerge, Yjs) add too much overhead:

+-----------+     +-----------+     +-----------+
|  Device A |     |  Device B |     |  Device C |
|  (offline)|     |  (offline)|     |  (offline)|
+-----+-----+     +-----+-----+     +-----+-----+
      |                 |                 |
      |  local edits    |  local edits    |  local edits
      |                 |                 |
      +--------+--------+--------+--------+
               |                 |
               v                 v
         +-----------+     +-----------+
         |   merge   |     |   merge   |
         +-----------+     +-----------+
               |                 |
               v                 v
          Same state!       Same state!    <-- Strong Eventual Consistency

Key Advantages

Built For

Quick Start

[dependencies]
crdt-kit = "0.3"

use crdt_kit::prelude::*;

// Two devices, working offline
let mut phone = GCounter::new("phone");
phone.increment();
phone.increment();

let mut laptop = GCounter::new("laptop");
laptop.increment();

// When they reconnect — merge. Always converges.
phone.merge(&laptop);
assert_eq!(phone.value(), 3);

With Persistence

[dependencies]
crdt-kit = { version = "0.3", features = ["serde"] }
crdt-store = { version = "0.1", features = ["sqlite"] }

use crdt_store::{CrdtDb, CrdtVersioned, SqliteStore};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct SensorReading { temperature: f32, humidity: f32 }

impl CrdtVersioned for SensorReading {
    const SCHEMA_VERSION: u8 = 1;
}

let store = SqliteStore::open("sensors.db").unwrap();
let mut db = CrdtDb::with_store(store);

// Save — automatically wrapped in a version envelope
db.save("sensor-42", &SensorReading { temperature: 22.5, humidity: 65.0 }).unwrap();

// Load — automatically migrated if the schema changed
let reading: Option<SensorReading> = db.load("sensor-42").unwrap();

Workspace Architecture

crdt-kit is a multi-crate workspace. Use only what you need:

crdt-kit/
├── crates/
│   ├── crdt-kit/              9 CRDTs + HLC + traits (the core library)
│   ├── crdt-store/            Persistence: SQLite, redb, memory + CrdtDb API
│   ├── crdt-migrate/          Version envelopes + migration engine
│   ├── crdt-migrate-macros/   #[crdt_schema] + #[migration] proc macros
│   ├── crdt-codegen/          Code generation from TOML schemas
│   ├── crdt-cli/              CLI: status/inspect/compact/export/generate/dev-ui
│   ├── crdt-dev-ui/           Embedded web panel for database inspection
│   └── crdt-example-tasks/    Full example: codegen + migrations + events

Persistence & Storage

Three backends, one trait surface:

All backends implement StateStore + EventStore with event sourcing, snapshots, and compaction:

use crdt_store::{EventStore, MemoryStore, StateStore};

let mut store = MemoryStore::new();

// State persistence
store.put("sensors", "s1", b"data").unwrap();

// Event sourcing
let seq = store.append_event("sensors", "s1", b"SetTemp(23.1)", 1000, "node-a").unwrap();

// Snapshots + compaction
store.save_snapshot("sensors", "s1", b"state", seq, 1).unwrap();
store.truncate_events_before("sensors", "s1", seq).unwrap();

Schema Migrations

When your data evolves between app versions, crdt-migrate handles it transparently:

use crdt_migrate::{crdt_schema, migration};

#[crdt_schema(version = 1, table = "sensors")]
#[derive(Serialize, Deserialize)]
struct SensorV1 { device_id: String, temperature: f32 }

#[crdt_schema(version = 2, table = "sensors")]
#[derive(Serialize, Deserialize)]
struct SensorV2 { device_id: String, temperature: f32, humidity: Option<f32> }

#[migration(from = 1, to = 2)]
fn add_humidity(old: SensorV1) -> SensorV2 {
    SensorV2 { device_id: old.device_id, temperature: old.temperature, humidity: None }
}

• Lazy: Data migrates on read, not on startup
• Deterministic: Two devices migrating the same data produce identical results
• Linear chain: v1 → v2 → v3 → current, never skipping steps
• Write-back: Migrated data is re-persisted automatically

Code Generation

Define your entities in a crdt-schema.toml file and generate all the Rust boilerplate:

[config]
output = "src/generated"

# Entity with CRDT-wrapped fields (conflict-free replicated)
[[entity]]
name = "Project"
table = "projects"

[[entity.versions]]
version = 1
fields = [
    { name = "name", type = "String", crdt = "LWWRegister" },
    { name = "members", type = "String", crdt = "ORSet" },
]

# Entity with plain fields, versioned schema, and a relation
[[entity]]
name = "Task"
table = "tasks"

[[entity.versions]]
version = 1
fields = [
    { name = "title", type = "String" },
    { name = "done", type = "bool" },
]

[[entity.versions]]
version = 2
fields = [
    { name = "title", type = "String" },
    { name = "done", type = "bool" },
    { name = "priority", type = "Option<u8>", default = "None" },
    { name = "tags", type = "Vec<String>", default = "Vec::new()" },
    { name = "project_id", type = "String", default = "String::new()", relation = "Project" },
]

$ crdt generate --schema crdt-schema.toml
  Generated: src/generated/project.rs
  Generated: src/generated/task.rs
  Generated: src/generated/task_migrations.rs
  Generated: src/generated/helpers.rs
  Generated: src/generated/mod.rs

Generated 5 files in src/generated/

Field options:

Supported CRDT types: GCounter, PNCounter, LWWRegister, MVRegister, GSet, TwoPSet, ORSet

What gets generated:

• project.rs / task.rs — Versioned structs with #[crdt_schema], CRDT-wrapped field types, and type Project = ProjectV1
• task_migrations.rs — Migration functions with #[migration] (auto-generated for field additions, CRDT fields get auto-defaults)
• helpers.rs — create_db() and create_memory_db() with all migrations pre-registered
• mod.rs — Module declarations and re-exports

All files are marked AUTO-GENERATED by crdt-codegen -- DO NOT EDIT.

See crdt-example-tasks for a complete working example.

Developer Tools

CLI

$ crdt status app.db          # Database overview
$ crdt inspect app.db sensor-42 --events  # Entity detail + event log
$ crdt compact app.db --threshold 100     # Snapshot + truncate events
$ crdt export app.db --namespace sensors  # JSON export
$ crdt generate --schema crdt-schema.toml # Generate code from TOML
$ crdt dev-ui app.db          # Launch web inspector

Dev UI

A dark-themed web panel for visual database inspection during development:

$ crdt dev-ui app.db
  Dev UI: http://localhost:4242

Browse namespaces, entities, event logs, version envelopes, and snapshots — all from your browser.

Edge Computing & IoT

crdt-kit is purpose-built for edge environments. Import it with no_std for bare metal or with serde for network serialization:

# Raspberry Pi / ESP32 / bare metal (no standard library)
[dependencies]
crdt-kit = { version = "0.3", default-features = false }

# Edge node with JSON sync over MQTT/HTTP
[dependencies]
crdt-kit = { version = "0.3", features = ["serde"] }
serde_json = "1"

use crdt_kit::prelude::*;

// Edge sensor node collects temperature readings
let mut sensor_a = GCounter::new("sensor-a");
let mut sensor_b = GCounter::new("sensor-b");

// Each sensor counts events independently (no network needed)
sensor_a.increment_by(142); // 142 events detected
sensor_b.increment_by(89);  // 89 events detected

// When the gateway collects data — merge. Order doesn't matter.
sensor_a.merge(&sensor_b);
assert_eq!(sensor_a.value(), 231); // exact total, no double-counting

// Delta sync: only send what changed (saves bandwidth on LoRa/BLE)
let mut gateway = GCounter::new("gateway");
let delta = sensor_a.delta(&gateway);  // minimal payload
gateway.apply_delta(&delta);            // gateway is up to date
assert_eq!(gateway.value(), 231);

Available CRDTs

Counters

Registers

Sets

Sequences

Traits

Examples

# CRDT basics
cargo run -p crdt-kit --example counter         # Distributed counters
cargo run -p crdt-kit --example todo_list        # Collaborative todo list
cargo run -p crdt-kit --example ecommerce        # E-commerce entities
cargo run -p crdt-kit --example chat             # Chat with conflict detection

# Persistence & migration
cargo run -p crdt-store --features sqlite --example iot_sensor      # Schema migration on OTA update
cargo run -p crdt-store --features sqlite --example collaborative   # Multi-node merge + persist
cargo run -p crdt-store --features sqlite --example event_sourcing  # Event log, snapshots, compaction

# Full-stack example (codegen + migrations + event sourcing)
cargo run -p crdt-example-tasks                                     # Task management app

Performance

Measured with Criterion on optimized builds:

cargo bench  # Run benchmarks yourself

Guarantees

All CRDTs satisfy Strong Eventual Consistency (SEC):

Verified by 256 tests across the workspace.

Roadmap

• G-Counter, PN-Counter
• LWW-Register, MV-Register
• G-Set, 2P-Set, OR-Set
• RGA List (ordered sequence)
• Text CRDT (collaborative text editing)
• no_std support (embedded / bare metal)
• serde serialization support
• Delta-state optimization
• WASM bindings
• Persistent storage (SQLite + redb)
• High-level CrdtDb API with version envelopes
• Transparent schema migrations (#[crdt_schema] + #[migration])
• Developer CLI (crdt status/inspect/compact/export/generate)
• Dev UI web panel
• Code generation from TOML schemas (crdt generate)
• Network transport layer (TCP, WebSocket, QUIC)
• Sync protocol (delta-based replication)
• Benchmarks against Automerge / Yrs

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

Dual-licensed under your choice of:

• MIT — LICENSE-MIT
• Apache 2.0 — LICENSE-APACHE