Stacks scopes

Stacks scopes define the if_this conditions in your Chainhook predicates. Each scope type monitors specific on-chain events on the Stacks 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"
  }
}

block_height

block_height matches blocks by their height.

Signature

{
  "scope": "block_height",
  "equals" | "higher_than" | "lower_than" | "between": value
}

Parameters

Name	Type	Required	Description
`equals`	integer	No*	Match exact block height
`higher_than`	integer	No*	Match blocks above height
`lower_than`	integer	No*	Match blocks below height
`between`	[integer, integer]	No*	Match blocks in range [start, end]

*One of these parameters is required

Examples

Match exact height

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

Match range of blocks

{
  "if_this": {
    "scope": "block_height",
    "between": [100000, 110000]
  }
}

ft_transfer

ft_transfer matches fungible token events.

Signature

{
  "scope": "ft_transfer",
  "asset_identifier": string,
  "actions": string[]
}

Parameters

Name	Type	Required	Description
`asset_identifier`	string	Yes	Fully qualified token identifier
`actions`	string[]	Yes	Token actions: `mint`, `transfer`, `burn`

Examples

Monitor token transfers

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

Track all token activities

{
  "if_this": {
    "scope": "ft_transfer",
    "asset_identifier": "SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-10-token::token",
    "actions": ["mint", "transfer", "burn"]
  }
}

nft_transfer

nft_transfer matches non-fungible token events.

Signature

{
  "scope": "nft_transfer",
  "asset_identifier": string,
  "actions": string[]
}

Parameters

Name	Type	Required	Description
`asset_identifier`	string	Yes	Fully qualified NFT identifier
`actions`	string[]	Yes	NFT actions: `mint`, `transfer`, `burn`

Examples

Monitor NFT mints

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

Track all NFT activities

{
  "if_this": {
    "scope": "nft_transfer",
    "asset_identifier": "SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.megapont-ape-club::apes",
    "actions": ["mint", "transfer", "burn"]
  }
}

stx_transfer

stx_transfer matches STX token events.

Signature

{
  "scope": "stx_transfer",
  "actions": string[]
}

Parameters

Name	Type	Required	Description
`actions`	string[]	Yes	STX actions: `mint`, `transfer`, `burn`, `lock`

Examples

Monitor STX transfers

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

Track all STX activities

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

print_event

print_event matches contract print events.

Signature

{
  "scope": "print_event",
  "contract_identifier": string,
  "contains" | "matches_regex": string
}

Parameters

Name	Type	Required	Description
`contract_identifier`	string	Yes	Fully qualified contract identifier
`contains`	string	No*	Match events containing string
`matches_regex`	string	No*	Match events by regex pattern

*One of these parameters is required

Examples

Match by substring

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

Match by regex pattern

{
  "if_this": {
    "scope": "print_event",
    "contract_identifier": "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-dao",
    "matches_regex": "vault-liquidated-.*"
  }
}

contract_call

contract_call matches specific contract function calls.

Signature

{
  "scope": "contract_call",
  "contract_identifier": string,
  "method": string
}

Parameters

Name	Type	Required	Description
`contract_identifier`	string	Yes	Fully qualified contract identifier
`method`	string	Yes	Contract method name

Example

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

contract_deployment

contract_deployment matches contract deployments.

Signature

{
  "scope": "contract_deployment",
  "deployer" | "implement_trait": string
}

Parameters

Name	Type	Required	Description
`deployer`	string	No*	STX address of deployer
`implement_trait`	string	No*	Trait the contract must implement

*One of these parameters is required

Examples

Monitor deployments by address

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

Monitor trait implementations

{
  "if_this": {
    "scope": "contract_deployment",
    "implement_trait": "SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-09-trait"
  }
}