Chainhook Now Powers the Token Metadata API

As we’ve built out the reliability of Hiro’s API services, a few things became clear to us. First, we needed to separate the older Stacks API into a subset of smaller API microservices. This would allow us to move faster for the changing needs of each of those services, improve maintainability, and allow API users to focus on on-chain data. So we launched the Token Metadata API in March 2023.

Second, building on Bitcoin is challenging for L2s like Stacks. In particular, Bitcoin reorgs can throw an L2 database into disarray as large numbers of transactions can be made invalid and have to be rolled back. We needed a solution for this problem that could elegantly handle reorgs while also helping developers work with customized and lightweight databases.

We launched Chainhook in August 2023 to do just that, and today we are excited to announce that Chainhook now powers Hiro’s Token Metadata API.

Why the Change?

In the last year, we’ve experienced some growing pains with the Token Metadata API. In particular, we faced two problems:

• Bitcoin reorgs were causing cascading rollbacks for token transactions specifically, and every Bitcoin reorg frequently caused thousands of Stacks tokens to be invalidated. Rolling back and reindexing those tokens could take hours, and it regularly resulted in outdated data being fetched from the Token Metadata API.
• The Token Metadata API struggled to keep up with token contracts that delayed their mints to a later time (instead of minting all at once upon deployment) because the API could not keep track of all of the different transactions during high volume minting scenarios.

As the volume of on-chain data continued to grow, we knew we needed a better method of indexing token data than the Token Metadata’s API current infrastructure, and we already had our eyes on an obvious solution—the indexer we’ve already built.

We built Chainhook a year ago as a tool for developers to build their own customizable indexes of on-chain data. What if we took that same engine and applied it to the Token Metadata API?

The Flexibility of Chainhook

Chainhook offers two superpowers for anyone trying to index on-chain data.

• It’s lightweight. You can specify what specific types of data you want to index.
• It’s reorg-aware. Chainhook monitors the Bitcoin chaintip and automatically rolls back and applies database changes when a reorg occurs. No manual intervention required.

These traits made Chainhook ideally suited to power the Token Metadata API, and we already have experience using Chainhook to power an API at scale: Hiro’s Ordinals API is powered by Ordhook (a fork of Chainhook), and today the Ordinals API serves over 100M requests per month.

Implementing Chainhook for the Token Metadata API

In order to keep an up-to-date collection of all tokens on Stacks, the Metadata API needs to continually listen for the following on-chain events: 

• Token contract deployments
• Token mints and burns
• Token metadata update notifications

To do this, we register a block predicate on Chainhook that gives us all blocks starting from block 1, including the Contract ABI for all deployed contracts. We need the full ABI because we need to check if deployed contracts conform to SIP-009, SIP-010, or SIP-013 when deploying tokens:

{
 "uuid": "bfbe0cce-fdf0-498d-bae6-59bf79accbbe",
 "name": "block",
 "version": 1,
 "chain": "stacks",
 "networks": {
   "mainnet": {
     "start_block": 1,
     "include_contract_abi": true,
     "if_this": {
       "scope": "block_height",
       "higher_than": 1
     },
     "then_that": {
       "http_post": {
         "url": "http://token-metadata-api:3099/payload",
         "authorization_header": "Bearer token"
       }
     }
   }
 }
}

Once we receive a block, we then scan all its contained transactions looking for these events:

if (tx.metadata.kind.type === 'ContractDeployment' && tx.metadata.contract_abi) {
 const sip = getSmartContractSip(tx.metadata.contract_abi);
 if (sip) {
   // Save incoming token contract
 }
}
for (const event of tx.metadata.receipt.events) {
 switch (event.type) {
   case 'SmartContractEvent':
     const notification = getMetadataUpdateNotification(tx.metadata.sender, event);
     if (notification) {
       // Refresh metadata for affected token
       continue;
     }
     const mint = getSftMintEvent(event);
     if (mint) {
       // Save SFT mint and fetch its metadata
       continue;
     }
     break;
   case 'FTMintEvent':
   case 'FTBurnEvent':
     // Save FT supply mint or burn
     break;
   case 'NFTMintEvent':
     // Save minted NFT and fetch its metadata
     break;
 }
}

This code omits details on how these events are handled, but if you want to look at the full code, visit this link.

Using Chainhook also allows us to revert any of these actions in the event a block gets re-orged, and this also simplifies event consumption because we no longer need to communicate directly with the Stacks Blockchain API’s database to get fresh contract or token information.

A Better Token Experience

With this release, you should find the Token Metadata API a more reliable tool for providing you with token data on Stacks and you can now see metadata being served within just a couple seconds after a token is deployed on chain. For users quickly creating new tokens on projects like STX.CITY, this will help your tokens appear more quickly across all wallets, the Stacks Explorer, and more.

Get started with the Token Metadata API in Hiro documentation, and reach out to us on the #api channel under Hiro Developer Tools on Discord to share your feedback and get help.