Skip to main content

How Cedra Indexing Works

Understand the complete journey from blockchain transactions to queryable data in your applications.

🔄 The Indexing Pipeline​

📦 What's in a Transaction?​

Every transaction your indexer receives contains:

Events - What happened during execution
// Example: Token Transfer Event
Event {
    account_address: "0x123...",
    type: "0x1::coin::TransferEvent",
    data: {
        from: "0xabc...",
        to: "0xdef...",
        amount: 1000000
    }
}

Events are perfect for:

  • ✅ Activity feeds
  • ✅ Transaction history
  • ✅ User analytics
State Changes - How storage was modified
// Example: Balance Update
WriteSet {
    resource: "0x1::coin::CoinStore",
    address: "0x456...",
    data: {
        coin: { value: 5000000 },
        frozen: false
    }
}

State changes are essential for:

  • ✅ Current balances
  • ✅ Ownership tracking
  • ✅ Protocol state
Metadata - Transaction details
// Transaction context
Transaction {
    version: 1234567,        // Unique sequence number
    hash: "0xabc123...",     // Transaction identifier
    timestamp: 1704067200,   // When it happened
    success: true,           // Execution status
    gas_used: 1500          // Computational cost
}

🎯 Processing Flow​

Step 1: Connect to Stream​

Your processor connects to Cedra's Transaction Stream Service:

# No authentication needed - it's public!
transaction_stream:
  endpoint: https://testnet.cedra.dev
  batch_size: 1000  # Process 1000 txns at once

Step 2: Extract Data​

Choose what to index based on your needs:

StrategyUse WhenExample
Events OnlyTracking actionsDEX swaps, transfers
State OnlyCurrent valuesToken balances, TVL
HybridComplete pictureFull protocol state

Step 3: Transform & Store​

Process data and save to PostgreSQL:

// Simplified processing logic
async fn process(transactions: Vec<Transaction>) {
    for txn in transactions {
        // Extract relevant events
        let events = txn.events
            .filter(|e| e.type.contains("YourContract"));
        
        // Transform to your schema
        let records = events.map(|e| transform(e));
        
        // Batch insert to database
        database.insert_batch(records).await;
    }
}

Step 4: Query via GraphQL​

Your data is instantly available:

query YourCustomData {
  your_table(
    where: {timestamp: {_gte: "2024-01-01"}}
    order_by: {value: desc}
  ) {
    id
    timestamp
    value
    metadata
  }
}

⚡ Key Features​

🔄 Real-time Processing​

  • Transactions indexed within seconds
  • Live data feeds for dashboards
  • WebSocket subscriptions available

🛡️ Reliability Built-in​

  • Version Tracking: Sequential processing guaranteed
  • Automatic Recovery: Resume from last checkpoint
  • No Data Loss: Every transaction processed exactly once

📈 Scalable Architecture​

  • Process millions of transactions
  • Parallel processing support
  • Optimized batch operations

🎬 See It In Action​

Example: Indexing Token Transfers
  1. Transaction occurs on Cedra blockchain
  2. Stream delivers to your processor (< 1 second)
  3. Processor extracts transfer events
  4. Data stored in PostgreSQL
  5. GraphQL serves to your application

Total time: ~2-3 seconds from transaction to queryable data!

📊 Version System​

Cedra uses a sequential version system that ensures data consistency:

Transaction Version Timeline:
[1] → [2] → [3] → [4] → [5] → ...
 ↑
Your indexer processes each version exactly once

Benefits:

  • ✅ No gaps: Every transaction captured
  • ✅ Ordered: Process in exact sequence
  • ✅ Resumable: Restart from any version
  • ✅ Verifiable: Check processing completeness

🚦 Processing Status​

Monitor your indexer's progress:

-- Check current processing status
SELECT * FROM processor_status;

┌─────────────┬────────────────────┬─────────────────┐
│ processor   │ last_success_version │ last_updated    │
├─────────────┼────────────────────┼─────────────────┤
│ my_indexer  │ 1234567           │ 2024-01-15 10:30 │
└─────────────┴────────────────────┴─────────────────┘

🔍 What Happens During a Restart?​

The indexer automatically handles failures:

No manual intervention needed - just restart and continue!

💡 Best Practices​

Performance Tips
  • Batch Operations: Process 1000-5000 transactions per batch
  • Index Strategy: Create database indexes on frequently queried fields
  • Monitor Lag: Keep processing within 100 versions of chain tip
Common Pitfalls
  • Don't process transactions one-by-one (too slow)
  • Don't skip version tracking (loses recovery ability)
  • Don't ignore failed transactions (may contain important reverts)

🎯 Next Steps​

Now that you understand how indexing works:

  1. SDK Guide - Get started with processors
  2. Processors - Available processor types
  3. Common Queries - GraphQL patterns
Ready to Build?

You now understand the complete indexing flow. Time to understand queries!

Continue to Common Queries →

Edit page