8 minutes
Graft a Subgraph to Ship Fixes and Replace Contracts
Grafting lets you deploy a new Subgraph that starts from an existing Subgraph’s indexed data instead of from scratch. Use it in two situations: to ship a fix for a Subgraph that failed on a bug, and to move to a contract redeployed at a new address while keeping the old contract’s history. Both skip a full re-index. This page covers how grafting works, when not to use it, and a walkthrough for each scenario.
What Grafting Is
When you deploy a Subgraph whose manifest contains a graft block, Graph Node copies the data of the base Subgraph up to and including the given block, then continues indexing the new Subgraph from that block on. Copying is much faster than indexing, though the initial copy can still take several hours for a very large Subgraph.
The base Subgraph must exist on the same Graph Node and must have indexed at least up to the graft block. Because of this, treat a grafted Subgraph as temporary: use it during development or an emergency, then replace it with an equivalent non-grafted version.
Set Up Grafting
Add two items to the new Subgraph’s manifest:
1features:2 - grafting3graft:4 base: Qm... # Deployment ID of the base Subgraph5 block: 6000000 # Last block to copy from the base Subgraphfeatures: Declaregraftinghere. Grafting does not work without it.graft.base: The Deployment ID of the base Subgraph (theQm...IPFS hash), not its Subgraph ID. See Subgraph ID vs Deployment ID.graft.block: The last block to copy. Choose it carefully: for a failed Subgraph, use the block of the last correctly processed event. A wrong block can lose or duplicate data.
Compatible Schema Changes
The grafted Subgraph’s schema does not have to match the base schema exactly, but it must be compatible with it. It must be a valid schema on its own, and it may differ from the base schema only in these ways:
- It adds or removes entity types
- It removes attributes from entity types
- It adds nullable attributes to entity types
- It turns non-nullable attributes into nullable attributes
- It adds values to enums
- It adds or removes interfaces
- It changes for which entity types an interface is implemented
Any other change, such as changing a field’s type or making a nullable field non-nullable, is not graft-compatible. That includes switching an entity’s id to Bytes. Marking a mutable entity as immutable is supported only if the copied history contains no updates or deletions of that entity.
When Not to Use Grafting
- Subgraphs on The Graph Network: Grafting is not recommended for Subgraphs published to The Graph Network, and some Indexers may not support it. Publish your first version to the network without grafting. You cannot graft a Subgraph from The Graph Network back to Subgraph Studio.
- Incompatible schema changes: If the fix needs a schema change outside the list above, re-index instead.
- Large mapping rewrites: If the fix changes how events are processed across the board, the new logic may not be consistent with data indexed under the old logic, which leads to incorrect data.
- Pruned blocks: You cannot graft at a block that has been pruned. If you graft often, keep a pruning window that covers it.
- Speeding up the rest of a sync: Grafting skips the blocks before the graft point only. Later blocks index faster only if the new code does less work per event.
Always test a graft in a development environment before you rely on it in production.
Scenario 1: Ship a Fix for a Failed Subgraph
When a Subgraph stops indexing because of a bug, grafting lets you deploy the fix right away. The new version copies everything the failed version indexed, so data services stay available and no history is lost.
- Find the graft block: Find the block of the last event the failed Subgraph processed correctly.
- Fix the mapping: Implement the fix in your mapping code, for example in
handleWithdrawal. - Add the graft: Point
graft.baseat the failed deployment’s Deployment ID, andgraft.blockat the block from step 1. - Deploy: Authenticate with the Graph CLI and run
graph deploy. - Verify: Confirm that indexing resumes from the graft point and that the fix resolves the error.
Here is the manifest for the fixed version. The data source is unchanged; only the mapping and the graft block are new:
1specVersion: 1.3.02schema:3 file: ./schema.graphql4dataSources:5 - kind: ethereum/contract6 name: SmartContract7 network: sepolia8 source:9 address: '0xYourContractAddress'10 abi: Lock11 startBlock: 500000012 mapping:13 kind: ethereum/events14 apiVersion: 0.0.915 language: wasm/assemblyscript16 entities:17 - Withdrawal18 abis:19 - name: Lock20 file: ./abis/Lock.json21 eventHandlers:22 - event: Withdrawal(uint256,uint256)23 handler: handleWithdrawal # fixed handler24 file: ./src/lock.ts25features:26 - grafting27graft:28 base: QmFailedDeploymentID # Deployment ID of the failed Subgraph29 block: 6000000 # Last correctly indexed blockScenario 2: Replace a Contract and Keep Its History
When you redeploy a contract at a new address, for example after an upgrade, graft a new Subgraph that tracks the new contract onto the Subgraph that tracked the old one. The new Subgraph serves the old contract’s history and the new contract’s events from one endpoint.
This walkthrough replaces a contract with an identical one (a new address, the same code) on Sepolia.
Build the Base Subgraph
To build and deploy the existing Subgraph used in this guide, use the example repo below. For the basics of building a Subgraph, see the Quick Start.
Note: The contract used in the Subgraph was taken from the following Hackathon Starterkit.
Base Subgraph Manifest
The Subgraph manifest subgraph.yaml identifies the data sources for the Subgraph, the triggers of interest, and the functions that should be run in response to those triggers. This is the manifest for the base Subgraph:
1specVersion: 1.3.02schema:3 file: ./schema.graphql4dataSources:5 - kind: ethereum6 name: Lock7 network: sepolia8 source:9 address: '0xb3aabe721794b85fe4e72134795c2f93b4eb7e63'10 abi: Lock11 startBlock: 595569012 mapping:13 kind: ethereum/events14 apiVersion: 0.0.915 language: wasm/assemblyscript16 entities:17 - Withdrawal18 abis:19 - name: Lock20 file: ./abis/Lock.json21 eventHandlers:22 - event: Withdrawal(uint256,uint256)23 handler: handleWithdrawal24 file: ./src/lock.ts- The
Lockdata source is the ABI and contract address you get when you compile and deploy the contract - The network should correspond to an indexed network being queried. Because this example runs on Sepolia testnet, the network is
sepolia - The
mappingsection defines the triggers of interest and the functions that should be run in response to those triggers. In this case, the Subgraph listens for theWithdrawalevent and calling thehandleWithdrawalfunction when it is emitted.
Deploy the Base Subgraph
- Go to Subgraph Studio and create a Subgraph on Sepolia testnet called
graft-example - Follow the directions in the
AUTH & DEPLOYsection on your Subgraph page in thegraft-examplefolder from the repo - Once finished, verify the Subgraph is indexing properly. If you run the following command in The Graph Playground
1{2 withdrawals(first: 5) {3 id4 amount5 when6 }7}It returns something like this:
1{2 "data": {3 "withdrawals": [4 {5 "id": "0xe8323d21c4f104607b10b0fff9fc24b9612b9488795dea8196b2d5f980d3dc1d0a000000",6 "amount": "0",7 "when": "1716394824"8 },9 {10 "id": "0xea1cee35036f2cacb72f2a336be3e54ab911f5bebd58f23400ebb8ecc5cfc45203000000",11 "amount": "0",12 "when": "1716394848"13 }14 ]15 }16}Once the base Subgraph is indexing properly, you can graft onto it.
Deploy the Grafted Subgraph
The graft replacement subgraph.yaml will have a new contract address. This could happen when you update your dapp, redeploy a contract, etc.
- Go to Subgraph Studio and create a Subgraph on Sepolia testnet called
graft-replacement - Create a new manifest. The
subgraph.yamlforgraft-replacementcontains a different contract address and new information about how it should graft. These are theblockof the last event emitted you care about by the old contract and thebaseof the old Subgraph. ThebaseSubgraph ID is theDeployment IDof your originalgraft-exampleSubgraph. You can find this in Subgraph Studio. - Follow the directions in the
AUTH & DEPLOYsection on your Subgraph page in thegraft-replacementfolder from the repo - Once finished, verify the Subgraph is indexing properly. If you run the following command in The Graph Playground
1{2 withdrawals(first: 5) {3 id4 amount5 when6 }7}It should return the following:
1{2 "data": {3 "withdrawals": [4 {5 "id": "0xe8323d21c4f104607b10b0fff9fc24b9612b9488795dea8196b2d5f980d3dc1d0a000000",6 "amount": "0",7 "when": "1716394824"8 },9 {10 "id": "0xea1cee35036f2cacb72f2a336be3e54ab911f5bebd58f23400ebb8ecc5cfc45203000000",11 "amount": "0",12 "when": "1716394848"13 },14 {15 "id": "0x2410475f76a44754bae66d293d14eac34f98ec03a3689cbbb56a716d20b209af06000000",16 "amount": "0",17 "when": "1716429732"18 }19 ]20 }21}You can see that the graft-replacement Subgraph is indexing from older graft-example data and newer data from the new contract address. The original contract emitted two Withdrawal events, Event 1 and Event 2. The new contract emitted one Withdrawal after, Event 3. The two previously indexed transactions (Event 1 and 2) and the new transaction (Event 3) were combined together in the graft-replacement Subgraph.
The grafted Subgraph now serves the full history across both contracts.
Note: The grafted manifest in this walkthrough has one data source, for the new contract. It copies the old contract’s data up to the graft block, but it does not index any events the old contract emits after that block. If the old contract can still emit events you need, keep a data source for it in the grafted manifest too.
After Grafting
- Republish without grafting: Once the grafted version is stable, deploy a non-grafted version for long-term maintenance. Relying on a graft indefinitely complicates future updates.
- Keep both contracts after a contract replacement: A non-grafted version indexes from scratch, so it needs two data sources, one for the old contract (with its original
startBlock) and one for the new contract. If you only replace the address, the non-grafted version indexes only the new contract’s data. - Move your apps: Point every app and service at the new, non-grafted version.
- Keep the old version serving until the new one has fully synced.
Learn More
- Grafting onto existing Subgraphs: the manifest reference.
- Debug with Subgraph Forking: find and fix the bug locally before you graft.
- Grafting examples for popular contracts: Curve, ERC-721, and Uniswap.
- Data source templates: another way to handle contracts that change over time.
- Guides & Best Practices overview: the full checklist and how this page fits with the rest of the section.