Bitcoin scopes

Bitcoin scopes define the if_this conditions in your Chainhook predicates. Each scope type monitors specific on-chain events on the Bitcoin blockchain.

txid

txid matches transactions by their transaction ID.

Signature

{
  "scope": "txid",
  "equals": string
}

Parameters

Name	Type	Required	Description
`equals`	string	Yes	32-byte hex encoded transaction ID to match

Example

{
  "if_this": {
    "scope": "txid",
    "equals": "0xfaaac1833dc4883e7ec28f61e35b41f896c395f8d288b1a177155de2abd6052f"
  }
}

outputs

outputs matches transactions based on their output scripts.

Available operations

Operation	Description
`op_return`	Data embedded in transactions
`p2pkh`	Pay-to-Public-Key-Hash outputs
`p2sh`	Pay-to-Script-Hash outputs
`p2wpkh`	Pay-to-Witness-Public-Key-Hash outputs
`p2wsh`	Pay-to-Witness-Script-Hash outputs
`descriptor`	Output descriptors for address derivation

op_return

{
  "scope": "outputs",
  "op_return": {
    "equals" | "starts_with" | "ends_with": string
  }
}

Parameter	Type	Required	Description
`equals`	string	No*	Match exact data
`starts_with`	string	No*	Match data prefix
`ends_with`	string	No*	Match data suffix

*One of these parameters is required

{
  "if_this": {
    "scope": "outputs",
    "op_return": {
      "starts_with": "0xbtc2100"
    }
  }
}

p2pkh

{
  "scope": "outputs",
  "p2pkh": {
    "equals": string
  }
}

Parameter	Type	Required	Description
`equals`	string	Yes	Bitcoin address to match

{
  "if_this": {
    "scope": "outputs",
    "p2pkh": {
      "equals": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    }
  }
}

p2sh

{
  "scope": "outputs",
  "p2sh": {
    "equals": string
  }
}

Parameter	Type	Required	Description
`equals`	string	Yes	Script hash address to match

{
  "if_this": {
    "scope": "outputs",
    "p2sh": {
      "equals": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"
    }
  }
}

p2wpkh

{
  "scope": "outputs",
  "p2wpkh": {
    "equals": string
  }
}

Parameter	Type	Required	Description
`equals`	string	Yes	Native SegWit address to match

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

p2wsh

{
  "scope": "outputs",
  "p2wsh": {
    "equals": string
  }
}

Parameter	Type	Required	Description
`equals`	string	Yes	Native SegWit script address to match

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

descriptor

{
  "scope": "outputs",
  "descriptor": {
    "expression": string,
    "range": [number, number]
  }
}

Parameter	Type	Required	Description
`expression`	string	Yes	Output descriptor string
`range`	array	Yes	Index range to derive [start, end]

{
  "if_this": {
    "scope": "outputs",
    "descriptor": {
      "expression": "wpkh(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)",
      "range": [0, 10]
    }
  }
}

This monitors addresses derived from index 0 to 10 of the provided extended public key.

stacks_protocol

stacks_protocol matches Bitcoin transactions related to Stacks Proof of Transfer operations.

Signature

{
  "scope": "stacks_protocol",
  "operation": string
}

Parameters

Name	Type	Required	Description
`operation`	string	Yes	PoT operation type to match

Available operations

Operation	Description
`block_committed`	Stacks block commitments
`leader_registered`	Mining leader registrations
`inscription_feed`	Ordinal inscription events
`stx_transferred`	STX token transfers
`stx_locked`	STX token locking events

Examples

Monitor block commitments

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

Track STX transfers

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

Monitor inscription events

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