Skip to main content

Start Indexing NFT Data on Supra

Crystara provides a powerful indexer tool that allows developers to efficiently index and process NFT data from the Supra blockchain. This guide will walk you through setting up and running the Crystara Indexer for your own applications.

Overview​

The Crystara Indexer is an open-source tool that:

  • Indexes NFT-related events from the Supra blockchain
  • Stores structured data in a PostgreSQL database
  • Provides a reliable way to track all Crystara platform activities
  • Can be customized for specific use cases

Prerequisites​

Before setting up the indexer, ensure you have:

  • Node.js (v16 or later)
  • PostgreSQL database
  • Git
  • Basic knowledge of JavaScript/TypeScript
  • Access to a Supra RPC endpoint

Getting Started​

1. Clone the Repository​

git clone https://github.com/tyhh00/Crystara_Indexer.git
cd Crystara_Indexer

2. Install Dependencies​

npm install

3. Configure Environment Variables​

Create a .env file in the root directory with the following variables:

DATABASE_URL="postgres://username:password@localhost:5432/"
DIRECT_URL="postgres://username:password@localhost:5432/"
NEXT_PUBLIC_SUPRA_RPC_URL="https://rpc-testnet.supra.com/rpc/v1"
START_BLOCK_HEIGHT=0
MAX_REQUESTS_PER_SECOND=100
NEXT_PUBLIC_DEBUG_MODE=true
NEXT_PUBLIC_CRYSTARA_ADR=0xfd566b048d7ea241ebd4d28a3d60a9eaaaa29a718dfff52f2ff4ca8581363b85
NEXT_PUBLIC_COLLECTIONS_MODULE_NAME=BlindBoxContract_Crystara_TestV17
NEXT_PUBLIC_MARKETPLACE0x3_MODULE_NAME=token0x3_marketplace_v3
NEXT_PUBLIC_TOKENS_MODULE_ADDRESS=0x3
NEXT_PUBLIC_TOKENS_MODULE_NAME=token
NEXT_PUBLIC_TOKENS_EVENT_STORE_MODULE_NAME=token_event_store

Environment Variables Explained​

VariableDescription
DATABASE_URLPostgreSQL connection string for Prisma ORM
DIRECT_URLDirect PostgreSQL connection string (same as above for most setups)
NEXT_PUBLIC_SUPRA_RPC_URLSupra blockchain RPC endpoint URL
START_BLOCK_HEIGHTThe block height to start indexing from (0 for genesis block)
MAX_REQUESTS_PER_SECONDRate limiting for RPC requests
NEXT_PUBLIC_DEBUG_MODEEnable verbose logging for debugging
NEXT_PUBLIC_CRYSTARA_ADRCrystara contract address
NEXT_PUBLIC_COLLECTIONS_MODULE_NAMEBlindBox module name (differs between Testnet/Mainnet)
NEXT_PUBLIC_MARKETPLACE0x3_MODULE_NAMEMarketplace module name (differs between Testnet/Mainnet)
NEXT_PUBLIC_TOKENS_MODULE_ADDRESSTokens module address (typically 0x3)
NEXT_PUBLIC_TOKENS_MODULE_NAMETokens module name
NEXT_PUBLIC_TOKENS_EVENT_STORE_MODULE_NAMEToken event store module name

4. Set Up the Database​

The indexer uses Prisma ORM to manage the database schema. Initialize your database with:

npx prisma migrate dev --name init

This will create all necessary tables in your PostgreSQL database.

5. Running the Indexer​

Development Mode​

For local development and testing:

npm run indexer

Production Deployment with PM2​

For production environments, we recommend using PM2 for process management:

  1. Install PM2 globally:
npm install -g pm2
  1. Create an ecosystem.config.js file:
module.exports = {
  apps: [
    {
      name: 'testnet-indexer',
      script: 'npm',
      args: 'run dev:indexer',
      watch: ['app', 'prisma', 'scripts', 'indexer'],
      env: {
        NODE_ENV: 'development',
        DEBUG: '*',
        NEXT_PUBLIC_DEBUG_MODE: 'true',  // Add this
        PM2_NO_AUTOMATION: 'true',
        PM2_SILENT: 'true',
        PM2_METRICS: 'false'

      },
      "pmx": false,
      max_memory_restart: '1G',
      instances: 1,
      autorestart: true,
      env_file: '.env',
    }
  ]
}
  1. Start the indexer with PM2:
pm2 start ecosystem.config.js
  1. Monitor the indexer:
pm2 logs testnet-indexer

How the Indexer Works​

The Crystara Indexer uses a poll-based approach to fetch and process blockchain data:

  1. Block Polling: The indexer periodically queries the Supra RPC for new blocks
  2. Event Filtering: It filters for relevant events from Crystara contracts
  3. Data Processing: Events are parsed and transformed into structured data
  4. Database Storage: Processed data is stored in PostgreSQL tables
  5. State Management: The indexer tracks its progress to ensure no data is lost

State Management and Reliability​

The indexer is designed with reliability in mind:

  • Transaction-Based Processing: Each block range is processed in a database transaction
  • Atomic Updates: Block ranges are only marked as processed when all events are successfully indexed
  • Crash Recovery: If the indexer crashes, it will resume from the last successfully processed block
  • Error Handling: Robust error handling prevents data corruption

Customizing the Indexer​

Adding Custom Event Handlers​

You can extend the indexer to handle additional events by modifying the event handlers in the src/handlers directory:

// Example of adding a custom event handler
import { prisma } from '../db';
import { MyCustomEvent } from '../types';
export async function handleMyCustomEvent(event: MyCustomEvent) {
await prisma.customEvents.create({
data: {
eventType: 'MyCustomEvent',
timestamp: event.timestamp,
// Add other relevant fields
},
});
}

Performance Considerations​

For optimal indexer performance:

  • Hardware Resources: Allocate sufficient CPU, memory, and disk space
  • Database Indexing: Create appropriate indexes for frequently queried fields
  • Rate Limiting: Adjust MAX_REQUESTS_PER_SECOND based on your RPC provider's limits
  • Block Range Size: Modify the block range size in the code for your specific needs
  • Database Maintenance: Regularly vacuum and analyze your PostgreSQL database

Troubleshooting​

Common Issues​

Indexer Falling Behind​

If the indexer can't keep up with new blocks:

  • Increase MAX_REQUESTS_PER_SECOND if your RPC provider allows it
  • Optimize database queries and indexes
  • Run the indexer on more powerful hardware

Database Connection Issues​

If you encounter database connection problems:

  • Verify your PostgreSQL credentials and connection string
  • Check that your database server is running and accessible
  • Ensure you have the correct permissions

RPC Errors​

If you see RPC-related errors:

  • Verify your RPC endpoint is correct and accessible
  • Check if you're hitting rate limits
  • Consider using a dedicated RPC provider for production

Support and Resources​

For additional help with the Crystara Indexer:

For enterprise support or custom indexing solutions, contact our developer team.