feat: register kyc data in soroban contract

[Bosun-Josh121]

feat: register kyc in soroban

Closes #154

🎯 Overview

Implements a POST /kyc/verify endpoint that registers KYC/KYB data in the Soroban smart contract for the Stellar wallet service. The endpoint generates a cryptographic hash of user KYC data, stores it in the contract with an approved status, and updates the SQLite database to reflect the registration.

✅ Changes Made

Core Implementation

• src/routes/kyc-verify.ts: New Express route handler for KYC verification
  • Validates input using existing validateKycData() function
  • Generates SHA-256 hash of KYC data for immutable storage
  • Calls Soroban contract's register_kyc function
  • Updates SQLite database with approved status
  • Returns structured JSON response with verification details

Environment Configuration

• config/envs.ts: Added required environment variables with Zod validation
  • STELLAR_SECRET_KEY: Deployer account secret key (required)
  • SOROBAN_CONTRACT_ID: Contract address from deployment (required)
• .env.example: Updated with new environment variable examples

Application Integration

• src/index.ts: Mounted KYC verify routes at /kyc path with rate limiting

Testing

• tests/routes/kyc-verify.test.ts: Comprehensive unit tests with mocked dependencies
  • Tests successful registration (201 response)
  • Tests input validation (400 responses)
  • Tests error scenarios (500 responses)
  • Uses in-memory SQLite database for reliable testing

🔧 Technical Details

API Specification

POST /kyc/verify
Content-Type: application/json

{
  "kyc_id": "123",
  "name": "John Doe",
  "document": "ABC12345"
}

Success Response (201):

{
  "kyc_id": "123",
  "data_hash": "a1b2c3d4e5f6...",
  "status": "approved"
}

Error Responses:

• 400: Invalid input or non-existent kyc_id
• 500: Contract call failure or internal error

Security Features

• Cryptographic Hashing: Uses SHA-256 for KYC data integrity
• Input Validation: Leverages existing Zod schema validation
• Rate Limiting: Inherits from existing KYC route protection
• Environment Validation: Ensures required credentials are present

Contract Interaction Flow

1. Validate request input and verify kyc_id exists in database
2. Generate SHA-256 hash of validated KYC data
3. Create Soroban contract transaction with register_kyc function
4. Submit transaction to Stellar testnet and await confirmation
5. Update SQLite database status to "approved"
6. Return success response with verification details

🧪 Testing Strategy

Unit Tests (Mocked)

• ✅ Database operations mocked with in-memory SQLite
• ✅ Soroban client mocked for predictable test execution
• ✅ Complete error path coverage
• ✅ TypeScript-safe mocking without type casting issues

🚀 Deployment Requirements

Environment Variables

STELLAR_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SOROBAN_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

Prerequisites

• Deployed KYC Soroban contract on Stellar testnet
• Funded deployer account with sufficient XLM
• SQLite database with existing KYC records

[salazarsebas]

hey @Bosun-Josh121 , please fix the workflow errors

[salazarsebas]

LGTM