Skip to content

Update F.A.Q. #1311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Wizard1209 merged 2 commits into from
Jan 19, 2026
Merged

Update F.A.Q. #1311

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60d3370
Update F.A.Q.
droserasprout Jan 12, 2026
86345e4
Merge branch 'next' into docs/faq-refresh
droserasprout Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 23 additions & 6 deletions docs/12.faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,27 +28,44 @@ DipDup is a Python framework for building indexing applications. It allows you t

### What hardware do I need to run DipDup?

DipDup can run on any amd64/arm64 machine that runs Python. Aim for good single-threaded and disk I/O performance.
DipDup can run on any amd64/arm64 machine that runs Python 3.12. Aim for good single-thread CPU performance and fast storage.

You need at least 512M of RAM, but actual requirements can grow significantly depending on the number and complexity of indexes, the size of internal queues and caches, and `CachedModel` usage.

## Indexing

### What's the difference between "level" and "block number"?

The term "level" is used in Tezos and some other blockchains as a synonym for "block height" or "block number". We use this term for historical reasons.

### What does "head" mean?

You may see the term "head" in logs, metrics and internal db tables. It refers to the latest known position in the blockchain, but with some nuances:

For **datasources** it means the last block available from the datalake/node/API indexer knows about. It may differ from the actual chain head for various reasons: network latency, node sync status, rate limits, etc.

For **indexes** it means the last block processed and stored in the database. It may lag behind the datasource head if indexing is still in progress or latest blocks have not triggered any handlers.

What to use for monitoring depend on your use case.

### How to index similar but not identical contracts as a single entity?

Multiple contracts can provide the same interface but have different storage structures. Examples are ERC20/ERC721/ERC1155 standard tokens on Ethereum and FA1.2/FA2 ones on Tezos. If you try to use the same typename for them, indexing will fail because of the storage mismatch. However, you can modify typeclasses manually. Edit the `types/<typename>/storage.py` file and comment out fields, leaving only the ones used in your index (common for all contracts with the same interface).

```python
class ContractStorage(BaseModel):
class Config:
extra = Extra.ignore
model_config = ConfigDict(
extra='forbid',
)

common_ledger: dict[str, str]
# unique_field_foo: str
# unique_field_bar: str
```

Don't forget the `Extra.ignore` Pydantic hint; otherwise, storage deserialization will fail. To restore the original typeclass, remove the modified file and run `dipdup init` again. You can also add the `--force` flag to overwrite all ABIs and typeclasses.
Don't forget the `model_config` field.

To restore the original typeclass, remove the modified file and run `dipdup init` again. You can also add the `--force` flag to overwrite all ABIs and typeclasses.

### How to use off-chain datasources?

Expand Down Expand Up @@ -177,11 +194,11 @@ It will update both the CLI tool and Python package.

**tl;dr**: Just use `uv` for everything.

For historical reasons, Python package management is a mess. There are multiple tools and approaches to manage Python dependencies. **pip** is a general-purpose package manager. It's simple and robust, but only covers basic functionality. For a full-fledged project, you need to use a tool to handle virtual environments, lock files, dependency resolution, publishing, etc. Some of the most popular tools are: uv, Poetry, PDM, Hatch and others.
For historical reasons, Python package management is a mess. There are multiple tools and approaches to manage Python dependencies. **pip** is a general-purpose package manager. It's simple and robust, but only covers basic functionality. For a full-fledged project, you need a tool to handle virtual environments, lock files, dependency resolution, publishing, etc. Some of the most popular tools are: uv, Poetry, PDM, pip-tools ([performance benchmark](https://lincolnloop.github.io/python-package-manager-shootout/)).

Starting with version 8.3, DipDup uses **uv** as the default package manager for both CLI installer and project management. This tool is extremely fast, reliable, and replaces the bulk of functionality provided by other tools.

Poetry and PDM integration in DipDup is deprecated and will be removed in future releases. To perform a migration, run the following commands:
Poetry and PDM integration in DipDup is deprecated and will be removed in future releases. To perform migration after updating to >8.3 run the following commands:

```shell [Terminal]
rm *.lock
Expand Down