Skip to content

docs: overhaul documentation ahead of v1 #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scarmuega merged 2 commits into from
Mar 13, 2026
Merged

docs: overhaul documentation ahead of v1 #944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9fec6c
docs: overhaul documentation ahead of v1
scarmuega Mar 13, 2026
4809e03
apply feedback
scarmuega Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/content/apis/_meta.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
label: APIs
order: 5
order: 6
collapsed: true
6 changes: 3 additions & 3 deletions docs/content/apis/grpc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: gRPC
title: UTxO RPC
sidebar:
order: 1
---

Dolos exposes a gRPC endpoint allowing clients to perform operations such as querying data, receiving notifications and submitting transactions.
Dolos exposes a [UTxO RPC](https://utxorpc.org) endpoint over gRPC, allowing clients to perform operations such as querying data, receiving notifications and submitting transactions.

The endpoint provide by _Dolos_ adheres to the [UTxO RPC](https://utxorpc.org) interface definition. UtxoRPC is a generic specification of how to exchange data with UTxO-based blockchains, such as Cardano.
UTxO RPC is a generic specification of how to exchange data with UTxO-based blockchains, such as Cardano.

If enabled via configuration, _Dolos_ will expose a TCP port accepting gRPC connections. The default port number is `50051`, but this value can be changed via configuration.

Expand Down
126 changes: 63 additions & 63 deletions docs/content/apis/minibf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,69 +6,6 @@ sidebar:

Dolos provides an HTTP endpoint to access data using [Blockfrost OpenAPI](https://github.com/blockfrost/openapi) specification.

## Coverage

Dolos provides many, but not all of the Blockfrost endpoints. The following list represent the endpoints currently supported by Dolos:

| Endpoint | Description |
|--------------------------------------------|----------------------------------------------------------|
| `/` | Service info (version, revision) |
| `/health` | Health check |
| `/health/clock` | Clock health |
| `/metrics` | Prometheus metrics |
| `/accounts/{stake_address}` | Get account information for a stake address |
| `/accounts/{stake_address}/addresses` | Get addresses for a stake address |
| `/accounts/{stake_address}/delegations` | Get delegations for a stake address |
| `/accounts/{stake_address}/registrations` | Get registrations for a stake address |
| `/accounts/{stake_address}/rewards` | Get rewards for a stake address |
| `/accounts/{stake_address}/utxos` | Get UTXOs for a stake address |
| `/addresses/{address}` | Get general information for a specific address |
| `/addresses/{address}/transactions` | Get transactions for a specific address |
| `/addresses/{address}/txs` | Alias of `/addresses/{address}/transactions` |
| `/addresses/{address}/utxos` | Get UTXOs for a specific address |
| `/addresses/{address}/utxos/{asset}` | Get UTXOs for a specific address and asset |
| `/assets/{subject}` | Get asset information |
| `/assets/{subject}/addresses` | Get addresses holding a specific asset |
| `/assets/{subject}/transactions` | Get transactions involving a specific asset |
| `/blocks/latest` | Get latest block information |
| `/blocks/latest/txs` | Get transactions for the latest block |
| `/blocks/slot/{slot_number}` | Get block by slot number |
| `/blocks/{hash_or_number}` | Get block information |
| `/blocks/{hash_or_number}/addresses` | Get addresses in a specific block |
| `/blocks/{hash_or_number}/next` | Get next block |
| `/blocks/{hash_or_number}/previous` | Get previous block |
| `/blocks/{hash_or_number}/txs` | Get transactions for a specific block |
| `/epochs/latest/parameters` | Get latest epoch parameters |
| `/epochs/{epoch}/blocks` | Get blocks in a specific epoch |
| `/epochs/{epoch}/parameters` | Get epoch parameters |
| `/genesis` | Get genesis information |
| `/governance/dreps/{drep_id}` | Get DRep information |
| `/metadata/txs/labels/{label}` | Get metadata for transactions with a specific label |
| `/metadata/txs/labels/{label}/cbor` | Get CBOR metadata for transactions with a specific label |
| `/network` | Get network information |
| `/network/eras` | Get network eras information |
| `/pools/extended` | Get extended pool information |
| `/pools/{id}/delegators` | Get delegators for a specific pool |
| `/pools/{id}/history` | Get history for a specific pool |
| `/scripts/{script_hash}` | Get script information |
| `/scripts/{script_hash}/json` | Get script JSON |
| `/scripts/{script_hash}/cbor` | Get script CBOR |
| `/scripts/datum/{datum_hash}` | Get datum by hash |
| `/scripts/datum/{datum_hash}/cbor` | Get datum CBOR by hash |
| `/tx/submit` | Submit a transaction |
| `/txs/{tx_hash}` | Get transaction information |
| `/txs/{tx_hash}/cbor` | Get CBOR data for a transaction |
| `/txs/{tx_hash}/delegations` | Get delegations for a specific transaction |
| `/txs/{tx_hash}/metadata` | Get metadata for a specific transaction |
| `/txs/{tx_hash}/metadata/cbor` | Get CBOR metadata for a specific transaction |
| `/txs/{tx_hash}/mirs` | Get MIRs for a specific transaction |
| `/txs/{tx_hash}/pool_retires` | Get pool retirements for a specific transaction |
| `/txs/{tx_hash}/pool_updates` | Get pool updates for a specific transaction |
| `/txs/{tx_hash}/redeemers` | Get redeemers for a specific transaction |
| `/txs/{tx_hash}/stakes` | Get stakes for a specific transaction |
| `/txs/{tx_hash}/utxos` | Get UTXOs for a specific transaction |
| `/txs/{tx_hash}/withdrawals` | Get withdrawals for a specific transaction |

## Usage

If enabled via configuration, _Dolos_ will expose a TCP port accepting HTTP connections. The default port number is `3000`, but this value can be changed via configuration.
Expand Down Expand Up @@ -155,3 +92,66 @@ max_scan_items = 3000
```

Check the [Configuration Schema](../configuration/schema) for detailed info on how to set this up.

## Coverage

Dolos provides many, but not all of the Blockfrost endpoints. The following list represent the endpoints currently supported by Dolos:

| Endpoint | Description |
|--------------------------------------------|----------------------------------------------------------|
| `/` | Service info (version, revision) |
| `/health` | Health check |
| `/health/clock` | Clock health |
| `/metrics` | Prometheus metrics |
| `/accounts/{stake_address}` | Get account information for a stake address |
| `/accounts/{stake_address}/addresses` | Get addresses for a stake address |
| `/accounts/{stake_address}/delegations` | Get delegations for a stake address |
| `/accounts/{stake_address}/registrations` | Get registrations for a stake address |
| `/accounts/{stake_address}/rewards` | Get rewards for a stake address |
| `/accounts/{stake_address}/utxos` | Get UTXOs for a stake address |
| `/addresses/{address}` | Get general information for a specific address |
| `/addresses/{address}/transactions` | Get transactions for a specific address |
| `/addresses/{address}/txs` | Alias of `/addresses/{address}/transactions` |
| `/addresses/{address}/utxos` | Get UTXOs for a specific address |
| `/addresses/{address}/utxos/{asset}` | Get UTXOs for a specific address and asset |
| `/assets/{subject}` | Get asset information |
| `/assets/{subject}/addresses` | Get addresses holding a specific asset |
| `/assets/{subject}/transactions` | Get transactions involving a specific asset |
| `/blocks/latest` | Get latest block information |
| `/blocks/latest/txs` | Get transactions for the latest block |
| `/blocks/slot/{slot_number}` | Get block by slot number |
| `/blocks/{hash_or_number}` | Get block information |
| `/blocks/{hash_or_number}/addresses` | Get addresses in a specific block |
| `/blocks/{hash_or_number}/next` | Get next block |
| `/blocks/{hash_or_number}/previous` | Get previous block |
| `/blocks/{hash_or_number}/txs` | Get transactions for a specific block |
| `/epochs/latest/parameters` | Get latest epoch parameters |
| `/epochs/{epoch}/blocks` | Get blocks in a specific epoch |
| `/epochs/{epoch}/parameters` | Get epoch parameters |
| `/genesis` | Get genesis information |
| `/governance/dreps/{drep_id}` | Get DRep information |
| `/metadata/txs/labels/{label}` | Get metadata for transactions with a specific label |
| `/metadata/txs/labels/{label}/cbor` | Get CBOR metadata for transactions with a specific label |
| `/network` | Get network information |
| `/network/eras` | Get network eras information |
| `/pools/extended` | Get extended pool information |
| `/pools/{id}/delegators` | Get delegators for a specific pool |
| `/pools/{id}/history` | Get history for a specific pool |
| `/scripts/{script_hash}` | Get script information |
| `/scripts/{script_hash}/json` | Get script JSON |
| `/scripts/{script_hash}/cbor` | Get script CBOR |
| `/scripts/datum/{datum_hash}` | Get datum by hash |
| `/scripts/datum/{datum_hash}/cbor` | Get datum CBOR by hash |
| `/tx/submit` | Submit a transaction |
| `/txs/{tx_hash}` | Get transaction information |
| `/txs/{tx_hash}/cbor` | Get CBOR data for a transaction |
| `/txs/{tx_hash}/delegations` | Get delegations for a specific transaction |
| `/txs/{tx_hash}/metadata` | Get metadata for a specific transaction |
| `/txs/{tx_hash}/metadata/cbor` | Get CBOR metadata for a specific transaction |
| `/txs/{tx_hash}/mirs` | Get MIRs for a specific transaction |
| `/txs/{tx_hash}/pool_retires` | Get pool retirements for a specific transaction |
| `/txs/{tx_hash}/pool_updates` | Get pool updates for a specific transaction |
| `/txs/{tx_hash}/redeemers` | Get redeemers for a specific transaction |
| `/txs/{tx_hash}/stakes` | Get stakes for a specific transaction |
| `/txs/{tx_hash}/utxos` | Get UTXOs for a specific transaction |
| `/txs/{tx_hash}/withdrawals` | Get withdrawals for a specific transaction |
78 changes: 77 additions & 1 deletion docs/content/apis/ouroboros.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,80 @@ sidebar:
order: 3
---

// TODO: explain how to connect using node-to-client Ouroboros mini-protocols through the unix socket.
import { Aside } from '@astrojs/starlight/components';

Dolos exposes a unix socket implementing Cardano's node-to-client Ouroboros mini-protocols. This provides drop-in compatibility with tools that normally connect to a Cardano full node, such as `cardano-cli`, Ogmios, and other ecosystem tooling.

<Aside type="note">
The Ouroboros endpoint is only available on Unix-based systems (Linux, macOS). It is not supported on Windows.
</Aside>

## Supported Mini-protocols

Dolos implements the following node-to-client mini-protocols:

| Mini-protocol | Description |
|-----------------|----------------------------------------------------------|
| ChainSync | Follow the chain tip and receive new blocks in real time |
| LocalStateQuery | Query the current ledger state |

### LocalStateQuery Coverage

The following local state queries are supported:

| Query | Description |
|----------------------|--------------------------------------------------|
| GetSystemStart | Get the system start time |
| GetChainBlockNo | Get the current chain block number |
| GetChainPoint | Get the current chain tip point |
| GetCurrentEra | Get the current era index |
| GetInterpreter | Get the era history / interpreter summary |
| GetCurrentPParams | Get the current protocol parameters |
| GetLedgerTip | Get the ledger tip point |
| GetEpochNo | Get the current epoch number |
| GetUTxOByAddress | Query UTxOs for a set of addresses |
| GetStakePools | List all registered stake pools |
| GetStakePoolParams | Get parameters for specific stake pools |
| GetPoolState | Get detailed state for specific pools |
| GetStakeSnapshots | Get stake snapshots for specific pools |
| GetAccountState | Get the global account state (treasury/reserves) |

## Usage

If enabled via configuration, Dolos will create a unix socket file accepting Ouroboros node-to-client connections. The default socket path is `dolos.socket` in the working directory, but this can be changed via configuration.

### Using with cardano-cli

Point `cardano-cli` to the Dolos socket using the `CARDANO_NODE_SOCKET_PATH` environment variable:

```sh
export CARDANO_NODE_SOCKET_PATH=./dolos.socket
cardano-cli query tip --testnet-magic 1
```

### Using with Ogmios

Start Ogmios pointing to the Dolos socket:

```sh
ogmios --node-socket ./dolos.socket --node-config config.json
```

## Configuration

The `serve.ouroboros` section controls the options for the Ouroboros endpoint.

| property | type | example |
|-------------|--------|----------------|
| listen_path | string | "dolos.socket" |

- `listen_path`: the file path for the unix socket that will listen for Ouroboros node-to-client mini-protocols.

This is an example of the `serve.ouroboros` fragment within a `dolos.toml` configuration file.

```toml
[serve.ouroboros]
listen_path = "dolos.socket"
```

Check the [Configuration Schema](../configuration/schema) for detailed info on how to set this up.
2 changes: 1 addition & 1 deletion docs/content/bootstrap/_meta.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
label: Bootstrap
order: 3
order: 4
collapsed: true
29 changes: 25 additions & 4 deletions docs/content/bootstrap/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,34 @@ sidebar:

import { CardGrid, LinkCard } from '@astrojs/starlight/components';

In the context of Dolos, we use the term _bootstrap_ to refer to the process of updating Dolos with the current state of the chain. This is usually a long process that involves processing a lot of data. There're ways to speed up process.
In the context of Dolos, we use the term _bootstrap_ to refer to the process of updating Dolos with the current state of the chain. This is usually a long process that involves processing a lot of data. There are ways to speed up the process.

In Dolos we present a few bootstrapping options:
The bootstrap command uses subcommands to select the method:

```sh
dolos bootstrap <method>
```

If no method is specified, an interactive prompt will let you choose.

## Global Flags

These flags apply to all bootstrap methods:

| flag | description | default |
| ---- | ----------- | ------- |
| `--force` | Clear existing data before bootstrapping | `false` |
| `--skip-if-data` | Skip bootstrap if data already exists (exit 0) | `false` |
| `--continue` | Continue bootstrap even if data exists, trusting the subcommand to handle resumption | `false` |
| `--verbose` | Enable verbose logging output | `false` |

By default, `dolos bootstrap` will error if it detects existing data in storage. Use one of the flags above to control this behavior.

## Bootstrap Methods

<CardGrid>
<LinkCard title="Public Relay" href="./bootstrap/relay" />
<LinkCard title="Local Full Node" href="./bootstrap/node" />
<LinkCard title="Mithril Snapshot" href="./bootstrap/mithril" />
<LinkCard title="Dolos Snapshot" href="./bootstrap/snapshot" />
<LinkCard title="Public Relay" href="./bootstrap/relay" />
<LinkCard title="Local Full Node" href="./bootstrap/local" />
</CardGrid>
Loading
Loading