Predicate design

Predicates are the building blocks of Chainhook.

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.

Requirements

Commands outlined here will require that you have installed Chainhook directly.

Predicate design

Below is the general strucure of the predicate JSON with its primary elements. These elements and their values are required.

  • 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.
  {
    "chain": "stacks",
    "uuid": "1",
    "name": "STX_Transfer_Predicate",
    "version": 1,
    "networks": {
      // Other configurations
    }
  }
Note

You can use the following command to verify your predicate:

  chainhook predicate check your-predicate-file.json --mainnet

Networks

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.
  "networks": {
    "mainnet": {
      // if_this and then_that specifications
      // Other configurations
    },
    "testnet": {
      // if_this and then_that specifications
      // Other configurations
    },
  }
Note

For additional information, check out the Bitcoin scopes and Stacks scopes 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.

  {
    "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.

{
  "then_that": {
    "file_append": { 
      "path": "/tmp/events.json"
    }
  }
}

When using http_post, specify the endpoint's url and authorization_header.

{
  "then_that": {
    "http_post": {
      "url": "https://webhook.site/abc123456-789e-0fgh-1ijk-23lmno456789",
      "authorization_header": "12345"
    }
  }
}
Note

Chainhook requires https to post to your endpoint. You can use a service like LocalTunnel to test locally or a site like WebhookSite.

Blockchain specific configurations

 {
   "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
     }
   }
 }

Note

The following command allows you to generate a predicate template for the Bitcoin blockchain.

  chainhook predicates new your-bitcoin-predicate.json --bitcoin

Next steps