DB Sync components

Cardano-db-sync consists of a set of components:

  • cardano-db – defines common data types and functions used by any application that needs to interact with the database from Haskell. In particular, it defines the database schema.
  • cardano-db-tool – a tool used to manage cardano-db-sync databases (create, run, validate and analyze migrations).
  • cardano-db-sync – acts as a Cardano node, following the chain and inserting data from the chain into a PostgreSQL database.
  • db-sync-node – designed to work with a locally running Cardano Node to store data in the PostgreSQL database.

The db-sync-node is written in a highly modular fashion to allow it to be as flexible as possible. It connects to a locally running cardano-node (i.e., the one connected to other nodes in the Cardano network over the internet with TCP/IP) using a Unix domain socket. Db-sync-node retrieves blocks, updates its internal ledger state, and stores parts of each block in a local PostgreSQL database.


PostgreSQL is a generic relational database used for the mapping of on-chain information to a relational model. It addresses specific user needs and requirements using the normalization technique to store relational data without duplication.

The following diagram outlines the interaction between the system components:


GraphQL and REST API export an interface to the data stored in the database to be accessed from spreadsheets, for example. Frontend explorer is the most user-oriented tool; it fetches data from the main database and reflects it in a straightforward and convenient web interface. Another component, the SMASH server, aggregates stake pool metadata and provides pool operators and delegators with a list of valid stake pools with verified metadata.

GraphQL API Server (Apollo)

The GraphQL API provides a query interface to all the blockchain data via GraphQL, which is a convenient choice for client applications based on web technologies (applications written in JavaScript, or any other browser-based languages, for example) that use HTTP/REST APIs to talk to other services. It is an alternative to the database SQL interface. Application developers can choose between SQL and GraphQL for accessing the chain data.

The implementation of the API is based on the Apollo Server, an open-source, spec-compliant GraphQL server that's compatible with any GraphQL client (including the Apollo Client).

REST API Components

There are two Cardano components that provide an HTTP REST API for interacting with a local node:

  • A dedicated transaction submission component, which has a single endpoint for submitting transactions.
  • A query component to access blockchain data. This is a legacy component provided to aid migration from the Byron era. Any applications currently using it should plan to migrate to the GraphQL API or the SQL interface.

The rationale for this is that the REST API is deprecated, so there is no reason for new applications to use it for querying chain data. The submission API is, for now, the only HTTP based API for tx submission, as GraphQL does not yet support tx submission, so any application authors that want to use web-tech APIs (rather than scripting APIs or low level or Haskell APIs) can use the REST API for tx submission.

Stake Pool Metadata Aggregation Server (SMASH)

The purpose of the Stake Pool Metadata Aggregation Server (SMASH) is to aggregate off-chain metadata that stake pools provide when they register on the Cardano blockchain. This metadata includes the name of the stake pool, its ticker name, web homepage, and so on.

The rationale for a metadata aggregation server in the Cardano architecture is two-fold:

  1. To keep the stake pool metadata stored off-chain; and
  2. To retain the ability to moderate stake pool metadata, without any centralized censor.

The metadata is hosted off-chain and referred to from the on-chain pool registration. SMASH collects the off-chain data to make it more convenient, performant, and reliable for wallets and other applications to access it.

The SMASH server also addresses the desire to moderate the content of stake pool metadata without a centralized censoring entity. For example, most wallet users and stake pool operators would like to have the ability to treat stake pool ticker names as if they were unique trademarks. It would be too complex to have a fair, on-chain system to resolve ticker name disputes. Instead of enforcing uniqueness on chain, this can optionally be enforced by filtering as part of metadata aggregation. Multiple aggregation services can be run by different organizations following different policies on filtering stake pool metadata. This enables wallet users and other consumers of stake pool metadata to choose which policy to follow, if any.