Sundial Node Configuration: L1 Provider, Network & Timing

The Sundial node reads all of its configuration from environment variables at startup. No flags or command-line arguments are required for the core settings — everything lives in a .env file that you create from the provided example. This reference covers every variable that operators need to control: your Cardano L1 provider, network selection, operator credentials, block production timing, Redis and PostgreSQL connection details, and the monitoring stack.

The template lives at demo/midgard-node/.env.example in the monorepo. Bootstrap your own file with cp .env.example .env, then edit it before starting the node.

L1 Provider

The node connects to Cardano L1 through one of two provider modes. Choose Blockfrost for the fastest initial setup, or Kupmios if you are running your own Cardano infrastructure and want lower latency and no external API dependency.

Blockfrost (recommended for quick start)
Kupmios (local, production)

L1_PROVIDER=Blockfrost
L1_BLOCKFROST_API_URL=https://cardano-preprod.blockfrost.io/api/v0
L1_BLOCKFROST_KEY=preprodYOUR_KEY_HERE

Get a free API key at blockfrost.io. For testnet, create a project under the Preprod network. For mainnet, create a Mainnet project and update L1_BLOCKFROST_API_URL accordingly.

Start with Blockfrost to get running in minutes, then switch to Kupmios once you have a local Cardano node deployed for production reliability and higher throughput.

L1_PROVIDER=Kupmios
L1_KUPO_KEY=http://localhost:1442
L1_OGMIOS_KEY=ws://localhost:1337

L1_KUPO_KEY and L1_OGMIOS_KEY are passed directly to Lucid Evolution — set them to the HTTP URL of your Kupo instance and the WebSocket URL of your Ogmios instance respectively.When using Kupmios, L1_BLOCKFROST_API_URL and L1_BLOCKFROST_KEY must still be present in your .env (they can be empty strings). The config loader always reads all provider variables.

Network

Set NETWORK to match the Cardano network your L1 provider is connected to. The value is passed directly to Lucid Evolution.

NETWORK=Preprod   # For testnet
NETWORK=Mainnet   # For mainnet

Valid values are Mainnet, Preprod, Preview, and Custom. Preprod is the standard testnet used by Sundial during the testnet phase.

Mismatching NETWORK and your L1 provider network (e.g., setting NETWORK=Mainnet with a Preprod Blockfrost key) will cause the node to fail at startup or produce incorrect block commitments. Always keep these in sync.

Operator Credentials

The node requires three separate operator wallets, each used for a different on-chain role. Supply each as a 24-word BIP-39 seed phrase:

# Main operator identity wallet
L1_OPERATOR_SEED_PHRASE="word1 word2 word3 ... word24"

# Wallet used to sign and submit block-header commitment transactions
L1_OPERATOR_SEED_PHRASE_FOR_BLOCK_COMMITMENT="word1 word2 word3 ... word24"

# Wallet used to sign and submit state-queue merge transactions
L1_OPERATOR_SEED_PHRASE_FOR_MERGE_TX="word1 word2 word3 ... word24"

Use three distinct, freshly generated seed phrases — one per variable. Never reuse a genesis wallet seed or a faucet wallet seed as an operator seed. Keep all three seed phrases stored securely and offline.

Core Configuration Reference

Variable	Required	Default	Description
`NETWORK`	Yes	—	Cardano network: `Mainnet`, `Preprod`, `Preview`, or `Custom`
`L1_PROVIDER`	Yes	—	L1 provider mode: `Blockfrost` or `Kupmios`
`L1_BLOCKFROST_API_URL`	Blockfrost only	—	Blockfrost REST API base URL
`L1_BLOCKFROST_KEY`	Blockfrost only	—	Blockfrost project API key
`L1_KUPO_KEY`	Kupmios only	—	Kupo HTTP endpoint URL
`L1_OGMIOS_KEY`	Kupmios only	—	Ogmios WebSocket endpoint URL
`L1_OPERATOR_SEED_PHRASE`	Yes	—	Main operator wallet seed phrase
`L1_OPERATOR_SEED_PHRASE_FOR_BLOCK_COMMITMENT`	Yes	—	Block-commitment wallet seed phrase
`L1_OPERATOR_SEED_PHRASE_FOR_MERGE_TX`	Yes	—	Merge-transaction wallet seed phrase
`PORT`	No	`3000`	HTTP RPC port the node listens on
`NODE_ROLE`	No	`all`	Node role: `all`, `api`, `tx-processor`, or `sequencer`
`REDIS_URL`	No	`redis://redis:6379`	Redis connection URL
`PROM_METRICS_PORT`	No	`9464`	Prometheus metrics exporter port

PostgreSQL Connection

The node uses two separate PostgreSQL connection pools — one for HTTP query traffic and one for sequencer-critical operations — both backed by the same database credentials.

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=midgard
POSTGRES_HOST=postgres       # Use "postgres" inside Docker, "localhost" outside

When running outside Docker, set POSTGRES_HOST=localhost. Docker Compose publishes PostgreSQL on host port 5433 (container port 5432).

Variable	Default	Description
`POSTGRES_USER`	`postgres`	PostgreSQL username
`POSTGRES_PASSWORD`	`postgres`	PostgreSQL password
`POSTGRES_DB`	`midgard`	Database name
`POSTGRES_HOST`	`postgres`	Hostname (use `localhost` outside Docker)

Node Role

Use NODE_ROLE to control which responsibilities the process takes on. In a single-server deployment, leave it as all. In a distributed setup, deploy each role separately and point them all at the same Redis and PostgreSQL instances.

NODE_ROLE=all          # All roles in one process (default)
NODE_ROLE=api          # HTTP ingress only — enqueues to Redis
NODE_ROLE=tx-processor # Mempool ingestion only — reads from Redis
NODE_ROLE=sequencer    # Block production and L1 sync only

The api role exposes the HTTP port (PORT). The tx-processor and sequencer roles do not expose an HTTP port but each export their own Prometheus metrics on configurable ports.

Timing Parameters

These variables control the intervals at which the node’s background fibers run. The defaults are tuned for testnet. For mainnet, adjust based on your observed block times and L1 confirmation latency.

Variable	Default	Unit	Description
`WAIT_BETWEEN_BLOCK_COMMITMENTS`	`1000`	ms	Delay between block-commitment fiber runs
`WAIT_BETWEEN_BLOCK_SUBMISSIONS`	`10000`	ms	Delay between block-submission fiber runs
`WAIT_BETWEEN_USER_EVENT_FETCHES`	`10000`	ms	Interval for polling L1 deposits and withdrawals
`WAIT_BETWEEN_MERGE_TXS`	`10000`	ms	Delay between state-queue merge fiber runs

WAIT_BETWEEN_BLOCK_COMMITMENTS controls how frequently the sequencer tries to build a new block from the mempool. Lower values mean more frequent (and smaller) blocks; higher values let the mempool fill for larger, more efficient batches.

Transaction Queue (Redis)

The node uses Redis to decouple transaction receipt from mempool processing. Set REDIS_URL to point at your Redis instance:

REDIS_URL=redis://redis:6379

Variable	Default	Description
`REDIS_URL`	`redis://redis:6379`	Redis connection URL

When running with Docker Compose, Redis is included in the stack and REDIS_URL defaults to redis://redis:6379. For external Redis instances, update the host and port accordingly.

Monitoring and Observability

Monitoring is activated by starting the node with the --with-monitoring flag. The Docker Compose monolith profile passes this flag automatically.

PROM_METRICS_PORT=9464

Variable	Default	Description
`PROM_METRICS_PORT`	`9464`	Port for the Prometheus `/metrics` scrape endpoint

When running the monolith Docker Compose profile, --with-monitoring is passed automatically and Prometheus scrapes metrics from PROM_METRICS_PORT. See the Layer Node deployment guide for the full list of observability service endpoints.

Manager Configuration File

The midgard CLI reads its settings from a JSON file rather than environment variables. The default configuration lives at demo/midgard-manager/config/settings.json:

{
  "node": {
    "endpoint": "http://localhost:3000"
  },
  "generator": {
    "enabled": false,
    "maxConcurrent": 10,
    "batchSize": 100,
    "intervalMs": 1000
  },
  "logging": {
    "level": "info",
    "format": "pretty"
  }
}

Update node.endpoint to point at a remote node, or pass --endpoint on the CLI to override it for a single command. The generator block controls the built-in test transaction generator (disabled by default).

Full `.env` Example

Here is a minimal working .env for a testnet operator using Blockfrost:

# Network
NETWORK=Preprod

# L1 Provider — Blockfrost
L1_PROVIDER=Blockfrost
L1_BLOCKFROST_API_URL=https://cardano-preprod.blockfrost.io/api/v0
L1_BLOCKFROST_KEY=preprodYOUR_KEY_HERE

# Keep these present even when using Blockfrost
L1_OGMIOS_KEY=
L1_KUPO_KEY=

# Operator wallets (use three distinct seed phrases)
L1_OPERATOR_SEED_PHRASE="your twenty four word seed phrase here ..."
L1_OPERATOR_SEED_PHRASE_FOR_BLOCK_COMMITMENT="your twenty four word seed phrase here ..."
L1_OPERATOR_SEED_PHRASE_FOR_MERGE_TX="your twenty four word seed phrase here ..."

# Node
PORT=3000
NODE_ROLE=all

# Redis
REDIS_URL=redis://redis:6379

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=midgard
POSTGRES_HOST=postgres

# Monitoring
PROM_METRICS_PORT=9464

Layer Node Deployment

Step-by-step guide to deploying the node with Docker Compose or Nix, including the full observability stack.

CLI Reference

Use the midgard CLI to manage wallets, submit transactions, and inspect node status.

Node API

SDKs & Libraries

Operator Toolkit

Sundial Node Configuration: L1 Provider, Network & Timing

L1 Provider

Network

Operator Credentials

Core Configuration Reference

PostgreSQL Connection

Node Role

Timing Parameters

Transaction Queue (Redis)

Monitoring and Observability

Manager Configuration File

Full `.env` Example

Layer Node Deployment

CLI Reference

​L1 Provider

​Network

​Operator Credentials

​Core Configuration Reference

​PostgreSQL Connection

​Node Role

​Timing Parameters

​Transaction Queue (Redis)

​Monitoring and Observability

​Manager Configuration File

​Full .env Example

​Related Pages

Layer Node Deployment

CLI Reference

L1 Provider

Network

Operator Credentials

Core Configuration Reference

PostgreSQL Connection

Node Role

Timing Parameters

Transaction Queue (Redis)

Monitoring and Observability

Manager Configuration File

Full `.env` Example

Related Pages