DOCSEARCHbyAlgolia
Submit Docs

Graph Tooling

repository·main·Indexed 19 days ago

https://github.com/graphprotocol/graph-tooling

A monorepo containing essential developer tools for building and managing subgraphs on The Graph protocol, including the @graphprotocol/graph-cli and TypeScript library. It provides a command reference for subgraph lifecycle management—from initialization to deployment—and a comprehensive set of example subgraphs for Ethereum, Cosmos, NEAR, and Arweave, as well as implementations for data aggregations and Substreams-powered subgraphs.

Tokens
58.6K
Snippets
185
Records
302
Agent score
62%

What's inside graph-tooling

  2. Overview of Graph Tooling packages

    main

    The Graph Tooling repository is a monorepo containing essential tools for subgraph developers. The primary packages available via NPM are:

    • @graphprotocol/graph-cli: The Graph Command Line Interface (CLI).
    • @graphprotocol/graph-ts: The Graph TypeScript library used for writing subgraph logic.

  3. Understand the NEAR Receipts Subgraph Example

    main

    This example subgraph demonstrates how to index NEAR Receipts for the app.good-morning.near contract. It serves as a reference implementation for developers looking to build subgraphs on the NEAR network using The Graph.

    To see the indexed data in action, you can interact with the application at: https://gm-near.surge.sh/

    For general guidance on indexing NEAR protocols, refer to the official documentation on supported networks.

  4. Explore Example Subgraphs

    main

    The examples/ directory contains a variety of subgraph implementations designed to demonstrate specific patterns, blockchain integrations, and advanced features of The Graph. Use these examples to learn how to implement custom logic for different ecosystems (Ethereum, Cosmos, NEAR, Arweave) or specific data processing tasks (aggregations, filtering, event handling).

    Key Example Categories:

    • Core Fundamentals: Minimal subgraphs showing basic structure, mapping, and querying.
    • Blockchain Specifics:
      • Ethereum: Basic event handlers and smart contract indexing (e.g., Gravatar).
      • Cosmos: Block filtering, token swaps (Osmosis), validator delegations, and rewards.
      • NEAR: Indexing blocks and transaction receipts.
      • Arweave: Indexing blocks, transactions, tags, and POAs.
    • Advanced Patterns:
      • Aggregations: Using block numbers as predictable values to demonstrate data aggregation logic.
      • Substreams: Integration with Substreams to track contract deployments using substreams_entity_change types and helpers.

  5. How the Graph CLI works

    main

    The CLI processes a subgraph manifest (typically subgraph.yaml) containing references to:

    • A GraphQL schema
    • Smart contract ABIs
    • Mappings (written in AssemblyScript for traditional subgraphs, or Substreams packages/triggers for Substreams-based subgraphs)

    Workflow:

    1. Compilation: It compiles mappings to WebAssembly.
    2. Building: It builds a version of the subgraph saved to IPFS or a local directory for debugging.
    3. Deployment: It deploys the subgraph to a Graph Node instance or Subgraph Studio.
    4. Publishing: It allows direct publishing to the decentralized network for indexing via Graph Explorer.

  6. Substreams directory structure and dependencies

    main

    As of version 0.50.0, when generating a directory tree for substreams, the structure follows this pattern:

    .
├── package.json
├── schema.graphql
└── subgraph.yaml

    In this setup, the package.json only depends on the CLI, as the CLI is the primary tool used by developers for deployment. The schema.graphql defines the subgraph schema, and subgraph.yaml serves as the manifest file.

    .
├── package.json
├── schema.graphql
└── subgraph.yaml

  8. Automatic entity renaming for contracts with 'id' events

    main
    In @graphprotocol/graph-cli version 0.45.0, if a contract contains an event named id, the CLI automatically renames the resulting id entity to {contractName}_id and updates the mapping to use {contractName}_id. This prevents naming collisions with the standard entity id.

  11. Quickstart: Deploy a Substreams-powered subgraph

    main

    To deploy the example Substreams-powered subgraph which tracks Ethereum contract deployments, follow these steps in order:

    1. Install the necessary dependencies, including graph-cli.
    2. Prepare the Substreams module by building and packaging it.
    3. Build the subgraph.
    4. Deploy the subgraph.

    Prerequisites: You must have the dependencies necessary for local Substreams development installed on your machine.

    yarn install # install graph-cli
yarn substreams:prepare # build and package the substreams module
yarn subgraph:build # build the subgraph
yarn deploy # deploy the subgraph