XRAY/Graph Koios Tiny — Cardano Explorer API

Note

XRAY/Graph Koios Tiny is a dockered Cardano blockchain explorer API tool based on Koios and Cardano-Db-Sync. With some custom RPCs added.

Getting Started

Prepare Installation

git clone \
  --recurse-submodules \
  https://github.com/xray-network/xray-graph-koios-tiny.git \
  && cd xray-graph-koios-tiny

cp .env.example .env

Build and Run via Docker Compose

You can combine profiles to run multiple networks on the same machine: docker compose --profile mainnet --profile preprod --profile preview up -d

MAINNET

RESTORE_SNAPSHOT_MAINNET=https://snapshots.koios.rest/db-sync-13.1-mainnet/db-sync-snapshot-schema-13.1-block-9684674-x86_64.tgz \
docker compose --profile mainnet up -d --build

Get the most recent snapshot link here (with db-sync started with --consumed-tx-out flag) or here (without flag, takes a lot longer to restore), and set it as RESTORE_SNAPSHOT_MAINNET below, or omit if you wish to sync from genesis. Restoring from snapshot takes >6 hours and full init of Koios cron jobs >3 hours, so keep that in mind.

PREPROD

docker compose --profile preprod up -d --build

PREVIEW

docker compose --profile preview up -d --build

Endpoints List

• Koios — https://api.koios.rest/

Differences with the original Koios:

• /submittx endpoint: send TX as CBOR string (content-type: application/cbor)
• /ogmios endpoint: not available, use XRAY/Graph Ogmios instead

API Status Check

Raw CURL query examples:

curl 0.0.0.0:8050/rpc/tip

curl 0.0.0.0:8050/rpc/blocks

TypeScript Client

We recommend to use cardano-koios-client. Visit cardano-koios-client repo for more information.

Advanced Usage

Postgresql Config

Config file (see end of file): postgresql.conf
Use https://pgtune.leopard.in.ua/ to tune the database settings

Koios Custom RPCs & Cron Tasks

Place the .sql files in the koios-tiny/extra-rpc folder to register with Postgrest. Then rebuild the koios-tiny-{network} container. Read more at https://postgrest.org/en/stable/references/api.html

Place the .sh files in koios-tiny/extra-cron-jobs and edit the koios-tiny/cron-schedule. Then rebuild the koios-tiny-{network} container.

Rebuild: docker compose up -d --build --force-recreate koios-tiny-{network}.

System Requirements

In general, this stack loads the system in the same way as cardano-db-sync, so the minimal system requirements will be the same:

• Any of the big well known Linux distributions (eg, Debian, Ubuntu, RHEL, CentOS, Arch etc).
• 64 Gigabytes of RAM or more.
• 4 CPU cores or more.
• Ensure that the machine has sufficient IOPS (Input/Output Operations per Second). Ie it should be 100k IOPS or better. Lower IOPS ratings will result in slower sync times and/or falling behind the chain tip.
• Minimum 1000 Gigabytes or more of SSD disk storage.

When building an application that will be querying the database, remember that for fast queries, low latency disk access is far more important than high throughput (assuming the minimal IOPS above is met).