Skip to main content

Use the Stacks Blockchain API Archive

Prerequisites​

Since the Stacks Blockchain API depends on a Stacks blockchain node being at the same block height, 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.

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)
  • Both archives were created on the same date

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.

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.

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. Download the archive and shasum for the appropriate network and restoration method
  2. Verify the archive with the shasum
  3. Import the archive file into a running Postgres database (may take up to an hour depending on database specs and tuning) 
        export PGPASSWORD=<YOUR POSTGRES PASSWORD>
        pg_restore --username postgres --verbose --jobs 4 --dbname stacks_blockchain_api /path/to/archive/file
  4. Launch the Stacks Blockchain API service
  5. Verify 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. It may take a few minutes for the local node to respond on this endpoint.
    2. Your 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. Download the archive and shasum for the appropriate network and restoration method
  2. Verify the archive with the shasum
  3. Extract the archive into the desired directory 
        # Target directory must already exist
        gzip -d <ARCHIVE FILE> --stdout > /path/to/extracted/file
  4. Follow these directions to process and import the events in the TSV file into your Postgres database.
  5. Launch the Stacks Blockchain API service
  6. Verify 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. It may take a few minutes for the local node to respond on this endpoint.
    2. Your 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.