113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# 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:
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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
|