Devnet

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.

What is Devnet?

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.

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.

When to Use Devnet

Devnet accelerates development by eliminating external dependencies:

Development Workflows: Test applications against a pristine blockchain state without network latency or rate limits. Reset state instantly by recreating the cluster.

Automated Testing: Run integration tests in CI/CD pipelines with reproducible blockchain environments. Each test suite gets a clean network state.

Smart Contract Development: Deploy and test Plutus scripts with controlled genesis UTxOs. Debug transaction failures in isolation.

Protocol Exploration: Experiment with custom protocol parameters (fees, slot timing, Plutus cost models) to understand behavior without risking real funds.

Why Use Devnet?

Traditional testnet development introduces friction: unpredictable faucet availability, slow block times, shared state with other developers, and API rate limits. Devnet solves these problems:

• Instant Setup: Launch a complete Cardano network in seconds
• Custom Genesis: Fund any address with any amount of ADA at network creation
• Fast Blocks: Configure slot timing from 20ms to match your testing needs
• Full Control: Start, stop, restart, and reset network state at will
• Offline Testing: No internet required once Docker images are pulled
• Reproducible State: Deterministic genesis configuration for consistent test results

How Devnet Works

Devnet orchestrates three Docker containers:

1. cardano-node: Produces blocks and validates transactions using a custom genesis configuration
2. Kupo (optional): Indexes UTxOs and provides fast lookups via HTTP API
3. Ogmios (optional): Exposes JSON-RPC and WebSocket interfaces for blockchain queries

The SDK handles image pulling, container lifecycle, network creation, and health checks. You interact through simple async APIs that abstract Docker complexity.

Quick Example

Create a devnet cluster with funded addresses:

import { Cluster } from "@evolution-sdk/devnet";

// Create cluster with custom genesis
const cluster = await Cluster.make({
  clusterName: "my-devnet",
  ports: { node: 3001, submit: 3002 },
  shelleyGenesis: {
    slotLength: 0.1, // 100ms blocks
    initialFunds: {
      "addr_test1_hex_address": 1_000_000_000_000 // 1M ADA
    }
  }
});

// Start the network
await Cluster.start(cluster);

// Network is ready for transactions
console.log("Devnet running on port", 3001);

// Cleanup when done
await Cluster.stop(cluster);
await Cluster.remove(cluster);

Prerequisites

• Docker: Install Docker Desktop or Docker Engine
• Node.js: Version 18 or higher

Verify Docker is running:

docker --version

Navigation

Next Steps

Start with Getting Started to launch your first devnet cluster, or jump to Configuration to learn about genesis customization.