Zero-config permissioned ledger with Raft consensus, smart contracts, SQL queries, and a built-in block explorer.
The simplest way to add a distributed ledger to any application.
npm install miniledger
MiniLedger is a private blockchain framework and permissioned distributed ledger that runs in a single Node.js process. Unlike Hyperledger Fabric or R3 Corda, there's no Docker, no Kubernetes, no certificate authorities, and no JVM — just npm install and you have a production-ready consortium blockchain with Raft consensus, JavaScript smart contracts, per-record encryption, on-chain governance, and full SQL queryability.
Built for enterprise use cases like supply chain tracking, audit trails, multi-party data sharing, tokenized assets, and any scenario where you need an immutable, tamper-proof ledger without the overhead of public blockchains or the complexity of legacy DLT platforms.
- 10-second setup —
npm install miniledger && npx miniledger start. No infrastructure. - SQL-queryable state — World state lives in SQLite. Run
SELECT * FROM world_statedirectly. - Embeddable — Import as a library into any Node.js/TypeScript app. No separate processes.
- Enterprise-grade consensus — Raft leader election with log replication and fault tolerance.
- Smart contracts in JavaScript — No Solidity, no Go, no Kotlin. Just plain JS.
- Built-in block explorer — Full dashboard with search, drill-down, and SQL console.
- Lightweight alternative to Hyperledger Fabric, R3 Corda, and Quorum for teams that want a private blockchain without the operational burden.
# Initialize and start a node
npx miniledger init
npx miniledger start
# Submit a transaction
curl -X POST http://localhost:4441/tx \
-H "Content-Type: application/json" \
-d '{"key": "account:alice", "value": {"balance": 1000}}'
# Query state with SQL (!)
curl -X POST http://localhost:4441/state/query \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT * FROM world_state"}'
# Open the block explorer dashboard
open http://localhost:4441/dashboardnpx miniledger demoSpins up a 3-node Raft cluster, deploys a token smart contract, submits sample transactions, and opens the web dashboard — a full blockchain explorer with block/tx drill-down, state browser, contract viewer, governance page, and search.
The built-in explorer at http://localhost:4441/dashboard includes:
- Overview — live stats, block rate chart, recent blocks & transactions
- Block explorer — paginated list, drill into any block to see its transactions
- Transaction viewer — filter by type, click through to full payload details
- State browser — browse all key-value entries or run raw SQL queries
- Contract inspector — view deployed smart contracts and their source code
- Governance — proposals, vote breakdowns, status tracking
- Network — peer list, consensus role, leader info
- Search — find blocks by height, transactions by hash, state keys, or addresses
Submit data via curl or the CLI:
# Store a user record
curl -X POST http://localhost:4441/tx \
-H "Content-Type: application/json" \
-d '{"key": "user:alice", "value": {"name": "Alice", "balance": 500, "role": "admin"}}'
# Store a product (supply chain, inventory, etc.)
curl -X POST http://localhost:4441/tx \
-H "Content-Type: application/json" \
-d '{"key": "product:widget-a", "value": {"name": "Widget A", "price": 29.99, "stock": 142}}'
# Invoke a smart contract method
curl -X POST http://localhost:4441/tx \
-H "Content-Type: application/json" \
-d '{"type": "contract:invoke", "payload": {"kind": "contract:invoke", "contract": "token", "method": "mint", "args": [5000]}}'
# Delete a key
curl -X POST http://localhost:4441/tx \
-H "Content-Type: application/json" \
-d '{"key": "product:widget-a", "value": null}'
# Query state with SQL
curl -X POST http://localhost:4441/state/query \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT key, value FROM world_state WHERE key LIKE '\''user:%'\''"}'Or use the CLI:
miniledger tx submit '{"key":"sensor:temp-1","value":{"celsius":22.5,"location":"warehouse"}}'
miniledger query "SELECT * FROM world_state ORDER BY updated_at DESC LIMIT 10"Use MiniLedger as a library — embed a private blockchain directly in your Node.js application:
import { MiniLedger } from 'miniledger';
const node = await MiniLedger.create({ dataDir: './my-ledger' });
await node.init();
await node.start();
// Submit a transaction
await node.submit({ key: 'account:alice', value: { balance: 1000 } });
// Query state with SQL
const results = await node.query(
'SELECT * FROM world_state WHERE key LIKE ?',
['account:%']
);
// Deploy a smart contract
await node.submit({
type: 'contract:deploy',
payload: {
kind: 'contract:deploy',
name: 'token',
version: '1.0',
code: `return {
mint(ctx, amount) {
const bal = ctx.get("balance:" + ctx.sender) || 0;
ctx.set("balance:" + ctx.sender, bal + amount);
}
}`
}
});| Feature | Description |
|---|---|
| Zero config | No Docker, no K8s, no certificate authorities. Single Node.js process. |
| SQL-queryable state | World state stored in SQLite. Run SQL queries directly against the ledger. |
| Raft consensus | Production-grade leader election, log replication, and fault tolerance. |
| Smart contracts | Write and deploy contracts in JavaScript. No Solidity required. |
| Per-record privacy | AES-256-GCM field-level encryption with ACLs. No channels needed. |
| On-chain governance | Propose and vote on network changes. Quorum-based decision making. |
| Block explorer | Built-in web dashboard with search, pagination, and drill-down views. |
| P2P networking | WebSocket mesh with auto-reconnect and peer discovery. |
| Ed25519 identity | Audited cryptographic signatures. No PKI setup required. |
| TypeScript native | Full type safety. Dual CJS/ESM package. Embed in any Node.js app. |
MiniLedger is ideal for:
- Supply chain tracking — Immutable record of goods movement across organizations
- Audit trails — Tamper-proof logs for compliance, finance, and healthcare
- Multi-party data sharing — Shared ledger between organizations without a central authority
- Asset tokenization — Issue and transfer digital tokens with smart contracts
- IoT data integrity — Sensor data committed to an immutable ledger
- Document notarization — Timestamped, cryptographically signed record keeping
- Internal microservice ledger — Embed a tamper-proof log in any Node.js backend
- Rapid prototyping — Build and test distributed ledger applications in minutes, not weeks
┌───────────┐
│ CLI │
└─────┬─────┘
│
┌─────▼─────┐
│ Node │ (orchestrator)
└─────┬─────┘
│
┌───────┬───────┬───┴───┬───────┬───────┐
│ │ │ │ │ │
┌──▼──┐ ┌─▼───┐ ┌─▼────┐ ┌▼─────┐ ┌▼────┐ ┌▼───────┐
│ API │ │Raft │ │ P2P │ │Contr.│ │Gov. │ │Privacy │
└──┬──┘ └──┬──┘ └──┬───┘ └──┬───┘ └──┬──┘ └───┬────┘
└───────┴───────┴────┬───┴────────┴────────┘
┌──────▼──────┐
│ Core │ (blocks, transactions, merkle)
└──────┬──────┘
┌────────────┼────────────┐
┌─────▼─────┐ ┌──────▼─────┐
│ SQLite │ │ Ed25519 │
└────────────┘ └─────────────┘
Set up a multi-organization private network:
# Node 1 (bootstrap)
miniledger init -d ./node1
miniledger start -d ./node1 --consensus raft --p2p-port 4440 --api-port 4441
# Node 2 (joins the network)
miniledger init -d ./node2
miniledger join ws://localhost:4440 -d ./node2 --p2p-port 4442 --api-port 4443
# Node 3 (joins the network)
miniledger init -d ./node3
miniledger join ws://localhost:4440 -d ./node3 --p2p-port 4444 --api-port 4445Each node maintains a full copy of the ledger. Raft consensus ensures all nodes agree on the same block history, with automatic leader election and fault tolerance.
| Command | Description |
|---|---|
miniledger init |
Initialize a new node (create keys, genesis block) |
miniledger start |
Start the node |
miniledger join <addr> |
Join an existing network |
miniledger demo |
Run a 3-node demo cluster |
miniledger status |
Show node status |
miniledger tx submit <json> |
Submit a transaction |
miniledger query <sql> |
Query state with SQL |
miniledger keys show |
Show node's public key |
miniledger peers list |
List connected peers |
| Endpoint | Method | Description |
|---|---|---|
/status |
GET | Node status (height, peers, uptime) |
/blocks |
GET | Block list (paginated: ?page=N&limit=M) |
/blocks/:height |
GET | Block by height |
/blocks/latest |
GET | Latest block |
/tx |
POST | Submit transaction |
/tx/:hash |
GET | Transaction by hash |
/tx/recent |
GET | Confirmed transactions (paginated, filterable by ?type=) |
/tx/sender/:pubkey |
GET | Transactions by sender address |
/state |
GET | State entries (paginated: ?page=N&limit=M) |
/state/:key |
GET | State entry by key |
/state/query |
POST | SQL query ({sql: "SELECT ..."}) |
/search |
GET | Unified search (?q=<block height, tx hash, key, address>) |
/peers |
GET | Connected peers |
/consensus |
GET | Consensus state |
/proposals |
GET | Governance proposals |
/proposals/:id |
GET | Proposal by ID |
/contracts |
GET | Deployed contracts |
/identity |
GET | Node identity |
/dashboard |
GET | Web explorer dashboard |
| MiniLedger | Hyperledger Fabric | R3 Corda | Quorum | |
|---|---|---|---|---|
| Setup time | 10 seconds | Hours/days | Hours | Hours |
| Dependencies | npm install |
Docker, K8s, CAs | JVM, Corda node | JVM, Go-Ethereum |
| Config files | 0 (auto) | Dozens of YAML | Multiple configs | Genesis + static nodes |
| Consensus | Raft (built-in) | Raft (separate orderer) | Notary service | IBFT / Raft |
| Smart contracts | JavaScript | Go/Java/Node | Kotlin/Java | Solidity |
| State queries | SQL | CouchDB queries | JPA/Vault | No native query |
| Privacy | Per-record ACLs | Channels (complex) | Point-to-point | Private transactions |
| Governance | On-chain voting | Off-chain manual | Off-chain | Off-chain |
| Dashboard | Built-in explorer | None (3rd party) | None | None |
| Embeddable | Yes (npm library) | No | No | No |
- Runtime: Node.js >= 22
- State: SQLite (better-sqlite3, WAL mode)
- Crypto: @noble/ed25519 + @noble/hashes (audited, pure JS)
- P2P: WebSocket mesh (ws)
- HTTP: Hono
- CLI: Commander
- Build: tsup (dual CJS/ESM)
- Tests: Vitest (86 tests)
Apache-2.0
Built by Chainscore Labs — blockchain infrastructure and developer tooling.
Need custom blockchain solutions, integrations, or developer tooling?
hello@chainscore.finance · chainscorelabs.com