Operation group in BCD explorer `operation` index config

tezos.operations index

Operation index allows you to query only operations related to your dapp and match them with handlers by content. A single contract call consists of implicit operation and, optionally, internal operations. For each of them, you can specify a handler that will be called when the operation group matches. As a result, you get something like an event log for your dapp.

Handlers

Each operation handler config item contains two required fields:

  • callback — a name of async function with a particular signature; DipDup will search for it in dipdup_indexer.handlers.<callback> module.
  • pattern — a non-empty list of items that need to be matched.
dipdup.yaml
indexes:
  my_index:
    kind: tezos.operations
    datasources:
      - tzkt
    contracts:
      - some_contract
    handlers:
      - callback: on_call
        pattern:
          - destination: some_contract
            entrypoint: transfer

You can think of the operation pattern as a regular expression on a sequence of operations (both external and internal) with a global flag enabled (there can be multiple matches). Multiple operation parameters can be used for matching (source, destination, etc.).

When the operation group matches the pattern, DipDup creates arguments for the callback function and invokes it.

Typed and untyped arguments

You will get slightly different callback argument types depending on whether the pattern item is typed or not. If so, DipDup will generate the dataclass for a particular entrypoint/storage, otherwise, you will have to handle untyped parameters/storage updates stored in TzktOperationData model.

Applying filters

In pattern items, you can specify filters to narrow down the search. For example, you can match only operations sent to a particular address. Each operation type has its own set of filters.

Originations

namedescriptionsupportedtyped
originated_contract.addressOrigination of exact contract.🟢🟢
originated_contract.code_hashOriginations of all contracts having the same code.🟢🟢
source.addressOriginations sent by address. Special cases only, see below.🟡🔴
source.code_hashNot supported.🔴🔴

Filtering originations by source.address is very slow and strict typing is not supported. For most cases originated_contract.code_hash suits better.

Transactions

namedescriptionsupportedtyped
source.addressSent by exact address🟢🔴
source.code_hashSent by any contract having this code hash🟢🔴
destination.addressInvoked contract address🟢🟢¹
destination.code_hashInvoked contract code hash🟢🟢¹
destination.entrypointEntrypoint called🟢🟢

¹ when entrypoint is specified too

Smart rollup calls

namedescriptionsupportedtyped
source.addressSent by exact address.🟢🔴
source.code_hashNot supported🔴🔴
destination.addressInvoked contract address🟢🔴
destination.code_hashNot supported🔴🔴

Optional items

Pattern items have optional field to continue matching even if this item is not found. It's usually unnecessary to match the entire operation content; you can skip external/internal calls that are not relevant. However, there is a limitation: optional items cannot be followed by operations ignored by the pattern.

dipdup.yaml
pattern:
  # Implicit transaction
  - type: transaction
    destination: some_contract
    entrypoint: mint
  # Internal transactions
  - type: transaction
    destination: another_contract
    entrypoint: transfer
  - type: transaction
    source: some_contract

Specifying contracts to index

DipDup will try to guess the list of used contracts by handlers' signatures. If you want to specify it explicitly, use contracts field:

dipdup.yaml
indexes:
  my_index:
    kind: tezos.operations
    datasources:
      - tzkt
    contracts:
      - foo
      - bar

Specifying operation types

By default, DipDup processes only transactions, but you can enable other operation types you want to process:

dipdup.yaml
indexes:
  my_index:
    kind: tezos.operations
    datasources:
      - tzkt
    types:
      - transaction
      - origination
      - migration
      - sr_execute

Indexing smart rollups (Etherlink)

Since version 7.2 you can index Tezos smart rollups the same way as regular contracts. Rollups have addresses starting with sr1 prefix, they have only one entrypoint (default) and their storage is always empty. Everything else is roughly the same.

If you want to index a smart rollup, choose a demo_tezos_etherlink template when creating a new project.

dipdup.yaml
contracts:
  rollup:
    address: sr1...
    typename: rollup

indexes:
  my_index:
    kind: tezos.operations
    datasources:
      - tzkt
    contracts:
      - rollup
    handlers:
      - callback: on_rollup_call
        pattern:
          - destination: rollup
            entrypoint: default

entrypoint field equal to default is required for rollup pattern items. Otherwise, the transaction will be treated as untyped.

Help and tips -> Join our Discord
Ideas or suggestions -> Issue Tracker
GraphQL IDE -> Open Playground