Merge pull request #736 from natebuch/main

Updates to Predicate Design and Addition of Bitcoin Scopes

Author: ryanwaits

content/docs/stacks/chainhook/concepts/bitcoin-predicates.mdx

@@ -3,62 +3,347 @@ title: Predicate design
 description: Predicates are the building blocks of Chainhook.
 ---
 
-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.
+<Callout type="warn" title="Requirements">
+  Commands outlined here will require that you have installed Chainhook [directly](/stacks/chainhook/installation).
+</Callout>
 
-## `if-this`
+## Predicate design
+Below is the general strucure of the `predicate` JSON with its primary elements.  These elements and their values are required. 
 
-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.
+- 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
-// [!code word:if_this]
-{
-  "if_this": {
-    "scope": "txid",
-    "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f"
+  {
+    "chain": "stacks",
+    "uuid": "1",
+    "name": "STX_Transfer_Predicate",
+    "version": 1,
+    "networks": {
+      // Other configurations
+    }
   }
-}
-```
+  ```
 
-Other available parameters:
+<Callout type="info" title="Note">
+  You can use the following command to verify your predicate:
+  ```
+    chainhook predicate check your-predicate-file.json --mainnet
+  ```
+</Callout>
+
+## Networks
 
-- `equals`
-- `op_return`
-- `ends_with`
-- `p2pkh`
-- `p2sh`
-- `p2wpkh`
-- `operation`
+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
+    },
+  }
+```
 
-<Callout title="Info">
-  For more information on predicate definitions, refer to the [scopes](/stacks/chainhook/references/scopes) reference page.
+<Callout type="info" title="Note">
+  For additional information, check out the [Bitcoin scopes](/stacks/chainhook/references/scopes/bitcoin) and [Stacks scopes](/stacks/chainhook/references/scopes/stacks) references pages.
 </Callout>
 
-## `then-that`
+## 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:
 
-The `then-that` predicate design can use the following attributes to output the result based on the `if-this` condition defined.
+1. `file_append`
+2. `http_post`
 
-```jsonc
+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",
-    },
-  },
+    "file_append": { 
+      "path": "/tmp/events.json"
+    }
+  }
 }
 ```
 
-```jsonc
+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://example.com/api/v1/events",
-      "authorization_header": "Bearer 1234567890"
+      "url": "https://webhook.site/abc123456-789e-0fgh-1ijk-23lmno456789",
+      "authorization_header": "12345"
     }
   }
 }
 ```
 
+<Callout title="Note">
+  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).
+</Callout>
+
+## Blockchain specific configurations
+
+<Tabs id="blockchain" items={["Bitcoin predicate", "Stacks predicate"]}>
+  <Tab value="Bitcoin predicate">
+
+     ```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
+          }
+        }
+      }
+    ```
+
+     <Accordions>
+      <Accordion title="Additional Bitcoin predicate 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
+        ```
+      </Accordion>
+    </Accordions> 
+
+    <Callout type="info" title="Note">
+    The following command allows you to generate a predicate template for the Bitcoin blockchain.
+    ```
+      chainhook predicates new your-bitcoin-predicate.json --bitcoin
+    ```
+    </Callout>
+
+  </Tab>
+
+  <Tab value="Stacks predicate">
+
+    ```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
+          }
+        }
+      }
+    ```
+
+    <Accordions>
+      <Accordion title="Additional Stacks predicate 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
+        ```
+      </Accordion>
+    </Accordions>
+
+    <Callout type="info" title="Note">
+    The following command allows you to generate a predicate template for the Stacks blockchain.
+    ```
+    chainhook predicates new your-stacks-predicate.json --stacks
+    ```
+  </Callout>
+
+  </Tab>
+
+</Tabs>
+
+## Next steps
+
+<Cards>
+  <Card
+    href="/stacks/chainhook/guides/observing-contract-calls"
+    title="Observing contract calls"
+    description="Learn use a predicate to observe Stacks contracts calls with Chainhook."
+  />
+  <Card
+    href="/stacks/platform/guides/create-chainhooks"
+    title="Create a Chainhook"
+    description="Learn how to create a Chainhook using the Hiro Platform."
+  />
+  <Card
+    href="/stacks/chainhook/references/scopes/stacks"
+    title="Stacks scopes"
+    description="Learn how to use additional scopes to scan for specific Stacks blockchain events."
+  />
+  <Card
+    href="/stacks/chainhook/references/scopes/bitcoin"
+    title="Bitcoin scopes"
+    description="Learn how to use additional scopes to scan for specific Bitcoin blockchain events."
+  />
+</Cards>
+