What a subgraph actually is

A subgraph is three files that together say: watch these contracts, and when this happens, write this.

• subgraph.yaml, the manifest. Which contracts, from which block, which events, and which handler runs for each.
• schema.graphql, the schema. Which entities exist and what fields they have. This becomes both your storage model and your query API.
• mappings, usually AssemblyScript. The handlers themselves. An event comes in, an entity goes out.

Deploy those and an indexer replays chain history through your handlers, materialising your entities, then keeps following the chain. Applications query the result over GraphQL.

The property everything depends on.

A subgraph must be deterministic. Given the same chain data, every indexer running it must produce byte-identical results.

This is not a style preference. It is the requirement that makes the whole protocol work. Indexers publish Proofs of Indexing, hashes committing to what they derived, and the security model rests on honest indexers producing matching hashes. If your subgraph could produce different output on different machines, honest indexers would disagree, and disputes would fire against people who did nothing wrong.

So the mapping runtime forbids everything that could vary:

• No network calls. You cannot fetch a price from an API mid-handler.
• No wall-clock time or randomness. Only block time and block data.
• No filesystem, no environment.
• Only chain state and what you have already written.

Once you internalise this, a whole class of design questions answers itself. “Can I call an oracle here” is no. “Can I use the current time” is no, use block time. “Can I read from a database I control” is no.

Where the difficulty actually lives.

Not in the syntax. The syntax is a day’s work. These are where the time goes:

Modelling. The schema is the API your consumers live with, and changing it later means a new deployment and a resync. Entity identity is the load-bearing decision: what is the ID of this thing, and is it stable across every event that touches it?

Reorgs. The chain can retract blocks. The framework handles unwinding, and your mapping still has to be written so that unwinding makes sense, which mostly means not accumulating state in ways that cannot be reversed.

Factories and dynamic sources. Contracts deployed by contracts mean the set of addresses to watch grows during indexing. Template data sources handle this and they are a common source of confusion.

Contract upgrades. A proxy upgrade changes behaviour under a stable address. Your mapping was written against the old ABI. This is the most common way a working subgraph starts failing without anyone touching it.

Indexing time. Reading a large history through handlers is slow. If your backfill takes days, that is a design constraint, and it is a large part of why Substreams exists.

What it is not.

• Not a server. You do not run it. You define it, and indexers execute it.
• Not a database you write to. The only writer is your mapping, and its only input is chain data.
• Not able to see anything off chain. If your product depends on off-chain state, that stays in your own systems.
• Not free to run. It needs signal to be indexed at all, which is the curator path’s subject and a real cost to plan for.