Skip to content

Indexer Overview

The Iyup Protocol Indexer is a TypeScript-based blockchain event indexer that monitors and indexes marketplace listings, document vault events, and zero-knowledge proof commitments into a PostgreSQL database, and exposes them via a REST API.

Overview

The indexer continuously polls the Sui blockchain for events from the Iyup smart contracts and stores them in a structured database. It provides:

  • Marketplace Indexing: Tracks RWA token listings, updates, cancellations, and purchases
  • Document Vault: Indexes document registrations, version updates, and endorsements
  • ZK Vault: Records zero-knowledge commitments and proof verifications
  • REST API: Query indexed data via Express endpoints

Architecture

The project consists of two main processes:

  1. Indexer (indexer.ts): Background service that listens to blockchain events
  2. API Server (server.ts): Express REST API for querying indexed data

Technology Stack

  • Language: TypeScript
  • Database: PostgreSQL (Prisma ORM)
  • Server: Express.js
  • Client: Sui TypeScript SDK
  • Runtime: Node.js 20+

Project Structure

indexer/
├── server.ts                 # Express API server
├── indexer.ts               # Event indexer entry point
├── config.ts                # Configuration loader
├── db.ts                    # Prisma client setup
├── sui-utils.ts             # Sui client utilities
├── helpers/
│   ├── event-filter-iyup.ts    # Event subscriptions
│   ├── iyup-indexer.ts         # Marketplace event handlers
│   ├── vault-indexer.ts        # Document vault handlers
│   └── zk-vault-indexer.ts     # ZK vault handlers
├── routes/
│   ├── listings.ts             # Listings API
│   ├── documents.ts            # Documents API
│   └── zk-commitments.ts       # ZK commitments API
├── prisma/
│   └── schema.prisma           # Database schema
└── data/
    └── rwa.data.ts              # Mock RWA metadata

Setup

Prerequisites

  • Node.js 20+
  • pnpm 10.20.0+
  • PostgreSQL database
  • Access to Sui RPC endpoint

Installation

cd indexer
pnpm install

Configuration

Create .env file:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/iyup"
 
# Network
NETWORK="testnet"  # or "mainnet"
SUI_NETWORK=testnet
SUI_RPC_URL=https://fullnode.testnet.sui.io:443
 
# Iyup Contract Addresses
IYUP_PACKAGE_ID="0x..."
IYUP_MARKETPLACE_ID="0x..."
IYUP_REGISTRY_ID="0x..."
ZK_REGISTRY_ID="0x..."
IYUP_DEPLOYER="0x..."
 
# API Server
NODE_ENV="development"
PORT=8000
LOG_LEVEL=debug
 
# Indexer Performance
POLLING_INTERVAL_MS=2000      # Poll interval in milliseconds
CONCURRENCY_LIMIT=5           # Concurrent event trackers

Initialize Database

# Generate Prisma client
pnpm db:generate
 
# Run migrations
pnpm db:setup:dev

Usage

Development

Run API server with hot reload: 
pnpm dev
Run indexer with hot reload: 
pnpm dev:indexer

Run both concurrently (recommended):

pnpm dev & pnpm dev:indexer

Production

Build TypeScript: 
pnpm build
Run indexer: 
pnpm indexer
Run API server: 
node dist/server.js

Indexed Events

The indexer monitors these Sui events:

Marketplace Events

  • ListingCreated - New RWA token listing
  • ListingUpdated - Price or status change
  • ListingCancelled - Seller cancellation
  • ListingPurchased - Successful purchase

Document Vault Events

  • DocumentRegistered - New document registration
  • VersionUpdated - Document version added
  • DocumentEndorsed - Auditor endorsement

ZK Vault Events

  • ZKCommitmentRegistered - New ZK commitment
  • ZKProofVerified - Proof verification
  • VerifyingKeyRegistered - Verifying key setup (logged but not indexed)

Data Models

Key database tables:

  • Listing - RWA token marketplace listings with metadata
  • Tag - Categorical tags for listings
  • PrimaryMarket - Primary market data (price, holders, etc.)
  • UnderlyingMarket - Traditional market data (52w high/low, volume)
  • Document - Registered documents with versions
  • DocumentVersion - Document version history
  • DocumentAuditor - Auditor endorsements
  • ZKCommitment - Zero-knowledge commitments
  • ZKProofVerification - Proof verification records
  • Cursor - Event polling state (for resuming indexing)

Cursor-Based Indexing

The indexer uses cursors to track progress:

  • Stored in database for persistence
  • Resumable after failures
  • Supports multiple concurrent indexers
  • Checkpoint-based for reliability

API Endpoints

See Indexer API Reference for detailed API documentation.

Event Indexing

See Event Indexing for detailed indexing documentation.

Troubleshooting

Indexer not processing events

  1. Check IYUP_PACKAGE_ID is correct
  2. Verify SUI_RPC_URL is accessible
  3. Check database connection (DATABASE_URL)
  4. Review logs for cursor errors (may need to reset cursors in DB)

Database connection errors

  • Ensure PostgreSQL is running
  • Verify DATABASE_URL credentials
  • Run pnpm db:generate after schema changes

API returns empty results

  • Ensure indexer is running (pnpm dev:indexer)
  • Check if events exist on-chain
  • Verify contract addresses in .env

Reset indexer state

If indexer gets stuck:

-- Connect to PostgreSQL and run:
DELETE FROM "Cursor";

Restart the indexer to begin from genesis.

Next Steps