From 5c9c426fa50f9745fbb7ce7704ca81f61fabb3d3 Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Fri, 20 Mar 2026 12:37:23 -0700 Subject: [PATCH 1/4] Migrate curated Hiro docs into Stacks docs --- HIRO_DOCS_MIGRATION_MATRIX.md | 44 +++++ docs/build/SUMMARY.md | 25 +++ docs/build/chainhooks/create.md | 106 +++++++++++ docs/build/chainhooks/evaluate.md | 52 ++++++ docs/build/chainhooks/faq.md | 56 ++++++ docs/build/chainhooks/fetch.md | 45 +++++ docs/build/chainhooks/migration.md | 160 ++++++++++++++++ docs/build/chainhooks/overview.md | 33 ++++ docs/build/chainhooks/quickstart.md | 124 +++++++++++++ docs/build/chainhooks/reference/README.md | 11 ++ docs/build/chainhooks/reference/filters.md | 170 +++++++++++++++++ docs/build/chainhooks/reference/options.md | 52 ++++++ .../chainhooks/reference/payload-anatomy.md | 116 ++++++++++++ docs/build/chainhooks/secrets.md | 54 ++++++ docs/build/chainhooks/update.md | 62 +++++++ docs/build/contract-monitoring/README.md | 29 +++ .../build/contract-monitoring/create-alert.md | 93 ++++++++++ .../build/get-started/clarity-crash-course.md | 2 +- .../create-a-token/fungible-tokens.md | 2 +- .../create-a-token/non-fungible-tokens.md | 2 +- .../build/get-started/developer-quickstart.md | 6 +- docs/build/get-started/path-to-production.md | 6 +- .../build-a-decentralized-kickstarter.md | 19 ++ .../more-guides/build-an-nft-marketplace.md | 173 ++++++++++++++++++ docs/build/more-guides/no-loss-lottery.md | 105 +++++++++++ .../build/more-guides/using-clarity-values.md | 46 +++++ docs/build/stacks-devtools-catalog.md | 11 +- .../run-a-signer/how-to-monitor-signer.md | 4 + .../stacks-blockchain-api-architecture.svg | 42 +++++ docs/reference/SUMMARY.md | 59 ++++++ docs/reference/api/api-keys.md | 38 ++++ docs/reference/api/chainhooks-api/README.md | 35 ++++ docs/reference/api/chainhooks-api/usage.md | 139 ++++++++++++++ docs/reference/api/rate-limits.md | 24 +++ docs/reference/api/response-headers.md | 56 ++++++ .../api/signer-metrics-api/README.md | 26 +++ .../reference/api/signer-metrics-api/usage.md | 45 +++++ .../api/stacks-blockchain-api/README.md | 41 +++++ .../api/stacks-blockchain-api/architecture.md | 57 ++++++ .../stacks-blockchain-api/nonce-handling.md | 27 +++ .../api/stacks-blockchain-api/pagination.md | 52 ++++++ .../requesting-proofs.md | 11 ++ .../api/stacks-blockchain-api/usage.md | 46 +++++ docs/reference/api/stacks-node-rpc/README.md | 6 +- .../api/token-metadata-api/README.md | 30 +++ .../reference/api/token-metadata-api/usage.md | 45 +++++ 46 files changed, 2372 insertions(+), 15 deletions(-) create mode 100644 HIRO_DOCS_MIGRATION_MATRIX.md create mode 100644 docs/build/chainhooks/create.md create mode 100644 docs/build/chainhooks/evaluate.md create mode 100644 docs/build/chainhooks/faq.md create mode 100644 docs/build/chainhooks/fetch.md create mode 100644 docs/build/chainhooks/migration.md create mode 100644 docs/build/chainhooks/overview.md create mode 100644 docs/build/chainhooks/quickstart.md create mode 100644 docs/build/chainhooks/reference/README.md create mode 100644 docs/build/chainhooks/reference/filters.md create mode 100644 docs/build/chainhooks/reference/options.md create mode 100644 docs/build/chainhooks/reference/payload-anatomy.md create mode 100644 docs/build/chainhooks/secrets.md create mode 100644 docs/build/chainhooks/update.md create mode 100644 docs/build/contract-monitoring/README.md create mode 100644 docs/build/contract-monitoring/create-alert.md create mode 100644 docs/build/more-guides/build-a-decentralized-kickstarter.md create mode 100644 docs/build/more-guides/build-an-nft-marketplace.md create mode 100644 docs/build/more-guides/no-loss-lottery.md create mode 100644 docs/build/more-guides/using-clarity-values.md create mode 100644 docs/reference/.gitbook/assets/stacks-blockchain-api-architecture.svg create mode 100644 docs/reference/api/api-keys.md create mode 100644 docs/reference/api/chainhooks-api/README.md create mode 100644 docs/reference/api/chainhooks-api/usage.md create mode 100644 docs/reference/api/rate-limits.md create mode 100644 docs/reference/api/response-headers.md create mode 100644 docs/reference/api/signer-metrics-api/README.md create mode 100644 docs/reference/api/signer-metrics-api/usage.md create mode 100644 docs/reference/api/stacks-blockchain-api/README.md create mode 100644 docs/reference/api/stacks-blockchain-api/architecture.md create mode 100644 docs/reference/api/stacks-blockchain-api/nonce-handling.md create mode 100644 docs/reference/api/stacks-blockchain-api/pagination.md create mode 100644 docs/reference/api/stacks-blockchain-api/requesting-proofs.md create mode 100644 docs/reference/api/stacks-blockchain-api/usage.md create mode 100644 docs/reference/api/token-metadata-api/README.md create mode 100644 docs/reference/api/token-metadata-api/usage.md diff --git a/HIRO_DOCS_MIGRATION_MATRIX.md b/HIRO_DOCS_MIGRATION_MATRIX.md new file mode 100644 index 0000000000..2ee31194e6 --- /dev/null +++ b/HIRO_DOCS_MIGRATION_MATRIX.md @@ -0,0 +1,44 @@ +# Hiro Docs Migration Matrix + +This document is the gating artifact for the Hiro-to-Stacks docs migration. +No section should merge until the `recommendation` and `review` fields have +been confirmed by Alex, Rafa, and Hugo. + +Guiding rules: + +- Use first-class Stacks docs placement, not a temporary `/hiro` subtree. +- Keep English as the repo source of truth. +- Publish Spanish through GitBook Translations after English approval. +- Use GitBook built-in OpenAPI blocks for API references. +- Keep existing Hiro-hosted runtime endpoints on `hiro.so`. + +Review checklist for each `keep` section: + +- Accuracy and relevance confirmed +- Duplicate coverage on Stacks docs checked +- Legacy/deprecated wording removed +- Internal links updated to final Stacks paths +- GitBook preview checked +- GitBook admin dependency captured if an OpenAPI spec must be registered + + +| Section | Source | Locale(s) | Target | Space | Spec source / dependency | Recommendation | Cleanup required | Review | Notes | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| Stacks Blockchain API | `content/docs/en/apis/stacks-blockchain-api/` | `en` | `docs/reference/api/stacks-blockchain-api/` | `reference` | Existing GitBook spec id: `stacks-blockchain-api-dereferenced` | `keep` | Manual editorial pass, verify links, keep Hiro branding | `phase-1 baseline` | Implemented via PR #1845 pattern | +| Chainhooks tool docs | `content/docs/en/tools/chainhooks/` | `en` | `docs/build/chainhooks/` | `build` | n/a | `keep` | Exclude platform-UI pages, remove stale beta/platform wording, add Hiro branding | `pending review` | Ship SDK/reference docs only in initial pass | +| Chainhooks API | `content/docs/en/apis/chainhooks-api/` | `en` | `docs/reference/api/chainhooks-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `chainhooks-api` | `keep` | Migrate curated prose only, GitBook admin registration needed | `pending review` | No per-endpoint markdown in destination | +| Token Metadata API | `content/docs/en/apis/token-metadata-api/` | `en` | `docs/reference/api/token-metadata-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `token-metadata-api` | `keep` | Editorial cleanup, cross-link from token guides, GitBook admin registration needed | `pending review` | Keep Hiro branding and `hiro.so` examples | +| Signer Metrics API | `content/docs/en/apis/signer-metrics-api/` | `en` | `docs/reference/api/signer-metrics-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `signer-metrics-api` | `keep` | Editorial cleanup, cross-link from signer monitoring docs, GitBook admin registration needed | `pending review` | Keep as Hiro API in Stacks reference | +| Contract Monitoring | `content/docs/en/tools/contract-monitoring/` | `en` | `docs/build/contract-monitoring/` | `build` | n/a | `keep` | Confirm product relevance, add Hiro Platform note, remove stale references | `pending review` | Pair with Chainhooks cross-links | +| Shared API usage guides | `content/docs/en/resources/guides/{api-keys,rate-limits,response-headers}.mdx` | `en` | `docs/reference/api/` | `reference` | n/a | `keep` | Remove references to dropped/deferred APIs where needed | `pending review` | Shared Hiro API guidance | +| Selected build guides | `content/docs/en/resources/guides/{build-an-nft-marketplace,build-a-decentralized-kickstarter,no-loss-lottery,using-clarity-values}.mdx` | `en` | `docs/build/more-guides/` | `build` | n/a | `keep` | Deduplicate against existing Stacks guides, remove React-only UI scaffolding | `pending review` | Keep only guides that add real value | +| Node RPC positioning improvements | existing Stacks docs plus Hiro comparison copy | `en` | existing `docs/reference/api/stacks-node-rpc/README.md` | `reference` | Existing Node RPC spec flow remains unchanged | `keep` | Clarify RPC vs indexed Hiro API distinction only | `pending review` | No Node RPC section migration | +| Platform API | `content/docs/en/apis/platform-api/` | `en` | `docs/reference/api/platform-api/` | `reference` | Permanent public spec URL and product-owner approval required | `defer` | Validate product scope, auth model, and value on Stacks docs | `pending review` | Visible in inventory, not auto-approved | +| Hiro Archive docs | `content/docs/en/resources/archive/` | `en` | undecided | `operate` | n/a | `defer` | Review whether archive docs belong on Stacks docs at all | `pending review` | Keep out of main migration until explicitly approved | +| Docker / sync guides already covered on Stacks docs | `content/docs/en/resources/guides/{installing-docker,sync-a-bitcoin-node,sync-a-stacks-node}.mdx` | `en` | none by default | `operate` | n/a | `drop` | Only rescue unique details if review finds real gaps | `pending review` | Existing Stacks operate docs already cover this area | +| Ordinals API | `content/docs/en/apis/ordinals-api/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | +| Runes API | `content/docs/en/apis/runes-api/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | +| Bitcoin Indexer | `content/docs/en/tools/bitcoin-indexer/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | +| Existing Spanish source | `content/docs/es/**` | `es` | GitBook translated variants, not repo source | n/a | GitBook admin translation setup required | `defer` | Spanish Chainhooks source already contains translation corruption | `policy locked` | Do not bulk-import Spanish MDX | + + diff --git a/docs/build/SUMMARY.md b/docs/build/SUMMARY.md index 9426615189..61e86fac5e 100644 --- a/docs/build/SUMMARY.md +++ b/docs/build/SUMMARY.md @@ -81,6 +81,27 @@ * [Implementation](post-conditions/implementation.md) * [Examples](post-conditions/examples.md) +## Chainhooks + +* [Overview](chainhooks/overview.md) +* [Quickstart](chainhooks/quickstart.md) +* [Create Chainhooks](chainhooks/create.md) +* [Fetch Chainhooks](chainhooks/fetch.md) +* [Update Chainhooks](chainhooks/update.md) +* [Evaluate Chainhooks](chainhooks/evaluate.md) +* [Manage Secrets](chainhooks/secrets.md) +* [FAQ](chainhooks/faq.md) +* [Migration Guide](chainhooks/migration.md) +* [Reference](chainhooks/reference/README.md) + * [Filters](chainhooks/reference/filters.md) + * [Options](chainhooks/reference/options.md) + * [Payload Anatomy](chainhooks/reference/payload-anatomy.md) + +## Contract Monitoring + +* [Overview](contract-monitoring/README.md) +* [Create an Alert](contract-monitoring/create-alert.md) + ## More Guides * [sBTC](more-guides/sbtc/README.md) @@ -96,6 +117,10 @@ * [Verifying Bitcoin Transactions in Clarity](more-guides/verify-bitcoin-transactions-clarity/README.md) * [Creating a Bitcoin Transaction](more-guides/verify-bitcoin-transactions-clarity/creating-btc-tx.md) * [Parsing a Bitcoin Transaction](more-guides/verify-bitcoin-transactions-clarity/parsing-a-bitcoin-transaction.md) +* [Build an NFT Marketplace](more-guides/build-an-nft-marketplace.md) +* [Build a Decentralized Kickstarter](more-guides/build-a-decentralized-kickstarter.md) +* [No-Loss Lottery](more-guides/no-loss-lottery.md) +* [Using Clarity Values](more-guides/using-clarity-values.md) * [Bridging USDCx](more-guides/bridging-usdcx.md) * [c32check](more-guides/c32check.md) diff --git a/docs/build/chainhooks/create.md b/docs/build/chainhooks/create.md new file mode 100644 index 0000000000..57b02f96da --- /dev/null +++ b/docs/build/chainhooks/create.md @@ -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) diff --git a/docs/build/chainhooks/evaluate.md b/docs/build/chainhooks/evaluate.md new file mode 100644 index 0000000000..bf2442cf92 --- /dev/null +++ b/docs/build/chainhooks/evaluate.md @@ -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) diff --git a/docs/build/chainhooks/faq.md b/docs/build/chainhooks/faq.md new file mode 100644 index 0000000000..cd0a1efa5d --- /dev/null +++ b/docs/build/chainhooks/faq.md @@ -0,0 +1,56 @@ +--- +description: Frequently asked questions about Hiro Chainhooks. +--- + +# FAQ + +## Versioning and migration + +
+What happened to legacy Chainhooks v1? + +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. + +
+ +
+How do I migrate older chainhooks? + +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. + +
+ +## Operating questions + +
+Can I edit an existing chainhook? + +Yes. Use the SDK or API to update a chainhook definition in place. Start with the [update guide](update.md). + +
+ +
+Can I filter by multiple event types? + +Yes. Add multiple entries to `filters.events`. A chainhook triggers when any event filter matches. See [filters](reference/filters.md#combining-filters). + +
+ +
+What happens if my webhook endpoint is down? + +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. + +
+ +
+Can I test chainhooks against historical blocks? + +Yes. Use [evaluate](evaluate.md) to replay a specific block height or block hash. + +
+ +## Support + +- Discord: `#chainhook` in [Stacks Discord](https://stacks.chat/) +- Product access and API keys: [Hiro Platform](https://platform.hiro.so) diff --git a/docs/build/chainhooks/fetch.md b/docs/build/chainhooks/fetch.md new file mode 100644 index 0000000000..22577bee4f --- /dev/null +++ b/docs/build/chainhooks/fetch.md @@ -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) diff --git a/docs/build/chainhooks/migration.md b/docs/build/chainhooks/migration.md new file mode 100644 index 0000000000..64934c63c0 --- /dev/null +++ b/docs/build/chainhooks/migration.md @@ -0,0 +1,160 @@ +--- +description: Migrate legacy Hiro Chainhooks definitions to the current event-based format. +--- + +# Migration Guide + +{% hint style="warning" %} +Legacy Chainhooks v1 was deprecated on March 9, 2026. Keep migration work explicit and validate deliveries before removing legacy hooks. +{% endhint %} + +## What you'll do + +- Inventory your existing v1 chainhooks +- Map predicate-based definitions to the current event-based schema +- Register and validate v2 hooks +- Retire the legacy definitions after parity checks + +## Prerequisites + +- A Hiro API key with access to the legacy Platform API and current Chainhooks API +- A webhook destination you can inspect during migration +- Optional: `@hirosystems/chainhooks-client` if you want to use the SDK path + +{% stepper %} +{% step %} +#### List existing v1 chainhooks + +```ts +const response = await fetch( + `https://api.platform.hiro.so/v1/ext/${process.env.HIRO_API_KEY}/chainhooks`, + { + headers: { + 'content-type': 'application/json', + }, + } +); + +const chainhooks = await response.json(); +``` +{% endstep %} + +{% step %} +#### Map the legacy schema to the current schema + +| v1 | v2 | Notes | +| --- | --- | --- | +| `if_this.scope` | `filters.events[].type` | Replace scope and action pairs with a concrete event type | +| `if_this.actions` | `type` | For example, `transfer` becomes `*_transfer` | +| `then_that.http_post.url` | `action.url` | Delivery target stays the same | +| `networks.mainnet` | `network: "mainnet"` | Create one hook per network | +| `authorization_header` | Consumer secret | Rotate a consumer secret after registration | + +Legacy example: + +```json +{ + "name": "stx-transfers", + "networks": { + "mainnet": { + "if_this": { "scope": "stx_event", "actions": ["transfer"] }, + "then_that": { "http_post": { "url": "https://example.com/webhooks" } } + } + } +} +``` + +Current example: + +```json +{ + "version": "1", + "name": "stx-transfers", + "chain": "stacks", + "network": "mainnet", + "filters": { + "events": [{ "type": "stx_transfer" }] + }, + "action": { + "type": "http_post", + "url": "https://example.com/webhooks" + }, + "options": { + "decode_clarity_values": true, + "enable_on_registration": true + } +} +``` +{% endstep %} + +{% step %} +#### Register the new hook + +Use either the REST API or the SDK. + +{% tabs %} +{% tab title="REST API" %} +```ts +const response = await fetch('https://api.hiro.so/chainhooks/v1/me/', { + method: 'POST', + headers: { + 'x-api-key': process.env.HIRO_API_KEY!, + 'content-type': 'application/json', + }, + body: JSON.stringify(v2Chainhook), +}); +``` +{% endtab %} +{% tab title="SDK" %} +```ts +import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client'; + +const client = new ChainhooksClient({ + baseUrl: CHAINHOOKS_BASE_URL.mainnet, + apiKey: process.env.HIRO_API_KEY!, +}); + +const chainhook = await client.registerChainhook(v2Chainhook); +``` +{% endtab %} +{% endtabs %} +{% endstep %} + +{% step %} +#### Validate deliveries and retire the legacy hook + +Keep both versions active until you confirm delivery parity. + +```ts +const chainhook = await client.getChainhook(uuid); +console.log(chainhook.status.enabled); +``` + +Delete the legacy definition only after the new hook is producing the expected payloads: + +```ts +await fetch( + `https://api.platform.hiro.so/v1/ext/${process.env.HIRO_API_KEY}/chainhooks/${uuid}`, + { + method: 'DELETE', + headers: { + 'content-type': 'application/json', + }, + } +); +``` +{% endstep %} +{% endstepper %} + +## Common mappings + +| v1 | Typical actions | Current type | +| --- | --- | --- | +| `stx_event` | `transfer` | `stx_transfer` | +| `contract_call` | n/a | `contract_call` | +| `ft_event` | `transfer` | `ft_transfer` | +| `nft_event` | `transfer`, `mint` | `nft_transfer`, `nft_mint` | + +## Replay historical blocks + +The current Chainhooks model does not use a start-block field for backfills. Instead, use [evaluate](evaluate.md) to replay specific historical blocks through the same webhook destination. diff --git a/docs/build/chainhooks/overview.md b/docs/build/chainhooks/overview.md new file mode 100644 index 0000000000..eb23f13873 --- /dev/null +++ b/docs/build/chainhooks/overview.md @@ -0,0 +1,33 @@ +--- +description: Build event-driven Stacks apps with Hiro Chainhooks. +--- + +# Chainhooks + +{% hint style="info" %} +Hiro Chainhooks are documented on Stacks docs, but the service and runtime endpoints remain Hiro-hosted. Use your Hiro API key and `hiro.so` endpoints when creating or managing hooks. +{% endhint %} + +## Overview + +Chainhooks lets you subscribe to Stacks blockchain activity, filter for the exact events you care about, and deliver those events to your app in real time. + +The build-side docs here focus on the Chainhooks SDK and webhook payload model. For the REST API surface, see the Hiro API reference in the Stacks docs `reference` space. + +## Key features + +- Reorg-aware indexing that emits rollback events when the canonical chain changes +- Event filters for STX, FT, NFT, contract-call, contract-log, and system events +- Historical evaluation so you can replay known blocks against an existing hook +- Programmatic lifecycle management through the Chainhooks SDK + +## Recommended workflow + +1. Start with the [Quickstart](quickstart.md) to install the SDK and authenticate. +2. Use [Create](create.md) to register and enable hooks. +3. Review the [Reference](reference/README.md) pages before you finalize filters or payload handling. +4. Use [Evaluate](evaluate.md) to replay known blocks while testing your webhook consumer. + +{% hint style="success" %} +Need help with Chainhooks? Join `#chainhook` in [Stacks Discord](https://stacks.chat/). +{% endhint %} diff --git a/docs/build/chainhooks/quickstart.md b/docs/build/chainhooks/quickstart.md new file mode 100644 index 0000000000..07318f530a --- /dev/null +++ b/docs/build/chainhooks/quickstart.md @@ -0,0 +1,124 @@ +--- +description: Install the Hiro Chainhooks SDK and register your first chainhook. +--- + +# Quickstart + +## Overview + +The Chainhooks SDK provides a TypeScript and JavaScript client for creating, listing, updating, evaluating, and securing chainhooks programmatically. + +{% stepper %} +{% step %} +#### Install the SDK + +Choose your package manager: + +{% tabs %} +{% tab title="npm" %} +```bash +npm install @hirosystems/chainhooks-client +``` +{% endtab %} +{% tab title="yarn" %} +```bash +yarn add @hirosystems/chainhooks-client +``` +{% endtab %} +{% tab title="pnpm" %} +```bash +pnpm add @hirosystems/chainhooks-client +``` +{% endtab %} +{% tab title="bun" %} +```bash +bun add @hirosystems/chainhooks-client +``` +{% endtab %} +{% endtabs %} +{% endstep %} + +{% step %} +#### Configure the client + +Chainhooks uses Hiro-hosted endpoints and a Hiro API key: + +```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!, +}); +``` + +Use `CHAINHOOKS_BASE_URL.mainnet` for production traffic. + +| Network | Constant | URL | +| --- | --- | --- | +| Testnet | `CHAINHOOKS_BASE_URL.testnet` | `https://api.testnet.hiro.so` | +| Mainnet | `CHAINHOOKS_BASE_URL.mainnet` | `https://api.mainnet.hiro.so` | +{% endstep %} + +{% step %} +#### Register your first chainhook + +```ts +const chainhook = await client.registerChainhook({ + version: '1', + name: 'my-first-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('Created chainhook:', chainhook.uuid); +``` +{% endstep %} + +{% step %} +#### Store your API key safely + +Get your API key from [Hiro Platform](https://platform.hiro.so), then load it from environment variables instead of hard-coding it into your app. + +{% hint style="warning" %} +Never commit API keys to source control. Use environment variables or a secrets manager. +{% endhint %} +{% endstep %} +{% endstepper %} + +## SDK methods + +| Method | Description | +| --- | --- | +| `registerChainhook()` | Create a new chainhook | +| `getChainhooks()` | List your chainhooks with pagination | +| `getChainhook()` | Fetch a single chainhook by UUID | +| `updateChainhook()` | Modify an existing chainhook | +| `deleteChainhook()` | Remove a chainhook | +| `enableChainhook()` | Enable or disable a single chainhook | +| `bulkEnableChainhooks()` | Enable or disable many chainhooks at once | +| `evaluateChainhook()` | Replay a block against a chainhook | +| `rotateConsumerSecret()` | Rotate the webhook secret used for delivery validation | + +## Next steps + +- [Create chainhooks](create.md) +- [Fetch chainhooks](fetch.md) +- [Manage consumer secrets](secrets.md) diff --git a/docs/build/chainhooks/reference/README.md b/docs/build/chainhooks/reference/README.md new file mode 100644 index 0000000000..b6195cef91 --- /dev/null +++ b/docs/build/chainhooks/reference/README.md @@ -0,0 +1,11 @@ +--- +description: Reference material for Hiro Chainhooks filters, options, and payloads. +--- + +# Chainhooks Reference + +Use this section when you need to design filters, tune payload options, or parse webhook deliveries. + +- [Filters](filters.md) +- [Options](options.md) +- [Payload anatomy](payload-anatomy.md) diff --git a/docs/build/chainhooks/reference/filters.md b/docs/build/chainhooks/reference/filters.md new file mode 100644 index 0000000000..3714e5f88b --- /dev/null +++ b/docs/build/chainhooks/reference/filters.md @@ -0,0 +1,170 @@ +--- +description: Complete reference for Hiro Chainhooks filter types. +--- + +# Filters + +Filters determine which blockchain events trigger a chainhook. + +| Filter | When to use | +| --- | --- | +| `ft_event` | Catch all SIP-010 transfers, mints, and burns | +| `ft_transfer` | Track transfers for a specific fungible token | +| `ft_mint` | Track mint activity for a specific fungible token | +| `ft_burn` | Track burn activity for a specific fungible token | +| `nft_event` | Catch all SIP-009 transfers, mints, and burns | +| `nft_transfer` | Track transfers for a specific collection | +| `nft_mint` | Track mint activity for a specific collection | +| `nft_burn` | Track burn activity for a specific collection | +| `stx_event` | Capture all STX transfers, mints, and burns | +| `stx_transfer` | Track STX transfers, optionally by sender or receiver | +| `contract_deploy` | React to new contract deployments | +| `contract_call` | Observe contract function invocations | +| `contract_log` | Capture contract `print` output | +| `coinbase` | Track miner rewards | +| `tenure_change` | Track Proof-of-Transfer tenure changes | + +## FT events + +```json +{ "type": "ft_event" } +``` + +```json +{ + "type": "ft_transfer", + "asset_identifier": "SP...ABC.ft::usdc" +} +``` + +```json +{ + "type": "ft_transfer", + "asset_identifier": "SP...ABC.ft::usdc", + "sender": "SP...FROM" +} +``` + +```json +{ + "type": "ft_transfer", + "asset_identifier": "SP...ABC.ft::usdc", + "receiver": "SP...TO" +} +``` + +## NFT events + +```json +{ "type": "nft_event" } +``` + +```json +{ + "type": "nft_transfer", + "asset_identifier": "SP...COLL.nft::collectible" +} +``` + +```json +{ + "type": "nft_transfer", + "asset_identifier": "SP...COLL.nft::collectible", + "value": "u123" +} +``` + +## STX events + +```json +{ "type": "stx_event" } +``` + +```json +{ "type": "stx_transfer" } +``` + +```json +{ + "type": "stx_transfer", + "sender": "SP...SENDER" +} +``` + +```json +{ + "type": "stx_transfer", + "receiver": "SP...RECEIVER" +} +``` + +## Contract events + +```json +{ "type": "contract_deploy" } +``` + +```json +{ + "type": "contract_deploy", + "sender": "SP...DEPLOYER" +} +``` + +```json +{ "type": "contract_call" } +``` + +```json +{ + "type": "contract_call", + "contract_identifier": "SP...XYZ.counter", + "function_name": "increment" +} +``` + +```json +{ + "type": "contract_log", + "contract_identifier": "SP...XYZ.counter" +} +``` + +## System events + +```json +{ "type": "coinbase" } +``` + +```json +{ "type": "tenure_change" } +``` + +```json +{ + "type": "tenure_change", + "cause": "block_found" +} +``` + +## Combining filters + +A chainhook triggers when any entry in `filters.events` matches. + +```json +{ + "filters": { + "events": [ + { + "type": "ft_transfer", + "asset_identifier": "SP...ABC.token::diko" + }, + { + "type": "contract_call", + "contract_identifier": "SP...XYZ.counter", + "function_name": "increment" + } + ] + } +} +``` diff --git a/docs/build/chainhooks/reference/options.md b/docs/build/chainhooks/reference/options.md new file mode 100644 index 0000000000..a14a2abe38 --- /dev/null +++ b/docs/build/chainhooks/reference/options.md @@ -0,0 +1,52 @@ +--- +description: Complete reference for Hiro Chainhooks configuration options. +--- + +# Options + +Options control payload enrichment, activation, and expiration behavior. Omit the `options` field entirely if you want the defaults. + +{% hint style="info" %} +Boolean options default to `false`. Integer expiration options are optional. +{% endhint %} + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `decode_clarity_values` | boolean | `false` | Include decoded Clarity representations | +| `include_contract_abi` | boolean | `false` | Include ABI data on deployments | +| `include_contract_source_code` | boolean | `false` | Include source code on deployments | +| `include_post_conditions` | boolean | `false` | Include decoded post-conditions | +| `include_raw_transactions` | boolean | `false` | Include raw transaction hex | +| `include_block_metadata` | boolean | `false` | Include Stacks and Bitcoin block metadata | +| `include_block_signatures` | boolean | `false` | Include signer metadata | +| `enable_on_registration` | boolean | `false` | Activate the hook immediately | +| `expire_after_evaluations` | integer | none | Expire after N blocks are evaluated | +| `expire_after_occurrences` | integer | none | Expire after N matches | + +## Examples + +```json +{ + "options": { + "decode_clarity_values": true, + "include_post_conditions": true, + "enable_on_registration": true + } +} +``` + +```json +{ + "options": { + "expire_after_evaluations": 10000 + } +} +``` + +```json +{ + "options": { + "expire_after_occurrences": 250 + } +} +``` diff --git a/docs/build/chainhooks/reference/payload-anatomy.md b/docs/build/chainhooks/reference/payload-anatomy.md new file mode 100644 index 0000000000..cdab1bf7a0 --- /dev/null +++ b/docs/build/chainhooks/reference/payload-anatomy.md @@ -0,0 +1,116 @@ +--- +description: Understand the shape of Hiro Chainhooks webhook payloads. +--- + +# Payload Anatomy + +A Chainhooks delivery has two top-level sections: + +- `event`, which contains chain data +- `chainhook`, which identifies the hook that triggered + +## Basic structure + +```json +{ + "event": { + "apply": [], + "rollback": [], + "chain": "stacks", + "network": "mainnet" + }, + "chainhook": { + "name": "my-chainhook", + "uuid": "be4ab3ed-b606-4fe0-97c4-6c0b1ac9b185" + } +} +``` + +## Apply and rollback + +The `apply` array contains blocks being added to the canonical chain. The `rollback` array contains blocks being removed during a reorg. + +{% hint style="info" %} +Handle rollback events explicitly if your app stores derived state. Reorgs require you to reverse the effects of the rolled-back blocks. +{% endhint %} + +## Transaction metadata + +Each transaction includes metadata such as type, nonce, execution result, fee rate, sender address, and execution cost. + +```json +{ + "metadata": { + "type": "contract_call", + "nonce": 6689, + "status": "success", + "fee_rate": "3000", + "sender_address": "SPV2YDN4RZ506655KZK493YKM31JQPKJ9NN3QCX9" + } +} +``` + +## Operations + +Each transaction includes an `operations` array describing state changes. + +### Fee operation + +```json +{ + "type": "fee", + "status": "success", + "operation_identifier": { + "index": 0 + } +} +``` + +### Contract call operation + +```json +{ + "type": "contract_call", + "status": "success", + "metadata": { + "contract_identifier": "SP...token", + "function_name": "transfer", + "args": [ + { + "name": "amount", + "repr": "u10352515582", + "type": "uint" + } + ] + } +} +``` + +### Token transfer operation + +```json +{ + "type": "token_transfer", + "status": "success", + "operation_identifier": { + "index": 2 + } +} +``` + +### Contract log operation + +```json +{ + "type": "contract_log", + "status": "success", + "metadata": { + "topic": "print", + "contract_identifier": "SP...arkadiko-token" + } +} +``` + +{% hint style="info" %} +If `decode_clarity_values` is enabled, argument and result objects include `repr` and inferred `type` values in addition to the raw hex payload. +{% endhint %} diff --git a/docs/build/chainhooks/secrets.md b/docs/build/chainhooks/secrets.md new file mode 100644 index 0000000000..93ae07b298 --- /dev/null +++ b/docs/build/chainhooks/secrets.md @@ -0,0 +1,54 @@ +--- +description: Rotate and validate Hiro Chainhooks consumer secrets. +--- + +# Manage Secrets + +## What you'll learn + +- Create or rotate a Chainhooks consumer secret +- Validate incoming webhook requests with the `Authorization` header + +## Prerequisites + +- A Hiro API key +- A webhook consumer you control +- Node.js if you want to follow the Fastify example below + +## Rotate a consumer secret + +When you create a consumer secret, Chainhooks adds an `Authorization: Bearer ` header to each webhook attempt. + +```ts +import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client'; + +const client = new ChainhooksClient({ + baseUrl: CHAINHOOKS_BASE_URL.mainnet, + apiKey: process.env.HIRO_API_KEY!, +}); + +const secret = (await client.rotateConsumerSecret()).secret; +``` + +Store the secret securely and rotate it whenever you need to replace the shared token. + +## Validate webhook requests + +```ts +server.post('/webhook', async (request, reply) => { + if (!secret) { + reply.code(503).send({ error: 'consumer secret unavailable' }); + return; + } + + const authHeader = request.headers.authorization; + if (authHeader !== `Bearer ${secret}`) { + reply.code(401).send({ error: 'invalid consumer secret' }); + return; + } + + const event = request.body; + console.log(`received chainhook ${event.chainhook.uuid}`); + reply.code(204).send(); +}); +``` diff --git a/docs/build/chainhooks/update.md b/docs/build/chainhooks/update.md new file mode 100644 index 0000000000..c9d358594e --- /dev/null +++ b/docs/build/chainhooks/update.md @@ -0,0 +1,62 @@ +--- +description: Update Hiro Chainhooks without recreating them. +--- + +# Update Chainhooks + +Use `updateChainhook()` to adjust filters, webhook destinations, and options without replacing the hook. + +{% hint style="info" %} +This flow is documented from the SDK side. If you need the underlying API operations, use the Hiro Chainhooks API reference in the Stacks docs `reference` space. +{% endhint %} + +## Basic update + +```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.updateChainhook('chainhook-uuid', { + name: 'updated-chainhook-name', + filters: { + events: [{ type: 'ft_transfer', asset_identifier: 'SP...ABC.token::usdc' }], + }, +}); +``` + +## Add an event filter safely + +Fetch the current definition first so you do not accidentally overwrite existing filters: + +```ts +const current = await client.getChainhook(uuid); + +await client.updateChainhook(uuid, { + filters: { + events: [ + ...(current.definition.filters.events ?? []), + { type: 'contract_call', contract_identifier: 'SP...XYZ.counter' }, + ], + }, +}); +``` + +## Update multiple fields + +```ts +await client.updateChainhook('chainhook-uuid', { + name: 'updated-name', + filters: { events: [{ type: 'stx_transfer', sender: 'SP...SENDER' }] }, + action: { type: 'http_post', url: 'https://new-url.com/webhooks' }, + options: { decode_clarity_values: true }, +}); +``` + +## Next steps + +- [Fetch chainhooks](fetch.md) +- [Filter reference](reference/filters.md) diff --git a/docs/build/contract-monitoring/README.md b/docs/build/contract-monitoring/README.md new file mode 100644 index 0000000000..b2e2167532 --- /dev/null +++ b/docs/build/contract-monitoring/README.md @@ -0,0 +1,29 @@ +--- +description: Monitor Stacks contract activity with Hiro-hosted alerts. +--- + +# Contract Monitoring + +{% hint style="info" %} +Hiro Contract Monitoring lives in the Stacks build docs, but it still requires a Hiro Platform account and Hiro-hosted alert delivery. +{% endhint %} + +## Overview + +Contract Monitoring lets you watch contract-call activity and receive notifications when specific functions or argument patterns appear. + +## Key features + +- Real-time notifications for contract activity +- Email and webhook delivery options +- Filtering by function and argument values +- A lighter-weight alerting workflow than a full custom Chainhooks integration + +## When to use it + +- Use Contract Monitoring when you want fast, product-managed alerts for contract activity. +- Use [Chainhooks](../chainhooks/overview.md) when you need a programmable, event-driven indexing workflow. + +{% hint style="success" %} +Need help with Contract Monitoring? Join `#api` in [Stacks Discord](https://stacks.chat/). +{% endhint %} diff --git a/docs/build/contract-monitoring/create-alert.md b/docs/build/contract-monitoring/create-alert.md new file mode 100644 index 0000000000..7422ef352f --- /dev/null +++ b/docs/build/contract-monitoring/create-alert.md @@ -0,0 +1,93 @@ +--- +description: Create a Hiro Platform alert for Stacks contract activity. +--- + +# Create an Alert + +## What you'll do + +- Add a contract to Hiro Platform monitoring +- Configure alert conditions for contract calls +- Choose email and webhook delivery channels + +## Prerequisites + +- A public contract on Stacks mainnet +- A [Hiro Platform](https://platform.hiro.so) account + +{% stepper %} +{% step %} +#### Open Contract Monitoring + +Sign in to [Hiro Platform](https://platform.hiro.so) and open the **Monitor** tab. +{% endstep %} + +{% step %} +#### Add a contract + +Add a contract either by entering the contract principal and name directly or by connecting a wallet to inspect your deployment history. +{% endstep %} + +{% step %} +#### Review activity + +After the contract is added, you can inspect recent transaction activity and open the alert creation flow. +{% endstep %} + +{% step %} +#### Configure the alert + +You can filter alerts by: + +- Function name +- Function arguments +- Caller address + +This works well for owner actions, mint and burn functions, or operational contract calls you want to watch closely. +{% endstep %} + +{% step %} +#### Choose delivery channels + +You can send alerts to: + +- Email +- A webhook endpoint + +You can enable both channels for the same alert. +{% endstep %} +{% endstepper %} + +## Webhook payload shape + +```json +{ + "tx_id": "0xa7f511b3f379efef6fe71d0de57712ed13a89c5b6e24dd049eb2cc9a7c24fcb5", + "nonce": 5, + "sender_address": "SP2W9QYAHJNS7YTQY9EK2MSTQGX9E2NDMV766JP9Z", + "tx_status": "pending", + "tx_type": "contract_call", + "contract_call": { + "contract_id": "SPHW0EJK5KPDMK03ZX792EMP0Q5J3A39ZMTVZZCY.sample-contract", + "function_name": "donate", + "function_signature": "(define-public (donate (amount uint)))", + "function_args": [ + { + "hex": "0x01000000000000000000000000002dc6c0", + "repr": "u3000000", + "name": "amount", + "type": "uint" + } + ] + } +} +``` + +{% hint style="info" %} +`tx_status` is `pending` for monitor alerts. These notifications are sent when the transaction reaches the mempool, not after confirmation. +{% endhint %} + +## Next steps + +- [Chainhooks overview](../chainhooks/overview.md) +- [Hiro Platform](https://platform.hiro.so) diff --git a/docs/build/get-started/clarity-crash-course.md b/docs/build/get-started/clarity-crash-course.md index 983c5dd94a..4894613878 100644 --- a/docs/build/get-started/clarity-crash-course.md +++ b/docs/build/get-started/clarity-crash-course.md @@ -360,7 +360,7 @@ The [Contract Monitoring](https://platform.hiro.so/contract-monitoring) features Chainhooks -[Chainhooks](https://docs.hiro.so/tools/chainhook) indexes Stacks & Bitcoin data, exposes queryable APIs, tracks contract state and transactions. You simply describe your chainhook filters and consume webhooks. The service handles queueing, retries, tier limits, observability, and parity between testnet and mainnet. +[Chainhooks](../chainhooks/overview.md) indexes Stacks data and delivers filtered events to your application through webhooks. You describe the filters, configure the destination, and consume reorg-aware payloads without running your own indexing stack. diff --git a/docs/build/get-started/create-a-token/fungible-tokens.md b/docs/build/get-started/create-a-token/fungible-tokens.md index afdb165c46..1e8abf25fc 100644 --- a/docs/build/get-started/create-a-token/fungible-tokens.md +++ b/docs/build/get-started/create-a-token/fungible-tokens.md @@ -240,7 +240,7 @@ If you plan on updating your token's metadata in the future, you should definite ;; ... ``` -Hiro’s [Token Metadata API](https://www.hiro.so/token-metadata-api) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing token’s metadata. +Hiro’s [Token Metadata API](../../../reference/api/token-metadata-api/README.md) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing token’s metadata. If your token contract did not implement this print event, you could use the helper contract below to invoke a function that'll emit the same print event notification. Just invoke the `ft-metadata-update-notify` function of this contract below: diff --git a/docs/build/get-started/create-a-token/non-fungible-tokens.md b/docs/build/get-started/create-a-token/non-fungible-tokens.md index ef064e622e..5ca055eb8f 100644 --- a/docs/build/get-started/create-a-token/non-fungible-tokens.md +++ b/docs/build/get-started/create-a-token/non-fungible-tokens.md @@ -186,7 +186,7 @@ If you plan on updating your NFT's metadata in the future, you should definitely ;; ... -Hiro’s [Token Metadata API](https://www.hiro.so/token-metadata-api) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing NFT’s metadata. +Hiro’s [Token Metadata API](../../../reference/api/token-metadata-api/README.md) watches for that specific print event (specifically the notification of "token-metadata-update") on the network and auto-updates the API’s database to reflect a change in the existing NFT’s metadata. If your NFT contract did not implement this print event, you could use the helper contract below to invoke a function that'll emit the same print event notification. Just invoke the `nft-metadata-update-notify` function of this contract below: diff --git a/docs/build/get-started/developer-quickstart.md b/docs/build/get-started/developer-quickstart.md index 6fca69ff15..8502c4d4b0 100644 --- a/docs/build/get-started/developer-quickstart.md +++ b/docs/build/get-started/developer-quickstart.md @@ -378,7 +378,7 @@ Emitting events on Stacks serves several critical purposes: 1. **Transparency**: Events provide an on-chain record of actions and transactions, ensuring transparency. 2. **Notification**: They serve as a signal mechanism for users and external applications, notifying them of specific occurrences on Stacks. 3. **State Tracking**: Developers can use events to track changes in the state of smart contracts without querying the chain continuously. -4. **Efficient Data Handling**: By emitting events, webhook services, such as Hiro's [Chainhooks](https://docs.hiro.so/en/tools/chainhooks), can filter and handle relevant data efficiently, reducing the on-chain computation load. +4. **Efficient Data Handling**: By emitting events, webhook services, such as Hiro's [Chainhooks](../chainhooks/overview.md), can filter and handle relevant data efficiently, reducing the on-chain computation load. @@ -811,7 +811,7 @@ function App() { {% hint style="info" %} -For the complete set of available API endpoints for the Stacks network, check out the [Hiro docs](https://docs.hiro.so/). But first create an API key from the [Hiro Platform](https://platform.hiro.so/) to determine your API rate plan. +For indexed Stacks API endpoints, see the [Stacks Blockchain API reference](../../reference/api/stacks-blockchain-api/README.md). Create an API key in [Hiro Platform](https://platform.hiro.so/) and review [API Keys](../../reference/api/api-keys.md) and [Rate Limits](../../reference/api/rate-limits.md) before you ship to production. {% endhint %} {% endstep %} {% endstepper %} @@ -825,7 +825,7 @@ And that's it, you've successfully created an sBTC powered Clarity smart contrac This is just the beginning. There are many ways we can improve upon this app. Here are some suggestions for you to extend the functionality of this app: * Deploy to mainnet and share your project with the community -* Use [Chainhooks](https://docs.hiro.so/en/tools/chainhooks) to index emitted events from the contract +* Use [Chainhooks](../chainhooks/overview.md) to index emitted events from the contract * Integrate the [`sbtc`](../more-guides/sbtc/bridging-bitcoin/) library so users can directly bridge their BTC to sBTC in-app * Utilize SIP-009 NFTs to uniquely identify each message for each author diff --git a/docs/build/get-started/path-to-production.md b/docs/build/get-started/path-to-production.md index 7d8c118202..401babf533 100644 --- a/docs/build/get-started/path-to-production.md +++ b/docs/build/get-started/path-to-production.md @@ -39,7 +39,7 @@ To ensure your app or smart contract is production-ready, we pulled together a s {% step %} ### Specific Clarity/Stacks.js best practices -* [**Post-conditions**](/broken/pages/0KPrPPKItMGZZL2u4tiF): Post conditions are an additional safety feature built into the Stacks chain itself that help to protect end users. Rather than being a function of Clarity smart contracts, they are implemented on the client side and meant to be an additional failsafe against malicious contracts. +* [**Post-conditions**](../post-conditions/overview.md): Post conditions are an additional safety feature built into the Stacks chain itself that help to protect end users. Rather than being a function of Clarity smart contracts, they are implemented on the client side and meant to be an additional failsafe against malicious contracts. * [**Usage of `tx-sender` vs `contract-caller`**](https://www.setzeus.com/public-blog-post/clarity-carefully-tx-sender) : The usage of `tx-sender` versus another Clarity keyword, `contract-caller` , is always a tricky concept because it determines who actually initiated the transaction versus who invoked the current function. Both of them can have certain implications on security based on the context of your code. * Write meaningful error codes to improve error handling * Adopt a modular contract design approach @@ -68,7 +68,7 @@ While contracts are immutable once deployed, you can deploy new versions of your ### Implement comprehensive testing tools * [**Unit tests**](../clarinet/testing-with-clarinet-sdk.md) -* [**Fuzzing**](/broken/pages/h06OJd7RHqUk2Dq7DHwJ) +* [**Fuzzing**](../rendezvous/overview.md) * [**Devnet**](../clarinet/local-blockchain-development.md) {% endstep %} @@ -131,7 +131,7 @@ To ensure a smooth deployment process, adopt lean DevOps strategies, which inclu {% step %} ### Monitor contract activity -* [**Chainhooks**](https://docs.hiro.so/en/tools/chainhooks): Chainhooks is a webhook service for the Stacks blockchain that lets you register event streams and define precise filters to capture on-chain data as it happens. +* [**Chainhooks**](../chainhooks/overview.md): Chainhooks is a webhook service for the Stacks blockchain that lets you register event streams and define precise filters to capture on-chain data as it happens. {% endstep %} {% step %} diff --git a/docs/build/more-guides/build-a-decentralized-kickstarter.md b/docs/build/more-guides/build-a-decentralized-kickstarter.md new file mode 100644 index 0000000000..859e16e1be --- /dev/null +++ b/docs/build/more-guides/build-a-decentralized-kickstarter.md @@ -0,0 +1,19 @@ +--- +description: Editorial placeholder for a Hiro guide that needs content review before publication. +--- + +# Build a Decentralized Kickstarter + +{% hint style="warning" %} +The English Hiro source page for this guide currently duplicates the NFT marketplace tutorial instead of documenting a crowdfunding flow. The page is being carried into Stacks docs as a tracked placeholder so it can be replaced with reviewed content rather than silently dropped. +{% endhint %} + +## Current status + +- The original Hiro page title and description describe a decentralized Kickstarter guide. +- The body content in the source repo is an NFT marketplace tutorial duplicate. +- Publishing that duplicate as-is would introduce inaccurate guidance. + +## Recommended next step + +Replace this placeholder with a reviewed crowdfunding example before treating the guide as canonical. diff --git a/docs/build/more-guides/build-an-nft-marketplace.md b/docs/build/more-guides/build-an-nft-marketplace.md new file mode 100644 index 0000000000..31844beff6 --- /dev/null +++ b/docs/build/more-guides/build-an-nft-marketplace.md @@ -0,0 +1,173 @@ +--- +description: Build an NFT marketplace in Clarity with listing, cancellation, and fulfillment flows. +--- + +# Build an NFT Marketplace + +This guide walks through a marketplace contract that lets users list NFTs for sale, cancel listings, and fulfill purchases with either STX or a SIP-010 token. + +## What you'll build + +- Error handling for listing and purchase flows +- Persistent listing storage +- Asset whitelisting +- Purchase fulfillment with STX or fungible tokens + +## Define error constants + +```clarity +(define-constant ERR_EXPIRY_IN_PAST (err u1000)) +(define-constant ERR_PRICE_ZERO (err u1001)) +(define-constant ERR_UNKNOWN_LISTING (err u2000)) +(define-constant ERR_UNAUTHORISED (err u2001)) +(define-constant ERR_LISTING_EXPIRED (err u2002)) +(define-constant ERR_NFT_ASSET_MISMATCH (err u2003)) +(define-constant ERR_PAYMENT_ASSET_MISMATCH (err u2004)) +(define-constant ERR_MAKER_TAKER_EQUAL (err u2005)) +(define-constant ERR_UNINTENDED_TAKER (err u2006)) +(define-constant ERR_ASSET_CONTRACT_NOT_WHITELISTED (err u2007)) +(define-constant ERR_PAYMENT_CONTRACT_NOT_WHITELISTED (err u2008)) +``` + +## Create listing storage + +```clarity +(define-map listings + uint + { + maker: principal, + taker: (optional principal), + token-id: uint, + nft-asset-contract: principal, + expiry: uint, + price: uint, + payment-asset-contract: (optional principal) + } +) + +(define-data-var listing-nonce uint u0) +``` + +## List an asset + +```clarity +(define-public (list-asset + (nft-asset-contract ) + (nft-asset { + taker: (optional principal), + token-id: uint, + expiry: uint, + price: uint, + payment-asset-contract: (optional principal) + }) +) + (let ((listing-id (var-get listing-nonce))) + (asserts! (is-whitelisted (contract-of nft-asset-contract)) ERR_ASSET_CONTRACT_NOT_WHITELISTED) + (asserts! (> (get expiry nft-asset) block-height) ERR_EXPIRY_IN_PAST) + (asserts! (> (get price nft-asset) u0) ERR_PRICE_ZERO) + (asserts! (match (get payment-asset-contract nft-asset) + payment-asset + (is-whitelisted payment-asset) + true + ) ERR_PAYMENT_CONTRACT_NOT_WHITELISTED) + (try! (transfer-nft + nft-asset-contract + (get token-id nft-asset) + tx-sender + (as-contract tx-sender) + )) + (map-set listings listing-id (merge + { maker: tx-sender, nft-asset-contract: (contract-of nft-asset-contract) } + nft-asset + )) + (var-set listing-nonce (+ listing-id u1)) + (ok listing-id) + ) +) +``` + +## Read and cancel listings + +```clarity +(define-read-only (get-listing (listing-id uint)) + (map-get? listings listing-id) +) +``` + +```clarity +(define-public (cancel-listing (listing-id uint) (nft-asset-contract )) + (let ( + (listing (unwrap! (map-get? listings listing-id) ERR_UNKNOWN_LISTING)) + (maker (get maker listing)) + ) + (asserts! (is-eq maker tx-sender) ERR_UNAUTHORISED) + (asserts! (is-eq + (get nft-asset-contract listing) + (contract-of nft-asset-contract) + ) ERR_NFT_ASSET_MISMATCH) + (map-delete listings listing-id) + (as-contract (transfer-nft nft-asset-contract (get token-id listing) tx-sender maker)) + ) +) +``` + +## Whitelist asset contracts + +```clarity +(define-map whitelisted-asset-contracts principal bool) + +(define-read-only (is-whitelisted (asset-contract principal)) + (default-to false (map-get? whitelisted-asset-contracts asset-contract)) +) + +(define-public (set-whitelisted (asset-contract principal) (whitelisted bool)) + (begin + (asserts! (is-eq contract-owner tx-sender) ERR_UNAUTHORISED) + (ok (map-set whitelisted-asset-contracts asset-contract whitelisted)) + ) +) +``` + +## Fulfill purchases + +### With STX + +```clarity +(define-public (fulfil-listing-stx (listing-id uint) (nft-asset-contract )) + (let ( + (listing (unwrap! (map-get? listings listing-id) ERR_UNKNOWN_LISTING)) + (taker tx-sender) + ) + (try! (assert-can-fulfil (contract-of nft-asset-contract) none listing)) + (try! (as-contract (transfer-nft nft-asset-contract (get token-id listing) tx-sender taker))) + (try! (stx-transfer? (get price listing) taker (get maker listing))) + (map-delete listings listing-id) + (ok listing-id) + ) +) +``` + +### With SIP-010 tokens + +```clarity +(define-public (fulfil-listing-ft + (listing-id uint) + (nft-asset-contract ) + (payment-asset-contract ) +) + (let ( + (listing (unwrap! (map-get? listings listing-id) ERR_UNKNOWN_LISTING)) + (taker tx-sender) + ) + (try! (assert-can-fulfil + (contract-of nft-asset-contract) + (some (contract-of payment-asset-contract)) + listing + )) + (try! (as-contract (transfer-nft nft-asset-contract (get token-id listing) tx-sender taker))) + (try! (transfer-ft payment-asset-contract (get price listing) taker (get maker listing))) + (map-delete listings listing-id) + (ok listing-id) + ) +) +``` diff --git a/docs/build/more-guides/no-loss-lottery.md b/docs/build/more-guides/no-loss-lottery.md new file mode 100644 index 0000000000..f639ce7cd8 --- /dev/null +++ b/docs/build/more-guides/no-loss-lottery.md @@ -0,0 +1,105 @@ +--- +description: Build a no-loss lottery pattern in Clarity using pooled deposits and reward distribution. +--- + +# No-Loss Lottery + +{% hint style="warning" %} +This migrated example comes from older Hiro docs and references CityCoins-era contracts. Treat it as a historical pattern, not a production-ready integration. +{% endhint %} + +This pattern shows how a contract can pool deposits, issue NFT tickets, select a winner, and distribute yield without risking a participant's principal deposit. + +## Core state + +```clarity +(define-constant OWNER tx-sender) +(define-constant ERR_UNAUTHORIZED (err u101000)) + +(define-data-var lotteryPool uint u0) +(define-data-var totalYield uint u0) +(define-data-var ticketCounter uint u0) +``` + +## Track participants and tickets + +```clarity +(define-map Participants + { participant: principal } + { ticketId: uint, amount: uint, cycle: uint, ticketExpirationAtCycle: uint, isWinner: bool } +) + +(define-map Tickets + { ticketId: uint } + { owner: principal } +) + +(define-non-fungible-token LotteryTicket uint) +``` + +## Enter the lottery + +```clarity +(define-public (roll-the-dice (cityName (string-ascii 10)) (amount uint) (lockPeriod (optional uint))) + (let + ( + (ticketId (+ (var-get ticketCounter) u1)) + (actualLockPeriod (default-to u1 lockPeriod)) + (rewardCycle (+ (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd007-citycoin-stacking get-current-reward-cycle) u1)) + ) + (begin + (try! (contract-call? 'SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.miamicoin-token-v2 transfer amount tx-sender (as-contract tx-sender) none)) + (try! (nft-mint? LotteryTicket ticketId tx-sender)) + (map-insert Participants { participant: tx-sender } { ticketId: ticketId, amount: amount, cycle: rewardCycle, ticketExpirationAtCycle: (+ rewardCycle actualLockPeriod), isWinner: false }) + (map-set Tickets { ticketId: ticketId } { owner: tx-sender }) + (var-set lotteryPool (+ (var-get lotteryPool) amount)) + (var-set ticketCounter (+ (var-get ticketCounter) u1)) + (ok ticketId) + ) + ) +) +``` + +## Select a winner + +```clarity +(define-private (select-winner) + (match (contract-call? 'SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11.citycoin-vrf-v2 get-save-rnd (- block-height u1)) randomTicketNumber + (let + ( + (ticketCount (var-get ticketCounter)) + (winningTicketId (mod randomTicketNumber ticketCount)) + (winner (unwrap! (get-ticket winningTicketId) (err u404))) + (owner (get owner winner)) + (participant (unwrap! (get-participant owner) (err u404))) + ) + (map-set Participants { participant: owner } + { ticketId: winningTicketId, amount: (get amount participant), cycle: (get cycle participant), ticketExpirationAtCycle: (get ticketExpirationAtCycle participant), isWinner: true }) + (ok owner) + ) + selectionError (err selectionError) + ) +) +``` + +## Claim and distribute rewards + +```clarity +(define-public (claim-rewards (cityName (string-ascii 10)) (cycle uint)) + (let + ( + (cityId (unwrap-panic (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd004-city-registry get-city-id cityName))) + (cycleAmount (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd002-treasury-mia-stacking get-balance-stx)) + ) + (if (is-eq cityName "mia") + (try! (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd011-stacking-payouts send-stacking-reward-mia cycle cycleAmount)) + (try! (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd011-stacking-payouts send-stacking-reward-nyc cycle cycleAmount)) + ) + (as-contract (contract-call? 'SP8A9HZ3PKST0S42VM9523Z9NV42SZ026V4K39WH.ccd007-citycoin-stacking claim-stacking-reward cityName cycle)) + ) +) + +(define-public (distribute-rewards) + (select-winner) +) +``` diff --git a/docs/build/more-guides/using-clarity-values.md b/docs/build/more-guides/using-clarity-values.md new file mode 100644 index 0000000000..1ea2fb7d24 --- /dev/null +++ b/docs/build/more-guides/using-clarity-values.md @@ -0,0 +1,46 @@ +--- +description: Serialize and deserialize Clarity values when calling Hiro-hosted APIs. +--- + +# Using Clarity Values + +Some API endpoints, such as read-only contract calls, expect serialized Clarity values as input and return serialized Clarity values in response. `@stacks/transactions` gives you the helpers you need to encode and decode those values cleanly. + +## Example + +```ts +import { + Configuration, + SmartContractsApiInterface, + SmartContractsApi, + ReadOnlyFunctionSuccessResponse, +} from '@stacks/blockchain-api-client'; +import { uintCV, UIntCV, cvToHex, hexToCV, ClarityType } from '@stacks/transactions'; + +(async () => { + const apiConfig: Configuration = new Configuration({ + fetchApi: fetch, + basePath: 'https://api.testnet.hiro.so', + }); + + const contractsApi: SmartContractsApiInterface = new SmartContractsApi(apiConfig); + const principal = 'ST000000000000000000002AMW42H'; + const rewardCycle: UIntCV = uintCV(22); + + const fnCall: ReadOnlyFunctionSuccessResponse = await contractsApi.callReadOnlyFunction({ + contractAddress: principal, + contractName: 'pox', + functionName: 'is-pox-active', + readOnlyFunctionArgs: { + sender: principal, + arguments: [cvToHex(rewardCycle)], + }, + }); + + console.log({ + status: fnCall.okay, + result: fnCall.result, + representation: hexToCV(fnCall.result).type === ClarityType.BoolTrue, + }); +})().catch(console.error); +``` diff --git a/docs/build/stacks-devtools-catalog.md b/docs/build/stacks-devtools-catalog.md index 6475c7cb58..e47faa9902 100644 --- a/docs/build/stacks-devtools-catalog.md +++ b/docs/build/stacks-devtools-catalog.md @@ -57,8 +57,8 @@ Official Stacks devtools are built and maintained by either **Stacks Labs** or * ### Indexing & Data * [**Stacks Blockchain APIs**](https://github.com/hirosystems/stacks-blockchain-api) **\[Hiro]** – High-performance APIs to query blockchain data, explore blocks, transactions, smart contracts, and more, without running your own node. -* [**Token Metadata APIs**](https://github.com/hirosystems/token-metadata-api) **\[Hiro] -** Fetch metadata for every token on Stacks and effortlessly put tokens into your app. Verify and display tokens in your app, for everything from DeFi to NFTs. -* [**Chainhooks**](https://github.com/hirosystems/chainhook) **\[Hiro]** – A notification service for dApps that triggers webhooks on specific blockchain events, helping you respond to transactions, contract calls, and chain reorganizations in real time. +* [**Token Metadata APIs**](https://github.com/stx-labs/token-metadata-api) **\[Hiro] -** Fetch metadata for every token on Stacks and effortlessly put tokens into your app. Verify and display tokens in your app, for everything from DeFi to NFTs. +* [**Chainhooks**](chainhooks/overview.md) **\[Hiro]** – A notification service for dApps that triggers webhooks on specific blockchain events, helping you respond to transactions, contract calls, and chain reorganizations in real time.
@@ -68,7 +68,7 @@ Official Stacks devtools are built and maintained by either **Stacks Labs** or * * [**BNS**](https://www.bnsv2.com/docs) - [API](https://github.com/Strata-Labs/bnsv2-api) and [SDK](https://github.com/Strata-Labs/bns-v2-sdk) documentation for BNSv2, covering how to programmatically register, resolve, and manage Bitcoin Name System identities using on-chain contracts and developer libraries. * [**Signal21**](https://signal21.io/) - Data analytics platform for the Bitcoin Economy: on-chain visibility into Bitcoin L1, L2s, and Dapps. * [**Velar Devtools**](https://docs.velar.com/velar/developers) - Velar SDK and APIs allowing developers to implement token swaps, manage liquidity, and interact with the Velar DEX/DeFi ecosystem. -* [**Bitcoin Indexer**](https://github.com/hirosystems/bitcoin-indexer) **-** Index Bitcoin meta-protocols like Ordinals, BRC-20, and Runes. +* **Bitcoin Indexer** **\[Deprecated]** - Deprecated in March 2026 and not part of the active Stacks docs migration. * [**Bitflow Devtools**](https://docs.bitflow.finance/bitflow-documentation/developers/overview) - Documentation on Bitflow's SDKs and contracts for interacting with Bitflow's DeFi ecosystem. * [**x402-Stacks**](https://github.com/tony1908/x402Stacks) - A TypeScript library for implementing the x402 payment protocol on Stacks blockchain. * [**StacksAgent MCP**](https://github.com/kai-builder/stacksagent-mcp) - A Model Context Protocol (MCP) server that enables Claude Desktop to interact with the Stacks blockchain. @@ -95,7 +95,7 @@ Official Stacks devtools are built and maintained by either **Stacks Labs** or * * [**Sign-In with Stacks**](https://github.com/pradel/sign-in-with-stacks/) - A library for creating and verifying Sign-In with Stacks messages. * [**sBTC Pay**](https://github.com/STX-CITY/sbtc-pay) - A complete "Stripe for sBTC" payment gateway that enables businesses to easily accept Bitcoin payments via sBTC on Stacks blockchain. * [**Bolt Protocol**](https://github.com/ronoel/bolt-protocol) - Bolt Protocol is a next-generation framework designed to enable near-instant transactions on the Bitcoin network and enable users to pay fees directly in sBTC. -* [**Multisig CLI**](https://github.com/hirosystems/multisig-cli/) - Command line utility written in NodeJS for creating and signing Stacks multisig transactions with a Ledger device +* [**Multisig CLI**](https://github.com/stx-labs/multisig-cli/) - Command line utility written in NodeJS for creating and signing Stacks multisig transactions with a Ledger device * [**Stacks Address Generator**](https://github.com/ECBSJ/stacks-address-generator) - Simple web app to quickly generate Stacks addresses * [**Stacks Electrum Plugin**](https://github.com/rafa-stacks/stacks-electrum-plugin) - An Electrum wallet plugin for composing Stacks blockchain transactions via Bitcoin `OP_RETURN` encoding, as defined in SIP-001 and SIP-007. @@ -107,6 +107,7 @@ Official Stacks devtools are built and maintained by either **Stacks Labs** or * * [**Explorer**](https://github.com/stx-labs/explorer) **\[StacksLabs] -** Explore transactions and accounts on the Stacks blockchain. Clone any contract and experiment in your browser with the Explorer sandbox. * [**Platform**](https://www.hiro.so/platform) **\[Hiro]** – Manage API keys, Chainhooks, and analyze onchain data streams in one command center. +* [**Contract Monitoring**](contract-monitoring/README.md) **\[Hiro]** – Configure indexed contract alerts in Hiro Platform and route them to email or Slack.
@@ -120,7 +121,7 @@ Official Stacks devtools are built and maintained by either **Stacks Labs** or * ### Docs & Standards -* [**Hiro Docs**](https://docs.hiro.so/) **\[Hiro]** - Official Hiro developer documentation website. +* [**Hiro APIs on Stacks Docs**](../reference/api/stacks-blockchain-api/README.md) **\[Hiro]** - Hiro-hosted APIs are being consolidated into the Stacks docs experience. * [**Stacks Docs**](https://docs.stacks.co/) **\[StacksLabs]** - Official Stacks developer documentation website. * [**SIPs**](https://github.com/stacksgov/sips) - Community-submitted Stacks Improvement Proposals (SIPs). diff --git a/docs/operate/run-a-signer/how-to-monitor-signer.md b/docs/operate/run-a-signer/how-to-monitor-signer.md index 8bfee6061b..ce099c3640 100644 --- a/docs/operate/run-a-signer/how-to-monitor-signer.md +++ b/docs/operate/run-a-signer/how-to-monitor-signer.md @@ -1,5 +1,9 @@ # How to Monitor Signer +{% hint style="info" %} +For Hiro-hosted, indexed signer participation data, see the [Signer Metrics API reference](../../reference/api/signer-metrics-api/README.md). +{% endhint %} + We will use [Grafana Cloud](https://grafana.com/) to observe and monitor both the Signer and its corresponding Stacks node. ## Requirements diff --git a/docs/reference/.gitbook/assets/stacks-blockchain-api-architecture.svg b/docs/reference/.gitbook/assets/stacks-blockchain-api-architecture.svg new file mode 100644 index 0000000000..a9452d780c --- /dev/null +++ b/docs/reference/.gitbook/assets/stacks-blockchain-api-architecture.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/reference/SUMMARY.md b/docs/reference/SUMMARY.md index 7bbd20b4bb..654be78061 100644 --- a/docs/reference/SUMMARY.md +++ b/docs/reference/SUMMARY.md @@ -4,6 +4,9 @@ ## API +* [API Keys](api/api-keys.md) +* [Rate Limits](api/rate-limits.md) +* [Response Headers](api/response-headers.md) * [Stacks Node RPC](api/stacks-node-rpc/README.md) * ```yaml props: @@ -16,6 +19,62 @@ kind: openapi spec: stacks-node-rpc-api-dereferenced-new ``` +* [Stacks Blockchain API](api/stacks-blockchain-api/README.md) + * [Usage](api/stacks-blockchain-api/usage.md) + * [Architecture](api/stacks-blockchain-api/architecture.md) + * [Pagination](api/stacks-blockchain-api/pagination.md) + * [Nonce Handling](api/stacks-blockchain-api/nonce-handling.md) + * [Requesting Proofs](api/stacks-blockchain-api/requesting-proofs.md) + * ```yaml + props: + models: true + downloadLink: false + type: builtin:openapi + dependencies: + spec: + ref: + kind: openapi + spec: stacks-blockchain-api-dereferenced + ``` +* [Chainhooks API](api/chainhooks-api/README.md) + * [Usage](api/chainhooks-api/usage.md) + * ```yaml + props: + models: true + downloadLink: false + type: builtin:openapi + dependencies: + spec: + ref: + kind: openapi + spec: chainhooks-api + ``` +* [Token Metadata API](api/token-metadata-api/README.md) + * [Usage](api/token-metadata-api/usage.md) + * ```yaml + props: + models: true + downloadLink: false + type: builtin:openapi + dependencies: + spec: + ref: + kind: openapi + spec: token-metadata-api + ``` +* [Signer Metrics API](api/signer-metrics-api/README.md) + * [Usage](api/signer-metrics-api/usage.md) + * ```yaml + props: + models: true + downloadLink: false + type: builtin:openapi + dependencies: + spec: + ref: + kind: openapi + spec: signer-metrics-api + ``` * [Stacks Mesh API](api/stacks-mesh-api/README.md) * ```yaml type: builtin:openapi diff --git a/docs/reference/api/api-keys.md b/docs/reference/api/api-keys.md new file mode 100644 index 0000000000..5a1aee6570 --- /dev/null +++ b/docs/reference/api/api-keys.md @@ -0,0 +1,38 @@ +# API Keys + +Many Hiro-hosted APIs are available without authentication for basic usage, but production integrations should use API keys for clearer quota tracking and higher service limits where available. + +{% hint style="info" %} +Create and manage Hiro API keys in [Hiro Platform](https://platform.hiro.so/). If you need quota changes beyond the standard self-service setup, contact Hiro through the platform support channels. +{% endhint %} + +## Sending an API key + +Pass your key in the `x-api-key` header: + +```bash +curl https://api.hiro.so/... \ + -H 'x-api-key: YOUR_API_KEY' +``` + +Example using `fetch`: + +```ts +async function makeApiRequest(apiKey: string) { + const response = await fetch('https://api.hiro.so/', { + headers: { + 'x-api-key': apiKey, + }, + }); + + return response.json(); +} +``` + +## Security guidance + +- Keep API keys in server-side environments such as backend services, workers, or CI jobs. +- Do not embed production keys in client-side applications where they can be extracted. +- Rotate keys periodically and revoke keys that are no longer needed. + +For quota behavior and rate limit inspection, see [Rate Limits](rate-limits.md) and [Response Headers](response-headers.md). diff --git a/docs/reference/api/chainhooks-api/README.md b/docs/reference/api/chainhooks-api/README.md new file mode 100644 index 0000000000..1d4f7dcb6d --- /dev/null +++ b/docs/reference/api/chainhooks-api/README.md @@ -0,0 +1,35 @@ +# Chainhooks API + +{% hint style="info" %} +This API is developed and hosted by [Hiro](https://www.hiro.so/). For authentication and quota guidance, see [API Keys](../api-keys.md), [Rate Limits](../rate-limits.md), and [Response Headers](../response-headers.md). +{% endhint %} + +The Chainhooks API is a REST API for programmatically creating, updating, evaluating, and deleting Chainhooks. It exposes the same Hiro-hosted service behind the Chainhooks tooling, making it possible to manage webhook-based indexing workflows over HTTP. + +Use this API when you want to automate Chainhook lifecycle management from your own backend, CI workflow, or operations tooling instead of configuring everything manually through the Hiro Platform. + +### Key features + +- Create, inspect, update, enable, and delete Chainhooks over HTTP +- Evaluate Chainhooks against historical chain data before enabling them +- Manage webhook delivery settings and consumer secrets programmatically + +### Base URLs + +```text +Testnet: https://api.testnet.hiro.so/chainhooks/v1 +Mainnet: https://api.mainnet.hiro.so/chainhooks/v1 +``` + +### Example request + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" +``` + +For authentication details, request conventions, and operational guidance, see [Usage](usage.md). + +{% hint style="info" %} +Need help building with the Chainhooks API? Reach out in the `#chainhook` channel on [Discord](https://stacks.chat/) under Hiro Developer Tools. +{% endhint %} diff --git a/docs/reference/api/chainhooks-api/usage.md b/docs/reference/api/chainhooks-api/usage.md new file mode 100644 index 0000000000..c6ed300bab --- /dev/null +++ b/docs/reference/api/chainhooks-api/usage.md @@ -0,0 +1,139 @@ +# Usage + +The Chainhooks API uses standard HTTPS JSON requests and requires a Hiro API key on every request. + +## Authentication + +Create or manage your API keys in [Hiro Platform](https://platform.hiro.so/), then send the key in the `x-api-key` header: + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" +``` + +For broader key-management guidance, see [API Keys](../api-keys.md). + +## Base URLs + +```text +Testnet: https://api.testnet.hiro.so/chainhooks/v1 +Mainnet: https://api.mainnet.hiro.so/chainhooks/v1 +``` + +Test on testnet first, then promote the same workflow to mainnet once your filters and webhook handling are stable. + +## Request conventions + +Most endpoints accept JSON request bodies and expect these headers: + +```http +Content-Type: application/json +x-api-key: YOUR_API_KEY +``` + +Example: create a Chainhook for Stacks token transfer events. + +```bash +curl -X POST https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-chainhook", + "version": "1", + "chain": "stacks", + "network": "testnet", + "filters": { + "events": [ + { + "type": "stx_transfer", + "sender": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" + } + ] + }, + "action": { + "type": "http_post", + "url": "https://example.com/webhooks" + } + }' +``` + +## Common operations + +List all Chainhooks: + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/ \ + -H "x-api-key: YOUR_API_KEY" +``` + +Fetch a single Chainhook: + +```bash +curl https://api.testnet.hiro.so/chainhooks/v1/me/{uuid} \ + -H "x-api-key: YOUR_API_KEY" +``` + +Enable a Chainhook: + +```bash +curl -X PATCH https://api.testnet.hiro.so/chainhooks/v1/me/{uuid}/enabled \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"enabled": true}' +``` + +Evaluate a Chainhook against historical data before enabling it: + +```bash +curl -X POST https://api.testnet.hiro.so/chainhooks/v1/me/{uuid}/evaluate \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"block_height": 150000}' +``` + +Delete a Chainhook: + +```bash +curl -X DELETE https://api.testnet.hiro.so/chainhooks/v1/me/{uuid} \ + -H "x-api-key: YOUR_API_KEY" +``` + +## Response codes + +| Code | Meaning | +| --- | --- | +| `200` | Request succeeded | +| `204` | Request succeeded without a response body | +| `400` | Invalid request body or parameters | +| `401` | Missing or invalid API key | +| `404` | The requested Chainhook was not found | +| `429` | Rate limit exceeded | +| `5xx` | Server-side error | + +Inspect the response headers described in [Response Headers](../response-headers.md) and apply retry logic when you receive `429` responses. + +## Webhook security + +Webhook payloads include an `x-chainhook-consumer-secret` header. Validate that value in your webhook consumer before processing the payload: + +```javascript +app.post('/webhooks', (req, res) => { + const receivedSecret = req.headers['x-chainhook-consumer-secret']; + const expectedSecret = process.env.CHAINHOOK_CONSUMER_SECRET; + + if (receivedSecret !== expectedSecret) { + return res.status(401).send('Unauthorized'); + } + + res.sendStatus(200); +}); +``` + +Rotate the secret periodically and store it server-side only. + +## Operational guidance + +- Start on testnet before enabling production webhooks. +- Create Chainhooks in a disabled state, evaluate them, then enable them. +- Retry `429` and transient `5xx` responses with backoff. +- Use HTTPS webhook endpoints and verify the consumer secret on every delivery. diff --git a/docs/reference/api/rate-limits.md b/docs/reference/api/rate-limits.md new file mode 100644 index 0000000000..18e290f192 --- /dev/null +++ b/docs/reference/api/rate-limits.md @@ -0,0 +1,24 @@ +# Rate Limits + +Hiro-hosted APIs enforce rate limits to protect shared infrastructure. The effective quota depends on the product you are calling, whether the request is authenticated, and any plan-specific limits attached to your account. + +## How limits are applied + +- Unauthenticated traffic is typically rate-limited by client IP. +- Authenticated traffic is tracked against the API key you send in `x-api-key`. +- Some Hiro-hosted products expose their own service-specific quota buckets. + +The most reliable way to understand your current quota is to inspect the response headers returned by the API you are calling. See [Response Headers](response-headers.md). + +{% hint style="info" %} +Platform-managed products can have their own quota rules and are not always part of the same public API rate limit pool. +{% endhint %} + +## Working within limits + +- Send an API key for production workloads so your usage is attributed correctly. +- Retry `429 Too Many Requests` responses with exponential backoff. +- Cache responses where possible and avoid polling endpoints more aggressively than needed. +- Track `ratelimit-remaining`, `ratelimit-reset`, and any service-specific `x-ratelimit-*` headers in your application logs. + +If you need an API key, start with [API Keys](api-keys.md). diff --git a/docs/reference/api/response-headers.md b/docs/reference/api/response-headers.md new file mode 100644 index 0000000000..8abe6899e3 --- /dev/null +++ b/docs/reference/api/response-headers.md @@ -0,0 +1,56 @@ +# Response Headers + +Hiro-hosted APIs return response headers that help you inspect rate limits, remaining quota, and retry timing. + +## Standard rate limit headers + +The following headers may be returned with API responses: + +```bash +curl -I https://api.hiro.so/extended/v1/info \ + -H 'x-api-key: YOUR_API_KEY' +``` + +| Header | Description | +| --- | --- | +| `ratelimit-limit` | The limit for the current window | +| `ratelimit-remaining` | Requests remaining in the current window | +| `ratelimit-reset` | When the current window resets | +| `retry-after` | How long to wait before retrying after rate limiting | + +## Stacks service headers + +Stacks-focused Hiro APIs can also return service-specific quota headers: + +```typescript +const response = await fetch( + 'https://api.hiro.so/extended/v1/address/SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP/assets', + { + headers: { 'x-api-key': apiKey }, + } +); + +console.log(response.headers.get('x-ratelimit-cost-stacks')); +``` + +| Header | Description | +| --- | --- | +| `x-ratelimit-cost-stacks` | Quota cost for the request | +| `x-ratelimit-limit-stacks-second` | Per-second limit for Stacks services | +| `x-ratelimit-remaining-stacks-second` | Remaining requests this second | +| `x-ratelimit-limit-stacks-minute` | Per-minute limit for Stacks services | +| `x-ratelimit-remaining-stacks-minute` | Remaining requests this minute | +| `x-ratelimit-limit-stacks-month` | Monthly limit for Stacks services | +| `x-ratelimit-remaining-stacks-month` | Remaining requests this month | + +{% hint style="info" %} +Exact header sets can vary by product. Use the headers returned by the API you are calling as the source of truth. +{% endhint %} + +## Using these headers + +- Log rate limit headers in your backend so you can detect sustained pressure before you hit hard limits. +- Back off when `ratelimit-remaining` reaches zero or when the response includes `retry-after`. +- Monitor `x-ratelimit-cost-stacks` for requests that consume more than one unit of quota. + +See also [Rate Limits](rate-limits.md) and [API Keys](api-keys.md). diff --git a/docs/reference/api/signer-metrics-api/README.md b/docs/reference/api/signer-metrics-api/README.md new file mode 100644 index 0000000000..8c4c064b4e --- /dev/null +++ b/docs/reference/api/signer-metrics-api/README.md @@ -0,0 +1,26 @@ +# Signer Metrics API + +{% hint style="info" %} +This API is developed and hosted by [Hiro](https://www.hiro.so/). For authentication and quota guidance, see [API Keys](../api-keys.md), [Rate Limits](../rate-limits.md), and [Response Headers](../response-headers.md). +{% endhint %} + +The Signer Metrics API exposes indexed data for monitoring signer participation and behavior on the Stacks network. It is useful when you need to inspect signer performance across reward cycles without querying raw metrics infrastructure yourself. + +### Key features + +- Reward-cycle views of signer participation and activity +- Aggregated metrics for signer and block analysis +- A simple REST interface for dashboards, monitoring, and incident response workflows + +### Example request + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' \ + -H 'Accept: application/json' +``` + +For request basics and response codes, see [Usage](usage.md). + +{% hint style="info" %} +Need help building with the Signer Metrics API? Reach out in the `#api` channel on [Discord](https://stacks.chat/) under Hiro Developer Tools. +{% endhint %} diff --git a/docs/reference/api/signer-metrics-api/usage.md b/docs/reference/api/signer-metrics-api/usage.md new file mode 100644 index 0000000000..38e568d871 --- /dev/null +++ b/docs/reference/api/signer-metrics-api/usage.md @@ -0,0 +1,45 @@ +# Usage + +The Signer Metrics API follows standard REST conventions over HTTPS. + +## Base URL + +```text +https://api.hiro.so +``` + +## Making requests + +Fetch signer participation data for a reward cycle: + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' \ + -H 'Accept: application/json' +``` + +For authenticated traffic, add your Hiro API key: + +```bash +curl -L 'https://api.hiro.so/signer-metrics/v1/cycles/95/signers' \ + -H 'Accept: application/json' \ + -H 'x-api-key: YOUR_API_KEY' +``` + +For more detail on key management and quotas, see [API Keys](../api-keys.md) and [Rate Limits](../rate-limits.md). + +## Response codes + +| Code | Meaning | +| --- | --- | +| `200` | Successful request | +| `400` | Invalid parameters | +| `401` | Missing API key where required | +| `403` | Invalid API key | +| `404` | Resource not found | +| `429` | Rate limit exceeded | +| `5xx` | Server-side error | + +## Related guidance + +- Use [Response Headers](../response-headers.md) to inspect rate limit information. +- For signer host monitoring, pair this API with the Grafana-based guide in the Operate docs. diff --git a/docs/reference/api/stacks-blockchain-api/README.md b/docs/reference/api/stacks-blockchain-api/README.md new file mode 100644 index 0000000000..6ef8bac628 --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/README.md @@ -0,0 +1,41 @@ +# Stacks Blockchain API + +{% hint style="info" %} +For the complete OpenAPI spec, navigate [here](https://raw.githubusercontent.com/hirosystems/stacks-blockchain-api/master/openapi.yaml). +{% endhint %} + +The Stacks Blockchain API is a REST API developed and hosted by [Hiro](https://www.hiro.so/) that extends the [Stacks Node RPC API](../stacks-node-rpc/) with additional indexed endpoints. While every Stacks node exposes a minimal set of RPC endpoints (account balances, contract calls, transaction broadcasting), the Blockchain API continuously ingests and indexes on-chain activity into a PostgreSQL database, making it possible to query transaction history, token transfers, smart contract events, and paginated lists of blocks — data that is not directly available from a Stacks node alone. + +The public base URL is `https://api.hiro.so`. No infrastructure setup is required, so you can start querying immediately. + +
+ +Who is this API for? + +The Stacks Blockchain API is the recommended API for wallets, dApps, explorers, and general developers who need rich query capabilities without running their own node. It proxies all standard [Stacks Node RPC](../stacks-node-rpc/) endpoints and adds the `/extended/` family of indexed endpoints on top. + +If you need a more decentralized setup or want direct access to the raw node RPC without a third-party service, see the [Stacks Node RPC API](../stacks-node-rpc/). For exchange or institutional integrations using the Coinbase Mesh standard, see the [Stacks Mesh API](../stacks-mesh-api/). + +
+ +### Key features + +- **Real-time data ingestion** -- Continuously indexes blockchain activity as it happens +- **Cached responses** -- Optimized performance through intelligent caching strategies +- **Complete data access** -- Transaction history, smart contracts, accounts, and blocks + +### Usage + +```bash +curl -L 'https://api.hiro.so/extended' -H 'Accept: application/json' +``` + +For more usage examples, see [Usage](usage.md). + +{% hint style="warning" %} +All Stacks Blockchain API responses include rate limit headers that help you monitor your API usage. +{% endhint %} + +{% hint style="info" %} +Need help building with the Stacks Blockchain API? Reach out on the **#api** channel on [Discord](https://stacks.chat/) under the Hiro Developer Tools section. +{% endhint %} diff --git a/docs/reference/api/stacks-blockchain-api/architecture.md b/docs/reference/api/stacks-blockchain-api/architecture.md new file mode 100644 index 0000000000..ade6b86bc5 --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/architecture.md @@ -0,0 +1,57 @@ +--- +description: Understand the architecture of the Stacks Blockchain API. +--- + +# Architecture + +![Stacks Blockchain API architecture](../../.gitbook/assets/stacks-blockchain-api-architecture.svg) + +## RPC Endpoints + +The `stacks-node` has its own minimal set of http endpoints referred to as `RPC endpoints`. + +- The `stacks-blockchain-api` allows clients to access RPC endpoints by proxying requests to a load-balanced pool of `stacks-nodes`. +- For more details on RPC endpoints, see: [RPC Endpoints Documentation](https://github.com/stacks-network/stacks-core/blob/master/docs/rpc-endpoints.md) +- Common RPC endpoints include: + - `POST /v2/transactions` - Broadcast a transaction + - `GET /v2/pox` - Retrieve current Proof of Transfer (PoX) relevant information + - `POST /v2/contracts/call-read//` - Evaluate and return the result of calling a Clarity function + - `POST /v2/fees/transaction` - Evaluate a given transaction and provide transaction fee estimation data + - `GET /v2/accounts/
` - Fetch the current nonce required for creating transactions + +## Additional Endpoints + +The Stacks Blockchain API implements additional endpoints that provide data unavailable directly from Stacks nodes due to various constraints. + +- The `stacks-node` may not persist certain data or may not serve it efficiently to many clients. For instance, while it can return the current STX balance of an account, it cannot provide a history of account transactions. +- The API previously included an embedded Rosetta implementation, but this was removed in favor of the standalone [Stacks Mesh API](../stacks-mesh-api/). +- The API includes support for the Blockchain Naming System (BNS) endpoints. +- For routes, see [`/src/api/routes`](https://github.com/hirosystems/stacks-blockchain-api/tree/master/src/api/routes) in the API repo. + +The API creates an "event observer" http server which listens for events from a stacks-node "event emitter". + +Events are HTTP POST requests containing: + - Blocks + - Transactions + +Byproducts of executed transactions such as: + - Asset transfers + - Smart-contract log data + - Execution cost data + +The API processes and stores these events as relational data in PostgreSQL. For the "event observer" code, see [`/src/event-stream`](https://github.com/hirosystems/stacks-blockchain-api/tree/master/src/event-stream) in the API repo. + +## OpenAPI and JSON Schema + +All http endpoints and responses are defined in OpenAPI and JSON Schema. + +- See [`openapi.yaml`](https://github.com/hirosystems/stacks-blockchain-api/blob/master/openapi.yaml) in the API repo +- These are used to auto-generate the docs at https://docs.stacks.co/reference/api/stacks-blockchain-api +- JSON Schemas are converted into TypeScript interfaces, which are used internally by the db controller module to transform SQL query results into the correct object shapes. +- OpenAPI and JSON Schemas are also used to generate a standalone `@stacks/blockchain-api-client`. + +## Development Setup + +To contribute to the [Stacks Blockchain API codebase](https://github.com/hirosystems/stacks-blockchain-api), the easiest way to get started is using the VS Code debugger. It uses docker-compose to set up a stacks-node and Postgres instance. + +Alternatively, you can run `npm run dev:integrated` which does the same thing but without a debugger. diff --git a/docs/reference/api/stacks-blockchain-api/nonce-handling.md b/docs/reference/api/stacks-blockchain-api/nonce-handling.md new file mode 100644 index 0000000000..6b7555259d --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/nonce-handling.md @@ -0,0 +1,27 @@ +--- +description: Learn how to handle nonces on Stacks. +--- + +# Nonce handling + +In order to prevent "stuck" transactions, you must track the next available nonce for principals issuing transactions. The +Stacks Blockchain API provides an endpoint to make nonce handling simpler when using the following command: + +```bash +curl 'https://api.hiro.so/extended/v1/address/SP3XXK8BG5X7CRH7W07RRJK3JZJXJ799WX3Y0SMCR/nonces' +``` + +```json +{ + "last_executed_tx_nonce": 2789412, + "last_mempool_tx_nonce": 2789413, + "possible_next_nonce": 2789414, + "detected_missing_nonces": [] +} +``` + +The `possible_next_nonce` property is the nonce suggested for a given principal's next transaction. It is derived as the next integer to the largest nonce found in blocks and mempool. It does not take into account missing nonces. + +The `detected_missing_nonces` property finds any non-contiguous nonces after inspecting transactions from blocks and the mempool. For example, for a given principal, if the latest transaction included in a block has a nonce of 5, and there's only one transaction in the mempool with nonce 7, then it indicates that something likely went wrong with transaction with nonce 6 (either it was not created or broadcasted correctly by a client, or it was dropped for whatever reason). This is a strong indication that the mempool transaction with nonce 7 will never be mined since the previous nonce is missing. + +Clients that continue to broadcast transactions with the `possible_next_nonce` property of 8, then 9, then 10, will likely result in all of their pending/mempool transactions never going through. For all transactions to go through, clients should first use any missing nonces before using the suggested `possible_next_nonce`. diff --git a/docs/reference/api/stacks-blockchain-api/pagination.md b/docs/reference/api/stacks-blockchain-api/pagination.md new file mode 100644 index 0000000000..cadb6302b5 --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/pagination.md @@ -0,0 +1,52 @@ +--- +description: Learn how to paginate through lists. +--- + +# Pagination + +To make API responses more compact, lists returned by the API are paginated. For lists, the response body includes: + +- `limit`: The number of list items returned per response +- `offset`: The number of elements to skip (starting from 0) +- `total`: The number of all available list items +- `results`: The array of list items (length of array equals the set limit) + +Here is a sample response: + +```json +{ + "limit": 10, + "offset": 0, + "total": 101922, + "results": [ + { + "tx_id": "0x924e0a688664851f5f96b437fabaec19b7542cfcaaf92a97eae43384cacd83d0", + "nonce": 308, + "fee_rate": "0", + "sender_address": "ST39F7SA0AKH7RB363W3NE2DTHD3P32ZHNX2KE7J9", + "sponsored": false, + "post_condition_mode": "deny", + "post_conditions": [], + "anchor_mode": "on_chain_only", + "block_hash": "0x17ceb3da5f36aab351d6b14f5aa77f85bb6b800b954b2f24c564579f80116d99", + "parent_block_hash": "0xe0d1e8d216a77526ae2ce40294fc77038798a179a6532bb8980d3c2183f58de6", + "block_height": 14461, + "burn_block_time": 1622875042, + "burn_block_time_iso": "2021-06-05T06:37:22.000Z", + "canonical": true, + "tx_index": 0, + "tx_status": "success", + "tx_result": {}, + "microblock_hash": "", + "microblock_sequence": 2147483647, + "microblock_canonical": true, + "event_count": 0, + "events": [], + "tx_type": "coinbase", + "coinbase_payload": {} + } + ] +} +``` + +Using the `limit` and `offset` properties, you can paginate through the entire list by increasing the offset by the limit until you reach the total. diff --git a/docs/reference/api/stacks-blockchain-api/requesting-proofs.md b/docs/reference/api/stacks-blockchain-api/requesting-proofs.md new file mode 100644 index 0000000000..94fdc34b2f --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/requesting-proofs.md @@ -0,0 +1,11 @@ +--- +description: Understand proof requests from API endpoints. +--- + +# Requesting proofs + +Several endpoints return the [MARF Merkle Proof](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md#marf-merkle-proofs) by default. + +Provided with the proof, a client can verify the value, cumulative energy spent, and the number of confirmations for the response value provided by the API. + +Requesting the proof requires more resources (computation time, response time, and response body size). To avoid the additional resources, in case verification is not required, API endpoints allow setting the request parameter: `proof=0`. The returned response object will not have any proof fields. diff --git a/docs/reference/api/stacks-blockchain-api/usage.md b/docs/reference/api/stacks-blockchain-api/usage.md new file mode 100644 index 0000000000..1456f44184 --- /dev/null +++ b/docs/reference/api/stacks-blockchain-api/usage.md @@ -0,0 +1,46 @@ +--- +description: Learn the basics of using the Stacks Blockchain API. +--- + +# Basic usage + +The Stacks Blockchain API is built on REST principles, enforcing HTTPS for all requests to ensure data security, integrity, and privacy. + +## Base URL + +```bash +https://api.hiro.so +``` + +## Making requests + +To make a request to the Stacks API, you can paste the curl command below in your terminal. + +```bash +curl -L 'https://api.hiro.so/extended' \ + -H 'Accept: application/json' +``` + +## Authentication + +If you are using an API key, replace `$HIRO_API_KEY` with your secret API key. + +```bash +curl -L 'https://api.hiro.so/extended' \ + -H 'Accept: application/json' \ + -H 'x-api-key: $HIRO_API_KEY' +``` + +## Response codes + +The Stacks Blockchain API uses standard HTTP response codes to indicate request success or failure. + +| Code | Description | +|------|-------------| +| `200` | Successful request | +| `400` | Check that the parameters were correct | +| `401` | Missing API key | +| `403` | Invalid API key | +| `404` | Resource not found | +| `429` | Rate limit exceeded | +| `5xx` | Server errors | diff --git a/docs/reference/api/stacks-node-rpc/README.md b/docs/reference/api/stacks-node-rpc/README.md index 62f9380e65..d8ece68713 100644 --- a/docs/reference/api/stacks-node-rpc/README.md +++ b/docs/reference/api/stacks-node-rpc/README.md @@ -18,7 +18,11 @@ The Stacks Node RPC API is designed for developers who want to self-host their o If you run a local Stacks node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. {% endhint %} -Note that the [Stacks Node RPC API](https://github.com/stacks-network/stacks-blockchain/) and the [Hiro Stacks Blockchain API](https://www.hiro.so/stacks-api) are two different things. The Hiro API is a centralized service run by Hiro, a developer tooling company, that makes it easy to get onboarded and begin interacting with the Stacks blockchain in a RESTful way. The Hiro API is a proxy for the Stacks Node RPC API that makes it a bit easier to work with by providing additional functionality. +{% hint style="info" %} +Looking for the indexed Stacks Blockchain API? See the [Stacks Blockchain API reference](../stacks-blockchain-api/). +{% endhint %} + +The self-hosted Stacks Node RPC API and the Hiro-hosted [Stacks Blockchain API](../stacks-blockchain-api/) are different interfaces. Use the Node RPC API when you want direct access to a running Stacks node and are comfortable managing your own infrastructure. Use the Hiro-hosted Stacks Blockchain API when you need indexed `/extended/` endpoints, historical lookups, and richer pagination without operating your own indexer. The Stacks Node RPC API is generated by every Stacks node and allows developers to self-host their own node and API for a more decentralized architecture. diff --git a/docs/reference/api/token-metadata-api/README.md b/docs/reference/api/token-metadata-api/README.md new file mode 100644 index 0000000000..af6c9859b2 --- /dev/null +++ b/docs/reference/api/token-metadata-api/README.md @@ -0,0 +1,30 @@ +# Token Metadata API + +{% hint style="info" %} +This API is developed and hosted by [Hiro](https://www.hiro.so/). For authentication and quota guidance, see [API Keys](../api-keys.md), [Rate Limits](../rate-limits.md), and [Response Headers](../response-headers.md). +{% endhint %} + +The Token Metadata API provides indexed metadata for fungible tokens, non-fungible tokens, and token collections on Stacks. It is designed for wallets, explorers, and apps that need a fast way to resolve token metadata without building their own indexing pipeline. + +### Key features + +- Indexed metadata for fungible, non-fungible, and semi-fungible tokens +- Cached responses for low-latency metadata lookups +- Support for SIP-016 metadata patterns and update notifications + +### Example request + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' \ + -H 'Accept: application/json' +``` + +For request basics and response codes, see [Usage](usage.md). + +{% hint style="warning" %} +Token Metadata API responses include rate limit headers. Use them to track your current quota and request cost. +{% endhint %} + +{% hint style="info" %} +Need help building with the Token Metadata API? Reach out in the `#api` channel on [Discord](https://stacks.chat/) under Hiro Developer Tools. +{% endhint %} diff --git a/docs/reference/api/token-metadata-api/usage.md b/docs/reference/api/token-metadata-api/usage.md new file mode 100644 index 0000000000..f81e644a3d --- /dev/null +++ b/docs/reference/api/token-metadata-api/usage.md @@ -0,0 +1,45 @@ +# Usage + +The Token Metadata API follows standard REST conventions over HTTPS. + +## Base URL + +```text +https://api.hiro.so +``` + +## Making requests + +Fetch fungible token metadata: + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' \ + -H 'Accept: application/json' +``` + +Many integrations can start without an API key. For production traffic and higher quotas, send your Hiro API key in the `x-api-key` header: + +```bash +curl -L 'https://api.hiro.so/metadata/v1/ft' \ + -H 'Accept: application/json' \ + -H 'x-api-key: YOUR_API_KEY' +``` + +For more detail on key management and quotas, see [API Keys](../api-keys.md) and [Rate Limits](../rate-limits.md). + +## Response codes + +| Code | Meaning | +| --- | --- | +| `200` | Successful request | +| `400` | Invalid parameters | +| `401` | Missing API key where required | +| `403` | Invalid API key | +| `404` | Resource not found | +| `429` | Rate limit exceeded | +| `5xx` | Server-side error | + +## Related guidance + +- Use [Response Headers](../response-headers.md) to inspect remaining quota. +- If your token metadata changes over time, emit SIP-019 update notifications from your contract so downstream indexers can refresh cached metadata. From 84a2124267edf2abf8562ee9892f5bf30f5596cd Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Fri, 20 Mar 2026 13:09:06 -0700 Subject: [PATCH 2/4] Remove migration planning artifact from PR --- HIRO_DOCS_MIGRATION_MATRIX.md | 44 ----------------------------------- 1 file changed, 44 deletions(-) delete mode 100644 HIRO_DOCS_MIGRATION_MATRIX.md diff --git a/HIRO_DOCS_MIGRATION_MATRIX.md b/HIRO_DOCS_MIGRATION_MATRIX.md deleted file mode 100644 index 2ee31194e6..0000000000 --- a/HIRO_DOCS_MIGRATION_MATRIX.md +++ /dev/null @@ -1,44 +0,0 @@ -# Hiro Docs Migration Matrix - -This document is the gating artifact for the Hiro-to-Stacks docs migration. -No section should merge until the `recommendation` and `review` fields have -been confirmed by Alex, Rafa, and Hugo. - -Guiding rules: - -- Use first-class Stacks docs placement, not a temporary `/hiro` subtree. -- Keep English as the repo source of truth. -- Publish Spanish through GitBook Translations after English approval. -- Use GitBook built-in OpenAPI blocks for API references. -- Keep existing Hiro-hosted runtime endpoints on `hiro.so`. - -Review checklist for each `keep` section: - -- Accuracy and relevance confirmed -- Duplicate coverage on Stacks docs checked -- Legacy/deprecated wording removed -- Internal links updated to final Stacks paths -- GitBook preview checked -- GitBook admin dependency captured if an OpenAPI spec must be registered - - -| Section | Source | Locale(s) | Target | Space | Spec source / dependency | Recommendation | Cleanup required | Review | Notes | -| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------- | -| Stacks Blockchain API | `content/docs/en/apis/stacks-blockchain-api/` | `en` | `docs/reference/api/stacks-blockchain-api/` | `reference` | Existing GitBook spec id: `stacks-blockchain-api-dereferenced` | `keep` | Manual editorial pass, verify links, keep Hiro branding | `phase-1 baseline` | Implemented via PR #1845 pattern | -| Chainhooks tool docs | `content/docs/en/tools/chainhooks/` | `en` | `docs/build/chainhooks/` | `build` | n/a | `keep` | Exclude platform-UI pages, remove stale beta/platform wording, add Hiro branding | `pending review` | Ship SDK/reference docs only in initial pass | -| Chainhooks API | `content/docs/en/apis/chainhooks-api/` | `en` | `docs/reference/api/chainhooks-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `chainhooks-api` | `keep` | Migrate curated prose only, GitBook admin registration needed | `pending review` | No per-endpoint markdown in destination | -| Token Metadata API | `content/docs/en/apis/token-metadata-api/` | `en` | `docs/reference/api/token-metadata-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `token-metadata-api` | `keep` | Editorial cleanup, cross-link from token guides, GitBook admin registration needed | `pending review` | Keep Hiro branding and `hiro.so` examples | -| Signer Metrics API | `content/docs/en/apis/signer-metrics-api/` | `en` | `docs/reference/api/signer-metrics-api/` | `reference` | Permanent flattened public URL needed; placeholder spec id `signer-metrics-api` | `keep` | Editorial cleanup, cross-link from signer monitoring docs, GitBook admin registration needed | `pending review` | Keep as Hiro API in Stacks reference | -| Contract Monitoring | `content/docs/en/tools/contract-monitoring/` | `en` | `docs/build/contract-monitoring/` | `build` | n/a | `keep` | Confirm product relevance, add Hiro Platform note, remove stale references | `pending review` | Pair with Chainhooks cross-links | -| Shared API usage guides | `content/docs/en/resources/guides/{api-keys,rate-limits,response-headers}.mdx` | `en` | `docs/reference/api/` | `reference` | n/a | `keep` | Remove references to dropped/deferred APIs where needed | `pending review` | Shared Hiro API guidance | -| Selected build guides | `content/docs/en/resources/guides/{build-an-nft-marketplace,build-a-decentralized-kickstarter,no-loss-lottery,using-clarity-values}.mdx` | `en` | `docs/build/more-guides/` | `build` | n/a | `keep` | Deduplicate against existing Stacks guides, remove React-only UI scaffolding | `pending review` | Keep only guides that add real value | -| Node RPC positioning improvements | existing Stacks docs plus Hiro comparison copy | `en` | existing `docs/reference/api/stacks-node-rpc/README.md` | `reference` | Existing Node RPC spec flow remains unchanged | `keep` | Clarify RPC vs indexed Hiro API distinction only | `pending review` | No Node RPC section migration | -| Platform API | `content/docs/en/apis/platform-api/` | `en` | `docs/reference/api/platform-api/` | `reference` | Permanent public spec URL and product-owner approval required | `defer` | Validate product scope, auth model, and value on Stacks docs | `pending review` | Visible in inventory, not auto-approved | -| Hiro Archive docs | `content/docs/en/resources/archive/` | `en` | undecided | `operate` | n/a | `defer` | Review whether archive docs belong on Stacks docs at all | `pending review` | Keep out of main migration until explicitly approved | -| Docker / sync guides already covered on Stacks docs | `content/docs/en/resources/guides/{installing-docker,sync-a-bitcoin-node,sync-a-stacks-node}.mdx` | `en` | none by default | `operate` | n/a | `drop` | Only rescue unique details if review finds real gaps | `pending review` | Existing Stacks operate docs already cover this area | -| Ordinals API | `content/docs/en/apis/ordinals-api/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | -| Runes API | `content/docs/en/apis/runes-api/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | -| Bitcoin Indexer | `content/docs/en/tools/bitcoin-indexer/` | `en` | none | none | Deprecated March 2026 | `drop` | Track only for historical awareness | `pending review` | Do not migrate to Stacks docs | -| Existing Spanish source | `content/docs/es/**` | `es` | GitBook translated variants, not repo source | n/a | GitBook admin translation setup required | `defer` | Spanish Chainhooks source already contains translation corruption | `policy locked` | Do not bulk-import Spanish MDX | - - From 32099123f4145848a1665990d4a2998c31796d1d Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Fri, 20 Mar 2026 15:28:47 -0700 Subject: [PATCH 3/4] Fix existing broken links in docs --- docs/build/README.md | 4 +- docs/build/more-guides/bridging-usdcx.md | 2 +- .../sbtc/sbtc-builder-quickstart.md | 4 +- .../press-and-top-links/2024/README.md | 48 +++++++++---------- .../press-and-top-links/2025/README.md | 44 ++++++++++++++++- docs/reference/README.md | 2 +- .../nakamoto-for-exchanges.md | 4 +- .../node-operations/signer-configuration.md | 6 +-- docs/tutorials/README.md | 2 +- 9 files changed, 79 insertions(+), 37 deletions(-) diff --git a/docs/build/README.md b/docs/build/README.md index 8edb5bdb1b..ddf4839804 100644 --- a/docs/build/README.md +++ b/docs/build/README.md @@ -96,7 +96,7 @@ There is also a subsection of example Clarity contracts where you'll find **star We all have different styles of learning. If you've already got a good concept of web3 fundamentals and want to get a quick taste of what the DevEx is like on Stacks, then check out the [Developer Quickstart](get-started/developer-quickstart.md). Or find the path that clicks for you — and if bandwidth allows, tackle them all! -

Try the Developer Quickstart

Your 0→1 guide for building a Clarity contract and app on Stacks.developer-quickstart.md

Start Learning Clarity

An easy starting point for learning smart contracts.clarity-crash-course.md

Bitcoin Primer Tutorial

A comprehensive end-to-end experience to building full-stack dApps on Bitcoin.Bitcoin Primer

Earn a Stacks Developer Degree

A hands-on Stacks bootcamp by LearnWeb3.https://learnweb3.io/degrees/stacks-developer-degree/

Watch Our Hands-On Videos

Developer insights and workshops from the Stacks ecosystemhttps://www.youtube.com/@stacks-developers

Clarity Development Using Clarinet

The smart contract toolkit for StacksBroken link
+

Try the Developer Quickstart

Your 0→1 guide for building a Clarity contract and app on Stacks.developer-quickstart.md

Start Learning Clarity

An easy starting point for learning smart contracts.clarity-crash-course.md

Bitcoin Primer Tutorial

A comprehensive end-to-end experience to building full-stack dApps on Bitcoin.Bitcoin Primer

Earn a Stacks Developer Degree

A hands-on Stacks bootcamp by LearnWeb3.https://learnweb3.io/degrees/stacks-developer-degree/

Watch Our Hands-On Videos

Developer insights and workshops from the Stacks ecosystemhttps://www.youtube.com/@stacks-developers

Clarity Development Using Clarinet

The smart contract toolkit for Stacksclarinet/overview.md
@@ -107,7 +107,7 @@ We all have different styles of learning. If you've already got a good concept o | If you are… | First check out... | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Completely new to building with Stacks | [Developer Quickstart](get-started/developer-quickstart.md) | -| Learning smart contract development | [Clarity Crash Course](get-started/clarity-crash-course.md), [Learn Clarinet](/broken/pages/UK5Kgh2MHLoQvfoFVnLr) | +| Learning smart contract development | [Clarity Crash Course](get-started/clarity-crash-course.md), [Learn Clarinet](clarinet/overview.md) | | Preferring a structured, guided course that shows you every step to build full-stack apps | [Stacks Developer Degree](https://learnweb3.io/degrees/stacks-developer-degree/), [Bitcoin Primer](https://app.gitbook.com/s/skGYu79qDNfITOqDNU3s/bitcoin-primer/introduction), [EasyA](https://www.easya.io/challenges/stacks) | | Wanting to integrate sBTC in your app | [sBTC guides](more-guides/sbtc/) | | Launching a token | [Create Tokens](get-started/create-a-token/) | diff --git a/docs/build/more-guides/bridging-usdcx.md b/docs/build/more-guides/bridging-usdcx.md index 1074fee294..12e5defdb7 100644 --- a/docs/build/more-guides/bridging-usdcx.md +++ b/docs/build/more-guides/bridging-usdcx.md @@ -31,7 +31,7 @@ ### Key Tools To Use * [viem](https://viem.sh/) - A Typescript-first library that interfaces with Ethereum. -* [stacks.js](/broken/pages/dH5waQhE6Vb7rhcrUG7z) - A js library that helps developers build Stacks apps by handling transactions, wallet authentication, and smart contract interactions. +* [Stacks.js](../stacks.js/overview.md) - A JavaScript library that helps developers build Stacks apps by handling transactions, wallet authentication, and smart contract interactions. * [Circle Faucet](https://faucet.circle.com/) - Get testnet USDC * [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) - Get testnet ETH * [USDCx API](https://app.gitbook.com/s/GVj1Z9vMuEOMe7oH7Wnq/api/usdcx-bridge) - Fetch deposit and withdrawal status diff --git a/docs/build/more-guides/sbtc/sbtc-builder-quickstart.md b/docs/build/more-guides/sbtc/sbtc-builder-quickstart.md index 6bc393950a..b191cf28e6 100644 --- a/docs/build/more-guides/sbtc/sbtc-builder-quickstart.md +++ b/docs/build/more-guides/sbtc/sbtc-builder-quickstart.md @@ -22,8 +22,8 @@ In order to get the most from this quickstart, you should familiarize yourself w * [Stacks Developer Quickstart](https://app.gitbook.com/o/hoh4mQXTl8NvI3cETroY/s/Zz9BLmTU9oydDpL3qiUh/) - For a quick holistic introduction to the Stacks development process, tools, and fundamentals * [Clarity Crash Course](../../get-started/clarity-crash-course.md) - For a quick introduction to Clarity -* [Clarinet Docs](/broken/pages/UK5Kgh2MHLoQvfoFVnLr) -* [Stacks.js Docs](/broken/pages/dH5waQhE6Vb7rhcrUG7z) +* [Clarinet Docs](../../clarinet/overview.md) +* [Stacks.js Docs](../../stacks.js/overview.md) #### Local with Clarinet diff --git a/docs/press-and-reports/press-and-top-links/2024/README.md b/docs/press-and-reports/press-and-top-links/2024/README.md index ba259fbbf3..e8b1c3c3a3 100644 --- a/docs/press-and-reports/press-and-top-links/2024/README.md +++ b/docs/press-and-reports/press-and-top-links/2024/README.md @@ -8,50 +8,50 @@ description: >- For weekly stories delivered to your inbox, subscribe to [Stacks Snacks](https://stackssnacks.com/). For quarterly ecosystem recaps, subscribe to the [Stacks Foundation newsletter](https://newsletters.stacks.org/). -{% content-ref url="/broken/pages/cd2e8707fe40b8a43e40923a688434e9aaf4922e" %} -[Broken link](/broken/pages/cd2e8707fe40b8a43e40923a688434e9aaf4922e) +{% content-ref url="january-2024.md" %} +[January 2024](january-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/29b9f8cda45db86fe5031ee567341583324e2f6b" %} -[Broken link](/broken/pages/29b9f8cda45db86fe5031ee567341583324e2f6b) +{% content-ref url="february-2024.md" %} +[February 2024](february-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/e7761aa2c81d3c8245dbc54570199f1aebd91325" %} -[Broken link](/broken/pages/e7761aa2c81d3c8245dbc54570199f1aebd91325) +{% content-ref url="march-2024.md" %} +[March 2024](march-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/bbb9712e169fccb44833d8d9f0d98ad2bccd62f2" %} -[Broken link](/broken/pages/bbb9712e169fccb44833d8d9f0d98ad2bccd62f2) +{% content-ref url="april-2024.md" %} +[April 2024](april-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/aec6e9d8a50d144e48a1dfdc8af0e834cd9af457" %} -[Broken link](/broken/pages/aec6e9d8a50d144e48a1dfdc8af0e834cd9af457) +{% content-ref url="may-2024.md" %} +[May 2024](may-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/629cc20de749db943380bddf1d69842a2863033c" %} -[Broken link](/broken/pages/629cc20de749db943380bddf1d69842a2863033c) +{% content-ref url="june-2024.md" %} +[June 2024](june-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/cf07211cab8be8b227dee91931874e3fe5792b8d" %} -[Broken link](/broken/pages/cf07211cab8be8b227dee91931874e3fe5792b8d) +{% content-ref url="july-2024.md" %} +[July 2024](july-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/1fc9a3503ea5c373fb758dc9be7401b5f70501d4" %} -[Broken link](/broken/pages/1fc9a3503ea5c373fb758dc9be7401b5f70501d4) +{% content-ref url="august-2024.md" %} +[August 2024](august-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/db2a454141ac04ca7ea4bc2666e5af5fab4deb68" %} -[Broken link](/broken/pages/db2a454141ac04ca7ea4bc2666e5af5fab4deb68) +{% content-ref url="september-2024.md" %} +[September 2024](september-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/4050fecb50c952b844915fafb1b214eb349e1931" %} -[Broken link](/broken/pages/4050fecb50c952b844915fafb1b214eb349e1931) +{% content-ref url="october-2024.md" %} +[October 2024](october-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/68a55e4003881342d50a527d6f8e683cd5803dde" %} -[Broken link](/broken/pages/68a55e4003881342d50a527d6f8e683cd5803dde) +{% content-ref url="november-2024.md" %} +[November 2024](november-2024.md) {% endcontent-ref %} -{% content-ref url="/broken/pages/bd6ef1fe15c0f8e10163ba8857053effe9eb20da" %} -[Broken link](/broken/pages/bd6ef1fe15c0f8e10163ba8857053effe9eb20da) +{% content-ref url="december-2024.md" %} +[December 2024](december-2024.md) {% endcontent-ref %} diff --git a/docs/press-and-reports/press-and-top-links/2025/README.md b/docs/press-and-reports/press-and-top-links/2025/README.md index 0a4fd73593..c82d3c10a9 100644 --- a/docs/press-and-reports/press-and-top-links/2025/README.md +++ b/docs/press-and-reports/press-and-top-links/2025/README.md @@ -2,4 +2,46 @@ For weekly stories delivered to your inbox, subscribe to [Stacks Snacks](https://stackssnacks.com/). For quarterly ecosystem recaps, subscribe to the [Stacks Foundation newsletter](https://newsletters.stacks.org/). -
IssueTarget
january-2024.mdBroken link
february-2025.mdBroken link
march-2025.mdBroken link
march-2025-1.mdBroken link
march-2025-2.mdBroken link
june-2025.mdBroken link
june-2025-1.mdBroken link
june-2025-2.mdBroken link
june-2025-2-1.mdBroken link
+{% content-ref url="january-2025.md" %} +[January 2025](january-2025.md) +{% endcontent-ref %} + +{% content-ref url="february-2025.md" %} +[February 2025](february-2025.md) +{% endcontent-ref %} + +{% content-ref url="march-2025.md" %} +[March 2025](march-2025.md) +{% endcontent-ref %} + +{% content-ref url="april-2025.md" %} +[April 2025](april-2025.md) +{% endcontent-ref %} + +{% content-ref url="may-2025.md" %} +[May 2025](may-2025.md) +{% endcontent-ref %} + +{% content-ref url="june-2025.md" %} +[June 2025](june-2025.md) +{% endcontent-ref %} + +{% content-ref url="july-2025.md" %} +[July 2025](july-2025.md) +{% endcontent-ref %} + +{% content-ref url="august-2025.md" %} +[August 2025](august-2025.md) +{% endcontent-ref %} + +{% content-ref url="september-2025.md" %} +[September 2025](september-2025.md) +{% endcontent-ref %} + +{% content-ref url="september-2025-1.md" %} +[September 2025 Update 1](september-2025-1.md) +{% endcontent-ref %} + +{% content-ref url="september-2025-2.md" %} +[September 2025 Update 2](september-2025-2.md) +{% endcontent-ref %} diff --git a/docs/reference/README.md b/docs/reference/README.md index 39137d170d..95a4a05bce 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -10,4 +10,4 @@ If you’re an experienced Stacks developer looking to quickly reference a speci ### Looking for references on... -

APIs

Endpoints for interacting with Stacks nodes, signers, sBTC bridge, and the USDCx bridgeBroken link

Clarity

Definitions for types, functions, and keywordsBroken link

Clarinet

CLI commands for developing and deploying contractsBroken link

Clarinet JS SDK

Test and simulate contracts in JavaScriptBroken link

Rendezvous

Property-based testing and fuzzing for ClarityBroken link

Stacks.js

Definitions for functions and types when building frontend/backend scriptsBroken link
+

APIs

Endpoints for interacting with Stacks nodes, signers, sBTC bridge, and the USDCx bridgeapi/stacks-blockchain-api/README.md

Clarity

Definitions for types, functions, and keywordsclarity/functions.md

Clarinet

CLI commands for developing and deploying contractsclarinet/cli-reference.md

Clarinet JS SDK

Test and simulate contracts in JavaScriptclarinet-js-sdk/sdk-reference.md

Rendezvous

Property-based testing and fuzzing for Clarityrendezvous/reference.md

Stacks.js

Definitions for functions and types when building frontend/backend scriptsstacks.js/stacks-wallet/README.md
diff --git a/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md b/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md index f413ee2125..78b3d3ddcb 100644 --- a/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md +++ b/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md @@ -6,7 +6,7 @@ The Nakamoto release brings many new capabilities and improvements to the Stacks blockchain by focusing on a set of core advancements: improving transaction speed, enhancing finality guarantees for transactions, mitigating Bitcoin miner MEV (miner extractable value) opportunities that affect PoX, and boosting robustness against chain reorganizations. This strategic upgrade aims to solidify trust in the Stacks network, offer greater alignment with Bitcoin's immutable nature, and foster an environment ripe for advanced Decentralized Finance (DeFi) applications. The expected outcome is a versatile, scalable, and secure platform that closely integrates with, yet distinctly enhances, the Bitcoin ecosystem. -Learn more: [Broken link](/broken/pages/fac008cad2409afc8de86501f205ee51e148b5af "mention") +Learn more: [What is the Nakamoto Release?](../what-is-the-nakamoto-release.md)
@@ -27,7 +27,7 @@ The main thing exchanges will notice when the Nakamoto rollout is complete is th ### Resources * [Testnet documentation](https://docs.stacks.co/nakamoto-upgrade/nakamoto) -* [API documentation](https://docs.hiro.so/nakamoto/stacks-js) +* [API documentation](../../api/stacks-blockchain-api/README.md) * [Stacks Core Binaries](https://github.com/stacks-network/stacks-core/releases/latest) * [Stacks Signer Binary](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.5.0) * [Stacks Core Docker Images](https://hub.docker.com/r/blockstack/stacks-core/tags?page=1\&name=3.1.0.0.5) diff --git a/docs/reference/node-operations/signer-configuration.md b/docs/reference/node-operations/signer-configuration.md index ed5e7439a5..9e1e1bb8da 100644 --- a/docs/reference/node-operations/signer-configuration.md +++ b/docs/reference/node-operations/signer-configuration.md @@ -24,7 +24,7 @@ The signer configuration file is a TOML file that contains the configuration opt #### Example Configs -Below are sample configuration files for running a Stacks node and signer provided in one place for convenience. You'll need to modify some of these according to the [How to Run a Signer](/broken/pages/261edd335c0b98fb052ad55906fbf90832800453) doc. +Below are sample configuration files for running a Stacks node and signer provided in one place for convenience. You'll need to modify some of these according to the [How to Run a Signer](../../operate/run-a-signer/README.md) doc. #### Testnet Signer @@ -63,9 +63,9 @@ stacks_private_key = "$your_stacks_private_key" Note that the `block_proposal_token` field has changed to `auth_token` in the Stacks node configuration file. {% endhint %} -This is the configuration you'll need to run a Stacks follower node if you are also running a signer. Be sure to change the commented lines to the appropriate data for your setup. If you are not familiar with the process of setting up a signer, be sure to follow the [How to Run a Signer](/broken/pages/261edd335c0b98fb052ad55906fbf90832800453) guide. +This is the configuration you'll need to run a Stacks follower node if you are also running a signer. Be sure to change the commented lines to the appropriate data for your setup. If you are not familiar with the process of setting up a signer, be sure to follow the [How to Run a Signer](../../operate/run-a-signer/README.md) guide. -An overview of all Stacks node configuration options can be found in the [Stacks Node Configuration](/broken/pages/79a6d21c88b879210b9f2036268ace38ae6a02af) doc. +An overview of all Stacks node configuration options can be found in the [Stacks Node Configuration](https://docs.stacks.co/reference/stacks-node-configuration) doc. Additions necessary specifically to run a signer are the `[connection_options]` and `[[events_observer]]` sections and the `stacker = true` line. There are also a few comments detailing other lines that need to change. diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 89deaacb3d..ef2d429dd1 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -12,4 +12,4 @@ This tutorials section consists of end-to-end guides on building complete applic Our tutorials section has launched with its first complete tutorial: the Bitcoin Primer, which gives a holistic introduction to both Bitcoin and Stacks. Additional tutorials are in the works to walk through how to build different things with Stacks. -
Cover image
Bitcoin PrimerA high-level introduction to Bitcoin and how to expand its functionality with Stacks.Broken linkbitcoinprimertutorial.png
+
Cover image
Bitcoin PrimerA high-level introduction to Bitcoin and how to expand its functionality with Stacks.bitcoin-primer/introduction.mdbitcoinprimertutorial.png
From 3b483fc6b85c57be1a3e63e12fd63b1d693cb7f9 Mon Sep 17 00:00:00 2001 From: huth-stacks <230392931+huth-stacks@users.noreply.github.com> Date: Sun, 22 Mar 2026 09:11:20 -0700 Subject: [PATCH 4/4] Point exchange rollout guide to Mesh API docs --- .../nakamoto-rollout-plan/nakamoto-for-exchanges.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md b/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md index 78b3d3ddcb..05707ed91a 100644 --- a/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md +++ b/docs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.md @@ -27,7 +27,7 @@ The main thing exchanges will notice when the Nakamoto rollout is complete is th ### Resources * [Testnet documentation](https://docs.stacks.co/nakamoto-upgrade/nakamoto) -* [API documentation](../../api/stacks-blockchain-api/README.md) +* [API documentation](../../api/stacks-mesh-api/README.md) * [Stacks Core Binaries](https://github.com/stacks-network/stacks-core/releases/latest) * [Stacks Signer Binary](https://github.com/stacks-network/stacks-core/releases/tag/signer-3.1.0.0.5.0) * [Stacks Core Docker Images](https://hub.docker.com/r/blockstack/stacks-core/tags?page=1\&name=3.1.0.0.5)