Dingo

Dingo

⚠️ This is a work in progress and is currently under heavy development

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 smart contract execution
• Client connectivity for wallets and applications
• Pluggable storage backends (Badger, SQLite, PostgreSQL, GCS, S3)
• Peer governance with dynamic peer selection and topology support
• Chain rollback support for handling forks with automatic state restoration

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

Running

Dingo supports configuration via both a YAML config file (dingo.yaml) and uses environment variables to modify its own behavior.

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: This behavior can be changed via the following environment variables:

• 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: "")
• CARDANO_UTXORPC_PORT
  • TCP port to bind for listening for UTxO RPC (default: 9090)
• 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)

Fast Bootstrapping with Mithril

Instead of syncing from genesis (which can take days on mainnet), you can bootstrap Dingo using a Mithril snapshot. Mithril provides cryptographically certified snapshots of the Cardano blockchain.

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

curl -L "https://github.com/input-output-hk/mithril/releases/latest/download/mithril-${MITHRIL_PLATFORM}.tar.zst" -o mithril.tar.zst
tar --zstd -xf mithril.tar.zst
sudo mv mithril-client /usr/local/bin/
rm mithril.tar.zst

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

Disk Space Requirements

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

Network	Snapshot Size	Dingo DB	Total Needed
mainnet	~180 GB	~200+ GB	~400 GB
preprod	~60 GB	~80 GB	~150 GB
preview	~15 GB	~25 GB	~50 GB

Note: 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.

Bootstrap Workflow

Step 1: Download the snapshot

Set the aggregator endpoint for your network and download:

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

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

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

# Download the latest snapshot
mithril-client cardano-db download --download-dir /path/to/download

Step 2: Load into Dingo

# Load the immutable DB into Dingo
./dingo load /path/to/download/db/immutable

The load process will import all blocks from the snapshot. Progress is logged as blocks are processed.

Step 3: Start Dingo

After loading completes, start Dingo normally and it will sync the remaining blocks from the network:

CARDANO_NETWORK=mainnet ./dingo

Step 4: Clean up (optional)

Once Dingo is running and synced, you can delete the downloaded snapshot to reclaim disk space:

rm -rf /path/to/download

Example: Full Bootstrap for Preview

# Set network
export CARDANO_NETWORK=preview
export AGGREGATOR_ENDPOINT=https://aggregator.pre-release-preview.api.mithril.network/aggregator

# Download snapshot
mithril-client cardano-db download --download-dir /tmp/mithril-preview

# Load into Dingo
./dingo load /tmp/mithril-preview/db/immutable

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

# Run Dingo
./dingo

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

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

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 (:sweat_smile:):

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
  • Certificates
    • Pool registration
    • Stake registration/delegation
    • Account registration checks
    • Governance
  • Transaction validation
    • Phase 1 validation
      • UTxO rules
      • Witnesses
      • Block body
      • Certificates
      • Delegation/pools
      • Governance
    • Phase 2 validation
      • Smart contracts
• Mempool
  • Accept transactions from local clients
  • Distribute transactions to other nodes
  • Validation of transaction on add
  • Consumer tracking
  • Transaction purging on chain update
• Database Recovery
  • Chain rollback support (SQLite and PostgreSQL plugins)
  • State restoration on rollback
  • WAL mode for crash recovery
  • Automatic rollback on transaction error
• Plutus Validation
  • Plutus V3 smart contract validation
  • Plutus V1/V2 smart contract validation

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.23 or better is installed. You also need make.

# Build
make
# Run
./dingo

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

go run ./cmd/dingo/