Update F.A.Q.

Author: droserasprout

docs/12.faq.md

@@ -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?
 
@@ -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