EAS Indexing Service

This tool allows you to quickly spin up your own EAS indexer on any EVM chain that has EAS contracts deployed.

Prerequisites

• Node.js 18+ (Node.js 20 LTS recommended)
• PostgreSQL database
• Docker and Docker Compose (optional, for easy database setup)

Quick Setup

For a complete development environment setup, run the automated setup script:

./scripts/setup-dev.sh

This script will:

• Check Node.js version compatibility
• Install dependencies
• Set up environment files
• Configure database (with Docker if available)
• Generate Prisma client and database schema
• Verify the setup

Manual Installation

If you prefer manual setup, follow these steps:

1. Install dependencies:

yarn install
# or
npm install

2. Create environment file:

cp .env.example .env

Edit the .env file with your configuration. Key variables include:

DATABASE_URL=postgresql://user:password@localhost:5432/eas-sepolia
INFURA_API_KEY=your_infura_key_here
ALCHEMY_ARBITRUM_API_KEY=your_alchemy_key_here
ALCHEMY_SEPOLIA_API_KEY=your_alchemy_key_here
ALCHEMY_OPTIMISM_GOERLI_API_KEY=your_optimism_key_here

# Chain to index (make sure it exists in EAS_CHAIN_CONFIGS)
CHAIN_ID=11155111

# Optional performance tuning
#POLLING_INTERVAL=60000
#DISABLE_LISTENER=true
#REQUEST_DELAY=500 # How many ms to wait before making a request to RPC (useful for free plans)
#BATCH_SIZE=2000 # How many blocks to fetch at once (some providers have limits)

Important: Set CHAIN_ID to the chain you want to index. Ensure the chain has a corresponding configuration in EAS_CHAIN_CONFIGS within utils.ts.

3. Set up database:

With Docker (recommended):

docker-compose up -d eas-postgres

Or set up PostgreSQL manually and ensure your DATABASE_URL points to it.

4. Generate Prisma client and push schema:

yarn prisma:generate
yarn prisma:push

5. Start the service:

# Development mode (with auto-restart)
yarn dev

# Production mode
yarn start

Docker Deployment

To deploy the full stack with Docker:

docker-compose up -d

If you make changes to the code, rebuild the containers:

docker-compose build
docker-compose up -d

Migration from Previous Versions

If you're updating from an older version of this service, please see MIGRATION_GUIDE.md for detailed migration instructions and breaking changes.

Available Endpoints

Once running, the service provides several endpoints:

• Root: http://localhost:4000/ - Service information
• GraphQL: http://localhost:4000/graphql - GraphQL playground and API
• Health Check: http://localhost:4000/health - Service health status

Available Scripts

• yarn dev - Start in development mode with auto-restart
• yarn start - Start in production mode
• yarn build - Build TypeScript to dist/
• yarn prisma:generate - Generate Prisma client
• yarn prisma:push - Push schema changes to database
• yarn prisma:migrate - Create and run database migrations

Adding Custom Chain Configs

To add support for a new chain:

1. Add a new configuration object to EAS_CHAIN_CONFIGS in utils.ts
2. Include all required fields: chainId, contractAddress, schemaRegistryAddress, rpcProvider, etc.
3. Set your CHAIN_ID environment variable to match
4. Rebuild if using Docker: docker-compose build && docker-compose up -d

Example configuration:

{
  chainId: 31337,
  chainName: "localhost",
  subdomain: "local.",
  version: "1.0.0",
  contractAddress: "0x...",
  schemaRegistryAddress: "0x...",
  etherscanURL: "http://localhost:8545",
  contractStartBlock: 0,
  rpcProvider: "http://host.docker.internal:8545", // For Docker
}

Localhost/Hardhat Testing

When running against a local blockchain (e.g., Hardhat):

• Use host.docker.internal:8545 instead of localhost:8545 in Docker
• Set contractStartBlock to 0 or the appropriate starting block
• Ensure your local node is accessible from the container

Performance Tuning

Adjust these environment variables for optimal performance:

# Polling interval in milliseconds
POLLING_INTERVAL=60000

# Disable real-time event listener (polling only)
DISABLE_LISTENER=true

# Delay between RPC requests (for rate limiting)
REQUEST_DELAY=500

# Blocks to fetch per batch
BATCH_SIZE=2000

# Node.js memory limit (for large datasets)
NODE_OPTIONS="--max-old-space-size=4096"

Troubleshooting

Common Issues

Prisma version conflicts:

SKIP_PRISMA_VERSION_CHECK=true npx prisma generate

TypeScript compilation errors:

yarn build

Database connection issues:

# Check if PostgreSQL is running
docker-compose ps eas-postgres

# Reset database
yarn prisma:push --force-reset

GraphQL schema generation errors:

rm -rf node_modules/@generated
yarn prisma:generate

Package Manager Issues

If using Yarn and encountering module resolution issues, create .yarnrc.yml:

nodeLinker: node-modules