subgraph-patterns

The Graph Subgraph Patterns

Project Structure

my-subgraph/
├── subgraph.yaml           # Manifest: data sources, event handlers
├── schema.graphql           # Entity definitions (GraphQL)
├── src/
│   └── mappings.ts          # Event handler logic (AssemblyScript)
├── tests/
│   └── mappings.test.ts     # Matchstick unit tests
├── abis/
│   └── MyContract.json      # Contract ABIs
└── networks.json            # Multi-network config

Subgraph Manifest (subgraph.yaml)

specVersion: 1.0.0
indexerHints:
  prune: auto
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: MyProtocol
    network: base
    source:
      address: "0xContractAddress"
      abi: MyProtocol
      startBlock: 12345678  # Block contract was deployed
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.9
      language: wasm/assemblyscript
      entities:
        - Deposit
        - Withdrawal
        - User
      abis:
        - name: MyProtocol
          file: ./abis/MyProtocol.json
        - name: ERC20
          file: ./abis/ERC20.json
      eventHandlers:
        - event: Deposit(indexed address,uint256,uint256)
          handler: handleDeposit
        - event: Withdrawal(indexed address,uint256)
          handler: handleWithdrawal
      file: ./src/mappings.ts
templates:
  - kind: ethereum
    name: Vault
    network: base
    source:
      abi: Vault
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.9
      language: wasm/assemblyscript
      entities:
        - VaultDeposit
      abis:
        - name: Vault
          file: ./abis/Vault.json
      eventHandlers:
        - event: VaultDeposit(indexed address,uint256)
          handler: handleVaultDeposit
      file: ./src/vault-mappings.ts

Schema Design (schema.graphql)

type Protocol @entity {
  id: Bytes!                    # Use Bytes! for addresses
  totalDeposited: BigDecimal!
  totalUsers: BigInt!
  vaults: [Vault!]! @derivedFrom(field: "protocol")
}

type User @entity {
  id: Bytes!                    # user address
  deposits: [Deposit!]! @derivedFrom(field: "user")
  totalDeposited: BigDecimal!
  firstDepositAt: BigInt!
  lastActiveAt: BigInt!
}

type Vault @entity {
  id: Bytes!                    # vault address
  protocol: Protocol!
  asset: Bytes!
  totalAssets: BigDecimal!
  deposits: [Deposit!]! @derivedFrom(field: "vault")
  createdAt: BigInt!
  createdAtBlock: BigInt!
}

type Deposit @entity(immutable: true) {
  id: Bytes!                    # tx hash + log index
  user: User!
  vault: Vault!
  amount: BigDecimal!
  shares: BigInt!
  timestamp: BigInt!
  blockNumber: BigInt!
  transactionHash: Bytes!
}

type DailySnapshot @entity {
  id: String!                   # "YYYY-MM-DD"
  date: BigInt!
  totalDeposited: BigDecimal!
  depositCount: BigInt!
  uniqueUsers: BigInt!
}