solpay/VALIDATION_SERVICE.md

Transaction Validation Service

The Transaction Validation Service automatically validates unvalidated transactions against blockchain data every 5 seconds.

Overview

The service runs as a background process that:

1. Fetches all transactions with validated_at = NULL from the database
2. Retrieves transaction data from the Solana blockchain using the explorer utility
3. Compares database transaction data with blockchain data
4. Updates validated transactions with validated_at = NOW()

Features

• Automatic Validation: Runs every 5 seconds without manual intervention
• Blockchain Verification: Compares transaction details with actual blockchain data
• Data Integrity: Ensures sender, receiver, amount, and token mint addresses match
• Rate Limiting: Includes delays between API calls to respect blockchain API limits
• Graceful Shutdown: Properly stops validation when the server shuts down
• Monitoring: Provides status endpoints to monitor validation progress

API Endpoints

Get Validation Status

GET /validation/status

Returns:

{
  "success": true,
  "validationService": {
    "isRunning": true,
    "hasInterval": true
  },
  "statistics": {
    "unvalidated": 5,
    "validated": 25,
    "total": 30
  }
}

Start Validation Service

POST /validation/start

Stop Validation Service

POST /validation/stop

Validation Logic

A transaction is considered valid if:

1. Sender Address: Database sender_address matches blockchain sender
2. Receiver Address: Database target_address matches blockchain receiver
3. Amount: Database amount matches blockchain amount
4. Token Mint: Database token_mint matches blockchain mint

Database Schema

The transactions table must include:

• validated_at field (TIMESTAMP, can be NULL)
• created_at field (TIMESTAMP)
• updated_at field (TIMESTAMP)

Configuration

The service automatically starts when the server starts and stops when the server shuts down. It can also be manually controlled via the API endpoints.

Error Handling

• Failed validations are logged but don't stop the service
• Blockchain API errors are handled gracefully
• Database connection issues are logged
• The service continues running even if individual validations fail

Performance Considerations

• Processes transactions sequentially to avoid overwhelming the blockchain API
• Includes 100ms delays between individual transaction validations
• Runs every 5 seconds to balance responsiveness with API usage
• Logs validation progress for monitoring and debugging

Testing

Run the test script to verify the service works correctly:

npx ts-node src/test-validation.ts

Monitoring

Monitor the service through:

• Application logs (look for validation-related log entries)
• /validation/status endpoint for real-time status
• Database queries on the validated_at field
• Transaction counts (validated vs unvalidated)

Troubleshooting

Common issues and solutions:

1. Service not starting: Check database connection and permissions
2. No validations occurring: Verify transactions exist with validated_at = NULL
3. Validation failures: Check blockchain API connectivity and transaction data integrity
4. High API usage: Consider increasing the validation interval or reducing batch sizes