miniledger 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,41 @@
-# MiniLedger
+<p align="center">
+  <img src="assets/miniledger-banner.svg" alt="MiniLedger — Private Blockchain Framework for Node.js" width="720" />
+</p>
 
-**The SQLite of private blockchains.** Zero-config, embeddable, SQL-queryable.
+<h3 align="center">Private Blockchain Framework for Node.js</h3>
+
+<p align="center">
+  Zero-config permissioned ledger with Raft consensus, smart contracts, SQL queries, and a built-in block explorer.<br/>
+  The simplest way to add a distributed ledger to any application.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/miniledger"><img src="https://img.shields.io/npm/v/miniledger.svg" alt="npm version" /></a>
+  <a href="https://github.com/Chainscore/miniledger/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="node version" />
+  <img src="https://img.shields.io/badge/consensus-Raft-blue.svg" alt="Raft consensus" />
+  <img src="https://img.shields.io/badge/state-SQLite-orange.svg" alt="SQLite state" />
+</p>
+
+---
 
 ```
 npm install miniledger
 ```
 
-MiniLedger is a private/permissioned blockchain that runs in a single Node.js process. No Docker. No Kubernetes. No certificate authorities. Just `npm install` and go.
+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.
+
+## Why MiniLedger?
+
+- **10-second setup** — `npm install miniledger && npx miniledger start`. No infrastructure.
+- **SQL-queryable state** — World state lives in SQLite. Run `SELECT * FROM world_state` directly.
+- **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.
 
 ## Quick Start
 
@@ -25,7 +54,7 @@ curl -X POST http://localhost:4441/state/query \
   -H "Content-Type: application/json" \
   -d '{"sql": "SELECT * FROM world_state"}'
 
-# Open the dashboard
+# Open the block explorer dashboard
 open http://localhost:4441/dashboard
 ```
 
@@ -35,9 +64,65 @@ open http://localhost:4441/dashboard
 npx miniledger demo
 ```
 
-Spins up a 3-node Raft cluster, deploys contracts, submits sample data, and opens a web dashboard.
+Spins 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.
+
+### Block Explorer Dashboard
+
+<p align="center">
+  <img src="assets/dashboard-screenshot.png" alt="MiniLedger Block Explorer Dashboard" width="800" />
+</p>
+
+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
+
+## Transaction Examples
 
-## Programmatic API
+Submit data via `curl` or the CLI:
+
+```bash
+# 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:
+
+```bash
+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"
+```
+
+## Programmatic API (Embeddable Blockchain)
+
+Use MiniLedger as a library — embed a private blockchain directly in your Node.js application:
 
 ```typescript
 import { MiniLedger } from 'miniledger';
@@ -76,16 +161,29 @@ await node.submit({
 
 | Feature | Description |
 |---------|-------------|
-| **Zero config** | No Docker, no K8s, no certificate authorities. Single process. |
-| **SQL queryable** | State stored in SQLite. Query with `SELECT * FROM world_state`. |
-| **Raft consensus** | Leader election, log replication, fault tolerance. |
-| **Smart contracts** | Write contracts in JavaScript. Deploy via transactions. |
-| **Per-record privacy** | AES-256-GCM field encryption with ACLs. No channels. |
-| **On-chain governance** | Propose and vote on network changes. Quorum-based. |
-| **Web dashboard** | Built-in block explorer, state browser, SQL console. |
+| **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 crypto. No PKI setup required. |
-| **TypeScript native** | Full type safety. Dual CJS/ESM package. |
+| **Ed25519 identity** | Audited cryptographic signatures. No PKI setup required. |
+| **TypeScript native** | Full type safety. Dual CJS/ESM package. Embed in any Node.js app. |
+
+## Use Cases
+
+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
 
 ## Architecture
 
@@ -113,22 +211,26 @@ await node.submit({
         └────────────┘           └─────────────┘
 ```
 
-## Multi-Node Cluster
+## Multi-Node Consortium Cluster
+
+Set up a multi-organization private network:
 
 ```bash
 # Node 1 (bootstrap)
 miniledger init -d ./node1
 miniledger start -d ./node1 --consensus raft --p2p-port 4440 --api-port 4441
 
-# Node 2
+# Node 2 (joins the network)
 miniledger init -d ./node2
 miniledger join ws://localhost:4440 -d ./node2 --p2p-port 4442 --api-port 4443
 
-# Node 3
+# Node 3 (joins the network)
 miniledger init -d ./node3
 miniledger join ws://localhost:4440 -d ./node3 --p2p-port 4444 --api-port 4445
 ```
 
+Each 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.
+
 ## CLI Commands
 
 | Command | Description |
@@ -148,32 +250,39 @@ miniledger join ws://localhost:4440 -d ./node3 --p2p-port 4444 --api-port 4445
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/status` | GET | Node status (height, peers, uptime) |
-| `/blocks` | GET | Recent blocks |
+| `/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 |
-| `/dashboard` | GET | Web dashboard |
-
-## Comparison
-
-| | MiniLedger | Hyperledger Fabric | R3 Corda |
-|---|---|---|---|
-| **Setup time** | 10 seconds | Hours/days | Hours |
-| **Dependencies** | `npm install` | Docker, K8s, CAs | JVM, Corda node |
-| **Config files** | 0 (auto) | Dozens of YAML | Multiple configs |
-| **Consensus** | Raft (built-in) | Raft (separate orderer) | Notary service |
-| **Smart contracts** | JavaScript | Go/Java/Node | Kotlin/Java |
-| **State queries** | SQL | CouchDB queries | JPA/Vault |
-| **Privacy** | Per-record ACLs | Channels (complex) | Point-to-point |
-| **Governance** | On-chain voting | Off-chain manual | Off-chain |
-| **Dashboard** | Built-in | None (3rd party) | None |
+| `/identity` | GET | Node identity |
+| `/dashboard` | GET | Web explorer dashboard |
+
+## Comparison with Enterprise Blockchain Platforms
+
+| | 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 |
 
 ## Tech Stack
 
@@ -184,8 +293,29 @@ miniledger join ws://localhost:4440 -d ./node3 --p2p-port 4444 --api-port 4445
 - **HTTP:** Hono
 - **CLI:** Commander
 - **Build:** tsup (dual CJS/ESM)
-- **Tests:** Vitest
+- **Tests:** Vitest (86 tests)
 
 ## License
 
 Apache-2.0
+
+---
+
+<p align="center">
+  <br />
+  <a href="https://chainscorelabs.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/chainscore-labs-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="assets/chainscore-labs-light.png" />
+      <img src="assets/chainscore-labs-light.png" alt="Chainscore Labs" width="280" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  Built by <a href="https://chainscorelabs.com"><strong>Chainscore Labs</strong></a> — blockchain infrastructure and developer tooling.
+  <br />
+  Need custom blockchain solutions, integrations, or developer tooling?
+  <br />
+  <a href="mailto:hello@chainscore.finance">hello@chainscore.finance</a> &nbsp;&middot;&nbsp; <a href="https://chainscorelabs.com">chainscorelabs.com</a>
+</p>