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.
  • cardano-db-sync-extended – a relatively simple extension to cardano-db-sync, which maintains an extra table containing epoch data.
  • db-sync-node – designed to work with a locally running Cardano Node to store data in the PostgreSQL database.

The two versions cardano-db-sync and cardano-db-sync-extended are fully compatible and use identical database schemas. The only difference is that the extended version maintains an Epoch table, which the non-extended version will also create but not maintain.

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.

© IOHK 2015 - 2022

Cardano Logo

Cardano is an open-source project.

Cardano is a software platform ONLY and does not conduct any independent diligence on, or substantive review of, any blockchain asset, digital currency, cryptocurrency or associated funds. You are fully and solely responsible for evaluating your investments, for determining whether you will exchange blockchain assets based on your own judgement, and for all your decisions as to whether to exchange blockchain assets with Cardano. In many cases, blockchain assets you exchange on the basis of your research may not increase in value, and may decrease in value. Similarly, blockchain assets you exchange on the basis of your research may fall or rise in value after your exchange.

Past performance is not indicative of future results. Any investment in blockchain assets involves the risk of loss of part or all of your investment. The value of the blockchain assets you exchange is subject to market and other investment risks