Dex & More Subgraphs Monorepo

This monorepo contains subgraphs for indexing and querying various protocol smart contracts. It includes subgraphs for the DEX (Uniswap V2 fork) and can be extended to index other contracts.

📦 Repository Structure

.
├── subgraphs/          # Individual subgraph packages
│   ├── dex/           # DEX subgraph (Uniswap V2 fork)
│   │   ├── abis/      # Smart contract ABIs
│   │   ├── queries/   # Example GraphQL queries
│   │   ├── scripts/   # Build and preparation scripts
│   │   └── src/       # TypeScript source files
│   │       ├── mappings/  # Event handlers and data transformation logic
│   │       └── types/     # Generated TypeScript interfaces
│   └── main-dapp/     # Main dapp subgraph
└── utils/             # Shared utilities
    ├── dockerfiles/   # Docker configurations
    │   ├── ci_cd/     # Containers for CI/CD pipeline
    │   └── core/      # Core infrastructure containers
    └── envfiles/      # Environment templates

🌐 Subgraph Architecture

This repository implements The Graph protocol for indexing blockchain data:

• DEX Subgraph: Indexes a Uniswap V2-compatible DEX, tracking:

  • Pairs and tokens with their reserves and pricing
  • Swaps (trades) with amounts and pricing
  • Liquidity events (mints and burns)
  • Time-series data (minute, 10-minute, hourly, daily metrics)
  • Protocol-wide statistics

• Graph Node: Processes blockchain events, runs the mapping handlers, and stores indexed data in PostgreSQL

• IPFS: Stores the subgraph definition (GraphQL schema + mappings)

• Anvil: Used for local development to simulate blockchain behavior

🚀 Getting Started

Prerequisites

• Node.js v20 or later
• PNPM package manager
• Docker and Docker Compose
• Foundry (for Anvil)
• The Graph CLI (@graphprotocol/graph-cli)

🔐 Environment Setup

The repository supports multiple environments:

• Localhost: Development environment with Anvil
• Testnet: Testnet deployment
• Mainnet: Mainnet deployment

Environment files should be placed in utils/envfiles/:

• .env.localhost
• .env.testnet
• .env.mainnet

Required Environment Variables

Each environment file should contain:

# Network configuration
NETWORK=testnet  # (localhost, testnet, or mainnet)
RPC_URL=https://your-rpc-endpoint

# Block configuration
RPC_START_BLOCK=12345678  # Starting block number for indexing
DEX_START_BLOCK=12345678  # Specific start block for DEX subgraph

# Subgraph flags
FLAG_ENABLE_SUB_DEX=true  # Enable/disable DEX subgraph
FLAG_ENABLE_SUB_MAIN_DAPP=false  # Enable/disable main-dapp subgraph

# Anvil configuration (for localhost only)
RPC_BLOCK_TIME=1  # Block time in seconds

🛠 Development

Initial Setup

1. Install dependencies:

pnpm install

2. Check environment and dependencies:

make check-deps

Local Development

Start a local development environment:

make dev

This command will:

1. Clean previous deployments
2. Set up localhost environment
3. Install dependencies
4. Start Anvil (if in localhost mode)
5. Prepare and deploy the DEX subgraph
6. Start monitoring logs

Testnet Deployment

Deploy to the testnet:

make deploy-prodtestnet

🤖 CI/CD Pipeline

This repository includes a GitHub Actions workflow for automated deployments to testnet:

• Trigger: Pushes to the testnet branch or manual workflow dispatch
• Process:
  1. Prepares the remote server environment
  2. Transfers repository files via SCP
  3. Executes make deploy-prodtestnet on the remote server
  4. Provides real-time monitoring of the deployment

To set up the CI/CD pipeline, configure the following GitHub secrets:

• REMOTE_HOST_TESTNET
• REMOTE_USERNAME
• SSH_PRIVATE_KEY
• REMOTE_PORT

🔧 Makefile Commands

The repository includes a comprehensive Makefile with various utility commands:

Command	Description
make dev	Full local development workflow
make simple	Simplified development workflow (uses local .env)
make deploy-prodtestnet	Production deployment for testnet
make clean	Clean up generated files and Docker containers
make prepare	Prepare subgraph configuration(s)
make deploy	Deploy subgraph(s)
make monitor	Monitor Graph Node logs
make monitor-error	Monitor only error logs
make help	Show all available commands

📊 Querying Subgraphs

Example queries for each subgraph are available in the queries/ directory:

DEX Queries

• Fetch pairs and tokens
• Track swaps, mints, and burns
• Monitor user positions
• Access global statistics

Query endpoints:

• Localhost: http://localhost:8000/subgraphs/name/<subgraph-name>
• Testnet: http://<your-server-ip>:8000/subgraphs/name/<subgraph-name>

Note: the subgraph name is the folder name of the subgraph (eg: dex).

Example Query

query {
  pairs(first: 5) {
    id
    token0 {
      id
      symbol
      name
    }
    token1 {
      id
      symbol
      name
    }
    reserve0
    reserve1
    totalSupply
  }
}

🔍 Troubleshooting

Common Issues

1. Graph Node fails to start:

   • Check PostgreSQL connection details
   • Verify RPC endpoint is accessible
   • Ensure database and IPFS volumes aren't corrupted

2. Subgraph fails to deploy:

   • Check for GraphQL schema validation errors
   • Verify contract addresses in the subgraph manifest
   • Ensure start blocks are correctly set

3. Indexing errors:

   • Monitor logs with make monitor
   • Check RPC endpoint stability and rate limits
   • Verify smart contract ABIs match on-chain contracts

📖 Documentation

• Each subgraph has its own README with specific details
• GraphQL schemas define the data structure:
  • subgraphs/dex/schema.graphql
  • subgraphs/main-dapp/schema.graphql