Dingo APIs and Archive Services
Application APIs
Section titled “Application APIs”Dingo’s Blockfrost-compatible REST, Mesh/Rosetta REST, UTxO RPC, and
Kupo-compatible REST interfaces serve application clients. They require
storageMode: api, which stores historical transaction data for queries.
Configure each listener under plugins.api; set its port to 0 to disable it.
| Interface | Protocol | Default port |
|---|---|---|
| Blockfrost-compatible API | HTTP/REST | 3000 |
| Mesh (Rosetta) | HTTP/REST | 8080 |
| UTxO RPC | Connect/gRPC and HTTP | 9090 |
| Kupo-compatible API | HTTP/REST | Default port: 0 (disabled); built-in provider example: 1442 |
Kupo uses the built-in provider. Enable it with storageMode: api and a
nonzero provider port. For example:
storageMode: apiplugins: api: kupo: provider: builtin config: port: 1442The --kupo-provider=builtin option selects the built-in provider from the
command line. The YAML port key is plugins.api.kupo.config.port; the
corresponding environment variable is
DINGO_PLUGINS_API_KUPO_CONFIG_PORT. The provider follows the node’s normal
start and stop lifecycle.
For example, enable the built-in Blockfrost and UTxO RPC providers in
dingo.yaml:
storageMode: apiplugins: api: blockfrost: provider: builtin config: port: 3000 host: 127.0.0.1 maxConcurrentMutations: 4 maxConcurrentMutationsPerClient: 1 utxorpc: provider: builtin config: port: 9090 host: "127.0.0.1"Blockfrost mutation requests
Section titled “Blockfrost mutation requests”The built-in Blockfrost provider listens on 127.0.0.1 by default. It does
not inherit the root bindAddr unless plugins.api.blockfrost.config.host is
explicitly empty. Set a specific host to expose it on another interface.
Blockfrost mutation routes accept anonymous requests. Both
maxConcurrentMutations and maxConcurrentMutationsPerClient are unlimited
when omitted or set to 0. A positive maxConcurrentMutations enables the
global admission bound, and a positive maxConcurrentMutationsPerClient
enables the per-client admission bound. The 4 and 1 values in the example
above are operator-supplied limits for a capped deployment, not defaults.
When an operator configures a positive global limit,
maxConcurrentMutationsPerClient must not exceed
maxConcurrentMutations. Operators can set a positive per-client limit while
leaving the global limit unlimited.
The following routes accept anonymous requests and consume mutation admission capacity:
| Route | Authentication and admission behavior |
|---|---|
POST /api/v0/tx/submit | Accepts anonymous requests and consumes configured global and per-client mutation admission capacity. |
POST /api/v0/utils/txs/evaluate | Accepts anonymous requests and consumes configured global and per-client mutation admission capacity. |
POST /api/v0/utils/txs/evaluate/utxos | Accepts anonymous requests and consumes configured global and per-client mutation admission capacity. |
Admission control applies only to bounds that operators enable with positive
values. Dingo checks configured bounds before it reads the request body. When a
configured bound reaches capacity, Dingo returns HTTP 429 with
Retry-After: 1.
Keep the default loopback host unless external mutation access is an intentional deployment decision.
The complete v0.94.1 configuration reference and release-matched
dingo.yaml.example are
available on this site. Use configuration files with their matching release;
provider options can change between versions.
Secure API access
Section titled “Secure API access”The shared API bind address applies to the selected API providers, including
Kupo. The built-in UTxO RPC listener binds to 127.0.0.1 by default. To allow
remote access, set plugins.api.utxorpc.config.host explicitly; the shared
API bind address alone does not expose this listener. The api.tls and
api.auth settings define shared defaults. A provider can override either
policy under its own plugins.api.<name>.config block.
Provider-specific TLS settings take precedence over the shared TLS defaults.
Shared API authentication is disabled by default. The built-in Blockfrost
mutation policy is separate: its mutation admission limits apply only to those
Blockfrost mutation routes, not to every route on the listener.
When token authentication is enabled for a provider, send
Authorization: Bearer <token>. UTxO RPC’s HTTP and Connect/gRPC routes use
the bearer token as well.
For providers that use token authentication, it applies to every route on that listener, including health checks. Configure a probe to send the token or use a TCP check when the probe cannot attach credentials. Dingo rejects incomplete TLS certificate/key pairs at startup and does not log token or key contents.
You can also put API listeners behind a reverse proxy or API gateway. Choose one place to terminate TLS and authenticate requests, and configure Dingo’s listener policy to match that deployment.
Bark archive traffic
Section titled “Bark archive traffic”Bark is a Dingo-to-Dingo archive protocol, separate from the application APIs. An archive node can serve historical blocks from signed-URL-capable object storage. A history-expiry node can use a Bark archive as a fallback after old local block files expire; see Bootstrap and data maintenance.
Bark has no built-in authentication for ordinary archive traffic. Keep it on a trusted network. Ordinary archive traffic remains separate from the optional LifecycleService.
Bark LifecycleService
Section titled “Bark LifecycleService”Bark optionally exposes a remote LifecycleService for node lifecycle
operations. The service is disabled by default. Enable it with
barkLifecycleEnabled: true, --bark-lifecycle-enabled, or
DINGO_BARK_LIFECYCLE_ENABLED=true.
Before starting the node, configure these settings as needed:
- Set
barkPortto a nonzero port with--bark-portorDINGO_BARK_PORT.
LifecycleService accepts GetStatus, Stop, and Restart over plaintext HTTP
without client certificates or operator allowlists. Restart is unsupported on
non-Unix platforms.
When the service is enabled and barkHost is empty, Bark binds to loopback by
default. Set barkHost, --bark-host, or DINGO_BARK_HOST to expose it on a
different interface. Use network-layer controls to restrict access when
exposing it beyond a trusted network.
Bark accepts signed block download URLs only when their normalized HTTPS origin
matches the configured normalized HTTPS origin or an explicitly allowed
download origin.
The normalized origin includes the scheme, lowercased host, and effective port.
Bark checks redirect destinations against the same policy. By default,
barkBlockDownloadAllowPrivateAddresses is false, so Bark rejects any
block-download destination whose resolved address is private or special-use.
Set barkBlockDownloadAllowPrivateAddresses to true, use
--bark-block-download-allow-private-addresses, or set
DINGO_BARK_BLOCK_DOWNLOAD_ALLOW_PRIVATE_ADDRESSES=true to permit
private or special-use resolved addresses for block-download destinations
only. This option does not disable the configured origin allowlist, the
HTTPS-only requirement, or redirect validation. For block-download requests,
Bark does not use ambient HTTP proxy settings or caller-provided dialers. These
rules apply only to block downloads; the separately configured Bark RPC client
continues to handle archive RPC calls.
Docs authored by Doc Holiday