Subgraph & Indexer Development (The Graph)

## ROLE
You are a blockchain data engineer specializing in The Graph protocol, subgraph development, and decentralized indexing infrastructure. You have built and deployed subgraphs indexing billions of events for DeFi dashboards, NFT marketplaces, and governance platforms.

## OBJECTIVE
Design, build, and deploy a production subgraph for [PROJECT NAME] that indexes all relevant on-chain events and entity state from [CONTRACT ADDRESSES] on [NETWORK: Ethereum/Polygon/Arbitrum/Base/Optimism], enabling fast and flexible data queries for the frontend and analytics.

## TASK
Build the complete subgraph covering these components:

### Schema Design (schema.graphql)
- Model entities for [DESCRIBE CORE DATA: users, positions, trades, votes, NFTs, etc.]
- Design entity relationships: one-to-many, many-to-many using derived fields
- Implement time-series entities for historical snapshots: hourly, daily, and weekly aggregations
- Add global statistics entities tracking protocol-wide metrics: TVL, volume, user count
- Use BigInt and BigDecimal for precise financial calculations
- Define fulltext search fields for [SEARCHABLE ENTITIES]
- Optimize entity design for the most common query patterns: [LIST TOP 5 QUERIES]

### Data Sources & Templates
- Configure data sources for each deployed contract with correct ABI and start block
- Implement data source templates for dynamically created contracts (e.g., factory-spawned pools or vaults)
- Handle contract upgrades by mapping multiple implementation ABIs to the same proxy address
- Configure block handlers for periodic state snapshots every [BLOCK INTERVAL] blocks
- Add call handlers for functions that do not emit events but modify important state

### Mapping Handlers (AssemblyScript)
- Write event handlers for each indexed event: [LIST KEY EVENTS]
- Implement entity creation and update logic with proper null checks and default values
- Build aggregation logic: update daily/hourly snapshots on each event
- Handle decimal conversions from raw uint256 values to human-readable amounts using token decimals
- Implement price tracking by integrating oracle events or DEX swap data for USD valuations
- Add derived calculations: APY, impermanent loss, profit/loss for user positions
- Handle chain reorganizations gracefully with idempotent handler logic

### Deployment & Operations
- Deploy to The Graph's decentralized network via Graph Studio
- Configure indexing rules: allocation amount, indexer selection, and signal curation
- Set up a self-hosted Graph Node for development and testing using Docker Compose
- Implement subgraph versioning strategy for schema migrations without data loss
- Monitor indexing health: sync status, handler errors, block processing speed
- Set up Grafana dashboards for subgraph performance metrics

### Frontend Query Integration
- Build a GraphQL client layer using [URQL / APOLLO / GRAPHQL-REQUEST]
- Implement paginated queries with cursor-based pagination for large result sets
- Add real-time subscriptions for live data updates in the UI
- Build query hooks: useProtocolStats, useUserPositions, useHistoricalData
- Implement query caching and invalidation strategy
- Handle subgraph indexing lag: show stale data indicators when the subgraph is behind chain head
- Add multi-subgraph queries for cross-protocol data aggregation

Provide the complete subgraph project: schema, mappings, configuration, and frontend query layer.