The Hiro Systems Stacks Blockchain API is a powerful tool for developers looking to interact with the Stacks blockchain. In this guide, we will walk you through the process of setting up the API, from local development to production deployment, and we will troubleshoot common issues along the way.

Quick Start

Before you dive into coding, ensure that your development environment is ready. This service requires PostgreSQL, Stacks node, and Bitcoind to be running. The Clarinet project is your best friend here, providing a straightforward way to spin up the API alongside its dependencies. You can set it up quickly in a local development environment, simulating the blockchain ecosystem.

Local Development Setup

To begin, follow these steps:

• Ensure Docker is installed on your machine.
• Clone the API repository.
• Install dependencies using npm install.
• Use Launch: w postgres in VSCode or run npm run dev:integrated to start everything up.
• Check server functionality by navigating to http://localhost:3999/extended/v1/status.

Local Development Explained

Think of setting up your local development environment as preparing a stage for a play. You have your actors (API, PostgreSQL, etc.), the stage (your local machine), and the audience (you, the developer!). Properly arranging the actors will ensure that the play runs smoothly, and by preparing the stage correctly, you prevent any mishaps that might disrupt the performance.

Production Deployment

When it’s time to take your API live, the recommended approach is to use the Docker image hirosystems/stacks-blockchain-api. However, remember that this image cannot run standalone; it requires other services to be configured and running correctly.

For an optimal experience, run the API’s database on PostgreSQL version 14 or newer. For step-by-step guidance read the full documentation on how to run the API node here.

Upgrading the API

When considering an upgrade (say, from version 3.0.0 to 4.0.0), be aware that the Postgres database from the old version may not be compatible, leading to a failed startup. Always use the Event Replay method detailed in our documentation to avoid data mishaps.

API Run Modes

Our API comes equipped with several run modes, allowing for customization according to your needs:

• Default Mode: All components active, allowing for read-write actions.
• Write-only Mode: Uses only the Stacks node event server, great for data ingestion without serving an API.
• Read-only Mode: Ideal for load-balancing, this mode reads from the database and requires another instance to provide updates.
• Offline Mode: A stripped-down version useful for specific rosetta endpoints.

Event Replay Instructions

Should you need to replay an event to synchronize your database without doing a full resync, Hiro provides an event-replay feature. This can streamline operations significantly, allowing for quicker upgrades and fewer hassles.

Event Replay Explained

Consider the event replay feature as a time machine for your database. Instead of restarting everything from the beginning, this tool allows you to rewind and replay events to catch up with updates swiftly, much like rewatching a favorite scene in a movie to fully grasp what’s happening.

Troubleshooting

Here are some troubleshooting tips to keep in mind:

• If the server fails to start, ensure all dependencies are running by verifying Docker and PostgreSQL services.
• In case of API response issues, check the environment variables and verify that they are set correctly.
• Try restarting services or clearing the cache as a first step in troubleshooting database connection issues.
• For more assistance, consider checking our support Discord channel.
• For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

Conclusion

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.