Skip to main content

Goldsky

How to build a subgraph

Talk to our team

What is a subgraph?

A subgraph is an index of a smart contract’s events: you describe the records you want, and an indexer turns each event into those records and serves them over a GraphQL API.

Teams building apps, wallets and chains use one so their front end can ask for only the data it shows without running an indexer or a database.

Goldsky hosts the subgraph, indexes the contract’s history, keeps it current and serves it at a public or private endpoint, with webhooks when records change; the schema, the mappings and the app that queries them are yours.

Who uses a subgraph?

DeFi teams, wallet apps, chain and rollup teams, and data firms that need a contract’s history behind an API.

How a subgraph gets built, deployed and queried

The diagram follows one subgraph from the schema and mappings you write to the app that queries it or handles its webhooks. Your setup may differ.

Your business, steps 1–2: Write schema and mappingsOr let the no-code wizard generate them
Your business, step 3: Deploy and tag itgoldsky subgraph deploy, then a prod tag
Goldsky, step 4: SubgraphsIndex from the start blockEvery event mapped into your entities
Your business, step 7: Use it in your appQuery the tag, or handle the webhooks
Goldsky, step 5: SubgraphsServe GraphQLA public or private endpoint per tag
or
Goldsky, step 6: SubgraphsPush entity changesA webhook for each insert, update or delete
  • Goldsky

How to build and host a subgraph

You write a schema and mappings, or let the no-code wizard generate them from a contract address, and deploy with the Goldsky CLI. Goldsky indexes the contract’s history, keeps the index current and serves it at a GraphQL endpoint, with optional webhooks when records change. Subgraphs run on EVM chains only, and their latency grows as event frequency climbs.

What you’ll need

  • Goldsky Subgraphs
  • The address of the contract to index and the network it runs on
  • A code repository for the schema and mappings
  • An HTTPS endpoint on your backend, if you use webhooks

  1. Install the CLI and log in

    Every deploy goes through a command-line tool, and it needs to know which project to deploy into.

    Install the tool on the machine or build server you deploy from and sign in to the right project. Deploy from the wrong project and the subgraph, its endpoint and its usage end up under another team’s account.

  2. Define the schema and mappings

    A subgraph has to know which contract events matter and how to turn each one into records your app can query.

    The schema sets the records (entities) and their fields, and the mappings are the code that creates or updates them from each event. A field you leave out can’t be queried later without changing the subgraph and indexing again; if you only need the contract’s events as they are, a no-code wizard can write both from the contract address.

  3. Deploy the subgraph

    Deploying hands your subgraph to the service that will index it and answer queries.

    Each deploy creates a new version that doesn’t change after it’s made, so the version your app uses keeps answering queries while a new one indexes.

  4. Index the contract’s history from the start block

    Handled by Goldsky Subgraphs

    Your app usually needs every past event too, so indexing starts from the block where the contract was deployed.

    Every event from that block on runs through your mappings into records, then new blocks are added as they arrive; reading the same history by scanning raw logs over RPC gets slower and runs into provider limits as the block range grows. A start block set too late skips early history without warning; one set too early only makes indexing take longer.

    Goldsky Subgraphs runs the same mapping code as other subgraph hosts, so an existing subgraph deploys unchanged with goldsky subgraph deploy. If you use the no-code wizard, it looks up the start block for you when it can.

    Deploy a subgraph to Goldsky (opens in a new tab)

  5. Serve the index over GraphQL

    Handled by Goldsky Subgraphs

    Your app reads the data by sending queries to a web address (an endpoint).

    The endpoint has to keep answering while new blocks are indexed. An endpoint anyone can find can be queried by anyone, so data that isn’t meant to be public needs one that asks for a key.

    Every subgraph and tag gets a hosted GraphQL endpoint in Subgraphs. Public endpoints are on by default, and you can turn on the private one so each request needs an API token in the Authorization header.

    Set up public and private endpoints (opens in a new tab)

  6. Push record changes to your backend

    Handled by Goldsky Subgraphs

    Some features, like a notification, need to react the moment data changes instead of asking over and over.

    Each change has to reach your server with enough detail to tell a new record from an update, or from a rollback after a reorg. Changes can arrive out of order, so your server keeps its own last-updated time for each record and doesn’t rely on arrival order.

    You can attach a webhook to any entity in Subgraphs, and it sends an INSERT, UPDATE or DELETE payload for every change. Each entity version carries a block_range, which is how you tell a reorg rollback from an ordinary update.

    Set up subgraph webhooks (opens in a new tab)

  7. Query from your app through a tag

    Your app needs one address that keeps working when you ship a new version of the subgraph.

    Point the app at a stable name, then move that name to the new version once it has caught up. Hard-code a version number instead and every subgraph update becomes an app release too.

What you control

Your team
  • Install the CLI and log in
  • Define the schema and mappings
  • Deploy the subgraph
  • Query from your app through a tag

Questions and answers

How do you create a subgraph?

You create a subgraph by writing a schema of the records you want and mappings that build them from contract events, then deploying it to an indexer. On Goldsky, the goldsky subgraph init command starts a no-code wizard that takes a contract address, fetches the ABI and generates the subgraph for you. When you need custom logic, write the schema and mappings yourself and deploy them with goldsky subgraph deploy; either way, you get a hosted GraphQL endpoint.

Security and deployment

  • SOC 2 Type IIIndependently audited security controls.
  • Dedicated infrastructureSingle-tenant options for production workloads.
  • Data residencyCloud, on-premises or co-located.

More use cases that stream chain data to your systems

Use cases built the same way

Build and host a subgraph with Goldsky

We’ll map it to your systems and show you what Goldsky runs, so your team builds the product, not the pipelines underneath it.

Talk to our team

© Endless Sky Inc. All rights reserved.

PrivacyTermsSecurity

System status