Skip to main content

Network Overview

Cardano DevKit supports seamless switching between networks for different stages of development.

Supported Networks​

NetworkTypeBlock TimeUse Case
LocalDevnetLocal100ms-1sDevelopment, testing
PreviewTestnet~20sEarly testing
PreprodTestnet~20sPre-production staging
MainnetProduction~20sLive deployment

Development Workflow​

Local Devnet → Preview/Preprod → Mainnet
     ↓              ↓              ↓
   Rapid         Testnet       Production
 Iteration       Testing       Deployment
  1. Local Devnet: Rapid development with 200ms blocks
  2. Preprod: Test with realistic network conditions
  3. Mainnet: Deploy with confidence

Quick Network Switching​

Using Helper Methods​

import { createDevKit } from 'cardano-devkit';

const devKit = createDevKit({ network: 'LocalDevnet' });
await devKit.init();

// Switch to testnet
await devKit.usePreprod();

// Switch to preview
await devKit.usePreview();

// Switch to mainnet (requires confirmation)
await devKit.useMainnet({ confirmMainnet: true });

// Back to local
await devKit.useLocalDevnet();

Using switchNetwork​

// Generic network switch
await devKit.switchNetwork('Preview');
await devKit.switchNetwork('Preprod');

// Mainnet requires explicit options
await devKit.switchNetwork('Mainnet', { confirmMainnet: true });

Environment Detection​

// Check current environment
const env = devKit.getEnvironment();
console.log(env); // 'development' | 'testnet' | 'production'

// Safety checks
if (devKit.isSafeForTesting()) {
  // OK to use test operations
}

if (devKit.isLocalDevnet()) {
  // Local devnet specific features
  await devKit.topup(address);
}

if (devKit.isTestnet()) {
  // Testnet features
}

Network Configuration​

Default Configuration​

const devKit = createDevKit({
  network: 'Preprod' // Default
});

Custom Provider​

const devKit = createDevKit({
  network: 'Preprod',
  provider: {
    type: 'blockfrost',
    apiKey: process.env.BLOCKFROST_KEY
  }
});

Local Devnet with Custom Port​

const devKit = createDevKit({
  network: 'LocalDevnet',
  provider: {
    type: 'koios',
    baseUrl: 'http://localhost:9090/api/v1'
  },
  localDevnetConfig: {
    blockTimeMs: 200
  }
});

Provider Types​

ProviderNetworksFeatures
BlockfrostAllHosted, reliable, rate-limited
KoiosAllSelf-hostable, no rate limits
MaestroPreprod, MainnetHigh performance
CustomAnyYour own provider

Setting Provider per Network​

// Different providers for different networks
const configs = {
  development: {
    network: 'LocalDevnet',
    provider: { type: 'koios', baseUrl: 'http://localhost:10080/api/v1' }
  },
  staging: {
    network: 'Preprod',
    provider: { type: 'blockfrost', apiKey: process.env.BLOCKFROST_PREPROD }
  },
  production: {
    network: 'Mainnet',
    provider: { type: 'blockfrost', apiKey: process.env.BLOCKFROST_MAINNET }
  }
};

const env = process.env.NODE_ENV || 'development';
const devKit = createDevKit(configs[env]);

Mainnet Safety​

Switching to mainnet requires explicit confirmation to prevent accidents:

// ❌ This will throw an error
await devKit.useMainnet();
// Error: Mainnet switch requires explicit confirmation

// ✅ Correct way
await devKit.useMainnet({
  confirmMainnet: true,
  checkWalletBalance: true, // Optional: warn if wallet has funds
  requireReadOnlyFirst: true // Optional: connect read-only first
});

Mainnet Checklist​

Before switching to mainnet, ensure:

  • All tests pass on Preprod
  • Smart contracts are audited
  • Wallet backup is secure
  • Transaction fees are acceptable
  • Error handling is robust

Network-Specific Features​

FeatureLocalDevnetPreviewPreprodMainnet
FaucetBuilt-inExternalExternalN/A
Fast blocks✅❌❌❌
Reset state✅❌❌❌
Free ADA✅✅✅❌
Real value❌❌❌✅

Network Magic Numbers​

For advanced use cases:

NetworkMagic ID
Mainnet764824073
Preprod1
Preview2
LocalDevnet42 (custom)

Next Steps​