Handlers

After defining the index in the configuration file and initializing the project, you can start implementing handlers. DipDup generates callback stubs for all handlers specified in the configuration file. You can find them in the handlers directory.

Callback signature

This partial callback definition matches two contract calls in the same transaction:

callback: on_transaction
pattern:
- type: transaction
  destination: contract
  entrypoint: foo
- type: transaction
  destination: contract
  entrypoint: bar

The callback stub will look like the following:

async def on_transaction(
    ctx: HandlerContext,
    foo: TzktTransaction[FooParameter, ContractStorage],
    bar: TzktTransaction[BarParameter, ContractStorage],
) -> None:
    ...

Don't rename module and function names, as DipDup uses them to find the callback.

The first argument is always HandlerContext. It provides useful helpers and contains an internal state (see Context Reference). The rest of the arguments are generated according to the handler pattern. Payloads of some arguments are typed, and DipDup generates corresponding models for them in the types directory.

Processing data

Define the callback body to process the data. The most common case is to perform some calculations and store the result in the database. DipDup provides a convenient ORM to work with the database.

from demo_raw import models
from dipdup.context import HandlerContext
from dipdup.models.tezos_tzkt import TzktOperationData


async def on_operation(
    ctx: HandlerContext,
    operation: TzktOperationData,
) -> None:
    await models.Operation.create(
        hash=operation.hash,
        level=operation.level,
        type=operation.type,
    )

Handling name collisions

Indexing operations of multiple contracts with the same entrypoints can lead to name collisions during code generation. In this case DipDup raises a ConfigurationError and suggests to set alias for each conflicting handler. Currently, it applies to tezos.tzkt.operation indexes only. In the the following snippet "call" entrypoint of both contracts is called. Add alias field to resolve the conflict:

callback: on_mint
pattern:
- type: transaction
  entrypoint: mint
  alias: foo_mint
- type: transaction
  entrypoint: mint
  alias: bar_mint

You can also change argument names (but not the order!) manually if you want to.