Packages • Development • Docs • Contributing • Security • License
--- [The Graph](https://thegraph.com/) 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](./packages/contracts) | [](https://badge.fury.io/js/@graphprotocol%2Fcontracts) | Contracts enabling the open and permissionless decentralized network known as The Graph protocol. | | [data-edge](./packages/data-edge) | [](https://badge.fury.io/js/@graphprotocol%2Fdata-edge) | Data edge testing and utilities for The Graph protocol. | | [hardhat-graph-protocol](./packages/hardhat-graph-protocol) | [](https://badge.fury.io/js/hardhat-graph-protocol) | A Hardhat plugin that extends the runtime environment with functionality for The Graph protocol. | | [horizon](./packages/horizon) | [](https://badge.fury.io/js/@graphprotocol%2Fhorizon) | Contracts for Graph Horizon, the next iteration of The Graph protocol. | | [interfaces](./packages/interfaces) | [](https://badge.fury.io/js/@graphprotocol%2Finterfaces) | Contract interfaces for The Graph protocol contracts. | | [issuance](./packages/issuance) | [](https://badge.fury.io/js/@graphprotocol%2Fissuance) | Smart contracts for The Graph's token issuance functionality | | [subgraph-service](./packages/subgraph-service) | [](https://badge.fury.io/js/@graphprotocol%2Fsubgraph-service) | Contracts for the Subgraph data service in Graph Horizon. | | [token-distribution](./packages/token-distribution) | [](https://badge.fury.io/js/@graphprotocol%2Ftoken-distribution) | Contracts managing token locks for network participants. | | [toolshed](./packages/toolshed) | [](https://badge.fury.io/js/@graphprotocol%2Ftoolshed) | A collection of tools and utilities for the Graph Protocol TypeScript components. | ## Development ### Setup To set up this project you'll need [git](https://git-scm.com) and [pnpm](https://pnpm.io/) installed. From your command line: ```bash 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 ```bash # 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](https://github.com/changesets/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: ```bash 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: ```bash 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: ```bash 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`](.github/workflows/publish.yml) 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`: ```bash 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: ```bash # 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. ```bash pnpm lint # Run all linters pnpm lint:staged # Lint only staged files ``` See [docs/Linting.md](docs/Linting.md) for detailed configuration, inline suppression syntax, and troubleshooting. ## Documentation - [Deployment Strategy](DEPLOYMENT.md) — Branching model and deployment workflow for Solidity contracts - [Linting](docs/Linting.md) — 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](https://discord.com/invite/vtvv7FP) or [The Graph Forum](https://forum.thegraph.com/) 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](https://immunefi.com/bounty/thegraph/). Responsible disclosure procedures must be followed to receive bounties. ## License Copyright © 2021 The Graph Foundation Licensed under [GPL license](LICENSE).