IFIF Indexer

Comprehensive real-time indexing for IFIF project contracts, providing complete project lifecycle tracking, investment analytics, NFT management, and asset distribution monitoring.

Overview

The IFIF indexer processes all project-related events from IFIF contracts, transforming raw blockchain events into structured, queryable data. It provides real-time tracking of project stages, user investments, NFT operations, token claims, and comprehensive analytics for project performance and user engagement.

Features

🔍 Event Processing

StageUpdated: Project lifecycle stage transitions
ConfigUpdated: Configuration changes tracking
NonceConsumed: Signature nonce consumption for replay attack prevention
Upgraded: Contract implementation upgrades
Purchased: Investment tracking with bonus calculations
Refunded: Refund processing and state reversals
NFTClaimed: NFT claiming operations
NFTSplitted: NFT splitting into multiple tokens
NFTMerged: NFT merging operations
NFTConverted: NFT conversion to tokens
Transfer: NFT ownership changes and transfers
Deposited: Asset distribution and earnings calculations
Claimed: Token claim tracking
DexPairCreated: DEX integration and liquidity tracking
DexLiquidityAdded: DEX liquidity event tracking and analytics

📊 Data Analytics

Project performance metrics
User investment summaries
NFT allocation and operations
Daily platform analytics
Cross-project user profiles

🛡️ Data Integrity

Duplicate event prevention
Transaction-level consistency
Type-safe data validation
Comprehensive error handling
Framework compliance (no return statements)

Database Schema

project Table

Core project state and configuration tracking.

{
  id: Address,              // Project contract address (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectId: number,        // Unique project ID from factory
  version: number,          // Project version (1 for v1, 2 for v2)
  stage: number,            // Current project stage (ProjectStage enum as integer)
  owner: Address,           // Project owner address
  distributor: Address,     // Asset distributor address
  fundToken: Address,       // Funding token contract
  fundingTarget: bigint,    // Target funding amount
  privateSaleTime: bigint,  // Private sale duration
  publicSaleTime: bigint,   // Public sale duration
  privateBonusPercent: number, // Private sale bonus percentage
  desiredEndEpoch: bigint,  // Target end timestamp
  distributorFeePercent: number,   // Distributor fee percentage
  projectOwnerFeePercent: number,  // Project owner fee percentage
  platformFeePercent: number,      // Platform fee percentage
  pairPrice: bigint,        // DEX pair pricing
  totalPurchase: bigint,    // Total investment amount
  totalWeight: bigint,      // Total weighted investment
  activeSaleEndTime: bigint | null, // Active sale end time
  token: Address | null,    // Deployed token address
  dexPair: Address | null,  // DEX pair address
  earningsMultiplier: bigint | null, // Earnings calculation multiplier
  createdAt: bigint,        // Project creation timestamp
  lastUpdated: bigint       // Last update timestamp
}

Use Cases:

Project dashboard data
Investment opportunity analysis
Stage transition tracking
Configuration audit trails

projectStageHistory Table

Complete audit trail for project stage transitions.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  previousStage: number,    // Previous stage (ProjectStage enum as integer)
  newStage: number,         // New stage (ProjectStage enum as integer)
  triggeredBy: Address,     // Transaction initiator
  saleEndTime: bigint | null, // Sale end timestamp if applicable
  triggeredByFunction: string, // Function that triggered change
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

Project lifecycle analysis
Stage duration tracking
Governance transparency
Performance optimization

projectConfigUpdate Table

Track configuration changes with old/new value comparisons.

{
  id: Hash,                    // Event ID (composite primary key with chainId)
  chainId: number,             // Chain ID for multi-chain support
  projectAddress: Address,     // Project contract address
  oldProjectOwner: Address,    // Previous owner
  newProjectOwner: Address,    // New owner
  oldDistributor: Address,     // Previous distributor
  newDistributor: Address,     // New distributor
  oldDistributorFeePercent: number,    // Previous distributor fee
  newDistributorFeePercent: number,    // New distributor fee
  oldProjectOwnerFeePercent: number,   // Previous owner fee
  newProjectOwnerFeePercent: number,   // New owner fee
  oldPlatformFeePercent: number,       // Previous platform fee
  newPlatformFeePercent: number,       // New platform fee
  oldPairPrice: bigint,        // Previous pair price
  newPairPrice: bigint,        // New pair price
  updatedBy: Address,          // Update initiator
  signatureCount: number,      // Multi-sig signature count
  timestamp: bigint,           // Block timestamp
  blockNumber: bigint,         // Block number
  transactionHash: Hash        // Transaction hash
}

Use Cases:

Configuration audit trails
Multi-signature governance tracking
Fee structure analysis
Governance transparency

contractUpgrade Table

Track contract implementation upgrades.

{
  id: Hash,                     // Event ID (composite primary key with chainId)
  chainId: number,              // Chain ID for multi-chain support
  projectAddress: Address,      // Project contract address
  oldImplementation: Address | null, // Previous implementation address
  newImplementation: Address,   // New implementation address
  version: number,              // Project version (1 for v1, 2 for v2)
  upgrader: Address,            // Upgrade initiator
  timestamp: bigint,            // Block timestamp
  blockNumber: bigint,          // Block number
  transactionHash: Hash         // Transaction hash
}

Use Cases:

Security monitoring
Upgrade history tracking
Implementation analysis
Governance oversight

userPurchase Table

Individual investment transaction tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  user: Address,            // Investor address
  amount: bigint,           // Investment amount
  weight: bigint,           // Weighted amount (with bonus)
  stage: SaleStage,         // Purchase stage (private/public)
  bonusAmount: bigint,      // Bonus amount earned
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

Investment transaction history
Bonus calculation verification
Stage-specific analytics
User investment patterns

userRefund Table

Refund transaction tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  user: Address,            // User address
  amount: bigint,           // Refund amount
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

Refund history tracking
Financial reconciliation
User protection monitoring
Project performance analysis

userInvestmentSummary Table

Aggregated user investment data per project.

{
  id: string,               // "{user}-{projectAddress}" (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  user: Address,            // User address
  projectAddress: Address,  // Project contract address
  totalPurchased: bigint,   // Total investment amount
  totalWeight: bigint,      // Total weighted investment
  purchaseCount: number,    // Number of purchases
  bonusEarned: bigint,      // Total bonus earned
  isRefunded: boolean,      // Refund status
  refundAmount: bigint,     // Refund amount if applicable
  firstPurchaseAt: bigint,  // First investment timestamp
  lastPurchaseAt: bigint,   // Last investment timestamp
  updatedAt: bigint         // Last update timestamp
}

Use Cases:

User investment dashboards
Portfolio analytics
Investment summary reports
Performance tracking

userProfile Table

Cross-project user analytics.

{
  id: Address,              // User address (primary key)
  totalProjectsInvested: number,   // Number of projects invested in
  totalAmountInvested: bigint,     // Total investment across projects
  totalAmountRefunded: bigint,     // Total refunds received
  totalTokensClaimed: bigint,      // Total tokens claimed
  totalNftsClaimed: number,        // Total NFTs claimed
  firstInvestment: bigint,         // First investment timestamp
  lastActivity: bigint,            // Last activity timestamp
  updatedAt: bigint                // Profile update timestamp
}

Use Cases:

User engagement analytics
Platform metrics
Investment behavior analysis
User journey tracking

nftAllocation Table

NFT ownership and weight tracking.

{
  id: string,               // "{projectAddress}-{tokenId}" (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  tokenId: number,          // NFT token ID
  owner: Address,           // Current owner
  weight: bigint,           // Current NFT weight
  originalWeight: bigint,   // Original minted weight
  isActive: boolean,        // Active status (not burned/converted)
  mintedAt: bigint,         // Mint timestamp
  lastTransferAt: bigint | null,   // Last transfer timestamp
  convertedAt: bigint | null       // Conversion timestamp
}

Use Cases:

NFT portfolio tracking
Weight distribution analysis
Transfer history
Conversion monitoring

nftOperation Table

Complete NFT operation history.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  user: Address,            // Operation initiator
  operationType: NFTOperationType, // Operation type (enum)
  tokenId: number | null,   // Primary token ID
  tokenIds: number[] | null, // Multiple token IDs (for merge)
  newTokenId: number | null, // New token ID (for split/merge)
  newTokenIds: number[] | null, // New token IDs (for split)
  tokenAmount: bigint | null, // Token amount (for conversion)
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Operation Types:

CLAIM - NFT claiming
SPLIT - NFT splitting
MERGE - NFT merging
CONVERT - NFT to token conversion

Use Cases:

NFT operation audit trails
User behavior analytics
Operation frequency analysis
Platform feature usage

nftTransfer Table

NFT transfer event tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  tokenId: number,          // NFT token ID
  from: Address,            // Sender address
  to: Address,              // Recipient address
  transferType: NFTTransferType, // Transfer type (enum)
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Transfer Types:

MINT - NFT minting
TRANSFER - Regular transfer
BURN - NFT burning

Use Cases:

Transfer history tracking
NFT circulation analysis
Ownership verification
Market activity monitoring

assetDeposit Table

Asset distribution and earnings tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  totalAmount: bigint,      // Total deposited amount
  earningsMultiplier: bigint, // Earnings calculation multiplier
  tokenMintAmount: bigint,  // Token mint amount
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

Asset distribution tracking
Earnings calculation
Token mint monitoring
Financial analytics

tokenClaim Table

Token claim event tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  user: Address,            // Claiming user
  amount: bigint,           // Claimed amount
  originalWeight: bigint,   // User's original investment weight
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

Token claim tracking
Distribution verification
User reward calculation
Platform analytics

dexPair Table

DEX integration and liquidity tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  pairAddress: Address,     // DEX pair contract address
  projectToken: Address,    // Project token address
  fundToken: Address,       // Funding token address
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

DEX integration monitoring
Liquidity tracking
Market integration analysis
Trading pair verification

dexLiquidity Table

DEX liquidity addition event tracking.

{
  id: Hash,                 // Event ID (composite primary key with chainId)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  pairAddress: Address,     // DEX pair contract address
  tokenAmount: bigint,      // Amount of project tokens added
  liquidityAmount: bigint,  // Amount of liquidity tokens received
  chainId: number,          // Chain ID for multi-chain support
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Use Cases:

DEX liquidity event analytics
Liquidity addition auditing
Project liquidity monitoring
Cross-chain liquidity tracking

dailyMetric Table

Daily platform analytics aggregation.

{
  id: string,               // Date string "YYYY-MM-DD" (primary key)
  chainId: number,          // Chain ID for multi-chain support
  newProjects: number,      // New projects created
  totalVolume: bigint,      // Total investment volume
  newInvestors: number,     // New unique investors
  nftOperations: number,    // Total NFT operations
  tokensClaimed: bigint     // Total tokens claimed
}

Use Cases:

Daily analytics dashboards
Platform growth tracking
Performance metrics
Business intelligence

nonceConsumption Table

Signature nonce consumption audit trail for replay attack prevention.

{
  id: Hash,                 // Event ID (primary key)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  signatureType: number,    // Signature type (SignatureType enum)
  signer: Address,          // Address whose nonce was consumed
  nonce: bigint,            // Nonce value that was consumed
  timestamp: bigint,        // Block timestamp
  blockNumber: bigint,      // Block number
  transactionHash: Hash     // Transaction hash
}

Signature Types:

0 (NONCE_NEXT_CONFIG) - NextConfig updates (v1 and v2)
1 (NONCE_FUND_CLAIM_CONFIG) - FundClaimConfig updates (v2 only)
2 (NONCE_DISTRIBUTOR_CONFIG) - DistributorConfig updates (v2 only, per-distributor)

Use Cases:

Replay attack prevention audit trail
Signature usage tracking
Security monitoring and analytics
Configuration update verification
Multi-signature governance transparency

nonceState Table

Current nonce state per signature type and signer.

{
  id: string,               // "{projectAddress}-{signatureType}-{signer}" (primary key)
  chainId: number,          // Chain ID for multi-chain support
  projectAddress: Address,  // Project contract address
  signatureType: number,    // Signature type (SignatureType enum)
  signer: Address,          // Address whose nonce is tracked
  currentNonce: bigint,     // Current nonce value (next expected)
  totalConsumptions: number, // Total number of nonce consumptions
  lastConsumedAt: bigint | null,   // Timestamp of last consumption
  firstConsumedAt: bigint | null   // Timestamp of first consumption
}

Key Features:

Independent nonce tracking per signature type
Per-distributor nonce sequences for type 2
Real-time current nonce state
Historical consumption statistics

Use Cases:

Current nonce value queries for signature creation
Nonce consumption pattern analysis
Security audit and monitoring
Configuration update workflow support
Per-distributor nonce tracking (v2)

GraphQL API

Core Queries

Get Project Details

query ProjectDetails($address: String!) {
  project(id: $address) {
    id
    projectId
    stage
    owner
    fundingTarget
    totalPurchase
    totalWeight
    token
    dexPair
    createdAt
    lastUpdated
  }
}

Get User Investment Summary

query UserInvestments($user: String!) {
  userInvestmentSummaries(where: { user: $user }) {
    items {
      id
      projectAddress
      totalPurchased
      totalWeight
      bonusEarned
      isRefunded
      purchaseCount
    }
  }
}

Get Project Stage History

query ProjectStageHistory($projectAddress: String!) {
  projectStageHistories(
    where: { projectAddress: $projectAddress }
    orderBy: "timestamp"
    orderDirection: "desc"
  ) {
    items {
      id
      previousStage
      newStage
      triggeredBy
      timestamp
      blockNumber
    }
  }
}

Get NFT Operations

query NFTOperations($user: String!) {
  nftOperations(
    where: { user: $user }
    orderBy: "timestamp"
    orderDirection: "desc"
  ) {
    items {
      id
      operationType
      tokenId
      tokenIds
      newTokenId
      newTokenIds
      tokenAmount
      timestamp
    }
  }
}

Get Daily Metrics

query DailyMetrics($limit: Int = 30) {
  dailyMetrics(
    limit: $limit
    orderBy: "id"
    orderDirection: "desc"
  ) {
    items {
      id
      newProjects
      totalVolume
      newInvestors
      nftOperations
      tokensClaimed
    }
  }
}

Get Current Nonce State

query CurrentNonceState($projectAddress: String!, $signatureType: Int!, $signer: String!) {
  nonceState(id: "{projectAddress}-{signatureType}-{signer}") {
    id
    projectAddress
    signatureType
    signer
    currentNonce
    totalConsumptions
    lastConsumedAt
    firstConsumedAt
  }
}

Get Nonce Consumption History

query NonceConsumptionHistory($projectAddress: String!, $signer: String!) {
  nonceConsumptions(
    where: { 
      projectAddress: $projectAddress, 
      signer: $signer 
    }
    orderBy: "timestamp"
    orderDirection: "desc"
  ) {
    items {
      id
      signatureType
      nonce
      timestamp
      blockNumber
      transactionHash
    }
  }
}

Get All Nonce States for Project

query ProjectNonceStates($projectAddress: String!) {
  nonceStates(
    where: { projectAddress: $projectAddress }
  ) {
    items {
      id
      signatureType
      signer
      currentNonce
      totalConsumptions
      lastConsumedAt
    }
  }
}

Advanced Queries

Get Active Projects

query ActiveProjects {
  projects(where: { stage: { not: 0 } }) {
    items {
      id
      projectId
      stage
      totalPurchase
      fundingTarget
      owner
      createdAt
    }
  }
}

Get User NFT Portfolio

query UserNFTPortfolio($user: String!) {
  nftAllocations(
    where: { owner: $user, isActive: true }
  ) {
    items {
      id
      projectAddress
      tokenId
      weight
      originalWeight
      mintedAt
    }
  }
}

Get Token Claims by Project

query ProjectTokenClaims($projectAddress: String!) {
  tokenClaims(
    where: { projectAddress: $projectAddress }
    orderBy: "timestamp"
    orderDirection: "desc"
  ) {
    items {
      id
      user
      amount
      originalWeight
      timestamp
    }
  }
}

Performance Optimizations

Framework Compliance

No Return Statements: All event handlers use conditional logic for Ponder framework compliance
Efficient Queries: Optimized database queries with proper indexing
Error Handling: Comprehensive try-catch blocks with graceful fallbacks

Data Integrity

Duplicate Prevention: Event ID-based deduplication
Conditional Processing: Only process events when required data exists
Type Safety: Full TypeScript integration with contract ABI validation

Analytics Performance

Aggregated Summaries: Pre-calculated user and project summaries
Daily Metrics: Batch-processed daily analytics
Optimized Indexes: Strategic database indexing for common queries

Integration Examples

Project Dashboard Integration

// Get complete project overview
const projectData = await ponder.query(`
  query ProjectOverview($address: String!) {
    project(id: $address) {
      ...projectFields
    }
    userInvestmentSummaries(where: { projectAddress: $address }) {
      items { ...investmentFields }
    }
    projectStageHistories(where: { projectAddress: $address }) {
      items { ...stageFields }
    }
  }
`);

User Portfolio Integration

// Get user's complete portfolio
const userPortfolio = await ponder.query(`
  query UserPortfolio($user: String!) {
    userProfile(id: $user) {
      ...profileFields
    }
    userInvestmentSummaries(where: { user: $user }) {
      items { ...investmentFields }
    }
    nftAllocations(where: { owner: $user, isActive: true }) {
      items { ...nftFields }
    }
  }
`);

Analytics Dashboard Integration

// Get platform analytics
const platformAnalytics = await ponder.query(`
  query PlatformAnalytics {
    dailyMetrics(limit: 30, orderBy: "id", orderDirection: "desc") {
      items { ...metricFields }
    }
    projects { items { ...projectSummaryFields } }
  }
`);