From 8c0dfccc4e94c6e1e58d83fdc801aed9e25ba8aa Mon Sep 17 00:00:00 2001 From: natebuch Date: Tue, 13 Aug 2024 22:15:49 -0500 Subject: [PATCH 01/21] Update file structure for chainhook references. Add pages for stacks and bitcoin scopes with copy updates. --- .../stacks/chainhook/references/scopes/bitcoin-scopes.mdx | 5 +++++ .../references/{scopes.mdx => scopes/stacks-scopes.mdx} | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx rename content/docs/stacks/chainhook/references/{scopes.mdx => scopes/stacks-scopes.mdx} (99%) diff --git a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx new file mode 100644 index 000000000..7bd729ab6 --- /dev/null +++ b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx @@ -0,0 +1,5 @@ +--- +title: Bitcoin Scopes +description: Reference guide for available scopes for Bitcoin. +toc: false +--- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/references/scopes.mdx b/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx similarity index 99% rename from content/docs/stacks/chainhook/references/scopes.mdx rename to content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx index 955112d6b..ca507fd06 100644 --- a/content/docs/stacks/chainhook/references/scopes.mdx +++ b/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx @@ -1,6 +1,6 @@ --- -title: Scopes -description: Reference guide for available scopes for Stacks and Bitcoin. +title: Stacks Scopes +description: Reference guide for available scopes for Stacks. toc: false --- From ddb44034b58a935863f816e1dff9bd33c03ed317 Mon Sep 17 00:00:00 2001 From: natebuch Date: Wed, 14 Aug 2024 00:08:37 -0500 Subject: [PATCH 02/21] Standarize code highlights and parameter descriptions. Add regex code example. --- .../references/scopes/stacks-scopes.mdx | 82 ++++++++++++------- 1 file changed, 53 insertions(+), 29 deletions(-) diff --git a/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx index ca507fd06..f74b6a561 100644 --- a/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx +++ b/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx @@ -6,20 +6,13 @@ toc: false import { Root, API, APIExample } from '@/components/layout'; import { Property } from 'fumadocs-ui/components/api' -import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'; import { Badge } from '@/components/ui/badge'; import { InlineCode } from '@/components/inline-code'; -Scopes are parameters you use to define the "if this" logic of your chainhook. In other words, scopes specify what on-chain events you are looking to monitor and track. For more information on Chainhook design, please view [predicate design](/stacks/chainhook/concepts/predicate-design). - -## Installation - -```console -brew install chainhook -``` +Stacks scopes are parameters you use to define the `if this` specification logic of your Chainhook on the Stacks blockchain. In other words, scopes specify what on-chain events you are looking to monitor and track. For more information on Chainhook design, please view [predicate design](/stacks/chainhook/concepts/predicate-design). @@ -55,7 +48,7 @@ The `equals` property is a 32 bytes hex encoded type used to specify the exact t { "if_this": { "scope": "txid", - "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" + "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" // [!code highlight] } } ``` @@ -125,40 +118,40 @@ The `between` property specifies a range of block heights to match, inclusive of { "if_this": { "scope": "block_height", - "equals": 141200 + "equals": 141200 // [!code highlight] } } ``` ```json - // [!code word:higher_than] + // [!code word:block_height] { "if_this": { "scope": "block_height", - "higher_than": 10000 + "higher_than": 10000 // [!code highlight] } } ``` ```json - // [!code word:lower_than] + // [!code word:block_height] { "if_this": { "scope": "block_height", - "lower_than": 10000 + "lower_than": 10000 // [!code highlight] } } ``` ```json - // [!code word:between] + // [!code word:block_height] { "if_this": { "scope": "block_height", - "between": [0, 10000] + "between": [0, 10000] // [!code highlight] } } ``` @@ -181,7 +174,7 @@ The `ft_transfer` scope allows you to query transactions based on fungible token -The `asset_identifier` property specifies the fully qualified asset identifier to observe, such as `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token::cbtc`. +The `asset_identifier` property specifies the fully qualified asset identifier to observe. @@ -211,12 +204,13 @@ The `actions` property specifies the types of token actions to observe, such as "if_this": { "scope": "ft_transfer", "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token::cbtc", - "actions": ["transfer"] + "actions": ["transfer"] // [!code highlight] } } ``` + // [!code word:ft_transfer] ```json { "if_this": { @@ -245,7 +239,7 @@ The `nft_transfer` scope allows you to query transactions based on non-fungible -The `asset_identifier` property specifies the fully qualified asset identifier to observe, such as `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys`. +The `asset_identifier` property specifies the fully qualified asset identifier to observe. @@ -275,13 +269,14 @@ The `actions` property specifies the types of NFT actions to observe, such as `m "if_this": { "scope": "nft_transfer", "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys", - "actions": ["mint"] + "actions": ["mint"] // [!code highlight] } } ``` ```json + // [!code word:nft_transfer] { "if_this": { "scope": "nft_transfer", @@ -320,7 +315,10 @@ The `actions` property specifies the types of STX token actions to observe, such - Scoping by STX token transfer + By STX token transfer + + + Passing all actions @@ -329,7 +327,18 @@ The `actions` property specifies the types of STX token actions to observe, such { "if_this": { "scope": "stx_transfer", - "actions": ["transfer", "lock"] + "actions": ["transfer"] // [!code highlight] + } + } + ``` + + + ```json + // [!code word:stx_transfer] + { + "if_this": { + "scope": "stx_transfer", + "actions": ["mint", "transfer", "burn", "lock"] // [!code highlight] } } ``` @@ -375,7 +384,10 @@ The `matches_regex` property is used for matching an event that regex matches wi - Scoping by print event + Using contains + + + Using matches_regex @@ -385,7 +397,19 @@ The `matches_regex` property is used for matching an event that regex matches wi "if_this": { "scope": "print_event", "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09", - "contains": "monkey" + "contains": "monkey" // [!code highlight] + } + } + ``` + + + ```json + // [!code word:print_event] + { + "if_this": { + "scope": "print_event", + "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09", + "matches_regex": "(?:^|\\W)monkey(?:$|\\W)" // [!code highlight] } } ``` @@ -435,7 +459,7 @@ The `method` property specifies the specific method within the contract to obser "if_this": { "scope": "contract_call", "contract_identifier": "SP000000000000000000002Q6VF78.pox", - "method": "stack-stx" + "method": "stack-stx" // [!code highlight] } } ``` @@ -483,22 +507,22 @@ The `implement_trait` property specifies the contract trait to observe. ```json - // [!code word:deployer] + // [!code word:contract_deployment] { "if_this": { "scope": "contract_deployment", - "deployer": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" + "deployer": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" // [!code highlight] } } ``` ```json - // [!code word:implement_trait] + // [!code word:contract_deployment] { "if_this": { "scope": "contract_deployment", - "implement_trait": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sip09-protocol" + "implement_trait": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sip09-protocol" // [!code highlight] } } ``` From 5418271ce2a436cf2910c72cc1a1d6e4431ca344 Mon Sep 17 00:00:00 2001 From: natebuch Date: Thu, 15 Aug 2024 23:33:20 -0500 Subject: [PATCH 03/21] Add reference page for bitcoin scopes. --- .../references/scopes/bitcoin-scopes.mdx | 392 +++++++++++++++++- 1 file changed, 391 insertions(+), 1 deletion(-) diff --git a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx index 7bd729ab6..6949b9779 100644 --- a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx +++ b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx @@ -2,4 +2,394 @@ title: Bitcoin Scopes description: Reference guide for available scopes for Bitcoin. toc: false ---- \ No newline at end of file +--- + +import { Root, API, APIExample } from '@/components/layout'; +import { Property } from 'fumadocs-ui/components/api' + +import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'; +import { Badge } from '@/components/ui/badge'; +import { + Tooltip, + TooltipContent, + TooltipProvider, + TooltipTrigger, +} from "@/components/ui/tooltip"; + +import { InlineCode } from '@/components/inline-code'; + +Bitcoin scopes are parameters you use to define the `if this` specification logic of your Chainhook on the Bitcoin blockchain. In other words, scopes specify what on-chain events you are looking to monitor and track. For more information on Chainhook design, please view [predicate design](/stacks/chainhook/concepts/predicate-design). + + + + + +
+ +

`txid`

+ +The `txid` scope allows you to query transactions based on their transaction ID. This is particularly useful for tracking specific transactions or auditing transaction histories. + +## Parameters + + + +The `equals` property is a 32 byte hex encoded type used to specify the exact transaction ID to match. + + + +
+ + + + + + + By transaction ID + + + + + ```json + // [!code word:txid] + { + "if_this": { + "scope": "txid", + "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" // [!code highlight] + } + } + ``` + + + + + + + + + +
+ +

`outputs`

+ +The `outputs` scope allows you to query blocks based on the payload returned by the specified operation. + +## Parameters + + + +The `operation` property is used to identify the Bitcoin operation that will trigger Chainhook as it observes Bitcoin transactions. The available operations are `op_return`, `p2pkh`, `p2sh`,`p2wpkh` and `p2wsh`. + + + +
+ + + + + + + Using op_return + + + Using p2pkh + + + Using p2sh + + + Using p2wpkh + + + Using p2wsh + + + Using descriptor + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "op_return": { // [!code highlight] + "equals": "0xbtc21000042stx016" // [!code highlight] + } + } + } + ``` + + + + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. + + + The `starts_with` property specifies the starting characters of the string or 32 byte encoded hex to match. + + + The `ends_with` property specifies the ending characters of the string or 32 byte encoded hex to match. + + + + + The `op_return` operation allows for `equals`, `starts_with` and `ends_with` for matching against the desired input. + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "p2kph": { // [!code highlight] + "equals": "0xbtc21000042stx016" // [!code highlight] + } + } + } + ``` + + + + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. + + + + + `p2pkh`(Pay-to-Public-Key-Hash) is a Bitcoin transaction output script type that allows users to send funds to a recipient's hashed public key, providing security and privacy by concealing the actual public key. + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "p2sh": { // [!code highlight] + "equals": "0xbtc21000042stx016" // [!code highlight] + } + } + } + ``` + + + + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. + + + + + `p2sh`(Pay-to-Script-Hash) is a Bitcoin transaction output script type that enables users to send funds to a script instead of a public key, allowing for more complex transaction conditions and multi-signature addresses. + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "p2wpkh": { // [!code highlight] + "equals": "0xbtc21000042stx016" // [!code highlight] + } + } + } + ``` + + + + The `equals` property specifies the exact characters of the string to match. + + + + + `p2wpkh`(Pay-to-Witness-Public-Key-Hash) is a Bitcoin transaction output script type used in Segregated Witness (SegWit) that allows for more efficient and secure transactions by separating the witness data from the transaction data and storing it in a separate block. + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "p2wsh": { // [!code highlight] + "equals": "0xbtc21000042stx016" // [!code highlight] + } + } + } + ``` + + + + The `equals` property specifies the exact characters of the string to match. + + + + + `p2wsh` (Pay-to-Witness-Script-Hash) is a Bitcoin transaction output script type used in Segregated Witness (SegWit) that enables users to send funds to a hashed script, allowing for more complex transaction conditions and greater scalability by separating the script from the transaction data. + + + + + ```json + // [!code word:outputs] + { + "if_this": { + "scope": "outputs", + "descriptor": { + "expression": "wpkh(tprv8ZgxMBicQKsPePxn6j3TjvB2MBzQkuhGgc6oRh2WZancZQgxktcnjZJ44XdsRiw3jNkbVTK9JW6KFHvnRKgAMtSyuBevMJprSkZ4PTfmTgV/84'/1'/0'/0/*)", // [!code highlight] + "range": [0, 3] // [!code highlight] + } + } + } + ``` + + + + The `expression` property specifies the exact characters of the string to match. + + + The `range` property specifies and array of integers representing the desired indexes. + + + + + + + Wallet descriptors provide a compact and semi-standardized method for describing how scripts and addresses within a wallet are generated. Chainhook users that want to track addresses derived from an extended pubkey or a multisig-wallet can now rely on this feature instead of defining one predicate per address. + For example, let's say we wanted to track the first 3 addresses generated by the following descriptor: + + ``` + wpkh(tprv8ZgxMBicQKsPePxn6j3TjvB2MBzQkuhGgc6oRh2WZancZQgxktcnjZJ44XdsRiw3jNkbVTK9JW6KFHvnRKgAMtSyuBevMJprSkZ4PTfmTgV/84'/1'/0'/0/*) + ``` + + This descriptor reads: describe a P2WPKH output with the specified extended public key, and it produces these BIP84 addresses: + + ``` + bcrt1qzy2rdyvu8c57qd8exyyp0mw7dk5drsu9ewzdsu + bcrt1qsfsjnagr29m8h3a3vdand2s85cg4cefkcwk2fy + bcrt1qauewfytqe5mtr0xwp786r6fl39kmum2lr65kmj + ``` + + + + + + + + + + + + +
+ +

`stacks_protocol`

+ +The `stacks_protocol` scope allows you query Bitcoin transactions related to the Stacks Proof of Transfer (PoT) [concensus mechanism](https://www.hiro.so/blog/securing-web3-apps-through-bitcoin-an-overview-of-stacks-consensus-mechanism). + +## Parameters + + + +The `operation` property is used to identify the Stacks operation that will trigger Chainhook as it observes Bitcoin transactions. The available operations are `block_committed`, `leader_registered`, `inscription_feed`, `stx_transferred` and `stx_locked`. + + + +
+ + + + + + + Using block_committed + + + Using leader_registered + + + Using inscription_feed + + + Using stx_transferred + + + Using stx_locked + + + + + ```json + // [!code word:stacks_protocol] + { + "if_this": { + "scope": "stacks_protocol", + "operation": "block_committed" // [!code highlight] + } + } + ``` + + + + ```json + // [!code word:stacks_protocol] + { + "if_this": { + "scope": "stacks_protocol", + "operation": "leader_registered" // [!code highlight] + } + } + ``` + + + + ```json + // [!code word:stacks_protocol] + { + "if_this": { + "scope": "stacks_protocol", + "operation": "inscription_feed" // [!code highlight] + } + } + ``` + + + `inscription_feed` observes the reveal and transfer of an Ordinal inscription. + + + + + ```json + // [!code word:stacks_protocol] + { + "if_this": { + "scope": "stacks_protocol", + "operation": "stx_transferred" // [!code highlight] + } + } + ``` + + + + ```json + // [!code word:stacks_protocol] + { + "if_this": { + "scope": "stacks_protocol", + "operation": "stx_locked" // [!code highlight] + } + } + ``` + + + + + + + + \ No newline at end of file From bd1eb5b8cb2a21c364ee0e695f6a04c0b58cdfa8 Mon Sep 17 00:00:00 2001 From: natebuch Date: Fri, 16 Aug 2024 13:17:16 -0500 Subject: [PATCH 04/21] Fix styling and content issues. --- .../chainhook/references/scopes/bitcoin-scopes.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx index 6949b9779..ae2cff059 100644 --- a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx +++ b/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx @@ -122,13 +122,13 @@ The `operation` property is used to identify the Bitcoin operation that will tri ``` - + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. - + The `starts_with` property specifies the starting characters of the string or 32 byte encoded hex to match. - + The `ends_with` property specifies the ending characters of the string or 32 byte encoded hex to match. @@ -152,7 +152,7 @@ The `operation` property is used to identify the Bitcoin operation that will tri ``` - + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. @@ -176,7 +176,7 @@ The `operation` property is used to identify the Bitcoin operation that will tri ``` - + The `equals` property specifies the exact characters of the string or 32 byte encoded hex to match. From 583af328da90193e7a8701c181e323291f8519e5 Mon Sep 17 00:00:00 2001 From: natebuch Date: Fri, 16 Aug 2024 13:18:33 -0500 Subject: [PATCH 05/21] Update predicate design page. --- .../chainhook/concepts/predicate-design.mdx | 94 +++++++++---------- 1 file changed, 46 insertions(+), 48 deletions(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index f34a6486e..4b325fc0e 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -1,64 +1,62 @@ --- title: Predicate design description: Predicates are the building blocks of Chainhook. +toc: true --- -The core design of chainhooks revolves around the concept of predicates. Each individual chainhook has a customizable predicate that specifies what information you are scanning for. +The core design of Chainhook revolves around the concept of predicates. Each individual Chainhook has a customizable predicate that specifies what the Bitcoin or Stacks blockchain data you are scanning for. -Predicates are defined in an `if-this`, `then-that` format. You'll write your condition in the `if-this` condition template and use `then-that` to output the result. +The `predicate` is a JSON object that is composed of elements that allows you to: +- Identify the predicate in the payload Chainhook returns +- Determine the blockchain and network Chainhook will evaluate the predicate against +- Define the scope Chainhook uses to observe transactions and their data +- Deliver the Chainhook payload to specfied end point or file destination +- Setup Stacks and Bitcoin specific configurations for the Chainhook payload -## `if-this` - -The `if-this` predicate design can use the following attributes to define the predicates. The 'scope' parameter is mandatory to use with any other parameters. +## Predicate JSON object ```json -// [!code word:if_this] -{ - "if_this": { - "scope": "txid", - "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" + { + // Chain configuration + "chain": "stacks", + // Idenfication + "uuid": "1", + "name": "STX_Transfer_Predicate", + "version": 1.0, + // Network definition + "networks": { + "testnet": { + // if_this specification + "if_this": { + "scope": "stx_transfer", + "actions": ["transfer"] + }, + // then_that specification + "then_that": { + "file_append": { + "path": "/tmp/events.json" + } + }, + // Additional blockchain specific configurations + "start_block": 21443, + "decode_clarity_values": true, + "expire_after_occurrence": 1, + } + } } -} -``` - -Other available parameters: + ``` -- `equals` -- `op_return` -- `ends_with` -- `p2pkh` -- `p2sh` -- `p2wpkh` -- `operation` + - - For more information on predicate definitions, refer to the [scopes](/stacks/chainhook/references/scopes) reference page. - - -## `then-that` +With Chainhook [installed](/stacks/chainhook/installation), the following commands allow you to generate a predicate template for the specified blockchain. -The `then-that` predicate design can use the following attributes to output the result based on the `if-this` condition defined. - -```jsonc -// [!code word:file_append] -{ - "then_that": { - "file_append": { - "path": "/tmp/events.json", - }, - }, -} ``` - -```jsonc -// [!code word:http_post] -{ - "then_that": { - "http_post": { - "url": "https://example.com/api/v1/events", - "authorization_header": "Bearer 1234567890" - } - } -} +chainhook predicates new your-bitcoin-predicate.json --bitcoin +``` +``` +chainhook predicates new your-stacks-predicate.json --stacks ``` + + + From eec069cfe0777c4733d7c0f088d210e37a26a031 Mon Sep 17 00:00:00 2001 From: natebuch Date: Fri, 16 Aug 2024 13:19:41 -0500 Subject: [PATCH 06/21] Create new concepts pages, update meta file. --- .../bitcoin-predicate-configurations.mdx | 5 +++ .../concepts/general-configuration.mdx | 5 +++ .../concepts/if-this-specification.mdx | 24 ++++++++++++++ .../stacks-predicate-configurations.mdx | 5 +++ .../concepts/then-that-specification.mdx | 32 +++++++++++++++++++ content/docs/stacks/chainhook/meta.json | 10 ++++-- 6 files changed, 78 insertions(+), 3 deletions(-) create mode 100644 content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx create mode 100644 content/docs/stacks/chainhook/concepts/general-configuration.mdx create mode 100644 content/docs/stacks/chainhook/concepts/if-this-specification.mdx create mode 100644 content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx create mode 100644 content/docs/stacks/chainhook/concepts/then-that-specification.mdx diff --git a/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx b/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx new file mode 100644 index 000000000..b7080ea5f --- /dev/null +++ b/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx @@ -0,0 +1,5 @@ +--- +title: Bitcoin Predicate Configurations +description: Bitcoin predicate configurations allow you to determine how Chainhook builds its payload for your predicate. +toc: true +--- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/general-configuration.mdx b/content/docs/stacks/chainhook/concepts/general-configuration.mdx new file mode 100644 index 000000000..02c0348ba --- /dev/null +++ b/content/docs/stacks/chainhook/concepts/general-configuration.mdx @@ -0,0 +1,5 @@ +--- +title: General Predicate Configuration +description: Predicate identifiers, blockchain and network(s). +toc: true +--- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/if-this-specification.mdx b/content/docs/stacks/chainhook/concepts/if-this-specification.mdx new file mode 100644 index 000000000..9680b4679 --- /dev/null +++ b/content/docs/stacks/chainhook/concepts/if-this-specification.mdx @@ -0,0 +1,24 @@ +--- +title: If_this Specification +description: The if_this specification is where the scope for your predicate is defined. +toc: true +--- + + +## The if_this specification + +The `if-this` predicate design can use the following attributes to define the predicates. The 'scope' parameter is mandatory to use with any other parameters. + +```json +// [!code word:if_this] +{ + "if_this": { + "scope": "txid", + "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" + } +} +``` + + + For more information on predicate definitions, refer to the [Bitcoin scopes](/stacks/chainhook/references/scopes/bitcoin-scopes) and[Stacks scope](/stacks/chainhook/references/scopes/stacks-scopes) reference pages. + \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx b/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx new file mode 100644 index 000000000..ca111f6c3 --- /dev/null +++ b/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx @@ -0,0 +1,5 @@ +--- +title: Stacks Predicate Configurations +description: Stacks predicate configurations allow you to determine how Chainhook builds its payload for your predicate. +toc: true +--- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/then-that-specification.mdx b/content/docs/stacks/chainhook/concepts/then-that-specification.mdx new file mode 100644 index 000000000..42becfea6 --- /dev/null +++ b/content/docs/stacks/chainhook/concepts/then-that-specification.mdx @@ -0,0 +1,32 @@ +--- +title: Then_that Specification +description: The if_this specification allows you to define where Chainhook delivers its payload when triggered. +toc: true +--- + +## The then_that specification + +The `then-that` predicate design can use the following attributes to output the result based on the `if-this` condition defined. + +```jsonc +// [!code word:file_append] +{ + "then_that": { + "file_append": { + "path": "/tmp/events.json", + }, + }, +} +``` + +```jsonc +// [!code word:http_post] +{ + "then_that": { + "http_post": { + "url": "https://example.com/api/v1/events", + "authorization_header": "Bearer 1234567890" + } + } +} +``` \ No newline at end of file diff --git a/content/docs/stacks/chainhook/meta.json b/content/docs/stacks/chainhook/meta.json index 2b6e736d5..2b5ce5f16 100644 --- a/content/docs/stacks/chainhook/meta.json +++ b/content/docs/stacks/chainhook/meta.json @@ -8,14 +8,18 @@ "quickstart", "---Concepts---", "concepts/predicate-design", - "concepts/stacks-predicates", - "concepts/bitcoin-predicates", + "concepts/general-configration", + "concepts/if-this-specification", + "concepts/then-that-specification", + "concepts/stacks-predicate-configurations", + "concepts/bitcoin-predicate-configurations", "---Guides---", "guides/register-chainhooks-on-devnet", "guides/chainhook-as-a-service", "guides/chainhook-as-a-service-with-stacks-node", "guides/observing-contract-calls", "---Reference---", - "...references" + "references/scopes/bitcoin-scopes", + "references/scopes/stacks-scopes" ] } \ No newline at end of file From 051e38088a54a60584021f9da7a40abc0c1b5c5a Mon Sep 17 00:00:00 2001 From: natebuch Date: Sat, 17 Aug 2024 02:26:14 -0500 Subject: [PATCH 07/21] Update predicate design page. --- .../chainhook/concepts/predicate-design.mdx | 321 ++++++++++++++++-- 1 file changed, 290 insertions(+), 31 deletions(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 4b325fc0e..2a59c8e86 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -6,57 +6,316 @@ toc: true The core design of Chainhook revolves around the concept of predicates. Each individual Chainhook has a customizable predicate that specifies what the Bitcoin or Stacks blockchain data you are scanning for. -The `predicate` is a JSON object that is composed of elements that allows you to: -- Identify the predicate in the payload Chainhook returns -- Determine the blockchain and network Chainhook will evaluate the predicate against -- Define the scope Chainhook uses to observe transactions and their data -- Deliver the Chainhook payload to specfied end point or file destination -- Setup Stacks and Bitcoin specific configurations for the Chainhook payload + + Commands outlined here will require that you have installed Chainhook [directly](/stacks/chainhook/installation). + + +## Predicate design +Below is the general strucure of the `predicate` JSON with its primary elements. These elements and their values are required. -## Predicate JSON object +- Chainhook will evaluate the predicate against the specfied blockchain specified in `chain`. +- The `uuid` will be returned in the Chainhook payload, providing a record of the predicate that triggers it. +- Identify your predicate for your DApp using `name` and `version`. ```json { - // Chain configuration "chain": "stacks", - // Idenfication "uuid": "1", "name": "STX_Transfer_Predicate", - "version": 1.0, - // Network definition + "version": 1, "networks": { - "testnet": { - // if_this specification - "if_this": { - "scope": "stx_transfer", - "actions": ["transfer"] - }, - // then_that specification - "then_that": { - "file_append": { - "path": "/tmp/events.json" - } - }, - // Additional blockchain specific configurations - "start_block": 21443, - "decode_clarity_values": true, - "expire_after_occurrence": 1, - } + // Other configurations } } ``` + You can use the following command to verify your predicate: + ``` + chainhook predicate check your-predicate-file.json --mainnet + ``` + + +## Networks -With Chainhook [installed](/stacks/chainhook/installation), the following commands allow you to generate a predicate template for the specified blockchain. +The `networks` element contains an object who's key determines the blockchain network you want Chainhook to scan. +- This object's value will contain the `if_this` and then `then_that` specifications. +- Multple networks can be specified in the `networks` element. +```json + "networks": { + "mainnet": { + // if_this and then_that specifications + // Other configurations + }, + "testnet": { + // if_this and then_that specifications + // Other configurations + }, + } ``` -chainhook predicates new your-bitcoin-predicate.json --bitcoin + +## if_this specification + +The `predicate` identifies what data you want Chainhook to scan for using the `scope` define within the `if_this` specification. Additional arguments specific to the `scope` will also be passed here. + +```json + // [!code word:if_this] + // [!code word:scope] + { + "if_this": { + "scope": "contract_call", + "contract_identifier": "STJ81C2WPQHFB6XTG518JKPABWM639R2X37VFKJV.simple-vote-v0", + "method": "cast-vote" + } + } ``` + +## then_that specification + +Chainhook delivers the payload when it is triggered by your `predicate` using the `then_that` specification. There are 2 options available: + +1. `file_append` +2. `http_post` + +When choosing to use file_append, specify the path where Chainhook will post the payload data. + +```json +// [!code word:then_that] +// [!code word:file_append] +{ + "then_that": { + "file_append": { + "path": "/tmp/events.json" + } + } +} ``` -chainhook predicates new your-stacks-predicate.json --stacks + +When using `http_post`, specify the endpoint's `url` and `authorization_header`. + +```json +// [!code word:then_that] +// [!code word:http_post] +{ + "then_that": { + "http_post": { + "url": "https://webhook.site/abc123456-789e-0fgh-1ijk-23lmno456789", + "authorization_header": "12345" + } + } +} ``` + + Chainhook requires `https` to post to your endpoint. You can use a service like [LocalTunnel](https://github.com/localtunnel/localtunnel) to test locally or a site like [WebhookSite](https://webhook.site). +## Blockchain specific configurations + + + + + ```json + { + "chain": "bitcoin", + "uuid": "1", + "name": "Wrap BTC", + "version": 1, + "networks": { + "testnet": { + "if_this": { + "scope": "ordinals_protocol", + "operation": "inscription_feed" + }, + "then_that": { + "http_post": { + "url": "http://localhost:3000/api/v1/ordinals", + "authorization_header": "Bearer cn389ncoiwuencr" + } + }, + "start_block": 10200 + // Additional configurations + }, + "mainnet": { + "if_this": { + "scope": "ordinals_protocol", + "operation": "inscription_feed" + }, + "then_that": { + "http_post": { + "url": "http://my-protocol.xyz/api/v1/ordinals", + "authorization_header": "Bearer cn389ncoiwuencr" + } + }, + "start_block": 90232 + // Additional configurations + } + } + } + ``` + + + + The following additional configurations can be used to improve the performance of Chainhook by preventing a full scan of the blockchain. + + Ignore any block before the given block: + + ```json + "start_block": 101 + ``` + + Ignore any block after the given block: + + ```json + "end_block": 201 + ``` + + Stop evaluating a chainhook after a given number of occurrences are found: + + ```json + "expire_after_occurrence": 1 + ``` + + Don't include proofs: + + ```json + "include_proof": false + ``` + + Don't include proofs: + + ```json + "include_proof": false + ``` + + Don't include Bitcoin transaction inputs in the payload: + + ```json + "include_inputs": false + ``` + + Don't include Bitcoin transaction outputs in the payload: + + ```json + "include_outputs": false + ``` + + Don't include Bitcoin transaction outputs in the payload: + + ```json + "include_outputs": false + ``` + + Don't include Bitcoin transaction witnesses in the payload: + + ```json + "include_witness": false + ``` + + Don't include Bitcoin transaction witnesses in the payload: + + ```json + "include_witness": false + ``` + + + + + The following command allows you to generate a predicate template for the Bitcoin blockchain. + ``` + chainhook predicates new your-bitcoin-predicate.json --bitcoin + ``` + + + + + + + ```json + { + "chain": "stacks", + "uuid": "1", + "name": "Contract-Call-Chainhook", + "version": 1, + "networks": { + "testnet": { + "if_this": { + "scope": "contract_call", + "contract_identifier": "STJ81C2WPQHFB6XTG518JKPABWM639R2X37VFKJV.simple-vote-v0", + "method": "cast-vote" + }, + "then_that": { + "file_append": { + "path": "/tmp/events.json" + } + }, + "start_block": 21443 + // Additional configurations + }, + "mainnet": { + "if_this": { + "scope": "contract_call", + "contract_identifier": "STJ81C2WPQHFB6XTG518JKPABWM639R2X37VFKJV.simple-vote-v0", + "method": "cast-vote" + }, + "then_that": { + "http_post": { + "url": "http://my-protocol.xyz/api/v1/ordinals", + "authorization_header": "Bearer cn389ncoiwuencr" + } + }, + "start_block": 142221 + // Additional configurations + } + } + } + ``` + + + + Thse additional configurations can be used to improve the performance of Chainhook by preventing a full scan of the blockchain: + + Ignore any block before the given block: + + ```json + "start_block": 101 + ``` + + Ignore any block after the given block: + + ```json + "end_block": 201 + ``` + + Stop evaluating chainhook after a given number of occurrences found: + + ```json + "expire_after_occurrence": 1 + ``` + + Include decoded Clarity values in the payload: + + ```json + "decode_clarity_values": true + ``` + + Include the contract ABI for transactions that deploy contracts: + + ```json + "include_contract_abi": true + ``` + + + + + The following command allows you to generate a predicate template for the Stacks blockchain. + ``` + chainhook predicates new your-stacks-predicate.json --stacks + ``` + + + + + From 11798e670d015804b2252a51069c2f02a59c7155 Mon Sep 17 00:00:00 2001 From: natebuch Date: Sat, 17 Aug 2024 02:26:43 -0500 Subject: [PATCH 08/21] Remove unneeded files. --- .../bitcoin-predicate-configurations.mdx | 5 --- .../concepts/general-configuration.mdx | 5 --- .../concepts/if-this-specification.mdx | 24 -------------- .../stacks-predicate-configurations.mdx | 5 --- .../concepts/then-that-specification.mdx | 32 ------------------- 5 files changed, 71 deletions(-) delete mode 100644 content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx delete mode 100644 content/docs/stacks/chainhook/concepts/general-configuration.mdx delete mode 100644 content/docs/stacks/chainhook/concepts/if-this-specification.mdx delete mode 100644 content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx delete mode 100644 content/docs/stacks/chainhook/concepts/then-that-specification.mdx diff --git a/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx b/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx deleted file mode 100644 index b7080ea5f..000000000 --- a/content/docs/stacks/chainhook/concepts/bitcoin-predicate-configurations.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Bitcoin Predicate Configurations -description: Bitcoin predicate configurations allow you to determine how Chainhook builds its payload for your predicate. -toc: true ---- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/general-configuration.mdx b/content/docs/stacks/chainhook/concepts/general-configuration.mdx deleted file mode 100644 index 02c0348ba..000000000 --- a/content/docs/stacks/chainhook/concepts/general-configuration.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: General Predicate Configuration -description: Predicate identifiers, blockchain and network(s). -toc: true ---- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/if-this-specification.mdx b/content/docs/stacks/chainhook/concepts/if-this-specification.mdx deleted file mode 100644 index 9680b4679..000000000 --- a/content/docs/stacks/chainhook/concepts/if-this-specification.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: If_this Specification -description: The if_this specification is where the scope for your predicate is defined. -toc: true ---- - - -## The if_this specification - -The `if-this` predicate design can use the following attributes to define the predicates. The 'scope' parameter is mandatory to use with any other parameters. - -```json -// [!code word:if_this] -{ - "if_this": { - "scope": "txid", - "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" - } -} -``` - - - For more information on predicate definitions, refer to the [Bitcoin scopes](/stacks/chainhook/references/scopes/bitcoin-scopes) and[Stacks scope](/stacks/chainhook/references/scopes/stacks-scopes) reference pages. - \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx b/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx deleted file mode 100644 index ca111f6c3..000000000 --- a/content/docs/stacks/chainhook/concepts/stacks-predicate-configurations.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Stacks Predicate Configurations -description: Stacks predicate configurations allow you to determine how Chainhook builds its payload for your predicate. -toc: true ---- \ No newline at end of file diff --git a/content/docs/stacks/chainhook/concepts/then-that-specification.mdx b/content/docs/stacks/chainhook/concepts/then-that-specification.mdx deleted file mode 100644 index 42becfea6..000000000 --- a/content/docs/stacks/chainhook/concepts/then-that-specification.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Then_that Specification -description: The if_this specification allows you to define where Chainhook delivers its payload when triggered. -toc: true ---- - -## The then_that specification - -The `then-that` predicate design can use the following attributes to output the result based on the `if-this` condition defined. - -```jsonc -// [!code word:file_append] -{ - "then_that": { - "file_append": { - "path": "/tmp/events.json", - }, - }, -} -``` - -```jsonc -// [!code word:http_post] -{ - "then_that": { - "http_post": { - "url": "https://example.com/api/v1/events", - "authorization_header": "Bearer 1234567890" - } - } -} -``` \ No newline at end of file From fbcd8ad550d3223bb37c01aeed6d4e814f01412a Mon Sep 17 00:00:00 2001 From: natebuch Date: Sat, 17 Aug 2024 02:38:49 -0500 Subject: [PATCH 09/21] Update file title. Fix issues with copy. --- content/docs/stacks/chainhook/concepts/predicate-design.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 2a59c8e86..7348513ac 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -1,5 +1,5 @@ --- -title: Predicate design +title: Predicate Design description: Predicates are the building blocks of Chainhook. toc: true --- From d4d40d476606d197a676b725c0917cbae4926dfe Mon Sep 17 00:00:00 2001 From: natebuch Date: Sat, 17 Aug 2024 02:39:40 -0500 Subject: [PATCH 10/21] Remove http_post from guide, update references to new predicate design page. --- .../guides/observing-contract-calls.mdx | 27 +++---------------- 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index 48a35f4c1..1b7cefa89 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -72,7 +72,7 @@ To begin, you need to configure the `predicate` to target the voting contract. A ``` - This block height of `21443` represents when the voting contract was deployed. For more details on optional configurations, check out the [Stacks predicates](/stacks/chainhook/concepts/stacks-predicates#additional-configurations-available) page. + This block height of `21443` represents when the voting contract was deployed. For more details on optional configurations and other predicate elements, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) page. Next, define the scope of the `predicate` within the `if_this` specification. @@ -100,12 +100,9 @@ The `contract_call` scope allows Chainhook to observe blockchain data when the s ``` -Finally, define how Chainhook delivers the payload when it is triggered by your `predicate` using the `then_that` specification. There are 2 options available: +Finally, define how Chainhook delivers the payload when it is triggered by your `predicate` using the `then_that` specification. -1. `file_append` -2. `http_post` - -When choosing to use file_append, specify the path where Chainhook will post the payload data. +Using `file_append`, specify the path where Chainhook will post the payload data. ```json title="contract-call-chainhook.json" // [!code word:file_append] @@ -118,20 +115,6 @@ When choosing to use file_append, specify the path where Chainhook will post the } ``` -When using `http_post`, specify the endpoint's `url` and `authorization_header`. - -```json title="contract-call-chainhook.json" -// [!code word:http_post] -{ - "then_that": { - "http_post": { - "url": "https://webhook.site/abc123456-789e-0fgh-1ijk-23lmno456789", - "authorization_header": "12345" - } - } -} -``` - ```json @@ -162,10 +145,6 @@ When using `http_post`, specify the endpoint's `url` and `authorization_header`. - - Chainhook requires `https` to post to your endpoint. You can use a service like [LocalTunnel](https://github.com/localtunnel/localtunnel) to test locally or a site like [WebhookSite](https://webhook.site). - - From aaa6210cffa5ac5c6e43e47dc7f94dfad1c9ea74 Mon Sep 17 00:00:00 2001 From: natebuch Date: Sun, 18 Aug 2024 22:23:16 -0500 Subject: [PATCH 11/21] Update links to predicate design and stacks scope pages. Update copy around predicate requirements. --- .../chainhook/guides/observing-contract-calls.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index 1b7cefa89..725ef9ec6 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -47,9 +47,9 @@ There are 3 main components to your `predicate` that you need to address: 2. Defining the scope and targeting the function you want to observe 3. Defining the payload destination -To begin, you need to configure the `predicate` to target the voting contract. A valid `predicate` must: +To begin, you need to configure the `predicate` to target the voting contract: -- Specify the `testnet` network object +- Specify `testnet` in the network object. - Set the `start_block` property to 21443This value represents the block height that our voting contract was deployed at.. ```json title="contract-call-chainhook.json" @@ -71,10 +71,6 @@ To begin, you need to configure the `predicate` to target the voting contract. A } ``` - - This block height of `21443` represents when the voting contract was deployed. For more details on optional configurations and other predicate elements, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) page. - - Next, define the scope of the `predicate` within the `if_this` specification. The `contract_call` scope allows Chainhook to observe blockchain data when the specified function is directly called from its contract. @@ -145,6 +141,12 @@ Using `file_append`, specify the path where Chainhook will post the payload data + + + For more details on optional configurations, other predicate elements and scopes, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) and [Stacks Scopes](/stacks/chainhook/references/scopes/stacks-scopes) pages. + + + From e97227bef482c62a749cc045a05e7a37b08d4b5f Mon Sep 17 00:00:00 2001 From: natebuch Date: Sun, 18 Aug 2024 22:31:15 -0500 Subject: [PATCH 12/21] Add next steps to predicate design. Update next step links on observing contract calls guide. --- .../chainhook/concepts/predicate-design.mdx | 20 +++++++++++++++++++ .../guides/observing-contract-calls.mdx | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 7348513ac..1b90aec80 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -319,3 +319,23 @@ When using `http_post`, specify the endpoint's `url` and `authorization_header`. +## Next steps + + + + + + + diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index 725ef9ec6..33724b666 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -386,6 +386,6 @@ The following is an example of how you might store your information in a databas From e83f25a65a499b594976ebccb4bbb20be1960ad1 Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 12:27:22 -0500 Subject: [PATCH 13/21] Remove bitcoin/stack predicate files after updating from main. --- .../chainhook/concepts/bitcoin-predicates.mdx | 425 ------------------ .../chainhook/concepts/stacks-predicates.mdx | 300 ------------- 2 files changed, 725 deletions(-) delete mode 100644 content/docs/stacks/chainhook/concepts/bitcoin-predicates.mdx delete mode 100644 content/docs/stacks/chainhook/concepts/stacks-predicates.mdx diff --git a/content/docs/stacks/chainhook/concepts/bitcoin-predicates.mdx b/content/docs/stacks/chainhook/concepts/bitcoin-predicates.mdx deleted file mode 100644 index 957be3f3d..000000000 --- a/content/docs/stacks/chainhook/concepts/bitcoin-predicates.mdx +++ /dev/null @@ -1,425 +0,0 @@ ---- -title: Bitcoin predicates -description: A list of predicates for using Chainhook with Bitcoin. The predicates are specified based on if-this, then-that constructs. ---- - -## `if_this` specifications - -Get any transaction matching a given transaction ID (`txid`). - -```jsonc -// [!code word:txid] -{ - "if_this": { - "scope": "txid", - "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" - } -} -``` - -The `txid` mandatory argument requires a 32-byte hex-encoded type. - ---- - - -Get any transaction, where its `OP_RETURN` payload starts with a set of characters. - -```jsonc -// [!code word:outputs] -// [!code word:starts_with] -{ - "if_this": { - "scope": "outputs", - "op_return": { - "starts_with": "ab" - } - } -} -``` - -The `starts_with` mandatory argument admits an ASCII string type (such as `ab`) or hex encoded bytes (such as `0x6162`). - ---- - -Get any transaction where its `OP_RETURN` payload is equals to a set of characters. - -```jsonc -// [!code word:outputs] -// [!code word:equals] -{ - "if_this": { - "scope": "outputs", - "op_return": { - "equals": "0x616263" - } - } -} -``` - -The mandatory argument for `equals` accepts either an ASCII string type (such as `abc`) or hex encoded bytes (such as `0x616263`). - ---- - -Get any transaction where its `OP_RETURN` payload ends with a set of characters. - -```jsonc -// [!code word:outputs] -// [!code word:ends_with] -{ - "if_this": { - "scope": "outputs", - "op_return": { - "ends_with": "0x6263" - } - } -} -``` - -The mandatory argument for `ends_with` accepts either an ASCII string type (such as `bc`) or hex encoded bytes (such as `0x6263`). - ---- - -Get any transaction with a p2pkh output paying a given recipient. - -```jsonc -// [!code word:outputs] -// [!code word:p2pkh] -{ - "if_this": { - "scope": "outputs", - "p2pkh": { - "equals": "mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC" - } - } -} -``` - -The `p2pkh` construct admits an ASCII string type: `"mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC"`. - -Or a hex encoded bytes type: `"0x76a914ee9369fb719c0ba43ddf4d94638a970b84775f4788ac"`. - - -`p2pkh`(Pay-to-Public-Key-Hash) is a Bitcoin transaction output script type that allows users to send funds to a recipient's hashed public key, providing security and privacy by concealing the actual public key. - - ---- - -Get any transaction including a p2sh output paying a given recipient. - -```jsonc -// [!code word:outputs] -// [!code word:p2sh] -{ - "if_this": { - "scope": "outputs", - "p2sh": { - "equals": "2MxDJ723HBJtEMa2a9vcsns4qztxBuC8Zb2" - } - } -} -``` - -The `p2sh` construct accepts the following types: - - A string type: `"2MxDJ723HBJtEMa2a9vcsns4qztxBuC8Zb2"`. - - A hex encoded bytes type: `"0x76a914ee9369fb719c0ba43ddf4d94638a970b84775f4788ac"`. - - -`p2sh`(Pay-to-Script-Hash) is a Bitcoin transaction output script type that enables users to send funds to a script instead of a public key, allowing for more complex transaction conditions and multi-signature addresses. - - ---- - -Get any transaction, including a `p2wpkh` output paying a given recipient. - -```jsonc -// [!code word:outputs] -// [!code word:p2wpkh] -{ - "if_this": { - "scope": "outputs", - "p2wpkh": { - "equals": "bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg" - } - } -} -``` - -The `p2wpkh` construct accepts a string type, for example: `"bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg"`. - - -`p2wpkh`(Pay-to-Witness-Public-Key-Hash) is a Bitcoin transaction output script type used in Segregated Witness (SegWit) that allows for more efficient and secure transactions by separating the witness data from the transaction data and storing it in a separate block. - - ---- - -Get any transaction, including a `p2wsh` output paying a given recipient. - -```jsonc -// [!code word:outputs] -// [!code word:p2wsh] -{ - "if_this": { - "scope": "outputs", - "p2wsh": { - "equals": "bc1qklpmx03a8qkv263gy8te36w0z9yafxplc5kwzc" - } - } -} -``` - -The `p2wsh` construct accepts a string type, for example: "bc1qklpmx03a8qkv263gy8te36w0z9yafxplc5kwzc". - - -`p2wsh` (Pay-to-Witness-Script-Hash) is a Bitcoin transaction output script type used in Segregated Witness (SegWit) that enables users to send funds to a hashed script, allowing for more complex transaction conditions and greater scalability by separating the script from the transaction data. - - - - -Wallet descriptors provide a compact and semi-standardized method for describing how scripts and addresses within a wallet are generated. Chainhook users that want to track addresses derived from an extended pubkey or a multisig-wallet can now rely on this feature instead of defining one predicate per address. -For example, let's say we wanted to track the first 3 addresses generated by the following descriptor: - -``` -wpkh(tprv8ZgxMBicQKsPePxn6j3TjvB2MBzQkuhGgc6oRh2WZancZQgxktcnjZJ44XdsRiw3jNkbVTK9JW6KFHvnRKgAMtSyuBevMJprSkZ4PTfmTgV/84'/1'/0'/0/*) -``` - -This descriptor reads: describe a P2WPKH output with the specified extended public key, and it produces these BIP84 addresses: - -``` -bcrt1qzy2rdyvu8c57qd8exyyp0mw7dk5drsu9ewzdsu -bcrt1qsfsjnagr29m8h3a3vdand2s85cg4cefkcwk2fy -bcrt1qauewfytqe5mtr0xwp786r6fl39kmum2lr65kmj -``` - -The predicate should then be defined like this: - -```json -{ - "if_this": { - "scope": "outputs", - "descriptor": { - "expression": "wpkh(tprv8ZgxMBicQKsPePxn6j3TjvB2MBzQkuhGgc6oRh2WZancZQgxktcnjZJ44XdsRiw3jNkbVTK9JW6KFHvnRKgAMtSyuBevMJprSkZ4PTfmTgV/84'/1'/0'/0/*)", - "range": [0, 3] - } - } -} -``` - - - ---- - -Get any Bitcoin transaction, including a block commitment. Broadcasted payloads include _Proof of Transfer_ reward information. - -```jsonc -// [!code word:stacks_protocol] -// [!code word:block_committed] -{ - "if_this": { - "scope": "stacks_protocol", - "operation": "block_committed" - } -} -``` - -Proof of Transfer (PoT) is the [blockchain consensus mechanism for Stacks](https://www.hiro.so/blog/securing-web3-apps-through-bitcoin-an-overview-of-stacks-consensus-mechanism) where miners can bid BTC for the chance to mine Stacks blocks. - ---- - -Get any transaction, including a key registration operation. - -```jsonc -// [!code word:stacks_protocol] -// [!code word:leader_registered] -{ - "if_this": { - "scope": "stacks_protocol", - "operation": "leader_registered" - } -} -``` - ---- - -Get any transaction including a new Ordinal inscription (inscription revealed and transferred). - -```jsonc -// [!code word:ordinals_protocol] -// [!code word:inscription_feed] -{ - "if_this": { - "scope": "ordinals_protocol", - "operation": "inscription_feed" - } -} -``` - ---- - -Get any transaction, including a STX transfer operation. - -```jsonc -// [!code word:stacks_protocol] -// [!code word:stx_transferred] -{ - "if_this": { - "scope": "stacks_protocol", - "operation": "stx_transferred" - } -} -``` - ---- - -Get any transaction, including a STX lock operation. - -```jsonc -// [!code word:stacks_protocol] -// [!code word:stx_locked] -{ - "if_this": { - "scope": "stacks_protocol", - "operation": "stx_locked" - } -} -``` - -## `then_that` constructs - -The following `then_that` constructs are supported: - -`HTTP Post` block/transaction payload to a given endpoint: - -- `http_post` construct admits: - - url (string type), like `http://localhost:3000/api/v1/wrapBtc` - - authorization_header (string type). - -```jsonc -{ - "then_that": { - "http_post": { - "url": "http://localhost:3000/api/v1/wrapBtc", - "authorization_header": "Bearer cn389ncoiwuencr", - }, - }, -} -``` - -Append events to a file through the filesystem, which is convenient for local tests: - -- `file_append` construct admits: - - path (string type). Path to the file on disk. - -```jsonc -{ - "then_that": { - "file_append": { - "path": "/tmp/events.json", - }, - }, -} -``` - -## Additional configuration knobs available - -The following additional configurations can be used to improve the performance of Chainhook by preventing a full scan of the blockchain. - -Ignore any block before the given block: - -```json -"start_block": 101 -``` - -Ignore any block after the given block: - -```json -"end_block": 201 -``` - -Stop evaluating a chainhook after a given number of occurrences are found: - -```json -"expire_after_occurrence": 1 -``` - -Don't include proofs: - -```json -"include_proof": false -``` - -Don't include proofs: - -```json -"include_proof": false -``` - -Don't include Bitcoin transaction inputs in the payload: - -```json -"include_inputs": false -``` - -Don't include Bitcoin transaction outputs in the payload: - -```json -"include_outputs": false -``` - -Don't include Bitcoin transaction outputs in the payload: - -```json -"include_outputs": false -``` - -Don't include Bitcoin transaction witnesses in the payload: - -```json -"include_witness": false -``` - -Don't include Bitcoin transaction witnesses in the payload: - -```json -"include_witness": false -``` - - - - ```json - { - "chain": "bitcoin", - "uuid": "1", - "name": "Wrap BTC", - "version": 1, - "networks": { - "testnet": { - "if_this": { - "scope": "ordinals_protocol", - "operation": "inscription_feed" - }, - "then_that": { - "http_post": { - "url": "http://localhost:3000/api/v1/ordinals", - "authorization_header": "Bearer cn389ncoiwuencr" - } - }, - "start_block": 10200 - }, - "mainnet": { - "if_this": { - "scope": "ordinals_protocol", - "operation": "inscription_feed" - }, - "then_that": { - "http_post": { - "url": "http://my-protocol.xyz/api/v1/ordinals", - "authorization_header": "Bearer cn389ncoiwuencr" - } - }, - "start_block": 90232 - } - } - } - ``` - - diff --git a/content/docs/stacks/chainhook/concepts/stacks-predicates.mdx b/content/docs/stacks/chainhook/concepts/stacks-predicates.mdx deleted file mode 100644 index f8fbbad34..000000000 --- a/content/docs/stacks/chainhook/concepts/stacks-predicates.mdx +++ /dev/null @@ -1,300 +0,0 @@ ---- -title: Stacks predicates -description: A list of predicates for using Chainhook with Stacks. The predicates are specified based on if-this, and then-that constructs. ---- - -## `if_this` specifications - -Get any transaction matching a given transaction ID, `txid`. - -```jsonc -// [!code word:txid] -{ - "if_this": { - "scope": "txid", - "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f" - } -} -``` - -The `txid` mandatory argument requires a 32-byte hex-encoded type. - ---- - -Get any Stacks block based on matching constraints. - -```jsonc -// [!code word:block_height] -{ - "if_this": { - "scope": "block_height", - "equals": 154100 - } -} -``` - -The `block_height` argument admits: `equals`, `higher_than`, `lower_than`, `between`. - -The `between` operator can be used by providing an array with two values: - -```jsonc -// [!code word:between] -{ - "if_this": { - "scope": "block_height", - "between": [0, 1000] - } -} -``` - ---- - -Get any transaction related to a given fungible token asset identifier: - -```jsonc -// [!code word:ft_event] -{ - "if_this": { - "scope": "ft_event", - "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token::cbtc", - "actions": ["burn"] - } -} -``` - -The `asset_identifier` argument admits an asset identifier to observe, for example: `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-sip10::cbtc`. - -The `actions` argument admits an array of string types constrained to `mint`, `transfer`, and `burn` values, such as `["mint", "burn"]`. - ---- - -Get any transaction related to a given non-fungible token asset identifier. - -The `asset-identifier` argument is mandatory and requires a string type that fully qualifies the asset identifier to observe, for example: `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys`. - -The `actions` argument is also mandatory and accepts an array of string types limited to the values `mint`, `transfer`, and `burn`, such as `["mint", "burn"]`. - -```jsonc -// [!code word:nft_event] -{ - "if_this": { - "scope": "nft_event", - "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys", - "actions": ["mint", "transfer", "burn"] - } -} -``` - ---- - -Get any transaction moving STX tokens. - -The `actions` argument is mandatory and accepts an array of string types limited to the values `mint`, `transfer`, `burn`, and `lock`, such as `["mint", "lock"]`. - -```json -// [!code word:stx_event] -{ - "if_this": { - "scope": "stx_event", - "actions": ["transfer", "lock"] - } -} -``` - ---- - -Get any transaction emitting a given print events predicate. - -The `contract-identifier` is a mandatory argument that requires a string type, fully qualifying the contract to observe, for example: `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09`. - -Additionally, you must include either the `contains` or `matches_regex` argument: - -- The `contains` argument accepts a string type, used for matching an event that contains the specified string, for example `vault`. -- The `matches_regex` argument accepts a string type that should be a valid regex, used for matching an event that regex matches with the specified string, such as `(?:^|\\W)vault(?:$|\\W)`. - -The following example uses `contains` argument: - -```jsonc -// [!code word:print_event] -// [!code word:contains] -{ - "if_this": { - "scope": "print_event", - "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09", - "contains": "vault" - } -} -``` - -The following example uses `matches_regex` argument: - -```jsonc -// [!code word:print_event] -// [!code word:matches_regex] -{ - "if_this": { - "scope": "print_event", - "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09", - "matches_regex": "(?:^|\\W)vault(?:$|\\W)" - } -} -``` - ---- - -Get any transaction calling a specific method for a given contract _directly_. - - -If the observed method is being called by another contract, this predicate won't detect it. - - -The `contract-identifier` is a mandatory argument that requires a string type, fully qualifying the contract to observe, for example `SP000000000000000000002Q6VF78.pox`. - -The `method` is also a mandatory argument that accepts a string type, used for specifying the method to observe, such as `stack-stx`. - -```jsonc -// [!code word:contract_call] -// [!code word:method] -{ - "if_this": { - "scope": "contract_call", - "contract_identifier": "SP000000000000000000002Q6VF78.pox", - "method": "stack-stx" - } -} -``` - ---- - -Get any transaction, including a contract deployment. - -The `deployer` argument is mandatory and accepts a string representing a valid STX address, for example `"ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG"`. - -```jsonc -// [!code word:contract_deployment] -// [!code word:deployer] -{ - "if_this": { - "scope": "contract_deployment", - "deployer": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" - } -} -``` - -## `then_that` specifications - -HTTP Post block/transaction payload to a given endpoint. - -The `http_post` construct requires a `url` of type string (for example, `http://localhost:3000/api/v1/wrapBtc`) and an `authorization_header` of type string, which is a secret added to the request's `authorization` header. - -```jsonc -// [!code word:http_post] -// [!code word:url] -// [!code word:authorization_header] -{ - "then_that": { - "http_post": { - "url": "http://localhost:3000/api/v1/wrapBtc", - "authorization_header": "Bearer cn389ncoiwuencr" - } - } -} -``` - ---- - -Append events to a file through the filesystem, which is convenient for local tests. - -The `file_append` construct requires a `path` parameter, which is a string representing the file path on the disk. - - -```jsonc -// [!code word:file_append] -// [!code word:path] -{ - "then_that": { - "file_append": { - "path": "/tmp/events.json" - } - } -} -``` - -## Additional configurations available - -The following additional configurations can be used to improve the performance of chainhook by preventing a full scan of the blockchain: - -Ignore any block before the given block: - -```json -"start_block": 101 -``` - -Ignore any block after the given block: - -```json -"end_block": 201 -``` - -Stop evaluating chainhook after a given number of occurrences found: - -```json -"expire_after_occurrence": 1 -``` - -Include decoded Clarity values in the payload: - -```json -"decode_clarity_values": true -``` - -Include the contract ABI for transactions that deploy contracts: - -```json -"include_contract_abi": true -``` - - - - ```jsonc - { - "chain": "stacks", - "uuid": "1", - "name": "Lorem ipsum", - "version": 1, - "networks": { - "testnet": { - "if_this": { - "scope": "print_event", - "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09", - "contains": "vault" - }, - "then_that": { - "http_post": { - "url": "http://localhost:3000/api/v1/vaults", - "authorization_header": "Bearer cn389ncoiwuencr" - } - }, - "start_block": 10200, - "expire_after_occurrence": 5 - }, - "mainnet": { - "if_this": { - "scope": "print_event", - "contract_identifier": "SP456HQKV0RJXZFY1DGX8MNSNYVE3VGZJSRT459863.monkey-sip09", - "contains": "vault" - }, - "then_that": { - "http_post": { - "url": "http://my-protocol.xyz/api/v1/vaults", - "authorization_header": "Bearer cn389ncoiwuencr" - } - }, - "start_block": 90232, - "expire_after_occurrence": 5 - } - } - } - ``` - - From 403600634afdba448c5cc773f6ea6aa6b255aa4b Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 12:45:31 -0500 Subject: [PATCH 14/21] Fix links to scopes pages based on Bitcoin and/or Stacks context. --- .../docs/stacks/chainhook/concepts/predicate-design.mdx | 5 +++++ .../stacks/chainhook/guides/chainhook-as-a-service.mdx | 8 ++++---- .../stacks/chainhook/guides/observing-contract-calls.mdx | 4 ++-- .../chainhook/guides/register-chainhooks-on-devnet.mdx | 2 +- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 1b90aec80..197f667b5 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -337,5 +337,10 @@ When using `http_post`, specify the endpoint's `url` and `authorization_header`. title="Stacks scopes" description="Learn how to use additional scopes to scan for specific Stacks blockchain events." /> + diff --git a/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx b/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx index 0fda3ad80..45c10912f 100644 --- a/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx +++ b/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx @@ -81,7 +81,7 @@ Here is a table of the relevant parameters this guide changes in our configurati ## Scan the blockchain based on predicates -Now that your `bitcoind` and Chainhook configurations are complete, you can define the Chainhook [predicate scope](/stacks/chainhook/references/scopes) you would like to scan for. +Now that your `bitcoind` and Chainhook configurations are complete, you can define the Chainhook [Bitcoin predicate scope](/stacks/chainhook/references/scopes/bitcoin-scopes) you would like to scan for. These predicates are where you specify the `if_this / then_that` pattern to trigger Chainhook to deliver a result (either a file appendation or an HTTP POST request). @@ -330,8 +330,8 @@ You can also run chainhook service by passing multiple predicates, ie `chainhook description="Learn how to register Chainhooks on devnet." /> \ No newline at end of file diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index b70442a14..fb6056940 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -386,8 +386,8 @@ The following is an example of how you might store your information in a databas description="Learn how to create a Chainhook using the Hiro Platform." /> diff --git a/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx b/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx index 0b09f2acd..bbe2cbedf 100644 --- a/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx +++ b/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx @@ -36,7 +36,7 @@ These should be situated in the root of your project directory. The files can ei -For examples on how to define your predicates, refer to the [scopes](/stacks/chainhook/references/scopes) reference page. +For examples on how to define your predicates, refer to the [scopes](/stacks/chainhook/references/scopes/stacks-scopes) reference page. ## Start devnet From 9b1f32a8dc7018d821486c47112405bdffae0161 Mon Sep 17 00:00:00 2001 From: Nate Buch Date: Mon, 19 Aug 2024 15:42:37 -0500 Subject: [PATCH 15/21] Update content/docs/stacks/chainhook/concepts/predicate-design.mdx Co-authored-by: Ryan --- content/docs/stacks/chainhook/concepts/predicate-design.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 197f667b5..3a6294da3 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -1,5 +1,5 @@ --- -title: Predicate Design +title: Predicate design description: Predicates are the building blocks of Chainhook. toc: true --- From 7893de59a1abca6276b8b872778b782daa52d2c7 Mon Sep 17 00:00:00 2001 From: Nate Buch Date: Mon, 19 Aug 2024 15:42:49 -0500 Subject: [PATCH 16/21] Update content/docs/stacks/chainhook/concepts/predicate-design.mdx Co-authored-by: Ryan --- content/docs/stacks/chainhook/concepts/predicate-design.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 3a6294da3..12dce1374 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -1,7 +1,6 @@ --- title: Predicate design description: Predicates are the building blocks of Chainhook. -toc: true --- The core design of Chainhook revolves around the concept of predicates. Each individual Chainhook has a customizable predicate that specifies what the Bitcoin or Stacks blockchain data you are scanning for. From 16b73a910a98d9b11c50f654db7bf75fc8fd1b9d Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 16:00:57 -0500 Subject: [PATCH 17/21] Add redirects to vercel.json. --- vercel.json | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/vercel.json b/vercel.json index da2fcb7fb..bceeaf0aa 100644 --- a/vercel.json +++ b/vercel.json @@ -546,6 +546,21 @@ "source": "/get-started/transactions", "destination": "/stacks/stacks.js/concepts/transactions", "permanent": true + }, + { + "source": "/stacks/chainhook/concepts/bitcoin-predicates", + "destination": "/stacks/chainhook/concepts/predicate-design", + "permanent": true + }, + { + "source": "/stacks/chainhook/concepts/stacks-predicates", + "destination": "/stacks/chainhook/concepts/predicate-design", + "permanent": true + }, + { + "source": "/stacks/chainhook/references/scopes", + "destination": "/stacks/chainhook/references/scopes/stacks-scopes", + "permanent": true } ] -} +} \ No newline at end of file From 867d8f16a0bfecf092c436de53bd3798388a2347 Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 16:22:40 -0500 Subject: [PATCH 18/21] Update scopes files names and references to those files. --- content/docs/stacks/chainhook/concepts/predicate-design.mdx | 4 ++-- .../guides/chainhook-as-a-service-with-stacks-node.mdx | 4 ++-- .../docs/stacks/chainhook/guides/chainhook-as-a-service.mdx | 4 ++-- .../docs/stacks/chainhook/guides/observing-contract-calls.mdx | 4 ++-- .../stacks/chainhook/guides/register-chainhooks-on-devnet.mdx | 2 +- .../references/scopes/{bitcoin-scopes.mdx => bitcoin.mdx} | 0 .../references/scopes/{stacks-scopes.mdx => stacks.mdx} | 0 vercel.json | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) rename content/docs/stacks/chainhook/references/scopes/{bitcoin-scopes.mdx => bitcoin.mdx} (100%) rename content/docs/stacks/chainhook/references/scopes/{stacks-scopes.mdx => stacks.mdx} (100%) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 12dce1374..5724f1d23 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -332,12 +332,12 @@ When using `http_post`, specify the endpoint's `url` and `authorization_header`. description="Learn how to create a Chainhook using the Hiro Platform." /> diff --git a/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx b/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx index 122852eaa..5b92e8f9c 100644 --- a/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx +++ b/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx @@ -321,8 +321,8 @@ The response should look something like this: description="Learn how to register Chainhooks on devnet." /> \ No newline at end of file diff --git a/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx b/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx index 45c10912f..27d76f9ec 100644 --- a/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx +++ b/content/docs/stacks/chainhook/guides/chainhook-as-a-service.mdx @@ -81,7 +81,7 @@ Here is a table of the relevant parameters this guide changes in our configurati ## Scan the blockchain based on predicates -Now that your `bitcoind` and Chainhook configurations are complete, you can define the Chainhook [Bitcoin predicate scope](/stacks/chainhook/references/scopes/bitcoin-scopes) you would like to scan for. +Now that your `bitcoind` and Chainhook configurations are complete, you can define the Chainhook [Bitcoin predicate scope](/stacks/chainhook/references/scopes/bitcoin) you would like to scan for. These predicates are where you specify the `if_this / then_that` pattern to trigger Chainhook to deliver a result (either a file appendation or an HTTP POST request). @@ -330,7 +330,7 @@ You can also run chainhook service by passing multiple predicates, ie `chainhook description="Learn how to register Chainhooks on devnet." /> diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index fb6056940..987545e9b 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -143,7 +143,7 @@ Using `file_append`, specify the path where Chainhook will post the payload data - For more details on optional configurations, other predicate elements and scopes, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) and [Stacks Scopes](/stacks/chainhook/references/scopes/stacks-scopes) pages. + For more details on optional configurations, other predicate elements and scopes, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) and [Stacks Scopes](/stacks/chainhook/references/scopes/stacks) pages. @@ -386,7 +386,7 @@ The following is an example of how you might store your information in a databas description="Learn how to create a Chainhook using the Hiro Platform." /> diff --git a/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx b/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx index bbe2cbedf..f9ccf335f 100644 --- a/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx +++ b/content/docs/stacks/chainhook/guides/register-chainhooks-on-devnet.mdx @@ -36,7 +36,7 @@ These should be situated in the root of your project directory. The files can ei -For examples on how to define your predicates, refer to the [scopes](/stacks/chainhook/references/scopes/stacks-scopes) reference page. +For examples on how to define your predicates, refer to the [scopes](/stacks/chainhook/references/scopes/stacks) reference page. ## Start devnet diff --git a/content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/bitcoin.mdx similarity index 100% rename from content/docs/stacks/chainhook/references/scopes/bitcoin-scopes.mdx rename to content/docs/stacks/chainhook/references/scopes/bitcoin.mdx diff --git a/content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx b/content/docs/stacks/chainhook/references/scopes/stacks.mdx similarity index 100% rename from content/docs/stacks/chainhook/references/scopes/stacks-scopes.mdx rename to content/docs/stacks/chainhook/references/scopes/stacks.mdx diff --git a/vercel.json b/vercel.json index bceeaf0aa..049c1a7ac 100644 --- a/vercel.json +++ b/vercel.json @@ -559,7 +559,7 @@ }, { "source": "/stacks/chainhook/references/scopes", - "destination": "/stacks/chainhook/references/scopes/stacks-scopes", + "destination": "/stacks/chainhook/references/scopes/stacks", "permanent": true } ] From fef62a8b43776084bbae670da01b4e87700d963f Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 16:27:11 -0500 Subject: [PATCH 19/21] Add note section in predicate-design for link to scopes in if_this section. --- content/docs/stacks/chainhook/concepts/predicate-design.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/docs/stacks/chainhook/concepts/predicate-design.mdx b/content/docs/stacks/chainhook/concepts/predicate-design.mdx index 5724f1d23..fff7133b0 100644 --- a/content/docs/stacks/chainhook/concepts/predicate-design.mdx +++ b/content/docs/stacks/chainhook/concepts/predicate-design.mdx @@ -54,6 +54,10 @@ The `networks` element contains an object who's key determines the blockchain ne } ``` + + For additional information, check out the [Bitcoin scopes](/stacks/chainhook/references/scopes/bitcoin) and [Stacks scopes](/stacks/chainhook/references/scopes/stacks) references pages. + + ## if_this specification The `predicate` identifies what data you want Chainhook to scan for using the `scope` define within the `if_this` specification. Additional arguments specific to the `scope` will also be passed here. From 031ceaa754c14edce4e8f608cbb6cafa8b87a10f Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 17:05:31 -0500 Subject: [PATCH 20/21] Update meta file for reference links. --- content/docs/stacks/chainhook/meta.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/stacks/chainhook/meta.json b/content/docs/stacks/chainhook/meta.json index 2b5ce5f16..d4936f3fe 100644 --- a/content/docs/stacks/chainhook/meta.json +++ b/content/docs/stacks/chainhook/meta.json @@ -19,7 +19,7 @@ "guides/chainhook-as-a-service-with-stacks-node", "guides/observing-contract-calls", "---Reference---", - "references/scopes/bitcoin-scopes", - "references/scopes/stacks-scopes" + "references/scopes/bitcoin", + "references/scopes/stacks" ] } \ No newline at end of file From 85949a7ff33820bece78f8301818e43eba8098b6 Mon Sep 17 00:00:00 2001 From: natebuch Date: Mon, 19 Aug 2024 17:12:16 -0500 Subject: [PATCH 21/21] Fix capitalization in copy for contract-call guide, fix next step name for stacks scopes in stacks node guide. --- .../guides/chainhook-as-a-service-with-stacks-node.mdx | 2 +- .../docs/stacks/chainhook/guides/observing-contract-calls.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx b/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx index 5b92e8f9c..db71f4d5d 100644 --- a/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx +++ b/content/docs/stacks/chainhook/guides/chainhook-as-a-service-with-stacks-node.mdx @@ -322,7 +322,7 @@ The response should look something like this: /> \ No newline at end of file diff --git a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx index 987545e9b..d45a4374e 100644 --- a/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx +++ b/content/docs/stacks/chainhook/guides/observing-contract-calls.mdx @@ -143,7 +143,7 @@ Using `file_append`, specify the path where Chainhook will post the payload data - For more details on optional configurations, other predicate elements and scopes, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) and [Stacks Scopes](/stacks/chainhook/references/scopes/stacks) pages. + For more details on optional configurations, other predicate elements and scopes, check out the [Predicate Design](/stacks/chainhook/concepts/predicate-design) and [Stacks scopes](/stacks/chainhook/references/scopes/stacks) pages.