Init

Author: MichaelMacaulay

website/src/pages/en/subgraphs/guides/_meta.js

@@ -1,4 +1,5 @@
 export default {
+  'subgraph-composition': '',
   'subgraph-debug-forking': '',
   near: '',
   arweave: '',

website/src/pages/en/subgraphs/guides/subgraph-composition.mdx

@@ -0,0 +1,154 @@
+---
+title: Aggregate Data Using Subgraph Composition
+sidebarTitle: 'Build a Composable Subgraph with Multiple Subgraphs'
+---
+
+Leverage Subgraph composition to speed up development time. Create a base Subgraph with essential data, then build additional Subgraphs on top of it.
+
+Optimize your Subgraph by merging data from 3 independent, source Subgraphs into a single composable Subgraph to enhance data aggregation.
+
+## Introduction
+
+Composable Subgraphs enable you to combine multiple Subgraphs' data sources into a new Subgraph, facilitating faster and more flexible Subgraph development. Subgraph composition empowers you to create and maintain smaller, focused Subgraphs that collectively form a larger, interconnected dataset.
+
+### Benefits of Composition
+
+Subgraph composition is a powerful feature for scaling, allowing you to:
+
+- Reuse, mix, and combine existing data
+- Streamline development and queries
+- Use multiple data sources (up to five source Subgraphs)
+- Speed up your Subgraph's syncing speed
+- Handle errors and optimize the resync
+
+## Architecture Overview
+
+The setup for this example involves two Subgraphs:
+
+1. **Source Subgraph**: Tracks event data as entities.
+2. **Dependent Subgraph**: Uses the source Subgraph as a data source.
+
+You can find these in the `source` and `dependent` directories.
+
+- The **source Subgraph** is a basic event-tracking Subgraph that records events emitted by relevant contracts.
+- The **dependent Subgraph** references the source Subgraph as a data source, using the entities from the source as triggers.
+
+While the source Subgraph is a standard Subgraph, the dependent Subgraph uses the Subgraph composition feature.
+
+## Prerequisites
+
+### Source Subgraphs
+- All Subgraphs need to be published with a **specVersion 1.3.0 or later** (Use the latest graph-cli version to be able to deploy composable Subgraphs)
+- See notes here: https://github.com/graphprotocol/graph-node/releases/tag/v0.37.0
+- Immutable entities only: All Subgraphs must have [immutable entities](https://thegraph.com/docs/en/subgraphs/best-practices/immutable-entities-bytes-as-ids/#immutable-entities ) when the Subgraph is deployed    
+- Pruning can be used in the source Subgraphs, but only entities that are immutable can be composed on top of
+- Source Subgraphs cannot use grafting on top of existing entities
+- Aggregated entities can be composed on, but the composed entities on them cannot also use aggregations directly
+
+### Composed Subgraphs
+- You can only compose up to a **maximum of 5 source Subgraphs**
+- Composed Subgraphs can only use **datasources from the same chain**
+- **Nested composition is not yet supported**: Composing on top of another composed Subgraph isn’t allowed at this time
+- Aggregated entities can be composed on, but the composed entities on them cannot also use aggregations directly
+- Developers cannot compose an onchain datasource with a Subgraph datasource (i.e. you can’t do normal event handlers and call handlers and block handlers in a composed Subgraph)
+
+Additionally, you can explore the [example-composable-subgraph](https://github.com/graphprotocol/example-composable-subgraph) repository for a working implementation of composable subgraphs
+
+### Source Subgraph
+
+The source Subgraph tracks events from the Sushiswap v3 Subgraph on the Base chain. This Subgraph's configuration file is `source/subgraph.yaml`.
+
+> The `source/subgraph.yaml` employs the advanced Subgraph feature, [declarative `eth_calls`](https://thegraph.com/docs/en/subgraphs/developing/creating/advanced/#declared-eth_call). To review the code for this `source/subgraph.yaml`, check out the [source Subgraph example repo](https://github.com/incrypto32/subgraph-composition-sample-subgraph/blob/a5f13cb4b961f92d5c5631dca589c54feb1c0a19/source/subgraph.yaml).
+
+### Dependent Subgraph
+
+The dependent Subgraph is in the `dependent/subgraph.yaml` file, which specifies the source Subgraph as a data source. This Subgraph uses entities from the source to trigger specific actions based on changes to those entities.
+
+> To review the code for this `dependent/subgraph.yaml`, check out the [dependent Subgraph example repo](https://github.com/incrypto32/subgraph-composition-sample-subgraph/blob/main/dependant/subgraph.yaml).
+
+## Get Started
+
+The following is a guide that illustrates how to use one Subgraph as a data source for another. This example uses:
+
+- Sushiswap v3 Subgraph on Base chain
+- Two Subgraphs (but you can use up to **5 source** Subgraphs in your own development).
+
+### Step 1. Set Up Your Source Subgraph
+
+To set the source Subgraph as a data source in the dependent Subgraph, include the following in `subgraph.yaml`:
+
+```yaml
+specVersion: 1.3.0
+schema:
+  file: ./schema.graphql
+dataSources:
+  - kind: subgraph
+    name: Factory
+    network: base
+    source:
+      address: 'QmdXu8byAFCGSDWsB5gMQjWr6GUvEVB7S1hemfxNuomerz'
+      startBlock: 82522
+```
+
+Here, `source.address` refers to the Deployment ID of the source Subgraph, and `startBlock` specifies the block from which indexing should begin.
+
+### Step 2. Define Handlers in Dependent Subgraph
+
+Below is an example of defining handlers in the dependent Subgraph:
+
+```typescript
+export function handleInitialize(trigger: EntityTrigger<Initialize>): void {
+  if (trigger.operation === EntityOp.Create) {
+    let entity = trigger.data
+    let poolAddressParam = Address.fromBytes(entity.poolAddress)
+
+    // Update pool sqrt price and tick
+    let pool = Pool.load(poolAddressParam.toHexString()) as Pool
+    pool.sqrtPrice = entity.sqrtPriceX96
+    pool.tick = BigInt.fromI32(entity.tick)
+    pool.save()
+
+    // Update token prices
+    let token0 = Token.load(pool.token0) as Token
+    let token1 = Token.load(pool.token1) as Token
+
+    // Update ETH price in USD
+    let bundle = Bundle.load('1') as Bundle
+    bundle.ethPriceUSD = getEthPriceInUSD()
+    bundle.save()
+
+    updatePoolDayData(entity)
+    updatePoolHourData(entity)
+
+    // Update derived ETH price for tokens
+    token0.derivedETH = findEthPerToken(token0)
+    token1.derivedETH = findEthPerToken(token1)
+    token0.save()
+    token1.save()
+  }
+}
+```
+
+In this example, the `handleInitialize` function is triggered when a new `Initialize` entity is created in the source Subgraph, passed as `EntityTrigger<Initialize>`. The handler updates the pool and token entities based on data from the new `Initialize` entity.
+
+`EntityTrigger` has three fields:
+
+1. `operation`: Specifies the operation type, which can be `Create`, `Modify`, or `Remove`.
+2. `type`: Indicates the entity type.
+3. `data`: Contains the entity data.
+
+Developers can then determine specific actions for the entity data based on the operation type.
+
+## Key Takeaways
+
+- Use this powerful tool to quickly scale your Subgraph development and reuse existing data.
+- The setup includes creating a base source Subgraph and referencing it in a dependent Subgraph.
+- You define handlers in the dependent Subgraph to perform actions based on changes in the source Subgraph's entities.
+
+This approach unlocks composability and scalability, simplifying both development and maintenance efficiency.
+
+## Additional Resources
+
+To use other advanced features in your Subgraph, check out [Subgraph advanced features](/developing/creating/advanced/) and [this Subgraph composition example repo](https://github.com/incrypto32/subgraph-composition-sample-subgraph).
+
+To learn how to define source Subgraphs, check out [this Subgraph composition example repo](https://github.com/isum/subgraph-composition-example).