The Graph Protocol

A decentralized network for querying and indexing blockchain data.

Packages • Development • Docs • Contributing • Security • License

---

The Graph is an indexing protocol for querying networks like Ethereum, IPFS, Polygon, and other blockchains. Anyone can build and Publish open APIs, called subgraphs, making data easily accessible.

Packages

This repository is a pnpm workspaces monorepo containing the following packages:

Package	Latest version	Description
contracts		Contracts enabling the open and permissionless decentralized network known as The Graph protocol.
data-edge		Data edge testing and utilities for The Graph protocol.
hardhat-graph-protocol		A Hardhat plugin that extends the runtime environment with functionality for The Graph protocol.
horizon		Contracts for Graph Horizon, the next iteration of The Graph protocol.
interfaces		Contract interfaces for The Graph protocol contracts.
issuance		Smart contracts for The Graph's token issuance functionality
subgraph-service		Contracts for the Subgraph data service in Graph Horizon.
token-distribution		Contracts managing token locks for network participants.
toolshed		A collection of tools and utilities for the Graph Protocol TypeScript components.

Development

Setup

To set up this project you'll need git and pnpm installed.

From your command line:

corepack enable
pnpm set version stable

# Clone this repository
$ git clone https://github.com/graphprotocol/contracts

# Go into the repository
$ cd contracts

# Install dependencies
$ pnpm install

# Build projects
$ pnpm build

# Run tests
$ pnpm test

Script Patterns

This monorepo follows consistent script patterns across all packages to ensure reliable builds and tests:

Build Scripts

• pnpm build (root) - Builds all packages by calling build:self on each
• pnpm build (package) - Builds dependencies first, then the package itself
• pnpm build:self - Builds only the current package (no dependencies)
• pnpm build:dep - Builds workspace dependencies needed by the current package

Test Scripts

• pnpm test (root) - Builds everything once, then runs test:self on all packages
• pnpm test (package) - Builds dependencies first, then runs tests
• pnpm test:self - Runs only the package's tests (no building)
• pnpm test:coverage (root) - Builds everything once, then runs test:coverage:self on all packages
• pnpm test:coverage (package) - Builds dependencies first, then runs coverage
• pnpm test:coverage:self - Runs only the package's coverage tests (no building)

Key Benefits

• Efficiency: Root pnpm test builds once, then tests all packages
• Reliability: Individual package tests always ensure dependencies are built
• Consistency: Same patterns work at any level (root or package)
• Child Package Support: Packages with child packages delegate testing appropriately

Examples

# Build everything from root
pnpm build

# Test everything from root (builds once, tests all)
pnpm test

# Test a specific package (builds its dependencies, then tests)
cd packages/horizon && pnpm test

# Test without building (assumes dependencies already built)
cd packages/horizon && pnpm test:self

Versioning and publishing packages

We use changesets to manage package versioning, this ensures that all packages are versioned together in a consistent manner and helps with generating changelogs.

Step 1: Creating a changeset

A changeset is a file that describes the changes that have been made to the packages in the repository. To create a changeset, run the following command from the root of the repository:

pnpm changeset

Changeset files are stored in the .changeset directory until they are packaged into a release. You can commit these files and even merge them into your main branch without publishing a release.

Step 2: Creating a package release

When you are ready to create a new package release, run the following command to package all changesets, this will also bump package versions and dependencies:

pnpm changeset version

Step 3: Tagging the release

Note: this step is meant to be run on the main branch.

After creating a package release, you will need to tag the release commit with the version number. To do this, run the following command from the root of the repository:

pnpm changeset tag
git push --follow-tags

Step 4: Publishing a package release

Note: this step is meant to be run on the main branch.

The Publish package to NPM workflow is the standard publish path. It uses OIDC trusted publishing — no NPM_TOKEN is involved, and SLSA provenance is attached automatically. Anyone with workflow_dispatch permission on the repo can run it; no local npm credentials needed. The workflow also creates and pushes the package's git tag after a successful publish (so Step 3 can be skipped when using this path).

Dispatch from the Actions tab, or via gh:

gh workflow run publish.yml -f package=interfaces -f tag=latest -f dry_run=false

Inputs:

• package — the workspace package to publish (one of address-book, contracts, interfaces, toolshed).
• tag — npm dist-tag. Use latest for stable releases; use a custom tag (dips, sepolia, next, …) for pre-releases so the stable channel isn't overwritten.
• dry_run — when true, validates the workflow without consuming a version or pushing a git tag.

The workflow publishes one package per dispatch; for a multi-package release, dispatch once per package.

Prerequisite: each package on the choice list must have a Trusted Publisher entry on npmjs.com (Settings → Publishing access) with owner graphprotocol, repo contracts, workflow publish.yml, environment blank. Adding a new package to the workflow's package input without configuring its npm-side entry first will 403 at the publish step.

Alternative: local publish

For maintainers with publish rights on @graphprotocol/* — useful as a fallback if OIDC is unavailable, or for packages not on the workflow's choice list. Run from the root of a clean checkout:

# Publish the packages
pnpm changeset publish

# Alternatively use
pnpm publish --recursive

Linting

This monorepo uses multiple linting tools: ESLint, Prettier, Solhint, Forge Lint, Markdownlint, and YAML Lint.

pnpm lint          # Run all linters
pnpm lint:staged   # Lint only staged files

See docs/Linting.md for detailed configuration, inline suppression syntax, and troubleshooting.

Documentation

• Deployment Strategy — Branching model and deployment workflow for Solidity contracts
• Linting — Linting configuration and troubleshooting

Each package also has its own README with package-specific documentation.

Contributing

Contributions are welcomed and encouraged! You can do so by:

• Creating an issue
• Opening a PR

If you are opening a PR, it is a good idea to first go to The Graph Discord or The Graph Forum and discuss your idea! Discussions on the forum or Discord are another great way to contribute.

Security

If you find a bug or security issue please go through the official channel, The Graph Security Bounties on Immunefi. Responsible disclosure procedures must be followed to receive bounties.

License

Copyright © 2021 The Graph Foundation

Licensed under GPL license.