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

# How it works

> How an EVM squid retrieves, transforms, persists, and serves blockchain data.

A running squid is a small pipeline of ordinary processes. This page walks through what they are
and how data moves between them.

## The processes

* **The processor** — the main Node.js process. It pulls blockchain data, runs your
  transformation code, and writes results through a store. All indexing logic lives here.
* **A database** — usually PostgreSQL (via the [TypeORM store](reference/data-stores/typeorm-store));
  [file datasets and BigQuery](guides/other-data-destinations) are alternatives.
* **A GraphQL server** (optional) — a separate process that [serves the indexed data](guides/serving-graphql)
  from PostgreSQL.

## The data flow

The processor is configured with a **data source** — where blocks come from and which data items
and fields to fetch (see the [EVM Portal stream](reference/evm-stream)). Filtering happens **upstream**:
the [SQD Network](/en/network/overview) sends only the requested items with only the requested
fields, in chunks covering thousands of blocks.

Each chunk arrives at your **batch handler** as a context object:

* `ctx.blocks` — the block slice with the requested data items;
* `ctx.store` — the persistence interface, bound to the current database transaction;
* a head flag telling you whether the squid has caught up with the chain.

The handler decodes and transforms the batch — arbitrary TypeScript, including
[external API calls](guides/advanced/external-apis-ipfs) — and persists results through the store,
ideally with [one write per table per batch](guides/advanced/batch-processing). The store commits
the data and the current block position **in the same database transaction**, which is what makes
squids restart-safe: on restart, indexing resumes exactly where the last committed batch ended.

## Keeping up with the chain

The Portal stream serves blocks all the way to the chain head, including
[unfinalized blocks](guides/advanced/unfinalized-blocks), so squids index in real time with no
extra data source. Blocks near the
tip are treated as *hot*: if the chain reorganizes, the store rolls back the affected changes and
the processor re-runs the replaced blocks — your handler code doesn't deal with forks.

## Serving the data

Squids that persist to PostgreSQL can expose the data as a GraphQL API. The schema-first flow:
you define entities in a [schema file](reference/schema-files/schema-files-codegen), generate
TypeORM model classes from it, and the [OpenReader server](reference/openreader/overview) derives
a full-featured API from the same schema. [Other serving options](guides/serving-graphql),
including Hasura, work from the same database.

Next: the [Quickstart](quickstart) runs this whole pipeline from a template, and
[Make an indexer](guides/make-an-indexer) walks the development flow in detail.