diff --git a/content/docs/en/resources/archive/meta.json b/content/docs/en/resources/archive/meta.json index e583e1c7d..1cce2fa6b 100644 --- a/content/docs/en/resources/archive/meta.json +++ b/content/docs/en/resources/archive/meta.json @@ -1,5 +1,5 @@ { "title": "Hiro Archive", "root": true, - "pages": ["index", "download-guide", "stacks-blockchain", "stacks-api", "token-metadata-api"] + "pages": ["index", "download-guide", "stacks-blockchain", "stacks-api"] } diff --git a/content/docs/en/resources/archive/stacks-api.mdx b/content/docs/en/resources/archive/stacks-api.mdx index c60df2778..371b898e1 100644 --- a/content/docs/en/resources/archive/stacks-api.mdx +++ b/content/docs/en/resources/archive/stacks-api.mdx @@ -5,18 +5,24 @@ description: Discover how to use the Hiro Archive to spin up a Stacks Blockchain ## 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](/resources/archive/stacks-blockchain) before restoring the Stacks Blockchain API. Otherwise, you may encounter errors when running the API. +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](/resources/archive/stacks-blockchain) 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](https://github.com/hirosystems/stacks-blockchain-api/releases) for guidance). -- Both archives were created on the same date. +- 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. +:::callout +type: info +### Deploying with Docker? +If you're running your setup with Docker, the [Stacks Blockchain Docker](https://github.com/stx-labs/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. @@ -76,7 +82,7 @@ or the most recent upload for a particular version: 1. Download the archive and shasum for the appropriate network and restoration method. 1. Verify the archive using the steps in the [download guide](/resources/archive/download-guide#verification-and-extraction) (note: API archives may not have SHA256 files available). -1. Import the archive file into a running Postgres database (may take up to an hour depending on database specs and tuning): +1. Import the archive file into a running Postgres database (may take several hours depending on database specs and tuning): ```terminal $ export PGPASSWORD= $ pg_restore --username postgres --verbose --jobs 4 --dbname stacks_blockchain_api /path/to/archive/file @@ -96,6 +102,31 @@ or the most recent upload for a particular version: ``` 1. [Follow these directions](https://github.com/hirosystems/stacks-blockchain-api#export-and-import) to process and import the events in the TSV file into your Postgres database. 1. Launch the Stacks Blockchain API service. -1. Verify the dataset is being used by comparing your nodes [local block height](http://localhost:3999/extended/v1/status) with [Hiro's](https://api.hiro.so/extended/v1/status). If the block height matches or is close to Hiro's block height, the restoration was successful. +1. Verify the dataset is being used by comparing your nodes [local block height](http://localhost:3999/extended) with [Hiro's](https://api.hiro.so/extended/v1/status). 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. 1. 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. + +## 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`](http://localhost:3999/extended) is steadily increasing and catching up to [Hiro's](https://api.hiro.so/extended). 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](#prerequisites) for the full archive compatibility criteria. diff --git a/content/docs/en/resources/archive/token-metadata-api.mdx b/content/docs/en/resources/archive/token-metadata-api.mdx deleted file mode 100644 index 85c37ca9f..000000000 --- a/content/docs/en/resources/archive/token-metadata-api.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Use the Token Metadata API archive -description: Discover how to use the Hiro Archive to spin up a Token Metadata API. ---- - -## Prerequisites - -Since the Token Metadata API depends on a Stacks Blockchain API, you will need to first launch a Stacks Blockchain API configured for the same Stacks network. - -If you don't already have one, you can follow [these instructions](/resources/archive/stacks-blockchain) to launch one with an archive. - -## Where to download archives - -Token Metadata API archives for each network can be found at the following locations: - -- mainnet: https://archive.hiro.so/mainnet/token-metadata-api-pg/ -- testnet: https://archive.hiro.so/testnet/token-metadata-api-pg/ - -The file name patterns are as follows: - -- archive: `token-metadata-api-pg---.dump` -- shasum: `token-metadata-api-pg---.sha256` - -There is a continually updated archive and shasum which always points to the most recent upload: - -- archive: `token-metadata-api-pg--latest.dump` -- shasum: `token-metadata-api-pg--latest.sha256` - -or the most recent upload for a particular version: - -- archive: `token-metadata-api-pg---latest.dump` -- shasum: `token-metadata-api-pg---latest.sha256` - -## Restoring the Token Metadata API using the Hiro Archive - -1. Download the archive and shasum for the appropriate network. -1. Verify the archive using the steps in the [download guide](/resources/archive/download-guide#verification-and-extraction) (note: API archives may not have SHA256 files available). -1. Import the archive file into a running Postgres database (may take up to an hour depending on database specs and tuning): - ```terminal - $ export PGPASSWORD= - $ pg_restore --username postgres --verbose --jobs 4 --dbname token_metadata_api /path/to/archive/file - ``` -1. Launch the Token Metadata API service. -1. Verify the restoration was successful by viewing the [total number of tokens and contracts tracked in the service.](http://localhost:3000/metadata) If the total number of each property is greater than zero, the restoration was successful. - 1. It may take a few minutes for the local node to respond on this endpoint. diff --git a/content/docs/es/resources/archive/meta.json b/content/docs/es/resources/archive/meta.json index e583e1c7d..1cce2fa6b 100644 --- a/content/docs/es/resources/archive/meta.json +++ b/content/docs/es/resources/archive/meta.json @@ -1,5 +1,5 @@ { "title": "Hiro Archive", "root": true, - "pages": ["index", "download-guide", "stacks-blockchain", "stacks-api", "token-metadata-api"] + "pages": ["index", "download-guide", "stacks-blockchain", "stacks-api"] } diff --git a/content/docs/es/resources/archive/token-metadata-api.mdx b/content/docs/es/resources/archive/token-metadata-api.mdx deleted file mode 100644 index e6b959dad..000000000 --- a/content/docs/es/resources/archive/token-metadata-api.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Usar el archivo de la API de metadatos de tokens -description: Descubre cómo utilizar el Hiro Archive para poner en marcha una API de Metadatos de Tokens. ---- -## Requisitos previos - -Dado que la API de metadatos de tokens depende de una API de Stacks Blockchain, primero deberá lanzar una API de Stacks Blockchain configurada para la misma red de Stacks. - -Si aún no tienes uno, puedes seguir [estas instrucciones](/resources/archive/stacks-blockchain) para lanzar uno con un archivo. - -## Dónde descargar archivos - -Los archivos de la API de metadatos de tokens para cada red se pueden encontrar en las siguientes ubicaciones: - -* mainnet: https://archive.hiro.so/mainnet/token-metadata-api-pg/ -* testnet: https://archive.hiro.so/testnet/token-metadata-api-pg/ - -Los patrones de nombres de archivo son los siguientes: - -* archivo: `token-metadata-api-pg---.dump` -* shasum: `token-metadata-api-pg---.sha256` - -Existe un archivo y un shasum que se actualizan continuamente y siempre apuntan a la carga más reciente: - -* archivo: `token-metadata-api-pg--latest.dump` -* shasum: `token-metadata-api-pg--latest.sha256` - -o la carga más reciente para una versión en particular: - -* archivo: `token-metadata-api-pg---latest.dump` -* shasum: `token-metadata-api-pg---latest.sha256` - -## Restaurando la API de metadatos de tokens utilizando el archivo de Hiro - -1. Descargue el archivo y el shasum para la red apropiada. -2. Verifique el archivo usando los pasos en el [descargar guía](/resources/archive/download-guide#verification-and-extraction) (note: API archives may not have SHA256 files available). -3. Importe el archivo de archivo en una base de datos Postgres en ejecución (puede tardar hasta una hora dependiendo de las especificaciones y la configuración de la base de datos): - ```terminal - $ export PGPASSWORD= - $ pg_restore --username postgres --verbose --jobs 4 --dbname token_metadata_api /path/to/archive/file - ``` -4. Inicie el servicio de API de metadatos de tokens. -5. Verifique que la restauración se haya realizado correctamente visualizando el [número total de tokens y contratos rastreados en el servicio.](http://localhost:3000/metadata) Si el número total de cada propiedad es mayor que cero, la restauración fue exitosa. - 1. Es posible que el nodo local tarde unos minutos en responder en este punto final.