> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lineage

> How BlockDB ties derived rows back to on-chain events using stable identifiers and coordinates.

## Overview

Every record BlockDB delivers comes with a **mathematical receipt you can independently verify**.

You can always ask: **where did this come from, and was it computed correctly?**

**Lineage is the answer** — a traceable path from any derived row (a price, a pool snapshot, a transfer) back to the raw on-chain log that produced it, anchored by cryptographically stable coordinates and verifiable against the Merkle trie that secures the chain itself.

<Frame>
  <img src="https://mintcdn.com/blockdb/eJa_EKZIjvwpdrMT/images/blockdb-proof-of-derivation.png?fit=max&auto=format&n=eJa_EKZIjvwpdrMT&q=85&s=5cffd39d8fef30fe507028eb7fa79b36" alt="Proof of derivation — how BlockDB traces derived dataset rows back to raw on-chain log events via stable coordinates and Merkle-verifiable receipts." width="1299" height="1045" data-path="images/blockdb-proof-of-derivation.png" />
</Frame>

***

## What Lineage Gives You

<CardGroup cols={3}>
  <Card title="Stable row handles" icon="fingerprint">
    `_tracing_id` repeats across API responses and warehouse exports for the same logical row — safe to store, join, and use in support tickets.
  </Card>

  <Card title="Explicit on-chain coordinates" icon="crosshairs">
    `block_height`, `transaction_hash`, `log_index`, and related fields anchor every row to chain execution, where the DDL defines them.
  </Card>

  <Card title="Cross-dataset joins" icon="code-merge">
    Shared coordinates and [dataset IDs](/api-reference/enumerations/dataset-id) let you join OHLC, reserves, transfers, and primitives in SQL or notebooks.
  </Card>
</CardGroup>

***

## Tracing Fields

| Location        | Field                                                                 | What it provides                                                            |
| --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| APIs (`/evm/*`) | `_tracing_id`                                                         | Opaque per-tenant handle for the row when present in that dataset's schema. |
| SQL exports     | `_tracing_id`, `_created_at`, `_updated_at`                           | Mirror API fields for warehouses (where the table defines them).            |
| Row payloads    | `block_height`, `transaction_hash`, `log_index`, pool/token addresses | Direct anchors to chain state and protocol entities.                        |

<Note>
  Not every aggregate table includes `_tracing_id` or `tracking_ids_view[]`. Use the [data catalog](/data-catalog/evm/dataset-index) for the exact column list per table.
</Note>

***

## Lineage API

For programmatic provenance expansion, use the Historic API [Lineage](/api-reference/evm/lineage/overview) suite:

<CardGroup cols={2}>
  <Card title="Record" icon="receipt" href="/api-reference/evm/lineage/record">
    `POST /evm/lineage/record` — retrieve lineage metadata for a specific row.
  </Card>

  <Card title="Parents" icon="sitemap" href="/api-reference/evm/lineage/parents">
    `POST /evm/lineage/parents` — walk the provenance graph up to parent records.
  </Card>
</CardGroup>