@blinklabs/dingo 0.36.1 → 0.38.0

package/AGENTS.md

@@ -1,115 +1,51 @@
 # AGENTS.md
 
-Concise guide for AI agents working with Dingo. For full details, see `ARCHITECTURE.md`.
+Go Cardano node (Ouroboros). See `CLAUDE.md` for detailed rules; this file has additional content (Build/test section, `make golines` in pre-commit, Key events table) and a different structure — the two are related but not exact copies. Package layout, targets, and flags are derivable from `Makefile`, `go.mod`, `node.go`.
 
-## Quick Reference
+## Build / test
 
-**Dingo**: Go-based Cardano blockchain node by Blink Labs (Ouroboros protocol, UTxO tracking, pluggable storage).
-
-```bash
-make              # Format, test, build
-make test         # Tests with race detection
-make bench        # Run benchmarks
-go run ./cmd/dingo/         # Run without building
-go test -v -race -run TestName ./path/to/package/  # Single test
 ```
-
-## Key Packages
-
-| Package | Purpose |
-|---------|---------|
-| `chain/` | Blockchain state, fork detection, rollback |
-| `chainselection/` | Multi-peer chain comparison (Ouroboros Praos) |
-| `chainsync/` | Block sync state tracking |
-| `connmanager/` | Network connection lifecycle |
-| `database/` | Storage plugins (badger, sqlite, postgres, mysql, gcs, s3) |
-| `event/` | Event bus (async pub/sub, 4 workers) |
-| `ledger/` | UTxO state, protocol params, Plutus execution |
-| `mempool/` | Transaction pool & validation |
-| `ouroboros/` | Protocol handlers (N2N, N2C) |
-| `peergov/` | Peer governance, churn, quotas |
-| `utxorpc/` | UTxO RPC gRPC server |
-
-## Code Quality (Run Before Committing)
-
-```bash
-golangci-lint run ./...    # Linters (39 via .golangci.yml)
-nilaway ./...              # Nil-safety analyzer
-modernize ./...            # Modern Go idioms
-make golines               # 80 char line limit
+make              # fmt, test, build
+make test         # tests with -race
+go test -v -race -run TestName ./path/to/pkg/
 ```
 
-## Essential Patterns
-
-### Error Handling
-```go
-// Wrap errors with context
-return fmt.Errorf("failed to process block: %w", err)
-```
+## Pre-commit
 
-### Event-Driven Communication
-```go
-// Subscribe to events (never call components directly)
-eventBus.SubscribeFunc(chain.ChainForkEventType, handler)
 ```
-
-### Database Queries
-```go
-// GOOD: Batch fetch (single query)
-db.Where("id IN ?", ids).Find(&records)
-
-// BAD: N+1 queries
-for _, id := range ids {
-    db.Where("id = ?", id).First(&record)
-}
-
-// Certificate ordering: use cert_index as tie-breaker
-Order("added_slot DESC, cert_index DESC")
+golangci-lint run ./...
+nilaway ./...
+modernize ./...
+make golines
 ```
 
-### Rollback Handling
-- `Chain.Rollback(point)` emits `ChainRollbackEvent`
-- State restoration in `database/plugin/metadata/sqlite/`
-- Use `TransactionEvent.Rollback` field to detect undo operations
-
-### CBOR Storage
-- UTxOs/TXs stored as 52-byte `CborOffset` (magic "DOFF" + slot + hash + offset + length)
-- `TieredCborCache` resolves: hot cache → block LRU → cold extraction
-
-### Stake Snapshots
-- Mark/Set/Go rotation at epoch boundaries (Ouroboros Praos)
-- `LedgerView.GetStakeDistribution(epoch)` for leader election queries
-- `PoolStakeSnapshot` model stores per-pool stake
-- `EpochSummary` stores network aggregates
-
-## Key Event Types
-
-| Event | Purpose |
-|-------|---------|
-| `chain.update` | Block added to chain |
-| `chain.fork-detected` | Fork detected |
-| `chainselection.chain_switch` | Active peer changed |
-| `epoch.transition` | Epoch boundary crossed (triggers stake snapshot) |
-| `mempool.add_tx` / `mempool.remove_tx` | Transaction lifecycle |
-| `connmanager.conn-closed` | Connection lifecycle |
-| `peergov.peer-churn` | Peer rotation |
+## Testing rules
 
-## Configuration
+- No `time.Sleep()` for sync — use `internal/test/testutil/` (`WaitForCondition`, `RequireReceive`, `context.WithTimeout`).
+- Integration tests: `internal/integration/` + `database/immutable/testdata/` (real blocks, slots 0–1.3M).
+- Mock fixtures come from `github.com/blinklabs-io/ouroboros-mock` (`fixtures/`, `ledger/`, `conformance/`). Never duplicate mocks inside dingo — extend the shared library so every Blink Labs app (dingo, gouroboros, adder, ...) reuses the same test surface.
 
-Priority: CLI flags > Env vars > YAML config > Defaults
+## Non-obvious invariants
 
-Key env vars: `CARDANO_NETWORK`, `CARDANO_DATABASE_PATH`, `DINGO_DATABASE_BLOB_PLUGIN`, `DINGO_DATABASE_METADATA_PLUGIN`
+- EventBus for async cross-component notifications: use `event.EventBus.SubscribeFunc()` for block/chain/mempool/peer events. Synchronous state queries between components still use direct method calls.
+- CBOR offsets: UTxOs/txs stored as 52-byte refs (magic `"DOFF"` + slot + hash + offset + length), resolved by `TieredCborCache` (hot → block LRU → cold extract). See `database/cbor_offset.go`.
+- Cert ordering: `Order("added_slot DESC, block_index DESC, cert_index DESC")` — `cert_index` resets per tx, so `block_index` is required to disambiguate across txs in the same block.
+- Rollbacks: delivered on `chain.update` as a `chain.ChainRollbackEvent` payload (no separate `chain.rollback` topic); also subscribe to `chain.fork_detected` for fork metrics. Check `TransactionEvent.Rollback` for undo.
+- Stake snapshots: mark/set/go rotation at epoch boundaries (Praos). `LedgerView.GetStakeDistribution(epoch)` for leader election. Per-pool stake in `PoolStakeSnapshot`; aggregates in `EpochSummary`.
+- Plugins (`database/plugin/`): blob = `badger` | `gcs` | `s3`; metadata = `sqlite` | `mysql` | `postgres`.
 
-## Critical Anti-Patterns
+## Key events
 
-1. **Don't bypass EventBus** - Components communicate via events, not direct calls
-2. **Don't use N+1 queries** - Batch fetch with `WHERE id IN ?`
-3. **Don't forget cert_index** - Multiple certs in same slot need ordering
-4. **Don't ignore rollbacks** - Check `TransactionEvent.Rollback` field
-5. **Don't skip linting** - Run `golangci-lint`, `nilaway`, `modernize` before commits
+| Event | Meaning |
+|---|---|
+| `chain.update` | block added |
+| `chain.fork_detected` | fork |
+| `chainselection.chain_switch` | active peer changed |
+| `epoch.transition` | epoch boundary — triggers stake snapshot |
+| `mempool.add_tx` / `mempool.remove_tx` | tx lifecycle |
+| `connmanager.conn_closed` | connection closed |
+| `peergov.peer_churn` | peer rotation |
 
-## Testing
+## Config
 
-- Integration tests: `internal/integration/`
-- Test data: `database/immutable/testdata/` (real blocks slots 0-1.3M)
-- Benchmarks: `make bench` (28+ benchmarks)
+Priority: CLI > env > YAML > defaults. Key env vars: `CARDANO_NETWORK`, `CARDANO_DATABASE_PATH`, `DINGO_DATABASE_BLOB_PLUGIN`, `DINGO_DATABASE_METADATA_PLUGIN`.

package/CLAUDE.md

@@ -1,33 +1,37 @@
 # CLAUDE.md
 
-Go-based Cardano node implementing Ouroboros. Most of what you need is derivable from code (`Makefile`, `go.mod`, `node.go`, `dingo.yaml.example`). Below is what isn't.
+Go Cardano node (Ouroboros). Derivable info (build targets, flags, package layout) lives in `Makefile`, `go.mod`, `node.go`, `dingo.yaml.example`. This file is only what isn't derivable.
 
-## Testing rules
+## Testing
 
-- **Never use `time.Sleep()` for synchronization.** Use helpers in `internal/test/testutil/`:
-  - `WaitForCondition` / `require.Eventually` for polling (2–5s timeout, 5–10ms interval, lock shared state inside the condition fn)
+- No `time.Sleep()` for sync. Use `internal/test/testutil/`:
+  - `WaitForCondition` / `require.Eventually` — 2–5s timeout, 5–10ms interval, lock shared state inside the condition fn
   - `RequireReceive` / `RequireNoReceive` for channel assertions
-  - `context.WithTimeout` for graceful shutdown — not sleep
-- Race detection is on by default in `make test`.
+  - `context.WithTimeout` for graceful shutdown
+- `make test` runs with `-race`.
 - Integration tests in `internal/integration/` load real blocks from `database/immutable/testdata/`.
+- Mock fixtures come from `github.com/blinklabs-io/ouroboros-mock` (`fixtures/`, `ledger/`, `conformance/`). Never add local ledger/consensus/network mocks — extend the shared library.
 
-## Before committing
+## Pre-commit
 
-```bash
-golangci-lint run ./...   # .golangci.yml configured
+```shell
+golangci-lint run ./...
 nilaway ./...
-modernize ./...           # --fix to auto-apply
+modernize ./...   # --fix to auto-apply
 ```
 
-## Non-obvious architecture
+## Non-obvious invariants
 
-- **CBOR offset storage**: UTxOs/txs store 52-byte `CborOffset` refs (magic `"DOFF"`, slot, hash, offset, length), not full CBOR. Resolved via `TieredCborCache` (hot → block LRU → cold extract from blob store). See `database/cbor_offset.go`, `database/cbor_cache.go`, `database/block_indexer.go`.
-- **Plugins** (`database/plugin/`): blob = `badger` (default) / `gcs` / `s3`; metadata = `sqlite` (default) / `mysql` / `postgres`.
-- **Event bus**: components communicate via `event.EventBus.SubscribeFunc()`, not direct calls.
+- CBOR offsets: UTxOs/txs store 52-byte `CborOffset` refs (magic `"DOFF"` + slot + hash + offset + length), not full CBOR. Resolved via `TieredCborCache` (hot → block LRU → cold blob extract). See `database/cbor_offset.go`, `database/cbor_cache.go`, `database/block_indexer.go`.
+- EventBus for async cross-component notifications: block/chain/mempool/peer events go through `event.EventBus.SubscribeFunc()`. Synchronous state queries between components still use direct method calls.
+- Cert ordering: multiple certs per slot — tie-break with `Order("added_slot DESC, block_index DESC, cert_index DESC")` (`cert_index` resets per tx, so `block_index` is required to disambiguate across txs in the same block).
+- Rollbacks: `Chain.Rollback(point)` emits `ChainRollbackEvent`; check `TransactionEvent.Rollback` for undo.
+- Plugins (`database/plugin/`): blob = `badger` (default) | `gcs` | `s3`; metadata = `sqlite` (default) | `mysql` | `postgres`.
+- Config priority: CLI > env > YAML > defaults.
 
 ## Profiling
 
-```bash
+```shell
 ./dingo --cpuprofile=cpu.prof --memprofile=mem.prof load database/immutable/testdata
 go tool pprof cpu.prof
 ```

package/RELEASE_NOTES.md

@@ -1,6 +1,81 @@
 # Release Notes
 
 
+## v0.37.0 (April 27, 2026)
+
+**Title:** Genesis bootstrap, governance, and steadier Mithril recovery
+
+**Date:** April 27, 2026
+
+**Version:** v0.37.0
+
+Hi folks! Here’s what we shipped in v0.37.0.
+
+### ✨ What's New
+
+* Added **Ouroboros Genesis bootstrap support:** Operators can now start from Genesis bootstrap flows, which gives early sync a clearer path before the node reaches the current chain tip.
+* Expanded **Genesis mode chain selection:** Nodes can now choose the chain more safely during Genesis mode, which keeps early sync aligned with the right history.
+* Introduced **bootstrap aware peer promotion:** Peer promotion now accounts for bootstrap state, which helps early sync keep useful peers active while the node is still catching up.
+* Delivered **Conway governance ratification support:** Governance aware services can now track ratified actions more completely as Conway governance advances.
+* Enabled **Conway governance enactment handling:** Governance state now follows enacted actions more accurately, which gives operators and integrators a clearer view of active governance outcomes.
+* Preserved **committee quorum persistence:** Committee quorum information now persists across restarts, which keeps governance state steadier after interruptions.
+* Opened **broader governance state handling:** Governance aware integrations can now read and handle more of the Conway governance state without losing important context.
+* Unlocked **new Blockfrost compatible block endpoints:** Blockfrost compatible users can now retrieve additional block details through new block endpoints.
+* Extended **new Blockfrost compatible network endpoints:** Network status integrations can now access new network endpoints in a Blockfrost compatible shape.
+* Introduced **new Blockfrost compatible era endpoints:** Era aware clients can now request era information through new Blockfrost compatible endpoints.
+* Added **new Blockfrost compatible genesis endpoints:** Genesis data is now available through new Blockfrost compatible endpoints for services that need network bootstrap details.
+
+### 💪 Improvements
+
+* Improved **newer Mithril snapshot compatibility:** Bootstrap runs now accept newer snapshot shapes more reliably, which makes setup and recovery smoother across current Mithril data.
+* Refined **interrupted Mithril resume safety:** Resuming after an interrupted Mithril run now behaves more safely, which reduces the chance of a broken recovery path.
+* Enhanced **bootstrap aware peer governance:** Peer promotion and selection now align more closely with bootstrap state, which helps early sync keep useful peers active.
+* Modernized **bootstrap and governance observability:** Operators can now see more metrics and event signals around bootstrap and governance behavior.
+* Updated **operator and integrator guidance:** Documentation and workflow refreshes make recent bootstrap, governance, and API behavior easier to follow.
+
+### 🔧 Fixes
+
+* Fixed **Mithril bootstrap resume reliability:** Mithril bootstrap and resume handling now recover more reliably when a previous run stopped before completion.
+* Corrected **snapshot bootstrap handling:** Snapshot based bootstrap flows now handle current snapshot layouts correctly, which reduces failed setup paths.
+* Hardened **early sync recovery behavior:** Recovery during early sync now follows Genesis mode chain selection and bootstrap aware promotion more safely after interruptions.
+* Stabilized **governance state continuity:** Governance state now keeps ratification, enactment, and committee quorum handling steadier across restarts and replay.
+
+### 📋 What You Need to Know
+
+* Clarified **Genesis bootstrap rollout:** Ouroboros Genesis bootstrap changes early sync behavior, including Genesis mode chain selection and bootstrap aware peer promotion.
+* Highlighted **governance support growth:** Conway governance coverage now reaches ratification, enactment, committee quorum persistence, and broader governance state handling.
+* Emphasized **steadier Mithril recovery:** Mithril bootstrap and resume handling now work more reliably with newer snapshot shapes and safer interrupted resume behavior.
+* Summarized **expanded Blockfrost compatibility:** Blockfrost compatible users can now use new block, network, era, and genesis endpoints.
+
+### 🙏 Thank You
+
+Thank you for trying!
+
+---
+
+## v0.36.1 (April 21, 2026)
+
+**Title:** Steadier catch-up sync and refreshed integrations
+
+**Date:** April 21, 2026
+
+**Version:** v0.36.1
+
+Hi folks! Here’s what we shipped in v0.36.1.
+
+### 💪 Improvements
+
+* Improved **catch-up sync stability:** Nodes now stay steadier while catching up because stall checks wait longer, plateau recovery allows more time, and recycle cooldowns stay longer until the node reaches tip, which reduces unnecessary connection recycling and socket churn during large syncs.
+* Updated **AWS integration currency:** AWS backed integrations stay current because the AWS SDK config package and related AWS modules were refreshed.
+* Refreshed **core AWS compatibility:** AWS integrated behavior stays aligned with upstream fixes because the core AWS SDK and `aws/smithy-go` were updated.
+* Modernized **Google API client support:** Google API client support stays current because `google.golang.org/api` now uses a newer release.
+
+### 🙏 Thank You
+
+Thank you for trying!
+
+---
+
 ## v0.36.0 (April 20, 2026)
 
 **Title:** Asset endpoints and steadier chain operations

package/dingo.yaml.example

@@ -4,11 +4,13 @@
 # runtime default.
 
 # Public bind address for the Dingo server
+# CLI: --bind-addr
 bindAddr: "0.0.0.0"
 
 # Path to the Cardano node configuration file
 #
 # Can be overridden with the config environment variable
+# CLI: --cardano-config
 cardanoConfig: "./config/cardano/preview/config.json"
 
 # Global data directory for both blob and metadata storage plugins.
@@ -110,9 +112,11 @@ database:
       dsn: ""
 
 # Path to the UNIX domain socket file used by the server
+# CLI: --socket-path
 socketPath: "dingo.socket"
 
 # Name of the Cardano network
+# CLI: --network
 network: "preview"
 
 # TLS certificate file path (for HTTPS)
@@ -129,17 +133,20 @@ tlsKeyFilePath: ""
 topology: ""
 
 # TCP port to bind for Prometheus metrics endpoint
+# CLI: --metrics-port
 metricsPort: 12798
 
 # Internal/private address to bind for listening for Ouroboros NtC
 privateBindAddr: "127.0.0.1"
 
 # TCP port to bind for listening for Ouroboros NtC
+# CLI: --private-port
 privatePort: 3002
 
 # TCP port to bind for listening for Ouroboros NtN
 #
 # Can be overridden with the port environment variable
+# CLI: --port
 relayPort: 3001
 
 # Storage mode controls how much data is persisted.
@@ -149,6 +156,7 @@ relayPort: 3001
 #   redeemers). All APIs start automatically on their default ports.
 #
 # Can be overridden with DINGO_STORAGE_MODE
+# CLI: --storage-mode
 storageMode: "core"
 
 # API ports — only used when storageMode is "api".
@@ -157,15 +165,19 @@ storageMode: "core"
 #
 # UTxO RPC gRPC API port (default: 9090)
 # Can be overridden with DINGO_UTXORPC_PORT
+# CLI: --utxorpc-port
 utxorpcPort: 9090
 # Blockfrost-compatible REST API port (default: 3000)
 # Can be overridden with DINGO_BLOCKFROST_PORT
+# CLI: --blockfrost-port
 blockfrostPort: 3000
 # Mesh (Coinbase Rosetta) REST API port (default: 8080)
 # Can be overridden with DINGO_MESH_PORT
+# CLI: --mesh-port
 meshPort: 8080
 
 # base url of bark archive server
+# CLI: --bark-url
 barkBaseUrl: ""
 
 # number of slots from tip within which blocks
@@ -173,6 +185,7 @@ barkBaseUrl: ""
 barkSecurityWindow: 10000
 
 # TCP port bind for listening for bark RPC calls
+# CLI: --bark-port
 barkPort: 0
 
 # ---
@@ -218,6 +231,7 @@ intersectTip: false
 # Maximum total size (in bytes) of all transactions allowed in the mempool.
 # Transactions exceeding this limit will be rejected.
 # Default: 1048576 (1 MB)
+# CLI: --mempool-capacity
 mempoolCapacity: 1048576
 
 # Forging tolerances (0 = defaults)
@@ -234,12 +248,14 @@ forgeStaleGapThresholdSlots: 0
 # Note: CLI commands (serve, load) take priority over this setting
 #
 # Can be overridden with the DINGO_RUN_MODE environment variable
+# CLI: --run-mode
 runMode: "serve"
 
 # Path to ImmutableDB for batch import (used when runMode is "load")
 # Can also be provided as argument to 'dingo load' command
 #
 # Can be overridden with the DINGO_IMMUTABLE_DB_PATH environment variable
+# CLI: --immutable-db-path
 immutableDbPath: ""
 
 # Validate historical blocks during ledger processing (default: false)
@@ -251,10 +267,13 @@ validateHistorical: false
 # Default: known=150, established=50, active=20
 #
 # Target number of known (cold) peers
+# CLI: --target-known-peers
 targetNumberOfKnownPeers: 0
 # Target number of established (warm) peers
+# CLI: --target-established-peers
 targetNumberOfEstablishedPeers: 0
 # Target number of active (hot) peers
+# CLI: --target-active-peers
 targetNumberOfActivePeers: 0
 
 # Per-source quotas for active peers
@@ -269,11 +288,52 @@ activePeersGossipQuota: 0
 # Active peer slots for ledger sources
 activePeersLedgerQuota: 0
 
+# Inbound peer governance budget (phase 1)
+# These define explicit operator intent for inbound peers as a governed source.
+# Current behavior remains conservative; these values are surfaced in metrics and
+# quota/status output to make inbound policy visible.
+#
+# Target number of inbound peers to keep in warm state.
+# CLI: --inbound-warm-target
+inboundWarmTarget: 0
+# Quota for inbound peers in hot state.
+# CLI: --inbound-hot-quota
+inboundHotQuota: 0
+# Minimum tenure before inbound peers are eligible for hot promotion.
+# CLI: --inbound-min-tenure
+inboundMinTenure: 0s
+# Minimum score threshold for inbound hot promotion.
+# CLI: --inbound-hot-score-threshold
+inboundHotScoreThreshold: 0
+# Future prune grace window for inbound peers.
+# CLI: --inbound-prune-after
+inboundPruneAfter: 0s
+# Future duplex policy knob for inbound peers.
+# CLI: --inbound-duplex-only-for-hot
+inboundDuplexOnlyForHot: false
+# Future cooldown knob for inbound peer governance actions.
+# CLI: --inbound-cooldown
+inboundCooldown: 0s
+
+# Genesis bootstrap configuration
+# Used only for from-origin sync. Default behavior keeps this enabled and
+# exits Genesis mode automatically near the best known peer tip.
+genesisBootstrap:
+  # Enable/disable Genesis bootstrap mode (default: true).
+  enabled: true
+  # Override the Genesis comparison window in slots.
+  # 0 auto-derives the window from genesis params (3k/f).
+  windowSlots: 0
+  # Minimum diversity groups to prefer while promoting peers during bootstrap.
+  # 0 uses the peer-governor default.
+  promotionMinDiversityGroups: 0
+
 # Cache configuration for tiered CBOR cache system
 # This controls the in-memory caching of UTxO and transaction CBOR data
 cache:
   # Number of entries in the hot UTxO cache (LFU eviction)
   # Default: 50000
+  # CLI: --cache-hot-utxo-entries
   hotUtxoEntries: 50000
   # Number of entries in the hot transaction cache (LFU eviction)
   # Default: 10000
@@ -283,16 +343,19 @@ cache:
   hotTxMaxBytes: 268435456
   # Number of blocks to keep in the block LRU cache
   # Default: 500
+  # CLI: --cache-block-lru-entries
   blockLruEntries: 500
   # Number of recent blocks to warm up on startup
   # Default: 1000
   warmupBlocks: 1000
   # Wait for cache warmup to complete before serving requests
   # Default: true
+  # CLI: --cache-warmup-sync
   warmupSync: true
 
 # Mithril snapshot bootstrap configuration
 # Use 'dingo mithril sync' or 'dingo sync --mithril' to bootstrap from a snapshot
+# CLI: --mithril-enabled, --mithril-verify-certs
 mithril:
   # Enable Mithril integration (default: true)
   enabled: true

package/docs/dashboards/README.md

@@ -0,0 +1,188 @@
+# Dingo Grafana Dashboards
+
+Monitoring dashboards for [Dingo](https://github.com/blinklabs-io/dingo), the Go Cardano node by Blink Labs.
+
+## Dashboards
+
+| Dashboard | File | Description |
+|-----------|------|-------------|
+| **Node Overview** | `node-overview.json` | At-a-glance header (epoch, slot, tip gap, density, blockfetch, mempool, KES, peers, storage, runtime), block height, epoch progress, forging stats |
+| **Block Production** | `block-production.json` | Forge latency heatmap, block delay CDFs, forge rates, KES lifecycle |
+| **Peer Health** | `peer-health.json` | Hot/warm/cold peers, connection types, peer state timeseries, promotions/demotions, network I/O |
+| **Mempool** | `mempool.json` | Pending TXs, mempool size, TX lifecycle, CBOR cache, event bus |
+| **Resource Usage** | `resources.json` | CPU, memory, GC heatmap, disk I/O, IOPS, PSI pressure, Badger, file descriptors |
+
+`full-panel.json` contains the standalone Business Text header panel for embedding into custom dashboards.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Grafana 12+** (tested on 12.4) — [install guide](https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
+- **Prometheus** scraping your Dingo node on port `12798` (configured in step 2 below)
+- **Dingo** node with metrics enabled (default port `12798`)
+- **[Business Text plugin](https://grafana.com/grafana/plugins/marcusolsson-dynamictext-panel/)** — required by all dashboards for the header panel
+- **[prometheus-node-exporter](https://github.com/prometheus/node_exporter)** — required only by the Resource Usage dashboard for host-level CPU, memory, and disk metrics
+
+## Quick start
+
+### 1. Install the Business Text plugin
+
+Open a terminal on the machine running Grafana and run:
+
+```bash
+grafana-cli plugins install marcusolsson-dynamictext-panel
+sudo systemctl restart grafana-server
+```
+
+If you are running Grafana in Docker or Kubernetes, set the environment variable instead:
+
+```text
+GF_INSTALL_PLUGINS=marcusolsson-dynamictext-panel
+```
+
+### 2. Configure Prometheus scrape targets
+
+Prometheus needs to know where to find your Dingo node. Add the following to your `prometheus.yml` under `scrape_configs`:
+
+```yaml
+- job_name: dingo
+  scrape_interval: 15s
+  static_configs:
+    - targets: ['localhost:12798']
+
+# Optional: required for Resource Usage dashboard
+- job_name: node
+  scrape_interval: 15s
+  static_configs:
+    - targets: ['localhost:9100']
+```
+
+Then reload Prometheus to apply the change:
+
+```bash
+sudo systemctl reload prometheus
+```
+
+### 3. Import dashboards
+
+There are two ways to get the dashboards into Grafana.
+
+**Option A: Provisioning (recommended)**
+
+Provisioning automatically loads dashboards from files on disk. Grafana will pick them up on startup or within about 30 seconds if already running.
+
+```bash
+sudo cp docs/dashboards/provisioning.yaml /etc/grafana/provisioning/dashboards/dingo.yaml
+sudo mkdir -p /var/lib/grafana/dashboards/dingo
+sudo cp docs/dashboards/*.json /var/lib/grafana/dashboards/dingo/
+sudo chown -R grafana:grafana /var/lib/grafana/dashboards/dingo/
+sudo systemctl restart grafana-server
+```
+
+After restarting, go to **Dashboards → Browse** in the Grafana UI and search for "Dingo". All five dashboards appear in a **Dingo** folder automatically.
+
+**Note:** `allowUiUpdates: true` lets you edit dashboards in the Grafana UI, but changes will be overwritten on the next provision cycle (every 30 seconds). To make permanent edits, modify the JSON files directly.
+
+**Option B: Manual import**
+
+1. Open Grafana in your browser
+2. Go to **Dashboards → New → Import**
+3. Upload each JSON file
+4. Select your Prometheus datasource when prompted
+
+### 4. Alert rules (optional)
+
+The alert rules file is ready to use as-is — no editing required.
+
+Copy the file to your Prometheus rules directory:
+
+```bash
+sudo cp docs/dashboards/alerts.yaml /etc/prometheus/rules/dingo.yaml
+```
+
+Then add it to `prometheus.yml`:
+
+```yaml
+rule_files:
+  - /etc/prometheus/rules/dingo.yaml
+```
+
+Reload Prometheus:
+
+```bash
+sudo systemctl reload prometheus
+```
+
+## Datasource
+
+All dashboards expect a Prometheus datasource with UID `prometheus`. If your datasource has a different UID, update it before importing or recreate the datasource with UID `prometheus`.
+
+## Template variables
+
+All dashboards include two template variables that auto-discover dingo instances:
+
+| Variable | Query | Purpose |
+|----------|-------|---------|
+| `$network` | `label_values(dingo_build_info, network)` | Selects the Cardano network (`preview`, `preprod`, `mainnet`). |
+| `$instance` | `label_values(dingo_build_info{network="$network"}, instance)` | Selects specific dingo instance(s). Multi-select with "All" default. |
+
+`dingo_build_info` is a metric only dingo exposes (includes `network`, `version`, `commit` labels). This ensures dropdowns show only dingo targets, never Haskell cardano-node.
+
+All panel queries use `{network="$network", instance=~"$instance"}` as their selector.
+
+The **Resource Usage** dashboard adds a third variable:
+
+| Variable | Query | Purpose |
+|----------|-------|---------|
+| `$node_instance` | `label_values(node_uname_info, instance)` | Selects the node_exporter target for host-level metrics (CPU, memory, disk, network). node_exporter runs on a different port (default `9100`) from the dingo metrics port, so it needs its own instance dropdown. |
+
+Set `$node_instance` to the hostname/port reported by your node_exporter scrape target (typically `localhost:9100` or the host IP).
+
+## Navigation
+
+Dashboard-level links at the top of each dashboard connect all 5 dashboards. Links preserve the selected time range and template variables.
+
+## Dormant metrics
+
+Some metrics only emit when their feature is active. Panels display "No data" until activated:
+
+| Metric | Activates when |
+|--------|---------------|
+| `cardano_node_metrics_Forge_node_is_leader_int` | Forging is enabled |
+| `cardano_node_metrics_Forge_adopted_int` | Block is forged and adopted |
+| `cardano_node_metrics_blockForgingLatency_seconds_bucket` | Block is forged |
+| `cardano_node_metrics_remainingKESPeriods_int` | KES key is configured |
+| `dingo_forge_tip_gap_slots` | Forging is enabled |
+| `dingo_database_size_bytes` | Database stores are initialized |
+| `database_blob_*` | Badger blob store is active |
+
+## File listing
+
+```text
+docs/dashboards/
+  node-overview.json       Node Overview dashboard
+  block-production.json    Block Production dashboard
+  peer-health.json         Peer Health dashboard
+  mempool.json             Mempool dashboard
+  resources.json           Resource Usage dashboard
+  full-panel.json          Business Text header panel (standalone)
+  provisioning.yaml        Grafana provisioning config
+  prometheus.yaml          Prometheus scrape config snippet
+  alerts.yaml              Prometheus alert rules
+  README.md                This file
+```
+
+## Troubleshooting
+
+**Business Text plugin not found / panels show "Panel plugin not found: marcusolsson-dynamictext-panel"**
+Install the plugin (step 1 above) and restart Grafana. If running in a managed environment, add `marcusolsson-dynamictext-panel` to your `GF_INSTALL_PLUGINS` list.
+
+**Panels show "No data"**
+Check that Prometheus is scraping your Dingo node: open Prometheus in the browser, go to **Status → Targets**, and confirm the `dingo` job is up. Also verify the `$network` and `$instance` template variables at the top of the dashboard are set to the correct values.
+
+**Datasource UID mismatch ("datasource not found")**
+All JSON files use the datasource UID `prometheus`. If your Prometheus datasource has a different UID, either rename it to `prometheus` in **Connections → Data sources**, or do a find-and-replace of `"prometheus"` with your actual UID in the JSON files before importing.
+
+**Dashboards not appearing after provisioning**
+Confirm `/etc/grafana/provisioning/dashboards/dingo.yaml` references the correct path. Grafana auto-reloads provisioned dashboards every 30 seconds; if it hasn't appeared after a minute, check the Grafana log (`journalctl -u grafana-server`) for errors.

package/docs/dashboards/alerts.yaml

@@ -0,0 +1,29 @@
+groups:
+  - name: dingo
+    rules:
+      - alert: DingoBlockStall
+        expr: changes(cardano_node_metrics_blockNum_int{network=~".+"}[5m]) == 0
+        for: 0m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Dingo block height stalled on {{ $labels.network }}"
+          description: "Node {{ $labels.instance }} on {{ $labels.network }}: block height has not changed in 5 minutes."
+
+      - alert: DingoSlotDrift
+        expr: changes(cardano_node_metrics_slotNum_int{network=~".+"}[2m]) == 0
+        for: 0m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Dingo slot counter stalled on {{ $labels.network }}"
+          description: "Node {{ $labels.instance }} on {{ $labels.network }}: slot counter has not advanced in 2 minutes."
+
+      - alert: DingoPeerLoss
+        expr: cardano_node_metrics_connectionManager_outgoingConns{network=~".+"} == 0
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Dingo has no outgoing peers on {{ $labels.network }}"
+          description: "Node {{ $labels.instance }} on {{ $labels.network }}: zero outgoing connections for 5+ minutes. Node cannot sync."

package/docs/dashboards/prometheus.yaml

@@ -0,0 +1,16 @@
+## Prometheus scrape configuration for Dingo dashboards
+##
+## Add these jobs to your prometheus.yml under scrape_configs:
+
+scrape_configs:
+  # Dingo node metrics (default port 12798)
+  - job_name: dingo
+    scrape_interval: 15s
+    static_configs:
+      - targets: ['localhost:12798']
+
+  # Node exporter for host-level metrics (required by Resource Usage dashboard)
+  - job_name: node
+    scrape_interval: 15s
+    static_configs:
+      - targets: ['localhost:9100']

package/docs/dashboards/provisioning.yaml

@@ -0,0 +1,14 @@
+apiVersion: 1
+
+providers:
+  - name: dingo
+    orgId: 1
+    folder: Dingo
+    folderUid: dingo-dashboards
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 30
+    allowUiUpdates: true
+    options:
+      path: /var/lib/grafana/dashboards/dingo
+      foldersFromFilesStructure: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinklabs/dingo",
-  "version": "0.36.1",
+  "version": "0.38.0",
   "description": "Dingo is a Cardano blockchain data node",
   "main": "index.js",
   "bin": {