dingo

Dingo

Dingo

A high-performance Cardano blockchain node implementation in Go by Blink Labs. Dingo provides:

• Full chain synchronization and validation via Ouroboros consensus protocol
• UTxO tracking with 41 UTXO validation rules and Plutus V1/V2/V3 smart contract execution
• Block production with VRF leader election and stake snapshots
• Multi-peer chain selection with density comparison and VRF tie-breaking
• Client connectivity for wallets and applications
• Pluggable storage backends (Badger, SQLite, PostgreSQL, MySQL, GCS, S3)
• Tiered storage modes ("core" for consensus, "api" for full indexing)
• Peer governance with dynamic peer selection, ledger peers, and topology support
• Chain rollback support for handling forks with automatic state restoration
• Fast bootstrapping via built-in Mithril client
• Multiple API servers: UTxO RPC, Blockfrost-compatible REST, Mesh (Coinbase Rosetta)

Note: On Windows systems, named pipes are used instead of Unix sockets for node-to-client communication.

Running

Dingo supports configuration via a YAML config file (dingo.yaml), environment variables, and command-line flags. Priority: CLI flags > environment variables > YAML config > defaults.

A sample configuration file is provided at dingo.yaml.example. You can copy and edit this file to configure Dingo for your local or production environment.

Environment Variables

The following environment variables modify Dingo's behavior:

• CARDANO_BIND_ADDR
  • IP address to bind for listening (default: 0.0.0.0)
• CARDANO_CONFIG
  • Full path to the Cardano node configuration (default: ./config/cardano/preview/config.json)
  • Use your own configuration files for different networks
  • Genesis configuration files are read from the same directory by default
• CARDANO_DATABASE_PATH
  • A directory which contains the ledger database files (default: .dingo)
  • This is the location for persistent data storage for the ledger
• CARDANO_INTERSECT_TIP
  • Ignore prior chain history and start from current position (default: false)
  • This is experimental and will likely break... use with caution
• CARDANO_METRICS_PORT
  • TCP port to bind for listening for Prometheus metrics (default: 12798)
• CARDANO_NETWORK
  • Named Cardano network (default: preview)
• CARDANO_PRIVATE_BIND_ADDR
  • IP address to bind for listening for Ouroboros NtC (default: 127.0.0.1)
• CARDANO_PRIVATE_PORT
  • TCP port to bind for listening for Ouroboros NtC (default: 3002)
• CARDANO_RELAY_PORT
  • TCP port to bind for listening for Ouroboros NtN (default: 3001)
• CARDANO_SOCKET_PATH
  • UNIX socket path for listening (default: dingo.socket)
  • This socket speaks Ouroboros NtC and is used by client software
• CARDANO_TOPOLOGY
  • Full path to the Cardano node topology (default: "")
• DINGO_UTXORPC_PORT
  • TCP port to bind for listening for UTxO RPC (default: 0, disabled)
• DINGO_BLOCKFROST_PORT
  • TCP port for the Blockfrost-compatible REST API (default: 0, disabled)
• DINGO_MESH_PORT
  • TCP port for the Mesh (Coinbase Rosetta) API (default: 0, disabled)
• DINGO_BARK_PORT
  • TCP port for the Bark block archive API (default: 0, disabled)
• DINGO_STORAGE_MODE
  • Storage mode: core (default) or api
  • core stores only consensus data (UTxOs, certs, pools, protocol params)
  • api additionally stores witnesses, scripts, datums, redeemers, and tx metadata
  • API servers (Blockfrost, UTxO RPC, Mesh) require api mode
• DINGO_RUN_MODE
  • Run mode: serve (full node, default), load (batch import), dev (development mode), or leios (experimental Leios protocol support)
• TLS_CERT_FILE_PATH - SSL certificate to use, requires TLS_KEY_FILE_PATH (default: empty)
• TLS_KEY_FILE_PATH - SSL certificate key to use (default: empty)

Block Production (SPO Mode)

To run Dingo as a stake pool operator producing blocks:

• CARDANO_BLOCK_PRODUCER - Enable block production (default: false)
• CARDANO_SHELLEY_VRF_KEY - Path to VRF signing key file
• CARDANO_SHELLEY_KES_KEY - Path to KES signing key file
• CARDANO_SHELLEY_OPERATIONAL_CERTIFICATE - Path to operational certificate file

Fast Bootstrapping with Mithril

Instead of syncing from genesis (which can take days on mainnet), you can bootstrap Dingo using a Mithril snapshot. There are two approaches depending on your use case:

Option 1: dingo sync --mithril (Recommended for Consensus)

Dingo has a built-in Mithril client that handles download, extraction, and import automatically. This is the fastest way to get a node running.

# Bootstrap from Mithril and start syncing
./dingo -n preview sync --mithril

# Then start the node
./dingo -n preview serve

Or use the subcommand form for more control:

# List available snapshots
./dingo -n preview mithril list

# Show snapshot details
./dingo -n preview mithril show <digest>

# Download and import
./dingo -n preview mithril sync

This imports:

• All blocks from genesis (stored in blob store for serving peers)
• Current UTxO set, stake accounts, pool registrations, DRep registrations
• Stake snapshots (mark/set/go) for leader election
• Protocol parameters, governance state, treasury/reserves
• Complete epoch history for slot-to-time calculations

What is NOT included: Individual transaction records, certificate history, witness/script/datum storage, and governance vote records for blocks before the snapshot. These are not needed for consensus, block production, or serving blocks to peers. New blocks processed after bootstrap will have full metadata.

Performance (preview network, ~4M blocks):

Option 2: mithril-client + dingo load (For Indexers/API Nodes)

If you need full historical data (transaction lookups, certificate queries, datum/script resolution), use the external mithril-client to download the snapshot and then load it with dingo load, which processes every block through the full indexing pipeline.

Prerequisites

Install the mithril-client CLI from Mithril releases:

# Detect OS and architecture
OS=$(uname -s)
ARCH=$(uname -m)

case "$OS" in
  Linux)
    case "$ARCH" in
      x86_64)  MITHRIL_PLATFORM="x64-linux-musl" ;;
      aarch64|arm64) MITHRIL_PLATFORM="arm64-linux-musl" ;;
      *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
    esac
    ;;
  Darwin)
    case "$ARCH" in
      x86_64)  MITHRIL_PLATFORM="x64-macos" ;;
      arm64)   MITHRIL_PLATFORM="arm64-macos" ;;
      *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
    esac
    ;;
  *) echo "Unsupported OS: $OS (see Mithril releases for Windows)"; exit 1 ;;
esac

MITHRIL_VERSION="2506.0"
curl -L "https://github.com/input-output-hk/mithril/releases/download/${MITHRIL_VERSION}/mithril-${MITHRIL_VERSION}-${MITHRIL_PLATFORM}.tar.gz" -o mithril.tar.gz
tar -xzf mithril.tar.gz
sudo mv mithril-client /usr/local/bin/
rm mithril.tar.gz

For Windows, download the appropriate binary from the Mithril releases page.

Bootstrap Workflow

# Set network (CARDANO_NETWORK is used by dingo, not mithril-client)
export CARDANO_NETWORK=preview
# AGGREGATOR_ENDPOINT is used by mithril-client
export AGGREGATOR_ENDPOINT=https://aggregator.pre-release-preview.api.mithril.network/aggregator

# For mainnet:
# export AGGREGATOR_ENDPOINT=https://aggregator.release-mainnet.api.mithril.network/aggregator

# Download snapshot (uses AGGREGATOR_ENDPOINT)
mithril-client cardano-db download --download-dir /tmp/mithril-snapshot

# Load into Dingo (uses CARDANO_NETWORK for chain config)
./dingo load /tmp/mithril-snapshot/db/immutable

# Clean up snapshot
rm -rf /tmp/mithril-snapshot

# Start Dingo
./dingo -n preview serve

This creates full historical data including transaction records, certificate history, witness data, scripts, datums, and governance votes -- everything needed for rich query APIs.

Disk Space Requirements

Bootstrapping requires temporary disk space for both the downloaded snapshot and the Dingo database:

These are approximate values that grow over time. The snapshot can be deleted after import, but you need sufficient space for both during the load process.

Database Plugins

Dingo supports pluggable storage backends for both blob storage (blocks, transactions) and metadata storage. This allows you to choose the best storage solution for your use case.

Available Plugins

Blob Storage Plugins:

• badger - BadgerDB local key-value store (default)
• gcs - Google Cloud Storage blob store
• s3 - AWS S3 blob store

Metadata Storage Plugins:

• sqlite - SQLite relational database (default)
• postgres - PostgreSQL relational database
• mysql - MySQL relational database

Plugin Selection

Plugins can be selected via command-line flags, environment variables, or configuration file:

# Command line
./dingo --blob gcs --metadata sqlite

# Environment variables
DINGO_DATABASE_BLOB_PLUGIN=gcs
DINGO_DATABASE_METADATA_PLUGIN=sqlite

# Configuration file (dingo.yaml)
database:
  blob:
    plugin: "gcs"
  metadata:
    plugin: "sqlite"

Plugin Configuration

Each plugin supports specific configuration options. See dingo.yaml.example for detailed configuration examples.

BadgerDB Options:

• data-dir - Directory for database files
• block-cache-size - Block cache size in bytes
• index-cache-size - Index cache size in bytes
• gc - Enable garbage collection

Google Cloud Storage Options:

• bucket - GCS bucket name
• project-id - Google Cloud project ID
• prefix - Path prefix within bucket

AWS S3 Options:

• bucket - S3 bucket name
• region - AWS region
• prefix - Path prefix within bucket
• access-key-id - AWS access key ID (optional - uses default credential chain if not provided)
• secret-access-key - AWS secret access key (optional - uses default credential chain if not provided)

SQLite Options:

• data-dir - Path to SQLite database file

PostgreSQL Options:

• host - PostgreSQL server hostname
• port - PostgreSQL server port
• username - Database user
• password - Database password
• database - Database name

MySQL Options:

• host - MySQL server hostname
• port - MySQL server port
• user - Database user
• password - Database password
• database - Database name
• ssl-mode - MySQL TLS mode (mapped to tls= in DSN)
• timezone - MySQL time zone location (default: UTC)
• dsn - Full MySQL DSN (overrides other options when set)
• storage-mode - Storage tier: core or api (default: core)

Listing Available Plugins

You can see all available plugins and their descriptions:

./dingo list

Plugin Development

For information on developing custom storage plugins, see PLUGIN_DEVELOPMENT.md.

Example

Running on mainnet:

CARDANO_NETWORK=mainnet CARDANO_CONFIG=path/to/cardano/configs/mainnet/config.json ./dingo

Note: you can find cardano configuration files at https://github.com/blinklabs-io/docker-cardano-configs/tree/main/config

Dingo will drop a dingo.socket file which can be used by other clients, such as cardano-cli or software like adder or kupo. This has only had limited testing, so success/failure reports are very welcome and encouraged!

Features

• Network
  • UTxO RPC
  • Ouroboros
    • Node-to-node
      • ChainSync
      • BlockFetch
      • TxSubmission2
    • Node-to-client
      • ChainSync
      • LocalTxMonitor
      • LocalTxSubmission
      • LocalStateQuery
    • Peer governor
      • Topology config
      • Peer churn (full PeerChurnEvent with gossip/public root churn, bootstrap events)
      • Ledger peers
      • Peer sharing
      • Denied peers tracking
    • Connection manager
      • Inbound connections
        • Node-to-client over TCP
        • Node-to-client over UNIX socket
        • Node-to-node over TCP
      • Outbound connections
        • Node-to-node over TCP
• Ledger
  • Blocks
    • Block storage
    • Chain selection (density comparison, VRF tie-breaker, ChainForkEvent)
  • UTxO tracking
  • Protocol parameters
  • Genesis validation
  • Block header validation (VRF/KES/OpCert cryptographic verification)
  • Certificates
    • Pool registration
    • Stake registration/delegation
    • Account registration checks
    • DRep registration
    • Governance
  • Transaction validation
    • Phase 1 validation
      • UTxO rules
      • Fee validation (full fee calculation with script costs)
      • Transaction size and ExUnit budget validation
      • Witnesses
      • Block body
      • Certificates
      • Delegation/pools
      • Governance
    • Phase 2 validation
      • Plutus V1 smart contract execution
      • Plutus V2 smart contract execution
      • Plutus V3 smart contract execution
• Block production
  • VRF leader election with stake snapshots
  • Block forging with KES/OpCert signing
  • Slot battle detection
• Mempool
  • Accept transactions from local clients
  • Distribute transactions to other nodes
  • Validation of transaction on add
  • Consumer tracking
  • Transaction purging on chain update
  • Watermark-based eviction and rejection
• Database Recovery
  • Chain rollback support (SQLite, PostgreSQL, and MySQL plugins)
  • State restoration on rollback
  • WAL mode for crash recovery
  • Automatic rollback on transaction error
• Stake Snapshots
  • Mark/Set/Go rotation at epoch boundaries
  • Genesis snapshot capture
• API Servers
  • UTxO RPC (gRPC)
  • Blockfrost-compatible REST API
  • Mesh (Coinbase Rosetta) API
  • Bark block archive API
• Mithril Bootstrap
  • Built-in Mithril client
  • Ledger state import (UTxOs, accounts, pools, DReps, epochs)
  • Block loading from ImmutableDB

Additional planned features can be found in our issue tracker and project boards.

Catalyst Fund 12 - Go Node (Dingo)
Catalyst Fund 13 - Archive Node

Check the issue tracker for known issues. Due to rapid development, bugs happen especially as there is functionality which has not yet been developed.

Development / Building

This requires Go 1.24 or later. You also need make.

# Build
make
# Run
./dingo

You can also run the code without building a binary, first

go run ./cmd/dingo/