Skip to content

Commit bdfe3ed

Browse files
solidsnakedevsolidsnakedev
committed
docs: add devnet docs
1 parent 0b4c0ab commit bdfe3ed

File tree

8 files changed

+1385
-0
lines changed

8 files changed

+1385
-0
lines changed

‎docs/content/docs/devnet/configuration.mdx‎

Lines changed: 453 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/content/docs/devnet/getting-started.mdx‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
title: Getting Started
3+
description: Create and manage your first local Cardano devnet cluster
4+
---
5+
6+
# Getting Started with Devnet
7+
8+
This guide walks through creating, starting, and managing a local Cardano development network. You'll learn cluster lifecycle operations, container management, and how to integrate Kupo and Ogmios for full blockchain access.
9+
10+
## Installation
11+
12+
Install the devnet package alongside the Evolution SDK:
13+
14+
```bash
15+
pnpm add @evolution-sdk/devnet @evolution-sdk/evolution
16+
```
17+
18+
The package requires Docker to be running. Verify Docker is available:
19+
20+
```bash
21+
docker --version
22+
```
23+
24+
## Basic Cluster Creation
25+
26+
A devnet cluster is the foundation of your local blockchain environment. The cluster consists of a cardano-node container that produces blocks and validates transactions.
27+
28+
Creating a minimal cluster requires only a name and port configuration. The SDK handles Docker image pulling, container creation, volume management, and genesis file generation automatically.
29+
30+
```typescript twoslash
31+
import { Devnet } from "@evolution-sdk/devnet";
32+
33+
// Create a basic devnet cluster
34+
const cluster = await Devnet.Cluster.make({
35+
clusterName: "my-first-devnet",
36+
ports: { node: 3001, submit: 3002 }
37+
});
38+
39+
console.log("Cluster created:", cluster.cardanoNode.name);
40+
```
41+
42+
The `make` function returns a cluster configuration containing container references. The cardano-node will bind to port 3001 for peer connections and port 3002 for transaction submission.
43+
44+
## Starting the Cluster
45+
46+
Once created, start the cluster to begin block production:
47+
48+
```typescript twoslash
49+
import { Devnet } from "@evolution-sdk/devnet";
50+
const cluster = await Devnet.Cluster.make()
51+
52+
// Start all containers in the cluster
53+
await Devnet.Cluster.start(cluster);
54+
55+
console.log("Devnet is now producing blocks");
56+
57+
// Wait for the node to fully initialize
58+
await new Promise(resolve => setTimeout(resolve, 3000));
59+
```
60+
61+
The node begins producing blocks immediately using the default genesis configuration. Initial startup takes a few seconds as the node processes the genesis block and establishes its database.
62+
63+
## Checking Container Status
64+
65+
Monitor individual container states to verify the cluster is running correctly:
66+
67+
```typescript twoslash
68+
import { Devnet } from "@evolution-sdk/devnet";
69+
const cluster = await Devnet.Cluster.make()
70+
71+
// Get detailed container status
72+
const status = await Devnet.Container.getStatus(cluster.cardanoNode);
73+
74+
console.log("Container state:", status?.State.Status); // "running"
75+
console.log("Container health:", status?.State.Health?.Status); // "healthy"
76+
```
77+
78+
The status object includes full Docker inspect output: state, network settings, mounts, resource usage, and health check results.
79+
80+
## Stopping and Removing
81+
82+
Clean up resources when testing is complete:
83+
84+
```typescript twoslash
85+
import { Devnet } from "@evolution-sdk/devnet";
86+
const cluster = await Devnet.Cluster.make()
87+
88+
// Stop all containers gracefully
89+
await Devnet.Cluster.stop(cluster);
90+
91+
console.log("Cluster stopped");
92+
93+
// Remove containers and networks
94+
await Devnet.Cluster.remove(cluster);
95+
96+
console.log("Cluster removed");
97+
```
98+
99+
Stopping containers preserves blockchain state in Docker volumes. Removing deletes containers but keeps named volumes by default. To completely reset state, manually remove volumes using Docker commands.
100+
101+
## Adding Kupo and Ogmios
102+
103+
Most applications need more than just a cardano-node. Kupo provides fast UTxO indexing, while Ogmios exposes JSON-RPC and WebSocket APIs for blockchain queries.
104+
105+
Enable both services when creating the cluster:
106+
107+
```typescript twoslash
108+
import { Devnet } from "@evolution-sdk/devnet";
109+
110+
const cluster = await Devnet.Cluster.make({
111+
clusterName: "full-stack-devnet",
112+
ports: { node: 3001, submit: 3002 },
113+
kupo: {
114+
enabled: true,
115+
port: 1442,
116+
logLevel: "Info"
117+
},
118+
ogmios: {
119+
enabled: true,
120+
port: 1337,
121+
logLevel: "info"
122+
}
123+
});
124+
125+
// Start all three containers
126+
await Devnet.Cluster.start(cluster);
127+
128+
// Wait for services to initialize
129+
await new Promise(resolve => setTimeout(resolve, 5000));
130+
131+
// Check Kupo status
132+
if (cluster.kupo) {
133+
const kupoStatus = await Devnet.Container.getStatus(cluster.kupo);
134+
console.log("Kupo status:", kupoStatus?.State.Status);
135+
}
136+
137+
// Check Ogmios status
138+
if (cluster.ogmios) {
139+
const ogmiosStatus = await Devnet.Container.getStatus(cluster.ogmios);
140+
console.log("Ogmios status:", ogmiosStatus?.State.Status);
141+
}
142+
```
143+
144+
Kupo and Ogmios containers share the node's socket via a Docker volume. They automatically detect the custom network configuration and begin syncing from genesis.
145+
146+
The log levels control output verbosity:
147+
- **Kupo**: `Debug`, `Info`, `Warning`, `Error`
148+
- **Ogmios**: `debug`, `info`, `notice`, `warning`, `error`
149+
150+
## Individual Container Operations
151+
152+
Fine-grained control over containers enables testing failure scenarios and resource management:
153+
154+
```typescript twoslash
155+
import { Devnet } from "@evolution-sdk/devnet";
156+
const cluster = await Devnet.Cluster.make()
157+
158+
// Stop just the cardano-node
159+
await Devnet.Container.stop(cluster.cardanoNode);
160+
161+
console.log("Node stopped, Kupo and Ogmios still running");
162+
163+
// Check stopped status
164+
const stoppedStatus = await Devnet.Container.getStatus(cluster.cardanoNode);
165+
console.log("Status:", stoppedStatus?.State.Status); // "exited"
166+
167+
// Restart the node
168+
await Devnet.Container.start(cluster.cardanoNode);
169+
170+
await new Promise(resolve => setTimeout(resolve, 2000));
171+
172+
// Verify running again
173+
const runningStatus = await Devnet.Container.getStatus(cluster.cardanoNode);
174+
console.log("Status:", runningStatus?.State.Status); // "running"
175+
```
176+
177+
Individual operations work on any container in the cluster. Kupo and Ogmios depend on the cardano-node socket, so stopping the node will cause queries to fail until it restarts.
178+
179+
## Complete Workflow Example
180+
181+
Putting it all together, here's a typical development session:
182+
183+
```typescript twoslash
184+
import { Devnet } from "@evolution-sdk/devnet";
185+
186+
async function runDevnetSession() {
187+
// Create cluster with full stack
188+
const cluster = await Devnet.Cluster.make({
189+
clusterName: "dev-session",
190+
ports: { node: 3001, submit: 3002 },
191+
kupo: { enabled: true, port: 1442 },
192+
ogmios: { enabled: true, port: 1337 }
193+
});
194+
195+
try {
196+
// Start the environment
197+
await Devnet.Cluster.start(cluster);
198+
console.log("✓ Devnet started");
199+
200+
// Wait for initialization
201+
await new Promise(resolve => setTimeout(resolve, 5000));
202+
203+
// Verify all services are healthy
204+
const nodeStatus = await Devnet.Container.getStatus(cluster.cardanoNode);
205+
const kupoStatus = cluster.kupo
206+
? await Devnet.Container.getStatus(cluster.kupo)
207+
: null;
208+
const ogmiosStatus = cluster.ogmios
209+
? await Devnet.Container.getStatus(cluster.ogmios)
210+
: null;
211+
212+
console.log("✓ Node:", nodeStatus?.State.Status);
213+
console.log("✓ Kupo:", kupoStatus?.State.Status);
214+
console.log("✓ Ogmios:", ogmiosStatus?.State.Status);
215+
216+
// Your development work happens here
217+
console.log("\n🚀 Devnet ready for development");
218+
console.log(" Ogmios: http://localhost:1337");
219+
console.log(" Kupo: http://localhost:1442");
220+
221+
// Keep running for development
222+
// In real usage, this would be your test suite or app runtime
223+
await new Promise(resolve => setTimeout(resolve, 10000));
224+
225+
} finally {
226+
// Always clean up
227+
await Devnet.Cluster.stop(cluster);
228+
await Devnet.Cluster.remove(cluster);
229+
console.log("\n✓ Devnet stopped and removed");
230+
}
231+
}
232+
233+
runDevnetSession().catch(console.error);
234+
```
235+
236+
This pattern ensures resources are properly cleaned up even if errors occur during development.
237+
238+
## Next Steps
239+
240+
Now that you can create and manage devnet clusters, learn how to:
241+
242+
- **[Configuration](/docs/devnet/configuration)**: Customize genesis parameters, fund addresses, and modify protocol settings
243+
- **[Integration](/docs/devnet/integration)**: Use the Evolution SDK client to query the blockchain and submit transactions
244+
245+
## Troubleshooting
246+
247+
**Port conflicts**: If ports are already in use, choose different values:
248+
249+
```typescript
250+
ports: { node: 4001, submit: 4002 }
251+
```
252+
253+
**Slow startup**: Initial Docker image pulls can take several minutes. Subsequent starts are fast. The SDK automatically pulls missing images.
254+
255+
**Container won't start**: Check Docker daemon is running and you have sufficient disk space for blockchain data.
256+
257+
**Network errors**: Ensure no firewall rules block localhost ports. The containers bind to 127.0.0.1 by default.

‎docs/content/docs/devnet/index.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Devnet
3+
description: Local Cardano development network with Docker
4+
---
5+
6+
# Devnet
7+
8+
The Evolution SDK provides a complete local Cardano development network powered by Docker. Spin up a full Cardano node with optional Kupo and Ogmios services for testing applications in a controlled environment.
9+
10+
## What is Devnet?
11+
12+
Devnet creates an isolated Cardano blockchain running entirely on your local machine. It manages Docker containers for cardano-node, Kupo (UTxO indexer), and Ogmios (JSON/WebSocket API), giving you full control over network configuration, genesis parameters, and initial funds.
13+
14+
Unlike testnet or mainnet, devnet provides instant block production, customizable genesis state, and complete privacy. Test transaction flows, smart contracts, and wallet integration without consuming real assets or waiting for block confirmations.
15+
16+
## When to Use Devnet
17+
18+
Devnet accelerates development by eliminating external dependencies:
19+
20+
**Development Workflows**: Test applications against a pristine blockchain state without network latency or rate limits. Reset state instantly by recreating the cluster.
21+
22+
**Automated Testing**: Run integration tests in CI/CD pipelines with reproducible blockchain environments. Each test suite gets a clean network state.
23+
24+
**Smart Contract Development**: Deploy and test Plutus scripts with controlled genesis UTxOs. Debug transaction failures in isolation.
25+
26+
**Protocol Exploration**: Experiment with custom protocol parameters (fees, slot timing, Plutus cost models) to understand behavior without risking real funds.
27+
28+
## Why Use Devnet?
29+
30+
Traditional testnet development introduces friction: unpredictable faucet availability, slow block times, shared state with other developers, and API rate limits. Devnet solves these problems:
31+
32+
- **Instant Setup**: Launch a complete Cardano network in seconds
33+
- **Custom Genesis**: Fund any address with any amount of ADA at network creation
34+
- **Fast Blocks**: Configure slot timing from 20ms to match your testing needs
35+
- **Full Control**: Start, stop, restart, and reset network state at will
36+
- **Offline Testing**: No internet required once Docker images are pulled
37+
- **Reproducible State**: Deterministic genesis configuration for consistent test results
38+
39+
## How Devnet Works
40+
41+
Devnet orchestrates three Docker containers:
42+
43+
1. **cardano-node**: Produces blocks and validates transactions using a custom genesis configuration
44+
2. **Kupo** (optional): Indexes UTxOs and provides fast lookups via HTTP API
45+
3. **Ogmios** (optional): Exposes JSON-RPC and WebSocket interfaces for blockchain queries
46+
47+
The SDK handles image pulling, container lifecycle, network creation, and health checks. You interact through simple async APIs that abstract Docker complexity.
48+
49+
## Quick Example
50+
51+
Create a devnet cluster with funded addresses:
52+
53+
```typescript twoslash
54+
import { Devnet } from "@evolution-sdk/devnet";
55+
56+
// Create cluster with custom genesis
57+
const cluster = await Devnet.Cluster.make({
58+
clusterName: "my-devnet",
59+
ports: { node: 3001, submit: 3002 },
60+
shelleyGenesis: {
61+
slotLength: 0.1, // 100ms blocks
62+
initialFunds: {
63+
"addr_test1_hex_address": 1_000_000_000_000 // 1M ADA
64+
}
65+
}
66+
});
67+
68+
// Start the network
69+
await Devnet.Cluster.start(cluster);
70+
71+
// Network is ready for transactions
72+
console.log("Devnet running on port", 3001);
73+
74+
// Cleanup when done
75+
await Devnet.Cluster.stop(cluster);
76+
await Devnet.Cluster.remove(cluster);
77+
```
78+
79+
## Prerequisites
80+
81+
- **Docker**: Install [Docker Desktop](https://www.docker.com/products/docker-desktop) or Docker Engine
82+
- **Node.js**: Version 18 or higher
83+
84+
Verify Docker is running:
85+
86+
```bash
87+
docker --version
88+
```
89+
90+
## Navigation
91+
92+
<Cards>
93+
<Card title="Getting Started" href="/docs/devnet/getting-started">
94+
Create your first devnet cluster and run basic operations
95+
</Card>
96+
<Card title="Configuration" href="/docs/devnet/configuration">
97+
Customize genesis parameters, protocol settings, and network behavior
98+
</Card>
99+
<Card title="Integration" href="/docs/devnet/integration">
100+
Build complete workflows with Evolution SDK client for transactions
101+
</Card>
102+
</Cards>
103+
104+
## Next Steps
105+
106+
Start with [Getting Started](/docs/devnet/getting-started) to launch your first devnet cluster, or jump to [Configuration](/docs/devnet/configuration) to learn about genesis customization.

0 commit comments

Comments
 (0)