Skip to main content

DevnetManager API

Manages the local Cardano devnet lifecycle.

createDevnetManager()​

Factory function to create a DevnetManager instance.

import { createDevnetManager } from 'cardano-devkit';

const devnet = createDevnetManager(config);

Parameters​

interface DevnetManagerConfig {
  // Port for the indexer API
  port?: number;  // Default: 10080

  // Block production interval in milliseconds
  blockTimeMs?: number;  // Default: 1000, Min: 100

  // Slot length in seconds
  slotLength?: number;  // Default: 1.0

  // Enable WebSocket subscriptions
  enableWebSocket?: boolean;  // Default: false

  // Enable multi-node setup
  enableMultiNode?: boolean;  // Default: false

  // Number of nodes (if multi-node enabled)
  nodeCount?: number;  // Default: 1

  // Disable faucet rate limiting
  faucetRateLimit?: boolean;  // Default: true
}

Returns​

DevnetManager instance

Example​

// Basic usage
const devnet = createDevnetManager();

// With fast blocks
const devnet = createDevnetManager({
  port: 10080,
  blockTimeMs: 200,
  enableWebSocket: true
});

DevnetManager Class​

start()​

Start the local devnet.

await devnet.start();

Returns: Promise<void>

Behavior:

  • Starts Docker containers for cardano-node, indexer, and explorer
  • Waits for services to be healthy
  • Applies configuration (block time, etc.)

Throws: Error if Docker is not available or containers fail to start

stop()​

Stop the local devnet.

await devnet.stop();

Returns: Promise<void>

Behavior:

  • Stops all Docker containers
  • Preserves data (unless --reset was used)

restart()​

Restart the devnet with fresh state.

await devnet.restart();

Returns: Promise<void>

Behavior:

  • Stops containers
  • Removes volumes (fresh state)
  • Starts containers

isRunning()​

Check if the devnet is currently running.

const running = await devnet.isRunning();

Returns: Promise<boolean>

getTip()​

Get the current chain tip.

const tip = await devnet.getTip();

Returns: Promise<ChainTip>

interface ChainTip {
  slot: number;
  height: number;
  hash: string;
  time: number;
}

Example:

const tip = await devnet.getTip();
console.log(`Slot: ${tip.slot}, Block: ${tip.height}`);

topup()​

Fund an address with test ADA.

const txHash = await devnet.topup(address, amount);

Parameters:

  • address: string - Bech32 address to fund
  • amount: bigint - Amount in lovelace (optional, default: 1000 ADA)

Returns: Promise<string> - Transaction hash

Example:

// Fund with 100 ADA
const txHash = await devnet.topup(
  'addr_test1qz...',
  100_000_000n
);

// Wait for confirmation
await lucid.awaitTx(txHash);

getApiUrl()​

Get the API URL for the indexer.

const url = devnet.getApiUrl();
// 'http://localhost:10080/api/v1'

Returns: string

getWebSocketUrl()​

Get the WebSocket URL for subscriptions.

const url = devnet.getWebSocketUrl();
// 'ws://localhost:10180/ws'

Returns: string

getExplorerUrl()​

Get the block explorer URL.

const url = devnet.getExplorerUrl();
// 'http://localhost:8081'

Returns: string

createFork()​

Create a new chain fork for testing (experimental).

const forkId = await devnet.createFork(name);

Parameters:

  • name: string - Fork identifier

Returns: Promise<string> - Fork ID

Note: This is an experimental feature for rollback testing.

joinFork()​

Join an existing chain fork.

await devnet.joinFork(forkId);

Parameters:

  • forkId: string - Fork ID from createFork()

Returns: Promise<void>

CLI Commands​

The DevnetManager functionality is also available via CLI:

# Start devnet
npx cardano-devkit start [options]

# Stop devnet
npx cardano-devkit stop

# Get status
npx cardano-devkit status

# Get chain tip
npx cardano-devkit tip

# Fund address
npx cardano-devkit topup <address> [--amount <lovelace>]

# Reset state
npx cardano-devkit reset

CLI Options​

Options:
  --port <port>         API port (default: 10080)
  --block-time <ms>     Block time in milliseconds (default: 1000)
  --websocket           Enable WebSocket subscriptions
  --persist             Persist data across restarts
  -h, --help           Display help

Type Definitions​

DevnetManagerConfig​

interface DevnetManagerConfig {
  port?: number;
  blockTimeMs?: number;
  slotLength?: number;
  enableWebSocket?: boolean;
  enableMultiNode?: boolean;
  nodeCount?: number;
  faucetRateLimit?: boolean;
}

ChainTip​

interface ChainTip {
  slot: number;
  height: number;
  hash: string;
  time: number;
}

DevnetStatus​

interface DevnetStatus {
  running: boolean;
  port: number;
  blockTime: number;
  tip: ChainTip | null;
  containers: {
    node: 'running' | 'stopped' | 'error';
    indexer: 'running' | 'stopped' | 'error';
    explorer: 'running' | 'stopped' | 'error';
  };
}