Scopes

Reference guide for available scopes for Stacks and Bitcoin.

Scopes are parameters you use to define the "if this" logic of your chainhook. In other words, scopes specify what on-chain events you are looking to monitor and track. For more information on Chainhook design, please view predicate design.

Installation

brew install chainhook

txid

The txid scope allows you to query transactions based on their transaction ID. This is particularly useful for tracking specific transactions or auditing transaction histories.

Parameters

equals
Required
string

The equals property is a 32 bytes hex encoded type used to specify the exact transaction ID to match.

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

block_height

The block_height scope allows you to query blocks based on their height. This is useful for identifying specific blocks or ranges of blocks in the blockchain.

Parameters

equals
Required
integer

The equals property specifies the exact height of the block to match.

higher_than
Required
integer

The higher_than property specifies that the block height should be greater than the provided value.

lower_than
Required
integer

The lower_than property specifies that the block height should be less than the provided value.

between
Required
array of integers

The between property specifies a range of block heights to match, inclusive of the provided start and end values.

{
  "if_this": {
    "scope": "block_height",
    "equals": 141200
  }
}

ft_transfer

The ft_transfer scope allows you to query transactions based on fungible token transfers. This is useful for tracking specific token movements or auditing token transfer histories.

Parameters

asset_identifier
Required
string

The asset_identifier property specifies the fully qualified asset identifier to observe, such as ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token::cbtc.

actions
Required
string[]

The actions property specifies the types of token actions to observe, such as mint, transfer, or burn.

{
  "if_this": {
    "scope": "ft_transfer",
    "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token::cbtc",
    "actions": ["transfer"]
  }
}

nft_transfer

The nft_transfer scope allows you to query transactions based on non-fungible token transfers. This is useful for tracking specific NFT movements or auditing NFT transfer histories.

Parameters

asset_identifier
Required
string

The asset_identifier property specifies the fully qualified asset identifier to observe, such as ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys.

actions
Required
array of strings

The actions property specifies the types of NFT actions to observe, such as mint, transfer, or burn.

{
  "if_this": {
    "scope": "nft_transfer",
    "asset_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09::monkeys",
    "actions": ["mint"]
  }
}

stx_transfer

The stx_transfer scope allows you to query transactions involving STX token movements. This is crucial for monitoring STX transfers, including minting, burning, and locking actions.

Parameters

actions
Required
array of strings

The actions property specifies the types of STX token actions to observe, such as mint, transfer, burn, and lock.

{
  "if_this": {
    "scope": "stx_transfer",
    "actions": ["transfer", "lock"]
  }
}

print_event

The print_event scope allows you to query transactions based on specific print events emitted during contract execution. This is useful for monitoring specific events for auditing or tracking purposes.

Parameters

contract_identifier
Required
string

The contract_identifier property specifies the fully qualified contract identifier to observe.

contains
Required
string

The contains property is used for matching an event containing the specified string.

matches_regex
Required
string

The matches_regex property is used for matching an event that regex matches with the specified string.

{
  "if_this": {
    "scope": "print_event",
    "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09",
    "contains": "monkey"
  }
}

contract_call

The contract_call scope allows you to query transactions that involve direct calls to specific methods within a smart contract. This is particularly useful for tracking interactions with critical contract functions.

Parameters

contract_identifier
Required
string

The contract_identifier property specifies the fully qualified contract identifier to observe.

method
Required
string

The method property specifies the specific method within the contract to observe.

{
  "if_this": {
    "scope": "contract_call",
    "contract_identifier": "SP000000000000000000002Q6VF78.pox",
    "method": "stack-stx"
  }
}

contract_deployment

The contract_deployment scope allows you to query transactions involving the deployment of smart contracts. This is crucial for monitoring new contract deployments and ensuring compliance with expected deployments.

Parameters

deployer
Required
string

The deployer property specifies the STX address of the deployer to observe.

implement_trait
Required
string

The implement_trait property specifies the contract trait to observe.

{
  "if_this": {
    "scope": "contract_deployment",
    "deployer": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
  }
}

Observing contract calls with Chainhook