Setup devnet

<!-- Documentation lookup path: ${CLAUDE_SKILL_DIR}/../../docs/sources/ -->

Set Up a Cardano Development Environment

Help the developer set up a local Cardano development network for building, testing, and deploying smart contracts.

When to use

• Developer wants to run a local Cardano network for development
• Setting up Yaci DevKit or similar local devnet tooling
• Configuring local chain indexers (Kupo, Ogmios) for development
• Establishing a smart contract development workflow (build, deploy, test)
• Connecting to Preview or Preprod public testnets
• Setting up CI/CD pipelines for Cardano projects

When NOT to use

• Querying mainnet or production chain data (use query-chain skill)
• Choosing between SDKs or tools broadly (use suggest-tooling skill)
• Writing smart contract logic in Aiken or Plutus
• Wallet integration in a web frontend (use connect-wallet skill)

Key principles

1. Start local, then move to testnets. Local devnets give instant feedback. Use Preview/Preprod for integration testing.
2. Two fast local-devnet options. Yaci DevKit (standalone CLI tool with a visual explorer) and Evolution SDK devnet (@evolution-sdk/devnet, a TypeScript library) are both Docker-based — pick by workflow, not speed.
3. Automate from day one. Scripts for devnet startup, contract deployment, and testing save hours.
4. Match your devnet to your target network. Ensure protocol parameters and era match what you will deploy to.
5. Keep test wallets organized. Use named wallets with known keys for reproducible testing.

Workflow

Step 1: Choose the environment

Ask the developer (if not already clear):

• Are you developing smart contracts or off-chain code (or both)?
• Do you need a fully isolated local network or a shared testnet?
• What OS are you on? (Docker availability matters)
• Do you need governance features (Conway era)?

Environment	Best for	Setup time
Yaci DevKit	Smart contract dev, fast iteration, visual block explorer	5 minutes
Evolution SDK devnet	TypeScript projects; code-first devnet inside the test suite	5 minutes
Preview testnet	Integration testing, shared state, longer-lived deployments	10 minutes
Preprod testnet	Pre-production testing, mirrors mainnet parameters	10 minutes
Custom local cluster	Advanced scenarios, custom protocol params	30+ minutes

Step 2: Search Bundled Documentation

Search the bundled documentation for relevant content:

• ${CLAUDE_SKILL_DIR}/../../docs/sources/yaci-devkit/ - Yaci DevKit docs
• ${CLAUDE_SKILL_DIR}/../../docs/sources/yaci-store/ - Yaci Store docs
• ${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/devnet/ - Evolution SDK devnet docs
• ${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-node-wiki/ - Cardano node wiki

Step 3: Set up Yaci DevKit (CLI tool, visual explorer)

Reference the quickstart guide for detailed commands:

File: skills/setup-devnet/references/yaci-devkit-quickstart.md

Quick setup

1. Prerequisites: Docker and Docker Compose installed
2. Install + start the devnet (the DevKit ships as a devkit script that manages the containers and opens the Yaci CLI):

   devkit start                        # opens yaci-cli
   yaci-cli:> create-node -o --start   # create + start a default devnet
   

3. Fund wallets: topup <address> <ada> inside the CLI (the devnet:default> prompt), or pre-fund via config/env
4. Access points:
   • Yaci Store API (Blockfrost-compatible): http://localhost:8080/api/v1/
   • Yaci Viewer (block explorer): http://localhost:5173
   • CLI/Admin, wallet, MCP: http://localhost:10000
   • cardano-cli against the node: devkit cli

Configure for your needs

• Set era (Babbage, Conway) for governance testing
• Adjust protocol parameters (min fee, collateral percentage)
• Configure slot length for faster/slower block production
• Enable/disable Plutus cost model overrides for testing

Step 3b: Set up Evolution SDK devnet (code-first alternative)

If the project is TypeScript-based, @evolution-sdk/devnet runs the same local Cardano network as a library — the devnet's genesis, lifecycle, and UTxO queries live in your code and test suite instead of a separate CLI tool. Reference the quickstart:

File: skills/setup-devnet/references/evolution-sdk-devnet.md

Quick setup

1. Prerequisites: Docker running, Node.js 18+
2. Install: pnpm add @evolution-sdk/devnet @evolution-sdk/evolution
3. Create and start a cluster in code:

   import { Cluster } from "@evolution-sdk/devnet";
   
   const cluster = await Cluster.make({
     clusterName: "dev",
     ports: { node: 3001, submit: 3002 },
     kupo: { enabled: true, port: 1442 },
     ogmios: { enabled: true, port: 1337 },
   });
   await Cluster.start(cluster);
   

4. Fund addresses at genesis via shelleyGenesis.initialFunds — deterministic, no faucet. Genesis UTxOs are not indexed by Kupo; derive them with Genesis.calculateUtxosFromConfig(...) and pass via the builder's availableUtxos.
5. Connect a client: Client.make(Cluster.getChain(cluster)).withKupmios({ kupoUrl, ogmiosUrl }).

Choose this over Yaci DevKit when you want the devnet managed from inside integration tests; choose Yaci DevKit for its visual block explorer and Blockfrost-compatible REST API. Both run a standard cardano-node, so chain behaviour is identical.

Step 4: Set up local chain indexers

If your application needs Ogmios/Kupo (e.g. for Evolution SDK's .withKupmios), use the DevKit's built-in services instead of hand-run containers:

# Inside Yaci CLI
yaci-cli:> enable-kupomios

# Or in the DevKit's config/env
ogmios_enabled=true
kupo_enabled=true

Ogmios serves ws://localhost:1337, Kupo http://localhost:1442. Since DevKit v0.12.0-beta5, Yaci Store evaluates scripts with scalus when Ogmios is not running — Ogmios is optional for transaction evaluation. For standalone (non-DevKit) setups, see docs/sources/ogmios/ and docs/sources/kupo/.

Step 5: Smart contract workflow

Aiken build-and-exercise cycle

1. Build: aiken build compiles validators to UPLC
2. Generate blueprint: Produces plutus.json with compiled scripts and parameter schemas
3. Lock: Use an off-chain SDK (Mesh, Evolution SDK, PyCardano, cardano-client-lib) to read the blueprint, derive the script address, and pay to it with a datum
4. Spend: Build a spending transaction that attaches the validator and a redeemer, submit to the local devnet, query results, iterate

There is no deployment step on Cardano. A validator is not installed on-chain ahead of time — it travels in the witness set of the transaction that spends from it. Publishing a script into a UTxO's script_ref (CIP-33) is an optional optimization for large, frequently-spent validators, not a prerequisite; see optimize-validator.

# Typical Aiken workflow
aiken build
aiken check        # Run unit tests
# Then use an SDK to lock to, and spend from, the script on the local devnet

Test structure

• Unit tests: Aiken's built-in test keyword for validator logic
• Integration tests: Off-chain SDK scripts against local devnet
• Property tests: Aiken's fuzz support for property-based testing
• End-to-end: Full workflow tests against Preview testnet

Step 6: Connect to public testnets

Preview testnet

• Purpose: Testing new features, faster epoch transitions
• Faucet: https://docs.cardano.org/cardano-testnets/tools/faucet/
• Network magic: 2
• Configuration files: Download from https://book.play.dev.cardano.org/environments.html

Preprod testnet

• Purpose: Pre-production testing, mirrors mainnet parameters
• Faucet: Same faucet site, select Preprod
• Network magic: 1
• Configuration files: Same source as Preview

Getting test ADA

# Request test ADA from the faucet (web interface or API)
# Provide your testnet address
# Dispenses ~10,000 test ADA per request (same on Preview and Preprod)
# Faucet is rate-limited per address/API key

Step 7: CI integration

GitHub Actions example

# .github/workflows/cardano-ci.yml
name: Cardano CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Aiken
        uses: aiken-lang/setup-aiken@v1
      - name: Build contracts
        run: aiken build
      - name: Run unit tests
        run: aiken check
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install Yaci DevKit
        run: npm install -g @bloxbean/yaci-devkit
      - name: Start a devnet
        run: |
          nohup yaci-devkit up --enable-yaci-store &
          # poll http://localhost:8080 until the Yaci Store API answers
      - name: Run integration tests
        run: |
          # Run off-chain integration tests against localhost:8080

Key CI considerations

• Install the Yaci DevKit npm package and start the devnet in a background step (yaci-devkit up)
• Cache Aiken build artifacts
• Run unit tests first (fast), then integration tests (slower)
• Use deterministic wallet keys for reproducible tests
• Clean devnet state between test suites if needed

Step 8: Troubleshooting common issues

• Docker not starting: Check Docker daemon is running, ports not in use
• Node not syncing: For local devnet, check logs inside container
• Transactions failing: Verify era matches (Babbage vs Conway), check collateral
• Slow block production: Adjust slot length in devnet config
• Out of test ADA: Re-create devnet (local) or use faucet (testnet)
• cardano-cli version mismatch: Match CLI version to node version in the devnet

References

• skills/setup-devnet/references/yaci-devkit-quickstart.md -- Yaci DevKit quickstart guide
• skills/setup-devnet/references/evolution-sdk-devnet.md -- Evolution SDK devnet quickstart guide
• Yaci DevKit: https://github.com/bloxbean/yaci-devkit
• Evolution SDK devnet: https://github.com/IntersectMBO/evolution-sdk
• Cardano testnets: https://docs.cardano.org/cardano-testnets/
• Aiken: https://aiken-lang.org
• Ogmios: https://ogmios.dev
• Kupo: https://cardanosolutions.github.io/kupo