feat: add docs

isum · isum · commit 60cadf0fa272 · 2025-02-10T13:11:45.000+02:00
diff --git a/README.md b/README.md
@@ -0,0 +1,30 @@
+# Subgraph Composition Example
+
+This repository provides a minimal example of how to use the new subgraph composition feature of [The Graph][0].
+
+## What is The Graph?
+
+[The Graph][0] is a powerful, decentralized protocol that enables seamless querying and indexing of blockchain data. 
+It simplifies the complex process of querying blockchain data, making DApp development faster and easier.
+
+## What is subgraph composition?
+
+Subgraph composition allows a subgraph to depend on another subgraph as a data source, allowing one subgraph to consume 
+and react to the data or entity changes of another subgraph. This feature enables modular subgraph architectures.
+
+Instead of interacting directly with on-chain data, a subgraph can be set up to listen to updates from another subgraph 
+and react to entity changes. This can be used for a variety of use cases, such as aggregating data from multiple 
+subgraphs or triggering actions based on changes in external subgraph entities.
+
+## How to use subgraph composition?
+
+The example defines 3 source subgraphs:
+- [block-time-subgraph](./block-time-subgraph) - a subgraph that calculates the block time for each block
+- [block-cost-subgraph](./block-cost-subgraph) - a subgraph that indexes the cost of each block
+- [block-size-subgraph](./block-size-subgraph) - a subgraph that indexes the size of each block
+
+and a composed subgraph that combines and aggregates the information from the 3 source subgraphs:
+
+- [block-stats-subgraph](./block-stats-subgraph) - a subgraph that collects statistics about blocks
+
+[0]: https://thegraph.com/
diff --git a/block-cost-subgraph/README.md b/block-cost-subgraph/README.md
@@ -0,0 +1,29 @@
+# Block Cost Subgraph
+
+This is a subgraph that indexes the cost of each block.
+
+## Local Deployment
+
+### Requirements
+
+These are minimal requirements to deploy this subgraph locally:
+
+- A [graph-node][0] instance running locally
+- An [IPFS][1] instance running locally
+- [Node.js][2] and npm
+
+### Deployment
+
+To deploy this subgraph locally, run the following commands:
+
+```bash
+npm install
+npm run codegen
+npm run build
+npm run create-local
+npm run deploy-local
+```
+
+[0]: https://github.com/graphprotocol/graph-node
+[1]: https://docs.ipfs.tech/
+[2]: https://nodejs.org/
diff --git a/block-cost-subgraph/subgraph.yaml b/block-cost-subgraph/subgraph.yaml
@@ -1,3 +1,4 @@
+# Subgraph composition is supported as of 1.3.0 spec version.
 specVersion: 1.3.0
 description: A subgraph that indexes the cost of each block.
 schema:
@@ -7,15 +8,22 @@ dataSources:
     name: BlockDataSource
     network: mainnet
     source:
+      # We are only using block data in the example, so an empty contract address is fine.
       address: "0x0000000000000000000000000000000000000000"
+
+      # The same is true for ABI, an empty event is provided.
       abi: BlockDataSource
+
+      # Randomly selected at a point of high activity on the network.
       startBlock: 10000000
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
       language: wasm/assemblyscript
       entities:
         - BlockCost
+
+      # We are only using block data in the example, so an empty event is fine.
       abis:
         - name: BlockDataSource
           file: ./abis/BlockDataSource.json
diff --git a/block-size-subgraph/README.md b/block-size-subgraph/README.md
@@ -0,0 +1,29 @@
+# Block Size Subgraph
+
+This is a subgraph that indexes the size of each block.
+
+## Local Deployment
+
+### Requirements
+
+These are minimal requirements to deploy this subgraph locally:
+
+- A [graph-node][0] instance running locally
+- An [IPFS][1] instance running locally
+- [Node.js][2] and npm
+
+### Deployment
+
+To deploy this subgraph locally, run the following commands:
+
+```bash
+npm install
+npm run codegen
+npm run build
+npm run create-local
+npm run deploy-local
+```
+
+[0]: https://github.com/graphprotocol/graph-node
+[1]: https://docs.ipfs.tech/
+[2]: https://nodejs.org/
diff --git a/block-size-subgraph/src/mapping.ts b/block-size-subgraph/src/mapping.ts
@@ -1,4 +1,4 @@
-import { ethereum , BigInt} from "@graphprotocol/graph-ts";
+import { BigInt, ethereum } from "@graphprotocol/graph-ts";
 import { BlockSize } from "../generated/schema";
 
 export function handleBlock(block: ethereum.Block): void {
diff --git a/block-size-subgraph/subgraph.yaml b/block-size-subgraph/subgraph.yaml
@@ -1,3 +1,4 @@
+# Subgraph composition is supported as of 1.3.0 spec version.
 specVersion: 1.3.0
 description: A subgraph that indexes the size of each block.
 schema:
@@ -7,15 +8,22 @@ dataSources:
     name: BlockDataSource
     network: mainnet
     source:
+      # We are only using block data in the example, so an empty contract address is fine.
       address: "0x0000000000000000000000000000000000000000"
+
+      # The same is true for ABI, an empty event is provided.
       abi: BlockDataSource
+
+      # Randomly selected at a point of high activity on the network.
       startBlock: 10000000
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
       language: wasm/assemblyscript
       entities:
         - BlockSize
+
+      # We are only using block data in the example, so an empty event is fine.
       abis:
         - name: BlockDataSource
           file: ./abis/BlockDataSource.json
diff --git a/block-stats-subgraph/README.md b/block-stats-subgraph/README.md
@@ -0,0 +1,39 @@
+# Block Stats Subgraph
+
+This is a composed subgraph that combines and aggregates the information from the 3 source subgraphs.
+
+To keep this example as simple as possible, all source subgraphs use only block handlers, but in a real environment 
+each source subgraph will use data from different smart contracts.
+
+> [!NOTE]
+> Any change to a source subgraph will most likely generate a new deployment ID. Be sure to update the deployment ID in 
+> the data source address of the subgraph manifest to take advantage of the latest changes.
+
+## Local Deployment
+
+### Requirements
+
+These are minimal requirements to deploy this subgraph locally:
+
+- A [graph-node][0] instance running locally
+- An [IPFS][1] instance running locally
+- [Node.js][2] and npm
+
+### Deployment
+
+> [!IMPORTANT]
+> All source subgraphs should be deployed before the composed subgraph is deployed.
+
+To deploy this subgraph locally, run the following commands:
+
+```bash
+npm install
+npm run codegen
+npm run build
+npm run create-local
+npm run deploy-local
+```
+
+[0]: https://github.com/graphprotocol/graph-node
+[1]: https://docs.ipfs.tech/
+[2]: https://nodejs.org/
diff --git a/block-stats-subgraph/schema.graphql b/block-stats-subgraph/schema.graphql
@@ -1,3 +1,7 @@
+# This type is used to collect data from multiple source subgraphs
+# before saving the final immutable data for aggregation.
+#
+# Each trigger will partially fill the block data.
 type BlockDataSource @entity {
     id: ID!
     number: BigInt!
@@ -6,8 +10,12 @@ type BlockDataSource @entity {
     size: BigInt
 }
 
+# The immutable data used as the source for aggregation.
 type Block @entity(timeseries: true) {
+    # This field is required and will be filled in automatically.
     id: Int8!
+
+    # This field is required and will be filled in automatically.
     timestamp: Timestamp!
 
     hash: Bytes!
@@ -17,34 +25,58 @@ type Block @entity(timeseries: true) {
     size: BigInt!
 }
 
+# This type defines our aggregation on the immutable block data.
+# Aggregation buckets are created automatically, and there is no need to define anything in the mappings.
+#
+# There is no hard limit on the number of aggregates an aggregation type can have,
+# but there may be a performance penalty if too many aggregates are created.
 type Stats @aggregation(intervals: ["hour", "day"], source: "Block") {
+    # This field is required.
     id: Int8!
+
+    # This field is required.
     timestamp: Timestamp!
 
+    # The total number of source values used in an aggregation bucket.
     count: Int! @aggregate(fn: "count")
 
+    # By default, each aggregate starts at 0 for each new bucket.
+    # Therefore, it only aggregates over the time interval for the bucket.
     minBlockTime: BigInt! @aggregate(fn: "min", arg: "blockTime")
     maxBlockTime: BigInt! @aggregate(fn: "max", arg: "blockTime")
     sumBlockTime: BigInt! @aggregate(fn: "sum", arg: "blockTime")
     firstBlockTime: BigInt! @aggregate(fn: "first", arg: "blockTime")
     lastBlockTime: BigInt! @aggregate(fn: "last", arg: "blockTime")
+
+    # Cumulative aggregations will aggregate over the entire time series
+    # up to the end of the time interval for the bucket.
     allTimeMinBlockTime: BigInt! @aggregate(fn: "min", arg: "blockTime", cumulative: true)
     allTimeMaxBlockTime: BigInt! @aggregate(fn: "max", arg: "blockTime", cumulative: true)
 
+    # By default, each aggregate starts at 0 for each new bucket.
+    # Therefore, it only aggregates over the time interval for the bucket.
     minGasUsed: BigInt! @aggregate(fn: "min", arg: "gasUsed")
     maxGasUsed: BigInt! @aggregate(fn: "max", arg: "gasUsed")
     sumGasUsed: BigInt! @aggregate(fn: "sum", arg: "gasUsed")
     firstGasUsed: BigInt! @aggregate(fn: "first", arg: "gasUsed")
     lastGasUsed: BigInt! @aggregate(fn: "last", arg: "gasUsed")
+
+    # Cumulative aggregations will aggregate over the entire time series
+    # up to the end of the time interval for the bucket.
     totalGasUsed: BigInt! @aggregate(fn: "sum", arg: "gasUsed", cumulative: true)
     allTimeMinGasUsed: BigInt! @aggregate(fn: "min", arg: "gasUsed", cumulative: true)
     allTimeMaxGasUsed: BigInt! @aggregate(fn: "max", arg: "gasUsed", cumulative: true)
 
+    # By default, each aggregate starts at 0 for each new bucket.
+    # Therefore, it only aggregates over the time interval for the bucket.
     minSize: BigInt! @aggregate(fn: "min", arg: "size")
     maxSize: BigInt! @aggregate(fn: "max", arg: "size")
     sumSize: BigInt! @aggregate(fn: "sum", arg: "size")
     firstSize: BigInt! @aggregate(fn: "first", arg: "size")
     lastSize: BigInt! @aggregate(fn: "last", arg: "size")
+
+    # Cumulative aggregations will aggregate over the entire time series
+    # up to the end of the time interval for the bucket.
     totalSize: BigInt! @aggregate(fn: "sum", arg: "size", cumulative: true)
     allTimeMinSize: BigInt! @aggregate(fn: "min", arg: "size", cumulative: true)
     allTimeMaxSize: BigInt! @aggregate(fn: "max", arg: "size", cumulative: true)
diff --git a/block-stats-subgraph/src/mapping.ts b/block-stats-subgraph/src/mapping.ts
@@ -1,4 +1,4 @@
-import {Bytes, EntityOp, EntityTrigger, store} from "@graphprotocol/graph-ts";
+import {BigInt, Bytes, EntityOp, EntityTrigger, store} from "@graphprotocol/graph-ts";
 import {Block, BlockDataSource} from "../generated/schema";
 import {BlockTime} from "../generated/subgraph-QmcKB3XQyfNM2Uzzeyd9UmGqsw83Ysh8t9LGQD94DdfSS7";
 import {BlockCost} from "../generated/subgraph-QmQ2kJphSSsSUXqnSAKLvxmhPGNxjVtrTsLTUPeCszns17";
@@ -10,12 +10,7 @@ export function handleBlockTime(trigger: EntityTrigger<BlockTime>): void {
   }
 
   let blockTime = trigger.data;
-  let blockData = BlockDataSource.load(blockTime.id);
-
-  if (!blockData) {
-    blockData = new BlockDataSource(blockTime.id);
-    blockData.number = blockTime.number;
-  }
+  let blockData = loadOrCreateBlockData(blockTime.id, blockTime.number);
 
   blockData.blockTime = blockTime.blockTime;
   blockData.save();
@@ -29,12 +24,7 @@ export function handleBlockCost(trigger: EntityTrigger<BlockCost>): void {
   }
 
   let blockCost = trigger.data;
-  let blockData = BlockDataSource.load(blockCost.id);
-
-  if (!blockData) {
-    blockData = new BlockDataSource(blockCost.id);
-    blockData.number = blockCost.number;
-  }
+  let blockData = loadOrCreateBlockData(blockCost.id, blockCost.number);
 
   blockData.gasUsed = blockCost.gasUsed;
   blockData.save();
@@ -48,19 +38,25 @@ export function handleBlockSize(trigger: EntityTrigger<BlockSize>): void {
   }
 
   let blockSize = trigger.data;
-  let blockData = BlockDataSource.load(blockSize.id);
-
-  if (!blockData) {
-    blockData = new BlockDataSource(blockSize.id);
-    blockData.number = blockSize.number;
-  }
+  let blockData = loadOrCreateBlockData(blockSize.id, blockSize.number);
 
   blockData.size = blockSize.size;
   blockData.save();
 
   maybeCreateBlock(blockData);
 }
 
+function loadOrCreateBlockData(id: string, number: BigInt): BlockDataSource {
+  let blockData = BlockDataSource.load(id);
+
+  if (!blockData) {
+    blockData = new BlockDataSource(id);
+    blockData.number = number;
+  }
+
+  return blockData;
+}
+
 function maybeCreateBlock(blockData: BlockDataSource): void {
   if (blockData.blockTime === null || blockData.gasUsed === null || blockData.size === null) {
     return;
@@ -73,7 +69,6 @@ function maybeCreateBlock(blockData: BlockDataSource): void {
   block.blockTime = blockData.blockTime!;
   block.gasUsed = blockData.gasUsed!;
   block.size = blockData.size!;
-
   block.save();
 
   store.remove("BlockDataSource", blockData.id);
diff --git a/block-stats-subgraph/subgraph.yaml b/block-stats-subgraph/subgraph.yaml
diff --git a/block-time-subgraph/README.md b/block-time-subgraph/README.md
diff --git a/block-time-subgraph/src/mapping.ts b/block-time-subgraph/src/mapping.ts
diff --git a/block-time-subgraph/subgraph.yaml b/block-time-subgraph/subgraph.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { ethereum , BigInt} from "@graphprotocol/graph-ts";`
	`1`	`+import { BigInt, ethereum } from "@graphprotocol/graph-ts";`
`2`	`2`	`import { BlockSize } from "../generated/schema";`
`3`	`3`
`4`	`4`	`export function handleBlock(block: ethereum.Block): void {`