DipDup Framework

DipDup is a Python framework designed for building smart contract indexers. It allows developers to focus on implementing business logic by abstracting away the boilerplate required to store and serve blockchain data.

Key features include:

• Selective Indexing: Only the required data is requested, which leads to faster indexing times and reduced load on underlying blockchain APIs.
• Business Logic Focus: Minimizes the need to write low-level data storage and serving code.

DipDup integrates with the Hasura GraphQL Engine to expose your data to the client side. This allows you to build a GraphQL API on top of your database with minimal effort and provides a subscription mechanism for live updates.

If you are not using GraphQL, you can ignore the GraphQL-specific sections of the documentation.

An index is a core DipDup entity that connects your data inventory with the rules for handling blockchain data. It defines three main components:

1. What to track: Contracts, events, operations, etc.
2. Where to get the data: The datasource (e.g., evm, starknet, tezos).
3. How to process it: A set of handlers.

A handler is a callback function triggered when new data arrives from the datasource. Handlers receive the data item as an argument and can perform actions like database storage, notifications, or external API calls. Handlers are linked to specific patterns like entrypoints, events, or operations.

A selective blockchain indexer is an application designed to extract and organize specific blockchain data from multiple sources instead of processing the entire blockchain. This approach reduces storage and computational overhead compared to full node indexing and enables efficient querying for specific use cases.

DipDup is a framework designed to help you implement these selective indexers by acting as a customizable filter that captures and stores only the specific blockchain data you require.

The Model Context Protocol (MCP) integration allows LLMs (like Claude, Copilot, or Cursor) to connect directly to your DipDup indexer. This enables AI assistants to understand your indexer's configuration, query indexed blockchain data, and execute custom tools you define.

DipDup uses three MCP primitives:

• Resources: Application-controlled data/content that clients can read as context.
• Tools: Model-controlled executable functions (e.g., performing computations or querying the database).
• Prompts: User-controlled reusable prompt templates.

By default, Hasura does not restrict the number of rows returned per request. To prevent server abuse and heavy loads, you should set limits in your configuration file.

When limits are applied, you must implement pagination to retrieve all items. Refer to the Hasura pagination documentation for implementation details.

Hooks are user-defined callbacks that are not linked to any specific index. They allow you to execute logic or SQL scripts in response to system-wide events or manual triggers. There are two categories of hooks:

1. System hooks: Reserved hooks that fire on system-wide events (e.g., process restart). They are not atomic, cannot be fired manually, and cannot be scheduled via the job scheduler.
2. User hooks: Custom hooks defined in your configuration. They can be triggered manually using ctx.fire_hook or automatically via the job scheduler.

By default, hooks attempt to execute SQL scripts located in a corresponding subdirectory within the sql/ directory.

# Example of defining a user hook in dipdup.yaml
hooks:
  calculate_stats:
    callback: calculate_stats
    atomic: False
    args:
      major: bool
      depth: int

DipDup provides several context objects used to pass state and configuration to various callbacks during execution.

• DipDupContext: The common execution context used for both handler and hook callbacks. It contains the global configuration, the package, available datasources, and the transaction manager.
• HandlerContext: A specialized context for handler callbacks. It extends DipDupContext by adding handler_config, which contains the configuration specific to the current handler.
• HookContext: A specialized context for hook callbacks. It extends DipDupContext by adding hook_config, which contains the configuration specific to the current hook.
• McpContext: The execution context for MCP (Model Context Protocol) tools, resources, and prompts. It includes the running McpServer instance and the HttpDatasource (DipDup API).

Pattern items can include an optional field. This allows the pattern to continue matching even if that specific item is not found in the operation sequence. This is useful for skipping irrelevant external or internal calls.

Limitation: Optional items cannot be followed by operations that are 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