Migrate curated Hiro docs into Stacks docs #1847
+2,110
−52
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| --- | ||
| description: Create, enable, and bulk-manage Hiro Chainhooks with the SDK. | ||
| --- | ||
|
|
||
| # Create Chainhooks | ||
|
|
||
| New chainhooks are created in a disabled state unless you set `enable_on_registration` to `true`. | ||
|
|
||
| ## Register a chainhook | ||
|
|
||
| ```ts | ||
| import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client'; | ||
|
|
||
| const client = new ChainhooksClient({ | ||
| baseUrl: CHAINHOOKS_BASE_URL.testnet, | ||
| apiKey: process.env.HIRO_API_KEY!, | ||
| }); | ||
|
|
||
| const chainhook = await client.registerChainhook({ | ||
| version: '1', | ||
| name: 'my-chainhook', | ||
| chain: 'stacks', | ||
| network: 'testnet', | ||
| filters: { | ||
| events: [ | ||
| { | ||
| type: 'contract_call', | ||
| contract_identifier: 'SP...XYZ.counter', | ||
| function_name: 'increment', | ||
| }, | ||
| ], | ||
| }, | ||
| action: { | ||
| type: 'http_post', | ||
| url: 'https://example.com/webhooks', | ||
| }, | ||
| options: { | ||
| decode_clarity_values: true, | ||
| enable_on_registration: true, | ||
| }, | ||
| }); | ||
|
|
||
| console.log('Chainhook UUID:', chainhook.uuid); | ||
| console.log('Enabled:', chainhook.status.enabled); | ||
| ``` | ||
|
|
||
| ## Enable or disable a single chainhook | ||
|
|
||
| ```ts | ||
| await client.enableChainhook('chainhook-uuid', true); | ||
| await client.enableChainhook('chainhook-uuid', false); | ||
| ``` | ||
|
|
||
| Successful enablement updates return HTTP `204 No Content`. | ||
|
|
||
| ## Bulk enable or disable chainhooks | ||
|
|
||
| ### By UUID | ||
|
|
||
| ```ts | ||
| await client.bulkEnableChainhooks({ | ||
| enabled: true, | ||
| filters: { | ||
| uuids: ['uuid-1', 'uuid-2', 'uuid-3'], | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ### By webhook URL | ||
|
|
||
| ```ts | ||
| await client.bulkEnableChainhooks({ | ||
| enabled: true, | ||
| filters: { | ||
| webhook_url: 'https://example.com/webhooks', | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ### By status | ||
|
|
||
| ```ts | ||
| await client.bulkEnableChainhooks({ | ||
| enabled: true, | ||
| filters: { | ||
| statuses: ['inactive'], | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ### Combined filters | ||
|
|
||
| ```ts | ||
| await client.bulkEnableChainhooks({ | ||
| enabled: false, | ||
| filters: { | ||
| webhook_url: 'https://old-server.com/webhooks', | ||
| statuses: ['active'], | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ## Next steps | ||
|
|
||
| - [Evaluate chainhooks](evaluate.md) | ||
| - [Filter reference](reference/filters.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| --- | ||
| description: Replay a block against a Hiro Chainhook to debug or backfill payloads. | ||
| --- | ||
|
|
||
| # Evaluate Chainhooks | ||
|
|
||
| The evaluate endpoint replays a single block against one of your registered chainhooks so you can test filters and webhook consumers without waiting for live traffic. | ||
|
|
||
| ## Supported inputs | ||
|
|
||
| | Method | Parameter | Example | | ||
| | --- | --- | --- | | ||
| | By height | `block_height` | `{ block_height: 100000 }` | | ||
| | By hash | `index_block_hash` | `{ index_block_hash: '0xa204...' }` | | ||
|
|
||
| ## Evaluate by block height | ||
|
|
||
| ```ts | ||
| import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client'; | ||
|
|
||
| const client = new ChainhooksClient({ | ||
| baseUrl: CHAINHOOKS_BASE_URL.testnet, | ||
| apiKey: process.env.HIRO_API_KEY!, | ||
| }); | ||
|
|
||
| await client.evaluateChainhook('chainhook-uuid', { | ||
| block_height: 100000, | ||
| }); | ||
| ``` | ||
|
|
||
| ## Evaluate by block hash | ||
|
|
||
| ```ts | ||
| await client.evaluateChainhook('chainhook-uuid', { | ||
| index_block_hash: '0xa204...', | ||
| }); | ||
| ``` | ||
|
|
||
| Successful evaluation returns HTTP `204 No Content`. If the block matches your filters, Chainhooks delivers the payload to your configured webhook URL. | ||
|
|
||
| ## Common use cases | ||
|
|
||
| | Use case | Description | | ||
| | --- | --- | | ||
| | Debug | Reproduce a block that should have triggered a delivery | | ||
| | Backfill | Replay historical activity after creating a new hook | | ||
| | Re-process | Test your webhook consumer after an infrastructure fix | | ||
|
|
||
| ## Next steps | ||
|
|
||
| - [Filter reference](reference/filters.md) | ||
| - [Payload anatomy](reference/payload-anatomy.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| --- | ||
| description: Frequently asked questions about Hiro Chainhooks. | ||
| --- | ||
|
|
||
| # FAQ | ||
|
|
||
| ## Versioning and migration | ||
|
|
||
| <details> | ||
| <summary>What happened to legacy Chainhooks v1?</summary> | ||
|
|
||
| Legacy Chainhooks v1 was deprecated on March 9, 2026. Use the current SDK and API flows documented in these build and reference sections for new work, and follow the [migration guide](migration.md) when moving older definitions forward. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>How do I migrate older chainhooks?</summary> | ||
|
|
||
| Use the [migration guide](migration.md) to map v1 predicates to the current event-based filter model, register a v2 hook, test deliveries, and then retire the legacy definition. | ||
|
|
||
| </details> | ||
|
|
||
| ## Operating questions | ||
|
|
||
| <details> | ||
| <summary>Can I edit an existing chainhook?</summary> | ||
|
|
||
| Yes. Use the SDK or API to update a chainhook definition in place. Start with the [update guide](update.md). | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Can I filter by multiple event types?</summary> | ||
|
|
||
| Yes. Add multiple entries to `filters.events`. A chainhook triggers when any event filter matches. See [filters](reference/filters.md#combining-filters). | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>What happens if my webhook endpoint is down?</summary> | ||
|
|
||
| Chainhooks retries deliveries and may pause the hook if the endpoint continues to fail. After you recover the consumer, use [evaluate](evaluate.md) to replay known blocks if needed. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Can I test chainhooks against historical blocks?</summary> | ||
|
|
||
| Yes. Use [evaluate](evaluate.md) to replay a specific block height or block hash. | ||
|
|
||
| </details> | ||
|
|
||
| ## Support | ||
|
|
||
| - Discord: `#chainhook` in [Stacks Discord](https://stacks.chat/) | ||
| - Product access and API keys: [Hiro Platform](https://platform.hiro.so) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| --- | ||
| description: List and fetch Hiro Chainhooks with the SDK. | ||
| --- | ||
|
|
||
| # Fetch Chainhooks | ||
|
|
||
| Use the SDK to paginate through your existing hooks or retrieve one hook by UUID. | ||
|
|
||
| ## List chainhooks | ||
|
|
||
| ```ts | ||
| import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client'; | ||
|
|
||
| const client = new ChainhooksClient({ | ||
| baseUrl: CHAINHOOKS_BASE_URL.testnet, | ||
| apiKey: process.env.HIRO_API_KEY!, | ||
| }); | ||
|
|
||
| const chainhooks = await client.getChainhooks(); | ||
|
|
||
| console.log('Total chainhooks:', chainhooks.total); | ||
| console.log('Results:', chainhooks.results.length); | ||
| console.log('Limit:', chainhooks.limit); | ||
| console.log('Offset:', chainhooks.offset); | ||
| ``` | ||
|
|
||
| ### Paginate results | ||
|
|
||
| ```ts | ||
| const chainhooks = await client.getChainhooks({ | ||
| limit: 50, | ||
| offset: 100, | ||
| }); | ||
| ``` | ||
|
|
||
| ## Fetch a single chainhook | ||
|
|
||
| ```ts | ||
| const chainhook = await client.getChainhook('be4ab3ed-b606-4fe0-97c4-6c0b1ac9b185'); | ||
| ``` | ||
|
|
||
| ## Next steps | ||
|
|
||
| - [Update chainhooks](update.md) | ||
| - [Create chainhooks](create.md) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noticed that the Bitcoin Indexer is omitted entirely, but the Hiro docs state that, while updates will cease, it's going to continue to be open sourced. Should we try to preserve that documentation somewhere rather than just not porting it over? I think it's worth thinking about that a bit more.
Same question for ordinals and runes. I think we should examine what's available in those GitHub repos before we decide that those docs should be omitted entirely.
Same question for the platform API. Are we no longer making that available? If we want to migrate all the Hiro docs and we're still going to allow people to interact with that API, I don't think we should cut it.