Use the Stacks Blockchain API archive

Discover how to use the Hiro Archive to spin up a Stacks Blockchain API.

Prerequisites

Since the Stacks Blockchain API depends on a Stacks blockchain node, you will need to first restore a Stacks blockchain node using the Hiro Archive before restoring the Stacks Blockchain API. Otherwise, you may encounter errors when running the API. The two do not need to be at the same block height; the API's block height can be greater than or equal to the Stacks blockchain node's block height.

In order for the Stacks blockchain and Stacks Blockchain API archives to be compatible, they must meet the following criteria:

  • Both archives correspond to the same Stacks network (mainnet/testnet).
  • The API archive version must be compatible with the Stacks blockchain archive version (See API release notes for guidance).
  • The Stacks blockchain archive was created on the same date as, or an earlier date than, the API archive.

Restoration methods

There are two ways to restore a Stacks Blockchain API using the Hiro Archive. The archive file you'll need to download will depend on your method of restoration. There is no scenario where you would need both restoration methods.

Deploying with Docker?

If you're running your setup with Docker, the Stacks Blockchain Docker tool provides scripts that automatically deploy a Stacks blockchain node and a Stacks Blockchain API from the Hiro Archive, handling the restoration steps below for you.

Restore via Postgres database dump (Recommended)

This is the quickest and most direct method, and it is suitable for most scenarios. It consists of a backup of the API's Postgres database taken using pg_dump. We generally recommend starting with this method before attempting the method below if this one does not work for any reason.

Postgres Schema

You will need to set the API PG_SCHEMA environment variable to: PG_SCHEMA=stacks_blockchain_api when restoring from an archive.

Restore via tab-separated-values (TSV) file

This method is several times slower than restoring from a Postgres dump. The API TSV file contains the raw unprocessed events from a Stacks blockchain node. The API can ingest this file to process events into a Postgres database. Restoring from a TSV file can be useful when a Postgres database archive for a particular API version is not available or when it cannot be used for any reason.

Where to download archives

Depending on the restoration method used above, the Stacks Blockchain API archives for each network can be found at the following locations:

The file name patterns are as follows:

  • Postgres database dump
    • archive: stacks-blockchain-api-pg-<DATABASE VERSION>-<API VERSION>-<DATE(YYYYMMDD)>.dump
    • shasum: stacks-blockchain-api-pg-<DATABASE VERSION>-<API VERSION>-<DATE(YYYYMMDD)>.sha256
  • TSV file
    • archive: <network>-stacks-blockchain-api-<API VERSION>-<DATE(YYYYMMDD)>.gz
    • shasum: <network>-stacks-blockchain-api-<API VERSION>-<DATE(YYYYMMDD)>.sha256

There is a continually updated archive and shasum which always points to the most recent upload:

  • Postgres database dump
    • archive: stacks-blockchain-api-pg-<DATABASE VERSION>-latest.dump
    • shasum: stacks-blockchain-api-pg-<DATABASE VERSION>-latest.sha256
  • TSV file
    • archive: <network>-stacks-blockchain-api-latest.gz
    • shasum: <network>-stacks-blockchain-api-latest.sha256

or the most recent upload for a particular version:

  • Postgres database dump
    • archive: stacks-blockchain-api-pg-<DATABASE VERSION>-<API VERSION>-latest.dump
    • shasum: stacks-blockchain-api-pg-<DATABASE VERSION>-<API VERSION>-latest.sha256
  • TSV file
    • archive: <network>-stacks-blockchain-api-<API VERSION>-latest.gz
    • shasum: <network>-stacks-blockchain-api-<API VERSION>-latest.sha256

Restoring the Stacks Blockchain API using the Hiro Archive

If restoring via Postgres dump

  1. 1Download the archive and shasum for the appropriate network and restoration method.
  2. 2Verify the archive using the steps in the download guide (note: API archives may not have SHA256 files available).
  3. 3Import the archive file into a running Postgres database (may take several hours depending on database specs and tuning):
    Terminal
    $ 
    export PGPASSWORD=<YOUR POSTGRES PASSWORD>

    $ 
    pg_restore --username postgres --verbose --jobs 4 --dbname stacks_blockchain_api /path/to/archive/file
  4. 4Launch the Stacks Blockchain API service.
  5. 5Verify the dataset is being used by comparing your nodes local block height with Hiro's. If the block height matches or is close to Hiro's block height, the restoration was successful.
    1. 1It may take a few minutes for the local node to respond on this endpoint.
    2. 2Your block height may be up to a few hundred blocks away from Hiro's depending on the age of the archive. It should catch up relatively quickly.

If restoring via TSV file

  1. 1Download the archive and shasum for the appropriate network and restoration method.
  2. 2Verify the archive using the steps in the download guide (note: API archives may not have SHA256 files available).
  3. 3Extract the archive into the desired directory:
    Terminal
    $ 
    gzip -d <ARCHIVE FILE> --stdout > /path/to/extracted/file
  4. 4Follow these directions to process and import the events in the TSV file into your Postgres database.
  5. 5Launch the Stacks Blockchain API service.
  6. 6Verify the dataset is being used by comparing your nodes local block height with Hiro's. If the block height matches or is close to Hiro's block height, the restoration was successful.
    1. 1It may take a few minutes for the local node to respond on this endpoint.
    2. 2Your block height may be up to a few hundred blocks away from Hiro's depending on the age of the archive. It should catch up relatively quickly.

Receiving new blocks

Once the archive is restored and the Stacks Blockchain API service is running and connected to your Stacks blockchain node, the API should begin receiving and accepting new block events from the node. As the node processes each new block, it sends the corresponding events to the API, which appends them to its Postgres database.

You can confirm this is working by watching the API logs for block ingestion messages and by checking that the block height reported at /extended is steadily increasing and catching up to Hiro's. Because the API's block height can be greater than or equal to the node's, the API will continue to accept new blocks as the node produces or replays them.

Troubleshooting

The API is not accepting new blocks

If the API is running but its block height is not advancing, check the API logs for an error similar to the following:

DB does not contain a parent block at height 8599913 with index_hash 0x7774575047357047226126c79a2c675fc2b14f4bc7b0a790ac135be2a267394c

Cause: This means the API received a block from the Stacks blockchain node whose parent block is missing from the API's database. It typically happens when the API's database is behind the Stacks blockchain node — that is, the node is at a higher block height than the API. This is usually the result of restoring an API archive that was created before the Stacks blockchain node archive, leaving a gap the API cannot reconcile.

Resolution: Restore the archives so that the API's block height is greater than or equal to the node's. Either:

  • Restore an API archive created on the same date as, or a later date than, the Stacks blockchain node archive, or
  • Restore an older Stacks blockchain node archive so the node is at or below the API's block height.

After re-restoring, restart the API service. See the prerequisites for the full archive compatibility criteria.

How is this guide?

Contents

PrerequisitesRestoration methodsWhere to download archivesRestoring the Stacks Blockchain API using the Hiro ArchiveReceiving new blocksTroubleshootingThe API is not accepting new blocks