Local Devnet Overview
The local devnet is a private Cardano blockchain running on your machine, perfect for rapid development and testing.
Why Local Devnet?
| Aspect | Local Devnet | Public Testnet |
|---|---|---|
| Block Time | 100ms - 1s (configurable) | ~20 seconds |
| ADA Supply | Unlimited (faucet) | Limited (request from faucet) |
| Network Latency | Zero | Variable |
| Privacy | Complete | Public |
| Availability | Always (your machine) | Depends on network |
Architecture
┌──────────────────────────────────────────────────────┐
│ Your Application │
└────────────────────────┬─────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ Cardano DevKit │
│ ┌─────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ DevKit API │ │ DevnetManager │ │ React Hooks│ │
│ └─────────────┘ └───────────────┘ └────────────┘ │
└────────────────────────┬─────────────────────────────┘
│ HTTP/WebSocket
▼
┌──────────────────────────────────────────────────────┐
│ Local Devnet (Docker) │
│ ┌─────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Cardano Node│ │ Indexer API │ │ Explorer │ │
│ │ (Producer) │ │ (Blockfrost) │ │ (Web UI) │ │
│ └─────────────┘ └───────────────┘ └────────────┘ │
└──────────────────────────────────────────────────────┘
Components
Cardano Node
- Full cardano-node in block-producer mode
- Configurable block time (100ms minimum)
- Genesis with pre-funded addresses
Indexer API
- Blockfrost-compatible REST API
- SQLite storage for persistence
- WebSocket for real-time subscriptions
- Built-in faucet endpoint
Block Explorer
- Web UI to explore transactions
- Real-time block updates
- Address and transaction search
Quick Start
# Start with fast blocks
npx cardano-devkit start --block-time 200
# Check status
npx cardano-devkit status
# View current tip
npx cardano-devkit tip
# Stop devnet
npx cardano-devkit stop
Configuration Options
| Option | Default | Description |
|---|---|---|
--port | 8080 | API port |
--block-time | 1000 | Block time in milliseconds |
--websocket | true | Enable WebSocket subscriptions |
--explorer-port | 8081 | Block explorer port |
Programmatic Usage
import { createDevnetManager } from 'cardano-devkit';
const devnet = createDevnetManager({
port: 8080,
blockTimeMs: 200,
enableWebSocket: true
});
// Start devnet
await devnet.start();
// Get chain tip
const tip = await devnet.getTip();
console.log('Current slot:', tip.slot);
console.log('Block height:', tip.height);
// Fund an address
await devnet.topup(address, 1000_000_000n);
// Stop devnet
await devnet.stop();
Data Persistence
By default, the devnet resets on restart. To persist data:
# Start with persistence
npx cardano-devkit start --persist
# Reset persisted data
npx cardano-devkit reset