complete task

[soring323]

Blockchain Indexer Implementation - EMURGO Backend Engineer Challenge

Summary

Complete implementation of a blockchain indexer API that tracks address balances using the UTXO (Unspent Transaction Output) model. All required endpoints, validations, and comprehensive test coverage included.

What's Implemented

API Endpoints

1. POST /blocks

• Accepts and validates blockchain blocks
• ✅ Height validation (must be current_height + 1)
• ✅ Block ID validation (SHA256 hash verification)
• ✅ Input/output sum validation
• ✅ Double-spend prevention
• ✅ UTXO validation (inputs must reference existing unspent outputs)

2. GET /balance/:address

• Returns current balance for any address
• Calculates balance from unspent outputs

3. POST /rollback?height=number

• Rolls back blockchain state to specified height
• Properly restores spent status of outputs
• Allows re-building chain after rollback

Technical Architecture

Database Schema (PostgreSQL)

• blocks - Stores block metadata (id, height, timestamp)
• transactions - Links transactions to blocks
• outputs - Implements UTXO model with spent tracking
• inputs - Tracks which outputs each transaction spends (enables proper rollback)

Key Design Decisions

1. UTXO Tracking: Used spent boolean flag on outputs instead of deletion
2. Inputs Table: Added to track spending relationships, enabling proper rollback functionality
3. Database Transactions: All state changes wrapped in PostgreSQL transactions for atomicity
4. Cascade Deletes: Configured foreign keys to simplify rollback operations
5. Indexes: Added on frequently queried fields (address, spent status)

Test Coverage

18/18 tests passing - 100% success rate

Test Categories:

• Block Validation (7 tests)

  • Valid block acceptance
  • Height validation
  • Hash validation
  • Input/output sum validation
  • Non-existent output rejection
  • Double-spend prevention
  • Sequential block processing

• Balance Queries (4 tests)

  • Unknown addresses
  • Receiving funds
  • Spending funds
  • Complex multi-block scenarios (README example)

• Rollback Functionality (4 tests)

  • Rollback to specified height
  • Re-adding blocks after rollback
  • Invalid parameter handling
  • Genesis rollback (height 0)

• Edge Cases (3 tests)

  • Multiple outputs to same address
  • Multiple inputs in transactions
  • Multiple transactions per block

Technologies Used

• Runtime: Bun v1.3.2
• Framework: Fastify v4.28.1
• Database: PostgreSQL 15
• Language: TypeScript 5.5
• Testing: Bun's built-in test runner
• Deployment: Docker Compose

Files Changed

• src/index.ts - Main API implementation (309 lines)
• src/types.ts - TypeScript type definitions (new)
• spec/index.spec.ts - Comprehensive test suite (610 lines)
• package.json - Added @types/node dependency
• docker-compose.yaml - Fixed version warning

How to Run

# Start the application and database
docker-compose up -d --build

# Run tests
docker-compose exec api bun test

# API available at http://localhost:3000