Zield Protocol - Subgraph Indexer

A Graph Protocol subgraph for indexing and querying blockchain events from the Zield Protocol smart contracts on Base Sepolia.

📊 Overview

This subgraph indexes events from the Zield Protocol's CDP (Collateralized Debt Position) system, tracking user activities including:

• Collateral deposits and withdrawals
• Borrowing and repayment operations
• Liquidation events
• Protocol adapter registration
• Token whitelisting

🎯 Indexed Contracts

MultiProtocolCDP

Address: 0x7928f54d9B05d50F5B0e7faC884A62e9302abe95

Tracks the main CDP operations:

• CollateralDeposited: User deposits yield-bearing tokens
• CollateralWithdrawn: User withdraws collateral
• Borrowed: User borrows zUSD against collateral
• Repaid: User repays borrowed zUSD
• Liquidated: Liquidation of undercollateralized positions
• ZieldTokenCreated: New Zield token wrapper creation

VaultRegistry

Address: 0x6cCF953aA3Cd41BE2013D86797671c21D1BF34AF

Tracks protocol configuration:

• AdapterRegistered: Protocol adapter added (Lido, Aave, Compound)
• AdapterRemoved: Protocol adapter removed
• TokenWhitelisted: Yield token approved for use
• TokenRemoved: Token removed from whitelist

📝 GraphQL Schema

Core Entities

CollateralDeposited

type CollateralDeposited @entity(immutable: true) {
  id: Bytes!
  user: Bytes!           # User address
  yieldToken: Bytes!     # Token address (wstETH, aUSDC, cDAI)
  amount: BigInt!        # Deposit amount
  protocol: String!      # Protocol name (Lido, Aave, Compound)
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

Borrowed

type Borrowed @entity(immutable: true) {
  id: Bytes!
  user: Bytes!          # Borrower address
  amount: BigInt!       # Amount borrowed in zUSD
  totalDebt: BigInt!    # User's total debt after borrowing
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

Repaid

type Repaid @entity(immutable: true) {
  id: Bytes!
  user: Bytes!
  amount: BigInt!           # Amount repaid
  remainingDebt: BigInt!    # Debt after repayment
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

Liquidated

type Liquidated @entity(immutable: true) {
  id: Bytes!
  user: Bytes!              # Liquidated user
  liquidator: Bytes!        # Liquidator address
  debtCovered: BigInt!      # Debt covered in liquidation
  collateralSeized: BigInt! # Collateral taken by liquidator
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

Registry Entities

TokenWhitelisted

type TokenWhitelisted @entity(immutable: true) {
  id: Bytes!
  token: Bytes!         # Token address
  protocolName: String! # Associated protocol
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

AdapterRegistered

type AdapterRegistered @entity(immutable: true) {
  id: Bytes!
  protocolName: String! # Protocol name
  adapter: Bytes!       # Adapter contract address
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

🚀 Quick Start

Prerequisites

• Node.js 16+
• Yarn package manager
• Graph CLI
• Goldsky account (for deployment)

Installation

yarn install

Configuration

Update networks.json with your contract addresses:

{
  "base-sepolia": {
    "MultiProtocolCDP": {
      "address": "0x7928f54d9B05d50F5B0e7faC884A62e9302abe95",
      "startBlock": 32708885
    },
    "VaultRegistry": {
      "address": "0x6cCF953aA3Cd41BE2013D86797671c21D1BF34AF"
    }
  }
}

Development

Code Generation

Generate TypeScript types from GraphQL schema and ABIs:

yarn codegen

Build

Compile the subgraph:

yarn build

Testing

Run unit tests with Matchstick:

yarn test

📤 Deployment

Goldsky (Production)

The subgraph is deployed to Goldsky for production use.

Initial Deployment

yarn goldsky-init

This will:

1. Login to Goldsky
2. Generate code
3. Build the subgraph
4. Deploy to Goldsky

Update Deployment

yarn goldsky

This will:

1. Login to Goldsky
2. Remove existing deployment
3. Regenerate and rebuild
4. Deploy new version

Local Development

Create Local Instance

yarn create-local

Deploy Locally

yarn deploy-local

Requires a local Graph node running at:

• Graph Node: http://localhost:8020/
• IPFS: http://localhost:5001

Remove Local Instance

yarn remove-local

The Graph Studio

Deploy to The Graph's hosted service:

yarn deploy

📊 Querying the Subgraph

Endpoint

https://api.goldsky.com/api/public/project_cmh2orech3c0v01q1ay82bvjm/subgraphs/zield/0.0.1/gn

Example Queries

Get Recent Deposits

query RecentDeposits {
  collateralDepositeds(
    first: 10
    orderBy: blockTimestamp
    orderDirection: desc
  ) {
    id
    user
    yieldToken
    amount
    protocol
    blockTimestamp
    transactionHash
  }
}

Get User Borrow History

query UserBorrows($user: Bytes!) {
  borroweds(
    where: { user: $user }
    orderBy: blockTimestamp
    orderDirection: desc
  ) {
    id
    amount
    totalDebt
    blockTimestamp
    transactionHash
  }
}

Get All User Activity

query UserActivity($user: Bytes!) {
  collateralDepositeds(where: { user: $user }) {
    id
    yieldToken
    amount
    protocol
    blockTimestamp
  }
  borroweds(where: { user: $user }) {
    id
    amount
    totalDebt
    blockTimestamp
  }
  repaids(where: { user: $user }) {
    id
    amount
    remainingDebt
    blockTimestamp
  }
  collateralWithdrawns(where: { user: $user }) {
    id
    yieldToken
    amount
    blockTimestamp
  }
}

Get Liquidations

query Liquidations {
  liquidateds(
    first: 20
    orderBy: blockTimestamp
    orderDirection: desc
  ) {
    id
    user
    liquidator
    debtCovered
    collateralSeized
    blockTimestamp
    transactionHash
  }
}

Get Whitelisted Tokens

query WhitelistedTokens {
  tokenWhitelisteds {
    id
    token
    protocolName
    blockTimestamp
  }
}

Get Protocol Adapters

query Adapters {
  adapterRegistereds {
    id
    protocolName
    adapter
    blockTimestamp
  }
}

🗂 Project Structure

/
├── abis/                        # Contract ABIs
│   ├── MultiProtocolCDP.json
│   └── VaultRegistry.json
├── src/                         # Event handlers
│   ├── multi-protocol-cdp.ts  # CDP event handlers
│   └── vault-registry.ts       # Registry event handlers
├── generated/                   # Auto-generated code
├── build/                       # Compiled subgraph
├── tests/                       # Matchstick tests
├── schema.graphql              # GraphQL schema definition
├── subgraph.yaml               # Subgraph manifest
├── networks.json               # Network configurations
├── docker-compose.yml          # Local Graph node setup
└── package.json

🔧 Event Handlers

All event handlers follow the pattern:

1. Create entity from event
2. Map event parameters to entity fields
3. Add block metadata (number, timestamp, hash)
4. Save entity to The Graph

Example:

export function handleBorrowed(event: BorrowedEvent): void {
  let entity = new Borrowed(
    event.transaction.hash.concatI32(event.logIndex.toI32())
  )
  entity.user = event.params.user
  entity.amount = event.params.amount
  entity.totalDebt = event.params.totalDebt
  entity.blockNumber = event.block.number
  entity.blockTimestamp = event.block.timestamp
  entity.transactionHash = event.transaction.hash
  entity.save()
}

📦 Dependencies

• @graphprotocol/graph-cli: 0.97.1 - Graph CLI tools
• @graphprotocol/graph-ts: 0.37.0 - AssemblyScript runtime
• matchstick-as: 0.6.0 - Unit testing framework

🌐 Network

• Chain: Base Sepolia (testnet)
• Network ID: base-sepolia
• Start Block: 32708885

📚 Resources

• The Graph Documentation
• AssemblyScript Book
• Goldsky Documentation
• Matchstick Testing

🔍 Monitoring

Query subgraph health and sync status via The Graph Explorer or Goldsky dashboard.

🐛 Troubleshooting

Code Generation Fails

# Clean and regenerate
rm -rf generated build
yarn codegen

Deployment Issues

• Verify contract addresses in networks.json
• Check start block number
• Ensure ABIs are up to date
• Confirm Goldsky authentication

Query Errors

• Check entity names match schema
• Verify field types
• Ensure proper filtering syntax

📝 License

UNLICENSED - Hackathon Project

🤝 Contributing

This is a hackathon project for the Zield Protocol. For questions or contributions, contact the development team.

---

Built for Base Sepolia testnet | Powered by The Graph & Goldsky