Asset Verification System Implementation

Overview

This PR implements a comprehensive asset issuer verification system for SwiftRemit that verifies asset code and issuer pairs against multiple trusted sources.

Changes

Smart Contract (Soroban/Rust)

✅ Added asset_verification.rs module for on-chain storage
✅ Implemented AssetVerification struct and VerificationStatus enum
✅ Added 4 new contract functions:
- set_asset_verification() - Store verification results (admin only)
- get_asset_verification() - Query verification data
- has_asset_verification() - Check if asset exists
- validate_asset_safety() - Validate asset is not suspicious
✅ Added 3 new error codes (AssetNotFound, InvalidReputationScore, SuspiciousAsset)

Backend Service (Node.js/TypeScript)

✅ AssetVerifier Service: Multi-source verification checking:
- Stellar Expert API integration
- Stellar TOML validation and parsing
- Trustline count analysis
- Transaction history verification
✅ PostgreSQL Database:
- verified_assets table with unique constraint on (asset_code, issuer)
- Indexes for performance optimization
- CRUD operations with proper error handling
✅ RESTful API with 5 endpoints:
- GET /api/verification/:assetCode/:issuer - Lookup verification
- POST /api/verification/verify - Trigger new verification
- POST /api/verification/report - Report suspicious asset
- GET /api/verification/verified - List verified assets
- POST /api/verification/batch - Batch lookup (max 50)
✅ Background Jobs: Periodic revalidation every 6 hours
✅ Stellar Integration: Stores results on-chain via Soroban contract

Frontend (React/TypeScript)

✅ VerificationBadge Component:
- Status-specific indicators (✓ Verified, ? Unverified, ⚠ Suspicious)
- Reputation score display (0-100)
- Detailed information modal
- Automatic warning modal for suspicious assets
- Community reporting functionality
✅ Fully responsive and accessible design

Security Features

✅ Input validation and sanitization
✅ Rate limiting (100 requests per 15 minutes)
✅ Safe HTTP clients with 5-second timeouts
✅ Retry logic with exponential backoff (3 attempts)
✅ SQL injection prevention via parameterized queries
✅ Admin-only on-chain updates
✅ Protection against abuse

Testing

✅ Smart contract tests (8 new test cases)
✅ Backend API tests
✅ Frontend component tests
✅ Integration test structure

Documentation

✅ ASSET_VERIFICATION.md: Complete system documentation
✅ IMPLEMENTATION_NOTES.md: Architecture decisions and notes
✅ SETUP_GUIDE.md: Deployment and configuration guide
✅ Inline code documentation

Verification Process

The system verifies assets against 4 sources:

Stellar Expert - Asset rating and community trust
Stellar TOML - Home domain and documentation validation
Trustline Analysis - Number of accounts holding the asset
Transaction History - Recent and historical activity

Reputation Score: Average of verified source scores (0-100)

Status Assignment:

Verified: Score ≥ 70 AND ≥ 3 sources verified
Suspicious: Score < 30 OR suspicious indicators detected
Unverified: All other cases

Database Schema

CREATE TABLE verified_assets (
  id SERIAL PRIMARY KEY,
  asset_code VARCHAR(12) NOT NULL,
  issuer VARCHAR(56) NOT NULL,
  status VARCHAR(20) NOT NULL,
  reputation_score INTEGER NOT NULL CHECK (reputation_score >= 0 AND reputation_score <= 100),
  last_verified TIMESTAMP NOT NULL DEFAULT NOW(),
  trustline_count BIGINT NOT NULL DEFAULT 0,
  has_toml BOOLEAN NOT NULL DEFAULT FALSE,
  stellar_expert_verified BOOLEAN DEFAULT FALSE,
  toml_data JSONB,
  community_reports INTEGER DEFAULT 0,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE(asset_code, issuer)
);

API Examples

Verify an Asset

curl -X POST http://localhost:3000/api/verification/verify \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "USDC",
    "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  }'

Get Verification Status

curl http://localhost:3000/api/verification/USDC/GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

Frontend Usage

import { VerificationBadge } from './components/VerificationBadge';

<VerificationBadge
  assetCode="USDC"
  issuer="GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  apiUrl="http://localhost:3000"
  onWarning={(verification) => console.warn(verification)}
/>

Performance Considerations

Database indexes on (asset_code, issuer), status, and last_verified
Verification results cached in database
On-chain storage for critical data only
Batch API for multiple asset lookups
Background jobs prevent blocking user requests
Rate limiting protects external APIs

Breaking Changes

None. This is a new feature that extends existing functionality without modifying current contract behavior.

Deployment Checklist

Set up PostgreSQL database
Configure environment variables (see backend/.env.example)
Deploy backend service
Build and deploy updated smart contract
Initialize contract with admin key
Start background job scheduler
Integrate frontend component
Test end-to-end flow

Testing Instructions

# Test smart contract
cargo test

# Test backend
cd backend && npm test

# Test frontend
cd frontend && npm test

# Manual API testing
curl http://localhost:3000/health

Files Changed

25 new files created
~3,000 lines of code added
3 files modified (src/lib.rs, src/errors.rs, README.md)

Related Issues

Closes #39

Additional Notes

All code follows secure coding practices
No regressions introduced
No security vulnerabilities detected
Comprehensive error handling implemented
Production-ready with proper logging and monitoring hooks

Review Focus Areas

Smart contract security (admin-only functions, input validation)
API rate limiting and abuse prevention
Database schema and indexing strategy
Frontend component accessibility
Error handling and edge cases

FilesExpand file tree

PR_DESCRIPTION.md

Latest commit

History