Bitcoin predicates

if_this specifications

Get any transaction matching a given transaction ID (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.

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

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

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

{
  "if_this": {
    "scope": "outputs",
    "p2pkh": {
      "equals": "mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC"
    }
  }
}

The p2pkh construct admits an ASCII string type: "mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC".

Or a hex encoded bytes type: "0x76a914ee9369fb719c0ba43ddf4d94638a970b84775f4788ac".

Get any transaction including a p2sh output paying a given recipient.

{
  "if_this": {
    "scope": "outputs",
    "p2sh": {
      "equals": "2MxDJ723HBJtEMa2a9vcsns4qztxBuC8Zb2"
    }
  }
}

The p2sh construct accepts the following types:

• A string type: "2MxDJ723HBJtEMa2a9vcsns4qztxBuC8Zb2".
• A hex encoded bytes type: "0x76a914ee9369fb719c0ba43ddf4d94638a970b84775f4788ac".

Get any transaction, including a p2wpkh output paying a given recipient.

{
  "if_this": {
    "scope": "outputs",
    "p2wpkh": {
      "equals": "bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg"
    }
  }
}

The p2wpkh construct accepts a string type, for example: "bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg".

Get any transaction, including a p2wsh output paying a given recipient.

{
  "if_this": {
    "scope": "outputs",
    "p2wsh": {
      "equals": "bc1qklpmx03a8qkv263gy8te36w0z9yafxplc5kwzc"
    }
  }
}

The p2wsh construct accepts a string type, for example: "bc1qklpmx03a8qkv263gy8te36w0z9yafxplc5kwzc".

Get any Bitcoin transaction, including a block commitment. Broadcasted payloads include Proof of Transfer reward information.

{
  "if_this": {
    "scope": "stacks_protocol",
    "operation": "block_committed"
  }
}

Proof of Transfer (PoT) is the blockchain consensus mechanism for Stacks where miners can bid BTC for the chance to mine Stacks blocks.

Get any transaction, including a key registration operation.

{
  "if_this": {
    "scope": "stacks_protocol",
    "operation": "leader_registered"
  }
}

Get any transaction including a new Ordinal inscription (inscription revealed and transferred).

{
  "if_this": {
    "scope": "ordinals_protocol",
    "operation": "inscription_feed"
  }
}

Get any transaction, including a STX transfer operation.

{
  "if_this": {
    "scope": "stacks_protocol",
    "operation": "stx_transferred"
  }
}

Get any transaction, including a STX lock operation.

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

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

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

"start_block": 101

Ignore any block after the given block:

"end_block": 201

Stop evaluating a chainhook after a given number of occurrences are found:

"expire_after_occurrence": 1

Don't include proofs:

"include_proof": false

Don't include proofs:

"include_proof": false

Don't include Bitcoin transaction inputs in the payload:

"include_inputs": false

Don't include Bitcoin transaction outputs in the payload:

"include_outputs": false

Don't include Bitcoin transaction outputs in the payload:

"include_outputs": false

Don't include Bitcoin transaction witnesses in the payload:

"include_witness": false

Don't include Bitcoin transaction witnesses in the payload:

"include_witness": false