miniledger 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,191 @@
+# MiniLedger
+
+**The SQLite of private blockchains.** Zero-config, embeddable, SQL-queryable.
+
+```
+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.
+
+## Quick Start
+
+```bash
+# 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 dashboard
+open http://localhost:4441/dashboard
+```
+
+## 30-Second Demo
+
+```bash
+npx miniledger demo
+```
+
+Spins up a 3-node Raft cluster, deploys contracts, submits sample data, and opens a web dashboard.
+
+## Programmatic API
+
+```typescript
+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);
+      }
+    }`
+  }
+});
+```
+
+## Features
+
+| 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. |
+| **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. |
+
+## Architecture
+
+```
+                    ┌───────────┐
+                    │    CLI    │
+                    └─────┬─────┘
+                          │
+                    ┌─────▼─────┐
+                    │   Node    │  (orchestrator)
+                    └─────┬─────┘
+                          │
+      ┌───────┬───────┬───┴───┬───────┬───────┐
+      │       │       │       │       │       │
+   ┌──▼──┐ ┌─▼───┐ ┌─▼────┐ ┌▼─────┐ ┌▼────┐ ┌▼───────┐
+   │ API │ │Raft │ │ P2P  │ │Contr.│ │Gov. │ │Privacy │
+   └──┬──┘ └──┬──┘ └──┬───┘ └──┬───┘ └──┬──┘ └───┬────┘
+      └───────┴───────┴────┬───┴────────┴────────┘
+                    ┌──────▼──────┐
+                    │    Core     │  (blocks, transactions, merkle)
+                    └──────┬──────┘
+              ┌────────────┼────────────┐
+        ┌─────▼─────┐           ┌──────▼─────┐
+        │  SQLite    │           │  Ed25519    │
+        └────────────┘           └─────────────┘
+```
+
+## Multi-Node Cluster
+
+```bash
+# Node 1 (bootstrap)
+miniledger init -d ./node1
+miniledger start -d ./node1 --consensus raft --p2p-port 4440 --api-port 4441
+
+# Node 2
+miniledger init -d ./node2
+miniledger join ws://localhost:4440 -d ./node2 --p2p-port 4442 --api-port 4443
+
+# Node 3
+miniledger init -d ./node3
+miniledger join ws://localhost:4440 -d ./node3 --p2p-port 4444 --api-port 4445
+```
+
+## CLI Commands
+
+| 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 |
+
+## REST API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/status` | GET | Node status (height, peers, uptime) |
+| `/blocks` | GET | Recent blocks |
+| `/blocks/:height` | GET | Block by height |
+| `/blocks/latest` | GET | Latest block |
+| `/tx` | POST | Submit transaction |
+| `/tx/:hash` | GET | Transaction by hash |
+| `/state/:key` | GET | State entry by key |
+| `/state/query` | POST | SQL query (`{sql: "SELECT ..."}`) |
+| `/peers` | GET | Connected peers |
+| `/consensus` | GET | Consensus state |
+| `/proposals` | GET | Governance proposals |
+| `/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 |
+
+## Tech Stack
+
+- **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
+
+## License
+
+Apache-2.0

package/dashboard/app.js

@@ -0,0 +1,262 @@
+// MiniLedger Dashboard — vanilla JS, no build step
+const API = window.location.origin;
+let refreshTimer = null;
+
+// ── Fetch helpers ─────────────────────────────────────────────────
+
+async function api(path) {
+  try {
+    const res = await fetch(API + path);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+async function apiPost(path, body) {
+  try {
+    const res = await fetch(API + path, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+// ── Formatters ────────────────────────────────────────────────────
+
+function shortHash(h) {
+  if (!h) return '—';
+  return h.substring(0, 8) + '...' + h.substring(h.length - 6);
+}
+
+function timeAgo(ts) {
+  if (!ts) return '—';
+  const diff = Date.now() - ts;
+  if (diff < 1000) return 'just now';
+  if (diff < 60000) return Math.floor(diff / 1000) + 's ago';
+  if (diff < 3600000) return Math.floor(diff / 60000) + 'm ago';
+  return Math.floor(diff / 3600000) + 'h ago';
+}
+
+function formatUptime(ms) {
+  if (!ms) return '—';
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return s + 's';
+  if (s < 3600) return Math.floor(s / 60) + 'm ' + (s % 60) + 's';
+  return Math.floor(s / 3600) + 'h ' + Math.floor((s % 3600) / 60) + 'm';
+}
+
+// ── Update functions ──────────────────────────────────────────────
+
+async function updateStatus() {
+  const data = await api('/status');
+  if (!data) {
+    document.getElementById('status-dot').className = 'dot red';
+    document.getElementById('status-text').textContent = 'Disconnected';
+    return;
+  }
+
+  document.getElementById('status-dot').className = 'dot green';
+  document.getElementById('status-text').textContent = 'Running';
+  document.getElementById('node-id').textContent = data.nodeId;
+  document.getElementById('uptime').textContent = formatUptime(data.uptime);
+  document.getElementById('stat-height').textContent = data.chainHeight;
+  document.getElementById('stat-txpool').textContent = data.txPoolSize;
+  document.getElementById('stat-peers').textContent = data.peerCount;
+}
+
+async function updateBlocks() {
+  const data = await api('/blocks');
+  if (!data) return;
+
+  const el = document.getElementById('blocks-list');
+  document.getElementById('block-count').textContent = data.height + 1;
+
+  if (!data.blocks || data.blocks.length === 0) {
+    el.innerHTML = '<div class="empty-state">No blocks yet</div>';
+    return;
+  }
+
+  // Show newest first
+  const blocks = [...data.blocks].reverse();
+  el.innerHTML = blocks.map(b => `
+    <div class="block-item">
+      <span class="block-num">#${b.height}</span>
+      <span class="block-hash">${shortHash(b.hash)}</span>
+      <span class="block-meta">${b.transactions.length} tx · ${timeAgo(b.timestamp)}</span>
+    </div>
+  `).join('');
+}
+
+async function updateTransactions() {
+  // Get transactions from recent blocks
+  const data = await api('/blocks');
+  if (!data || !data.blocks) return;
+
+  const el = document.getElementById('tx-list');
+  const allTx = [];
+
+  for (const block of data.blocks) {
+    for (const tx of block.transactions) {
+      allTx.push({ ...tx, blockHeight: block.height });
+    }
+  }
+
+  allTx.sort((a, b) => b.timestamp - a.timestamp);
+  const recent = allTx.slice(0, 20);
+
+  document.getElementById('tx-count').textContent = allTx.length;
+
+  if (recent.length === 0) {
+    el.innerHTML = '<div class="empty-state">No transactions yet</div>';
+    return;
+  }
+
+  el.innerHTML = recent.map(tx => `
+    <div class="tx-item">
+      <span class="tx-hash">${shortHash(tx.hash)}</span>
+      <span class="tx-type">${tx.type}</span>
+      <div style="font-size:12px;color:var(--text-dim);margin-top:2px">
+        Block #${tx.blockHeight} · ${timeAgo(tx.timestamp)}
+      </div>
+    </div>
+  `).join('');
+}
+
+async function updatePeers() {
+  const data = await api('/peers');
+  if (!data) return;
+
+  const el = document.getElementById('peers-list');
+  document.getElementById('peer-badge').textContent = data.count;
+
+  if (!data.peers || data.peers.length === 0) {
+    el.innerHTML = '<div class="empty-state">No peers connected (solo mode)</div>';
+    return;
+  }
+
+  el.innerHTML = data.peers.map(p => `
+    <div class="peer-item">
+      <span class="dot ${p.status === 'connected' ? 'green' : 'red'}"></span>
+      <span class="peer-id">${p.nodeId}</span>
+      <span style="color:var(--text-dim);font-size:12px">${p.address || '—'}</span>
+      <span style="margin-left:auto;font-size:12px;color:var(--text-dim)">H:${p.chainHeight}</span>
+    </div>
+  `).join('');
+}
+
+async function updateContractsGov() {
+  const [contracts, proposals] = await Promise.all([
+    api('/contracts'),
+    api('/proposals'),
+  ]);
+
+  const el = document.getElementById('contracts-gov');
+  let html = '';
+
+  if (contracts && contracts.contracts && contracts.contracts.length > 0) {
+    html += '<div style="margin-bottom:12px;font-size:12px;color:var(--text-dim);font-weight:600">CONTRACTS</div>';
+    html += contracts.contracts.map(c => `
+      <div class="tx-item">
+        <strong>${c.name}</strong> <span class="tx-type">v${c.version}</span>
+        <div style="font-size:12px;color:var(--text-dim);margin-top:2px">by ${shortHash(c.deployedBy)}</div>
+      </div>
+    `).join('');
+  }
+
+  if (proposals && proposals.proposals && proposals.proposals.length > 0) {
+    html += '<div style="margin-top:12px;margin-bottom:12px;font-size:12px;color:var(--text-dim);font-weight:600">PROPOSALS</div>';
+    html += proposals.proposals.map(p => `
+      <div class="tx-item">
+        <strong>${p.title}</strong>
+        <span class="tx-type">${p.status}</span>
+        <div style="font-size:12px;color:var(--text-dim);margin-top:2px">
+          ${Object.keys(p.votes).length} votes · by ${shortHash(p.proposer)}
+        </div>
+      </div>
+    `).join('');
+  }
+
+  if (!html) {
+    html = '<div class="empty-state">No contracts or proposals</div>';
+  }
+
+  el.innerHTML = html;
+}
+
+async function updateStateCount() {
+  const data = await apiPost('/state/query', {
+    sql: 'SELECT COUNT(*) as count FROM world_state WHERE key NOT LIKE \'_%\'',
+  });
+  if (data && data.results && data.results.length > 0) {
+    document.getElementById('stat-state').textContent = data.results[0].count || 0;
+  }
+}
+
+// ── SQL Query ─────────────────────────────────────────────────────
+
+async function runQuery() {
+  const sql = document.getElementById('sql-input').value.trim();
+  if (!sql) return;
+
+  const el = document.getElementById('query-results');
+  el.innerHTML = '<div class="empty-state">Running...</div>';
+
+  const data = await apiPost('/state/query', { sql });
+  if (!data) {
+    el.innerHTML = '<div class="empty-state" style="color:var(--red)">Query failed</div>';
+    return;
+  }
+
+  if (data.error) {
+    el.innerHTML = `<div class="empty-state" style="color:var(--red)">${data.error}</div>`;
+    return;
+  }
+
+  if (!data.results || data.results.length === 0) {
+    el.innerHTML = '<div class="empty-state">No results</div>';
+    return;
+  }
+
+  const cols = Object.keys(data.results[0]);
+  const headerRow = cols.map(c => `<th>${c}</th>`).join('');
+  const rows = data.results.map(r =>
+    '<tr>' + cols.map(c => `<td title="${String(r[c] ?? '')}">${String(r[c] ?? '')}</td>`).join('') + '</tr>'
+  ).join('');
+
+  el.innerHTML = `
+    <table class="result-table">
+      <thead><tr>${headerRow}</tr></thead>
+      <tbody>${rows}</tbody>
+    </table>
+  `;
+}
+
+// Enter key runs query
+document.getElementById('sql-input').addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') runQuery();
+});
+
+// ── Refresh loop ──────────────────────────────────────────────────
+
+async function refreshAll() {
+  await Promise.all([
+    updateStatus(),
+    updateBlocks(),
+    updateTransactions(),
+    updatePeers(),
+    updateContractsGov(),
+    updateStateCount(),
+  ]);
+}
+
+// Initial load
+refreshAll();
+
+// Auto-refresh every 2 seconds
+refreshTimer = setInterval(refreshAll, 2000);

package/dashboard/index.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MiniLedger Dashboard</title>
+  <link rel="stylesheet" href="/dashboard/style.css">
+</head>
+<body>
+  <header>
+    <h1><span>Mini</span>Ledger</h1>
+    <div class="status-bar">
+      <span><span class="dot green" id="status-dot"></span><span id="status-text">Connecting...</span></span>
+      <span>Node: <strong id="node-id">—</strong></span>
+      <span>Uptime: <strong id="uptime">—</strong></span>
+    </div>
+  </header>
+
+  <div class="stats">
+    <div class="stat">
+      <div class="stat-value" id="stat-height">0</div>
+      <div class="stat-label">Block Height</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value" id="stat-txpool">0</div>
+      <div class="stat-label">TX Pool</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value" id="stat-peers">0</div>
+      <div class="stat-label">Peers</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value" id="stat-state">0</div>
+      <div class="stat-label">State Keys</div>
+    </div>
+  </div>
+
+  <div class="grid">
+    <!-- Blocks -->
+    <div class="card">
+      <div class="card-header">
+        Recent Blocks
+        <span class="badge" id="block-count">0</span>
+      </div>
+      <div class="card-body" id="blocks-list">
+        <div class="empty-state">Loading blocks...</div>
+      </div>
+    </div>
+
+    <!-- Transactions -->
+    <div class="card">
+      <div class="card-header">
+        Recent Transactions
+        <span class="badge" id="tx-count">0</span>
+      </div>
+      <div class="card-body" id="tx-list">
+        <div class="empty-state">No transactions yet</div>
+      </div>
+    </div>
+
+    <!-- SQL Query -->
+    <div class="card full-width">
+      <div class="card-header">
+        State Explorer
+        <span class="badge">SQL</span>
+      </div>
+      <div class="card-body">
+        <div class="query-area">
+          <input type="text" id="sql-input" placeholder="SELECT * FROM world_state LIMIT 20" value="SELECT * FROM world_state ORDER BY updated_at DESC LIMIT 20">
+          <button onclick="runQuery()">Run Query</button>
+        </div>
+        <div id="query-results">
+          <div class="empty-state">Run a query to see results</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Peers -->
+    <div class="card">
+      <div class="card-header">
+        Network Peers
+        <span class="badge" id="peer-badge">0</span>
+      </div>
+      <div class="card-body" id="peers-list">
+        <div class="empty-state">No peers connected</div>
+      </div>
+    </div>
+
+    <!-- Contracts & Governance -->
+    <div class="card">
+      <div class="card-header">
+        Contracts & Governance
+      </div>
+      <div class="card-body" id="contracts-gov">
+        <div class="empty-state">Loading...</div>
+      </div>
+    </div>
+  </div>
+
+  <script src="/dashboard/app.js"></script>
+</body>
+</html>