{"id":42277166,"url":"https://github.com/inferadb/ledger","last_synced_at":"2026-06-06T05:00:59.849Z","repository":{"id":333022433,"uuid":"1130805053","full_name":"inferadb/ledger","owner":"inferadb","description":"InferaDB Ledger — distributed database purpose-built for authorization.","archived":false,"fork":false,"pushed_at":"2026-05-31T03:11:18.000Z","size":10368,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T05:21:13.057Z","etag":null,"topics":["access-control","audit-log","authorization","blockchain","cryptography","database","distributed-systems","fine-grained-access-control","grpc","immutable-ledger","inferadb","permissions","rebac","rust","storage","zanzibar"],"latest_commit_sha":null,"homepage":"https://inferadb.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inferadb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-09T03:24:51.000Z","updated_at":"2026-05-06T04:43:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"414a1286-d788-4115-97d4-67f8f64627be","html_url":"https://github.com/inferadb/ledger","commit_stats":null,"previous_names":["inferadb/ledger"],"tags_count":240,"template":false,"template_full_name":null,"purl":"pkg:github/inferadb/ledger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inferadb%2Fledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inferadb%2Fledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inferadb%2Fledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inferadb%2Fledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inferadb","download_url":"https://codeload.github.com/inferadb/ledger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inferadb%2Fledger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33969883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","audit-log","authorization","blockchain","cryptography","database","distributed-systems","fine-grained-access-control","grpc","immutable-ledger","inferadb","permissions","rebac","rust","storage","zanzibar"],"created_at":"2026-01-27T08:09:19.483Z","updated_at":"2026-06-06T05:00:59.822Z","avatar_url":"https://github.com/inferadb.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cp\u003e\u003ca href=\"https://inferadb.com\"\u003e\u003cimg src=\".github/inferadb.png\" width=\"100\" alt=\"InferaDB Logo\" /\u003e\u003c/a\u003e\u003c/p\u003e\n    \u003ch1\u003eInferaDB Ledger\u003c/h1\u003e\n    \u003cp\u003e\n        \u003ca href=\"https://discord.gg/inferadb\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\" /\u003e\u003c/a\u003e\n        \u003ca href=\"#license\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n        \u003ca href=\"https://github.com/inferadb/ledger/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/inferadb/ledger/ci.yml?branch=main\" alt=\"CI\" /\u003e\u003c/a\u003e\n        \u003ca href=\"https://crates.io/crates/inferadb-ledger-sdk\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/inferadb-ledger-sdk?label=sdk\" alt=\"SDK crate\" /\u003e\u003c/a\u003e\n        \u003ca href=\"https://docs.rs/inferadb-ledger-sdk\"\u003e\u003cimg src=\"https://img.shields.io/docsrs/inferadb-ledger-sdk?label=docs.rs\" alt=\"docs.rs\" /\u003e\u003c/a\u003e\n    \u003c/p\u003e\n    \u003cp\u003e\u003cb\u003eBlockchain storage for cryptographically verifiable authorization.\u003c/b\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003e [!IMPORTANT]\n\u003e Under active development. Not production-ready.\n\n**[InferaDB](https://inferadb.com) Ledger is a distributed authorization database that produces a cryptographic proof for every permission check.** Every write commits to an append-only per-tenant blockchain; every read returns a Merkle proof clients can verify independently. Use it when \"who had access to what, when\" must be tamper-proof and provable — compliance, financial-grade authz, audit-logged permission systems.\n\nUnder the hood: custom multi-shard Raft consensus, per-vault AES-256-GCM WAL encryption, and sub-millisecond reads from B+ tree indexes. Ledger is the storage layer behind [InferaDB Engine](https://github.com/inferadb/engine) and [InferaDB Control](https://github.com/inferadb/control).\n\n- [Features](#features)\n- [Architecture at a glance](#architecture-at-a-glance)\n- [Where Ledger fits in InferaDB](#where-ledger-fits-in-inferadb)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Contributing](#contributing)\n- [Using AI Assistants](#using-ai-assistants)\n- [Documentation](#documentation)\n- [Community](#community)\n- [License](#license)\n\n## Features\n\n- **Tamper-Proof Authorization History** — Every permission change is committed to a per-vault blockchain with consensus-verified block hashes. Not even database administrators can retroactively alter who had access to what, when.\n- **Client-Side Proof Verification** — Clients receive Merkle proofs with every read and can verify authorization decisions independently, without trusting the server. Proofs are pre-computed during apply for near-instant verified reads.\n- **Custom Consensus Engine** — Purpose-built multi-shard Raft engine with an event-driven reactor, pipelined replication, zero-copy rkyv serialization, and batched I/O across shards. Single WAL fsync on the consensus critical path.\n- **Data Residency** — Pin authorization data to geographic regions. Nodes only join Raft groups for their assigned region, keeping data within jurisdictional boundaries. Automatic region shard creation and membership management.\n- **Tenant Isolation** — Per-organization, per-vault security boundaries with per-vault WAL frame encryption (AES-256-GCM). Each vault maintains its own blockchain — one tenant's data can never leak into another's.\n- **Immediate Consistency** — Raft consensus ensures permission changes are visible cluster-wide before the write returns. Closed timestamps enable zero-hop follower reads for bounded-staleness queries.\n- **Sub-Millisecond Reads** — B+ tree indexes serve lookups without touching the Merkle layer. Leader lease reads at ~50ns, follower closed-timestamp reads at ~100ns.\n\n## Architecture at a glance\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/architecture.svg\" alt=\"InferaDB Ledger architecture — SDK on top, Node boundary containing Service/SlugResolver, Saga Orchestrator, Router, Consensus Engine, StorageEngine, and Global plus Regional Raft groups at the bottom\" width=\"900\"\u003e\n\u003c/p\u003e\n\nA multi-shard Raft cluster; one Global group owns directory and routing, per-region groups own PII-bearing state. The SDK uses redirect-only routing — cross-region traffic returns `NotLeader` + `LeaderHint` and the SDK reconnects directly. Full detail in [DESIGN.md](DESIGN.md).\n\n## Where Ledger fits in InferaDB\n\nLedger is the storage component of [InferaDB](https://inferadb.com), a platform for cryptographically verifiable authorization. Most users don't run Ledger directly — they run the higher-level components that sit on top of it:\n\n| Component                                               | What it does                                                                                 |\n| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| [InferaDB Engine](https://github.com/inferadb/engine)   | Evaluates authorization decisions; the API surface applications call.                        |\n| [InferaDB Control](https://github.com/inferadb/control) | Management plane, admin console, policy authoring.                                           |\n| **InferaDB Ledger** (this repo)                         | Storage, consensus, per-tenant blockchain, Merkle proofs — the layer the other two build on. |\n\nRun Ledger directly when you need cryptographic authorization history but want to build your own policy engine or control plane on top. Otherwise, start with the [InferaDB product documentation](https://inferadb.com), which covers the full platform including how Engine and Control use Ledger underneath.\n\n## Quick Start\n\n**Install:**\n\n```bash\n# Build from source (requires Rust 1.92+)\ncargo +1.92 install --locked --path crates/server\n\n# Or grab a prebuilt binary from Releases\n# https://github.com/inferadb/ledger/releases\n```\n\nFor Kubernetes, Docker Compose, or systemd deployments, see the [deployment guide](docs/how-to/deployment.md).\n\n**Start a node:**\n\n```bash\ninferadb-ledger --listen 0.0.0.0:50051 --data /var/lib/ledger\n```\n\n`--data \u003cpath\u003e` is mandatory for production deployments. For local development or one-off testing, swap it for `--dev`, which puts the database under an auto-generated tempdir and discards everything on restart:\n\n```bash\ninferadb-ledger --listen 0.0.0.0:50051 --dev\n```\n\n`--data` and `--dev` are mutually exclusive; the server-launch invocation requires exactly one of them. Client subcommands like `init` ignore both flags — they connect to a running server over `--host`.\n\n**Bootstrap the cluster (once, from any machine):**\n\n```bash\ninferadb-ledger init --host node1:50051\n```\n\n**Add more nodes:**\n\n```bash\ninferadb-ledger \\\n  --listen 0.0.0.0:50051 \\\n  --data /var/lib/ledger \\\n  --join node1:50051\n```\n\nNodes discover each other via `--join` seed addresses. The cluster manages membership automatically — new nodes are added as learners and promoted to voters once caught up. On restart, only `--data` is required; peer addresses are read from persisted Raft membership state.\n\n**Data residency (regulated regions):**\n\n```bash\ninferadb-ledger \\\n  --listen 0.0.0.0:50051 \\\n  --data /var/lib/ledger \\\n  --join node1:50051 \\\n  --region ie-east-dublin\n```\n\nSee the [deployment guide](docs/how-to/deployment.md) for multi-node setup, Kubernetes, adding/removing nodes, backup, and recovery.\n\n## Configuration\n\n| CLI           | Purpose                                                                                           | Default         |\n| ------------- | ------------------------------------------------------------------------------------------------- | --------------- |\n| `--data`      | Persistent [storage](docs/architecture/durability.md) (WAL, state, snapshots)                     | _(none)_        |\n| `--dev`       | Ephemeral file-backed storage at an auto-generated tempdir; data is lost on restart               | _(off)_         |\n| `--listen`    | TCP address for the RPC API (custom wire protocol over QUIC)                                      | _(none)_        |\n| `--socket`    | Unix domain socket path for the RPC API                                                           | _(none)_        |\n| `--join`      | Seed addresses for [cluster discovery](docs/how-to/deployment.md#adding-a-node) (comma-separated) | _(none)_        |\n| `--region`    | Geographic data residency [region](docs/how-to/deployment.md)                                     | `global`        |\n| `--advertise` | Address advertised to peers ([details](docs/how-to/deployment.md#advertise-address))              | _(auto-detect)_ |\n\nExactly one of `--data` or `--dev` is required when launching the server; supplying neither aborts at the start of `main` with a clear error, and supplying both is rejected at parse time. Client subcommands (`init`, `vaults`, `config schema`, `restore apply`) do not require a storage flag — they either talk to a running server over the wire RPC API or carry their own arguments. At least one of `--listen` or `--socket` must also be specified for the server-launch path. On restart, only the storage flag is required — all other flags are persisted on first boot and ignored on subsequent starts.\n\nSee [Configuration Reference](docs/how-to/deployment.md#configuration-reference) for environment variables and all options including metrics, batching, and tuning.\n\n## Contributing\n\n### Prerequisites\n\n- Rust 1.92+\n- [mise](https://mise.jdx.dev/) for synchronized development tooling\n- [just](https://github.com/casey/just) for convenient development commands\n\n### Build and Test\n\n```bash\ngit clone https://github.com/inferadb/ledger.git\ncd ledger\n\n# Install development tools\nmise trust \u0026\u0026 mise install\n\n# Build\njust build\n\n# Run tests\njust test\n```\n\n## Using AI Assistants\n\nClaude Code, Codex, and Cursor users: this repository ships rich agent context.\n\n- **[CLAUDE.md](CLAUDE.md)** (symlinked as `AGENTS.md`) — 16 non-negotiable golden rules covering wire-protocol codegen, storage keys, PII data residency, error handling, consensus I/O boundaries, and test hygiene.\n- **Per-crate `CLAUDE.md`** — each crate's `CLAUDE.md` extends the root rules with crate-specific invariants.\n- **Seven audit agents** under `.claude/agents/` fire proactively on matching file changes.\n- **Nine task skills** under `.claude/skills/` (`/add-new-entity`, `/add-storage-key`, `/new-rpc`, etc.) encode project-specific workflows.\n- **Hooks** in `.claude/settings.json` block unsafe operations (editing generated code, running `git commit` from an agent) and auto-run `cargo fmt` + `cargo check` after edits.\n\nRead [CONTRIBUTING.md → Using AI Assistants](CONTRIBUTING.md#using-ai-assistants) for detail.\n\n## Documentation\n\n**Evaluate:**\n\n- [Technical White Paper](WHITEPAPER.md) — How Ledger works, benchmarks, fit analysis.\n\n**Build with Ledger:**\n\n- [SDK crate docs](https://docs.rs/inferadb-ledger-sdk) — Rust client reference.\n- [FAQ](docs/faq.md) — Operational questions and quick answers.\n\n**Operate Ledger:**\n\n- [Deployment guide](docs/how-to/deployment.md) — Multi-node setup, Kubernetes, adding/removing nodes, backup, recovery.\n- [Dashboards](docs/dashboards/) — Prometheus + Grafana references.\n\n**Contribute to Ledger:**\n\n- [Technical Design Document](DESIGN.md) — Authoritative specification; explains architectural reasoning.\n- [CONTRIBUTING.md](CONTRIBUTING.md) — First-PR guide, conventions, troubleshooting.\n- [CLAUDE.md](CLAUDE.md) — Golden rules and agentic guardrails.\n- [docs/testing/](docs/testing/) — Fuzz, property, and simulation testing.\n\n## Community\n\n- [Discord](https://discord.gg/inferadb) — questions, discussions, announcements.\n- [open@inferadb.com](mailto:open@inferadb.com) — general inquiries.\n- [security@inferadb.com](mailto:security@inferadb.com) — responsible disclosure.\n\n## License\n\nDual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finferadb%2Fledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finferadb%2Fledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finferadb%2Fledger/lists"}