Predicate design

The core design of Chainhook revolves around the concept of predicates. Each individual chainhook has a customizable predicate that specifies what Bitcoin or Stacks blockchain data you are scanning for.

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 app using name and version.

  {
    "chain": "stacks",
    "uuid": "1",
    "name": "STX_Transfer_Predicate",
    "version": 1,
    "networks": {
      // Other configurations
    }
  }

  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
    },
  }

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. 1file_append
2. 2http_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"
    }
  }
}

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

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

Next steps