The Graph

The Graph is a decentralized indexing protocol for querying blockchain data. Subgraphs define which smart contract events to index, how to transform them into entities, and expose them via a GraphQL API. The protocol supports Ethereum, Arbitrum, Optimism, Base, Polygon, Avalanche, BSC, Celo, Gnosis, and 40+ other networks.

What You Probably Got Wrong

• Hosted service is DEPRECATED -- do not use graph deploy --node https://api.thegraph.com/deploy/. Use Subgraph Studio exclusively. Hosted service endpoints stopped serving queries in Q2 2024. All documentation referencing --node https://api.thegraph.com/deploy/ is outdated.

• Mappings are AssemblyScript, NOT TypeScript -- despite .ts file extensions, subgraph mappings compile to WebAssembly via AssemblyScript. This means: no closures, no union types, no optional chaining (?.), no nullish coalescing (??), no Array.map/filter/reduce, no JSON.parse, no async/await, no try/catch. If you write standard TypeScript, the build will fail with cryptic errors.

• graph-ts types are NOT standard TS types -- BigInt, BigDecimal, Bytes, Address, and ethereum.Event come from @graphprotocol/graph-ts. They are NOT bigint, number, or Uint8Array. You must use BigInt.fromI32(), BigDecimal.fromString(), and Address.fromString() constructors. Arithmetic uses method calls: a.plus(b), a.minus(b), a.times(b), a.div(b).

• graph codegen must run before build -- entities and contract bindings are auto-generated from schema.graphql and ABIs. If you skip codegen, imports like import { Transfer } from '../generated/ERC20/ERC20' will fail. Always run graph codegen after ANY change to schema or ABIs.

• Entity IDs must be Bytes or String, not numeric -- the @entity directive requires an id field of type ID! which maps to Bytes or String in AssemblyScript. Using BigInt or Int as entity ID causes schema validation failure.

• store.get returns nullable -- Entity.load(id) returns Entity | null. You must null-check before accessing fields. AssemblyScript does not have optional chaining, so you need explicit if (entity != null) blocks.

• Subgraph Studio requires authentication per machine -- graph auth --studio <deploy-key> stores the key in ~/.graph. This is per-machine, not per-project. CI/CD must re-auth on each run.