Core Concepts

Architecture Overview

FromChain is built on NestJS with a modular, production-ready architecture designed for reliability and scalability.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     FromChain API Gateway                       │
│                       (NestJS Monolith)                         │
├─────────────┬─────────────┬─────────────┬─────────────┬────────┤
│   Auth      │  Invoices   │ Blockchain  │  Webhooks   │ Jobs   │
│   Module    │   Module    │   Module    │   Module    │ Module │
│             │             │             │             │        │
│ • API Keys  │ • Create    │ • Monitor   │ • Endpoints │• Recon │
│ • Scopes    │ • List      │ • Confirm   │ • Delivery  │• Sweep │
│ • Rate      │ • Query     │ • Reorg     │ • Retry     │• Expire│
│   Limiting  │ • Lifecycle │   Detection │ • Signature │        │
├─────────────┴─────────────┴─────────────┴─────────────┴────────┤
│                    Prisma ORM Layer                             │
├─────────────────────────────────────────────────────────────────┤
│               PostgreSQL 15+ (Primary Database)                 │
│  • Tenants  • Invoices  • Transfers  • Webhooks  • Audit       │
└─────────────────────────────────────────────────────────────────┘
         │                                              │
         │                                              │
         ▼                                              ▼
┌──────────────────┐                          ┌──────────────────┐
│ Redis (ioredis)  │                          │   BSC Network    │
│                  │                          │  (via dRPC.org)  │
│ • BullMQ Queues  │                          │                  │
│ • Rate Limiting  │                          │ • WebSocket Sub  │
│ • Caching        │                          │ • USDT Contract  │
│ • Idempotency    │                          │ • Block Events   │
└──────────────────┘                          └──────────────────┘

Payment Processing Flow

1. Invoice Creation

Client calls POST /v1/invoices
System derives unique HD wallet address using BIP-44
Encrypts private key with AES-256-GCM
Stores invoice in PostgreSQL with status PENDING
Returns deposit address to client

2. Blockchain Monitoring

WebSocket subscription to BSC via eth_subscribe
Filters for USDT Transfer events to monitored addresses
Cost: $0 (no polling, only WebSocket push)
Detection latency: ~3 seconds per block

3. Payment Detection & Confirmation

Transfer event detected → Status: PAID_DETECTED
Creates TransferEvent record, links to invoice
Monitors block confirmations (default: 5 blocks)
Validates parentHash for reorg detection
After 5 confirmations → Status: CONFIRMED
Webhook: invoice.confirmed

4. Gas Funding (if needed)

Checks if deposit address has BNB for gas
If balance < 0.001 BNB, sends 0.002 BNB from hot wallet
Waits for gas funding tx to confirm (2 blocks)
Records GasFunding in database

5. Payout / Sweep

Status: PROCESSING_PAYOUT
Validates actual USDT balance matches expected
Calculates fee split: fee% → FEE_WALLET, rest → CUSTODY_WALLET
Creates multicall transaction to transfer both amounts
Waits for 2 confirmations
Updates tenant balance in database
Status: PAID_OUT
Webhook: invoice.paid_out

Core Modules

Auth Module

API key authentication, scopes, and rate limiting

• SHA-256 hashed API keys
• Scope-based permissions
• Redis-backed rate limiting
• Audit logging

Blockchain Module

BSC network interaction via ethers.js

• WebSocket event subscription
• Reorg detection
• Gas estimation
• Transaction signing

Invoices Module

Payment invoice lifecycle management

• HD wallet address derivation
• Status state machine
• Idempotency support
• Query & pagination

Webhooks Module

Reliable event delivery system

• HMAC-SHA256 signatures
• Exponential backoff retry
• Dead-letter queue
• Manual replay support

Jobs Module

Background processing with BullMQ

• Invoice expiration checks
• Confirmation tracking
• Blockchain reconciliation
• Webhook delivery queue

Payouts Module

Automated fund sweeping and splitting

• Fee calculation per tenant
• Balance validation
• Gas funding orchestration
• Tenant balance tracking

Security Architecture

🔐 Encryption at Rest

All private keys stored with AES-256-GCM encryption. Master encryption key stored separately in environment.

🔑 API Key Security

API keys hashed with SHA-256. Only prefixes stored in plaintext for identification.

🛡️ Reorg Protection

Validates parent hashes across blocks. Requires 5 confirmations before marking payments as confirmed.

📝 Audit Trail

Comprehensive audit logging for all sensitive operations with user context and timestamps.

Technology Stack

package.json (key dependencies)

{
  "dependencies": {
    "@nestjs/core": "^10.4.0",           // Web framework
    "@nestjs/bullmq": "^10.2.0",         // Job queues
    "@prisma/client": "^5.20.0",         // Database ORM
    "ethers": "^6.13.0",                 // Blockchain interaction
    "ioredis": "^5.4.1",                 // Redis client
    "bcrypt": "^6.0.0",                  // Password hashing
    "jsonwebtoken": "^9.0.3",            // JWT tokens
    "class-validator": "^0.14.1",        // DTO validation
    "zod": "^3.23.8"                     // Schema validation
  }
}