Trust-Link Backend is a NestJS application that manages escrow transactions on the Stellar blockchain. Vendors create escrow agreements, buyers fund them via Stellar payments, and the system automatically tracks shipments, releases funds, and handles disputes.
┌──────────────────────────────────────────────────────────────────────────┐
│ External Clients │
│ ┌──────────────┐ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ Web / Mobile │ │ Stellar Horizon │ │ Background Workers │ │
│ │ Clients │ │ (webhook retries) │ │ (in-process timers) │ │
│ └──────┬───────┘ └────────┬─────────┘ └──────────┬─────────────┘ │
└──────────┼────────────────────┼────────────────────────┼────────────────┘
│ HTTPS │ POST /webhooks/stellar │ Node.js setInterval
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────────┐
│ NestJS HTTP Layer │
│ │
│ Global Middleware Global Guards Global Filters │
│ ┌──────────────────┐ ┌────────────────────┐ ┌──────────────────┐ │
│ │ SecurityMiddleware│ │ ThrottlerGuard │ │GlobalException │ │
│ │ LoggerMiddleware │ │ (per-route caps) │ │Filter │ │
│ └──────────────────┘ └────────────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Feature Modules │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Escrow │ │ Vendor │ │ Dispute │ │ Webhooks │ │
│ │ Module │ │ Module │ │ Module │ │ Module │ │
│ │ │ │ │ │ │ │ │ │
│ │ POST /escrow │ │ POST /vendor │ │ POST /:id/ │ │ POST │ │
│ │ GET /:id │ │ /profile │ │ dispute │ │ /webhooks/ │ │
│ │ PATCH/:id/ │ │ GET /vendor │ │ GET /:id/ │ │ stellar │ │
│ │ ship|cancel│ │ /escrows │ │ dispute │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Admin Modules │ │
│ │ ┌─────────────┐ ┌────────────────┐ ┌───────────────────────┐ │ │
│ │ │ AdminStats │ │ AdminDispute │ │ QueueDashboard │ │ │
│ │ │ GET /admin/ │ │ GET /admin/ │ │ GET /admin/queues │ │ │
│ │ │ stats │ │ disputes │ │ (BullMQ placeholder) │ │ │
│ │ └─────────────┘ └────────────────┘ └───────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Shared Infrastructure Layer │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ PrismaService │ │ CacheService │ │ NotificationsService │ │
│ │ (PostgreSQL) │ │ (Redis / noop) │ │ (SendGrid + Twilio) │ │
│ │ │ │ │ │ │ │
│ │ @Global() │ │ @Global() │ │ Optional clients │ │
│ │ In-memory mock │ │ Graceful no-op │ │ with retry logic │ │
│ │ for dev/tests │ │ when REDIS_URL │ │ (MAX_ATTEMPTS=3) │ │
│ │ │ │ not set │ │ │ │
│ └────────┬────────┘ └────────┬─────────┘ └────────────────────────┘ │
│ │ │ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Auth & Config │ │
│ │ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ │
│ │ │ ConfigModule │ │ Sep10Module │ │ │
│ │ │ @Global() + Joi │ │ SEP-10 JWT challenge/verify │ │ │
│ │ │ validation │ │ JwtGuard for protected routes │ │ │
│ │ └──────────────────────┘ └──────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ External Systems │
│ ┌───────────────┐ ┌────────────────┐ ┌──────────────────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Stellar Network │ │
│ │ │ │ │ │ │ │
│ │ Escrow │ │ escrow:{id} │ │ Horizon API │ │
│ │ Dispute │ │ keys, 60s TTL │ │ Smart contracts │ │
│ │ Notification │ │ │ │ SEP-10 auth │ │
│ │ VendorProfile│ │ │ │ Webhook callbacks │ │
│ │ Processed │ │ │ │ │ │
│ │ WebhookEvent │ │ │ │ │ │
│ └───────────────┘ └────────────────┘ └──────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
AppModule
├── ConfigModule (@Global) — Joi-validated env config, available everywhere
├── PrismaModule (@Global) — PostgreSQL via in-memory mock; real Prisma in prod
├── LoggerModule — Structured JSON logger (JsonLoggerService)
├── CacheModule (@Global) — Redis CacheService; no-op when REDIS_URL unset
├── Sep10Module — SEP-10 Stellar auth challenge + JWT issuance
├── EscrowModule
│ ├── PrismaModule
│ ├── NotificationsModule — SendGrid/Twilio dispatch with 3-attempt retry
│ └── DisputeModule — Dispute repository and resolution logic
├── StellarModule — ContractService: auto-release, delivery recording
├── VendorModule — Vendor profile CRUD
├── AdminStatsModule — Aggregated platform statistics
├── AdminDisputeModule — Admin dispute review and resolution
├── QueueDashboardModule — BullMQ/ioredis queue metrics (placeholder)
├── WebhooksModule — Stellar Horizon webhook receiver
│ └── EscrowModule (imported)
└── WorkersModule
├── EscrowModule
├── DisputeModule
└── StellarModule
| Field | Type | Notes |
|---|---|---|
id |
UUID | Primary key |
itemName |
string | 3–100 chars |
itemRef |
string | Vendor-scoped dedup key |
amount |
Decimal(18,8) | Stellar asset amount |
currency |
string | 3–12 uppercase, e.g. USDC |
buyerAddress |
string | Stellar public key |
vendorAddress |
string | Stellar public key |
state |
EscrowState | See state machine below |
trackingId |
string? | Set when shipped |
shippedAt |
DateTime? | |
deliveredAt |
DateTime? | Set by TrackingPollWorker |
autoReleaseSubmittedAt |
DateTime? | Optimistic lock for auto-release |
autoReleaseTxHash |
string? | Horizon transaction hash |
disputeId |
string? | FK to Dispute |
| Field | Type | Notes |
|---|---|---|
id |
UUID | Primary key |
escrowId |
UUID | FK → Escrow (cascade delete) |
reason |
string | |
description |
string | |
evidenceUrls |
string[] | |
status |
DisputeState | OPEN → UNDER_REVIEW → RESOLVED |
| Field | Type | Notes |
|---|---|---|
operationId |
string | PK — Stellar operation ID |
processedAt |
DateTime | Default now() |
| Field | Type | Notes |
|---|---|---|
address |
string | PK — Stellar public key |
businessName |
string | |
email |
string? | |
phone |
string? | |
| Relationships | accountDetails, trackingSettings, escrows |
┌─────────┐
create ──►│ FUNDED │──── cancel ───────────────────► CANCELLED
└────┬────┘
│ ship (vendor)
▼
┌─────────┐
│ SHIPPED │
└────┬────┘
┌───────┴────────────────────────┐
│ TrackingPollWorker │ buyer opens dispute
│ (every 10 min) ▼
▼ ┌──────────┐
┌───────────┐ │ DISPUTED │
│ DELIVERED │ └────┬─────┘
└─────┬─────┘ │ admin resolves
│ AutoReleaseWorker │
│ (48 h after delivery, ┌────┴─────────┐
│ every 5 min) ▼ ▼
▼ RELEASED REFUNDED
┌───────────┐
│ COMPLETED │
└───────────┘
HTTP Request
│
├─ SecurityMiddleware Sets CSP / HSTS headers
├─ LoggerMiddleware Emits structured request log
├─ ThrottlerGuard (global) Enforces per-route + per-IP limits (Redis storage when REDIS_URL is set, else in-memory)
├─ JwtGuard (route-level) Validates SEP-10 JWT, injects AuthUser
│
├─ Controller Parses + validates DTO (ValidationPipe)
├─ EscrowService Business logic, state validation
│ ├─ CacheService Read: check Redis (escrow:{id}, 60s TTL)
│ ├─ EscrowRepository DB read/write via PrismaService
│ │ └─ CacheService Write: invalidate Redis key after every mutation
│ └─ NotificationsService Fire-and-forget email/SMS
│
└─ GlobalExceptionFilter Maps exceptions to RFC 7807 JSON responses
All HTTP errors are normalized by GlobalExceptionFilter before they leave the
API. Controllers and services should throw Nest HttpException subclasses (for
example BadRequestException, UnauthorizedException, NotFoundException) and
let the global filter write the response.
Every error response uses this envelope:
{
"statusCode": 400,
"message": "Validation failed",
"error": "BadRequestException",
"timestamp": "2026-06-27T12:00:00.000Z",
"path": "/escrow",
"requestId": "1a1d98a2-12c2-48a9-9b4d-36e568c89b5d"
}message may be a string array for class-validator failures. requestId is
resolved by RequestIdMiddleware from x-request-id or generated when absent,
then echoed in both logs and error responses. In development only, the filter may
also include details for diagnostics. Swagger registers the same contract as
ErrorResponseDto and exposes a reusable StandardError response component.
Both workers implement OnModuleInit / OnApplicationShutdown for clean startup and graceful shutdown via clearInterval.
- Query escrows in
DELIVEREDstate wheredeliveredAt≤AUTO_RELEASE_WINDOW_HOURS(48 h) ago, no open dispute, noautoReleaseTxHash. The state must match whatmarkDeliveredwrites, or the query matches nothing (issue #395). - Call
markAutoReleaseSubmitting(id)— setsautoReleaseSubmittedAtas an optimistic lock. - Submit on-chain auto-release via
ContractService.submitAutoRelease(escrowId). - On success:
recordAutoReleaseSubmission(id, txHash)— records the hash, leaves the state atDELIVERED. Submission is not confirmation, so the worker does not finalise; theAutoReleasedchain event does, viamarkAutoReleased→RELEASEDplusnotifyCompleted. - On failure:
clearAutoReleaseSubmitting(id)— unlocks for next cycle.
- Query all
SHIPPEDescrows with atrackingId. - Call
LogisticsService.getStatus(trackingId)for each. - On
DELIVEREDstatus:markDelivered(id)+ContractService.recordDelivery(escrowId). - Errors are caught per-escrow so one failure doesn't block the rest.
Horizon ──POST /webhooks/stellar──► StellarWebhookController
│
verifySignature()
(HMAC-SHA256 with STELLAR_WEBHOOK_SECRET)
│
processedWebhookEvent.findUnique(operationId)
─── already seen? return {skipped: true} ───►
│ first time
processedWebhookEvent.create(operationId)
(DB-persisted cursor — survives restarts)
│
processEvent(dto)
─── type === 'payment'? ──►
│
escrowRepository.findByBuyer(dto.to)
filter state === FUNDED
escrowRepository.updateState(id, FUNDED)
│
─── error? delete cursor, rethrow ──────────►
- Store: Redis (ioredis), configured via
REDIS_URL. - Scope:
GET /escrow/:idonly — single-record lookups under burst traffic. - Key format:
escrow:{uuid}— one key per escrow ID. - TTL: 60 seconds.
- Read path:
EscrowRepository.findByIdchecks Redis before hitting PostgreSQL. - Invalidation: Every
EscrowRepositorywrite method (markShipped,markCancelled,markDelivered,markAutoReleased,updateState, etc.) callscache.del(escrow:{id})immediately after the DB mutation. - Graceful degradation: If
REDIS_URLis not set,CacheServiceis a no-op — reads always hit PostgreSQL, no errors.
SEP-10 (Stellar Ecosystem Proposal 10) provides wallet-native authentication: the client proves ownership of a Stellar private key by signing a server-generated challenge transaction rather than submitting a password.
Client Server (Sep10Controller)
│ │
│── POST /auth/challenge ──────────────► │
│ { publicKey: "G..." } │
│ │ 1. WebAuth.buildChallengeTx()
│ │ (serverKeypair signs the tx)
│ │ 2. Hash tx → nonce
│ │ 3. prisma.nonce.create()
│ │ { nonce, walletAddress,
│ │ challenge (XDR), used=false,
│ │ expiresAt = now + 900s }
│◄── { transaction: "<XDR>", ──────────│
│ network_passphrase } │
Client Server (Sep10Service)
│ │
│ (client signs the XDR with its │
│ Stellar private key) │
│ │
│── POST /auth ──────────────────────── ►│
│ { transaction: "<signed XDR>" } │
│ │ 1. WebAuth.readChallengeTx()
│ │ → extracts clientAccountID
│ │ 2. Hash tx → look up nonce record
│ │ 3. Reject if: not found | used
│ │ | expired
│ │ 4. WebAuth.verifyChallengeTxSigners()
│ │ confirms client signature
│ │ 5. nonce.update({ used: true })
│ │ 6. issueJwt(sub=clientAccountID)
│ │ HS256, exp=now+3600s
│ │ role="admin" if sub===ADMIN_ADDRESS
│ │ 7. Generate 32-byte refresh token,
│ │ store HMAC-SHA256 hash in DB
│◄── { token, refreshToken } ───────────│
Client Server (Sep10Service)
│ │
│── POST /auth/refresh ────────────────►│
│ { refreshToken: "<hex>" } │
│ │ 1. Hash token → look up in DB
│ │ 2. If revoked → revokeTokenFamily()
│ │ (revoke ALL tokens for userId)
│ │ → 401 Refresh token reuse detected
│ │ 3. If expired → 401
│ │ 4. Mark old token revoked=true
│ │ 5. Generate new token pair,
│ │ parentTokenId = old token id
│◄── { token, refreshToken } ───────────│
| Threat | Mitigation |
|---|---|
| Nonce reuse | Each challenge nonce is stored with used=false; set to true after one successful verify. Replaying the same signed XDR is rejected. |
| Expired challenges | expiresAt stored with the nonce (default 900 s). Server rejects if now > expiresAt. |
| Refresh token theft | Rotation: each use issues a new token and revokes the old one. If a stolen token is replayed, the revoked=true check triggers full session revocation via revokeTokenFamily(). |
| Token family escalation | parentTokenId links child tokens to their parent so the entire chain can be revoked on reuse detection. |
| Privilege escalation | JWT role: "admin" is only embedded when sub === ADMIN_ADDRESS (set via env var, not user-supplied). |
Protected endpoints use @UseGuards(JwtGuard) + @CurrentUser() to extract the verified Stellar address from the JWT.
| Layer | Mechanism |
|---|---|
| Transport | HTTPS enforced in production |
| Headers | SecurityMiddleware: CSP, HSTS, X-Frame-Options |
| CORS | ALLOWED_ORIGINS allowlist; blocks all in production if unset |
| Auth | SEP-10 JWT on protected routes |
| Rate limiting | ThrottlerGuard (@nestjs/throttler) with per-route @Throttle limits; Redis-backed storage when REDIS_URL is set |
| Webhook integrity | HMAC-SHA256 signature verification (X-Stellar-Signature) |
| Input validation | ValidationPipe (whitelist, transform, forbid extra fields) |
| SQL injection | Parameterised queries via Prisma ORM |
| Variable | Required | Default | Purpose |
|---|---|---|---|
DATABASE_URL |
Yes | — | PostgreSQL connection string |
SEP10_JWT_SECRET |
Yes | — | JWT signing secret (min 32 chars) |
ADMIN_ADDRESS |
Yes | — | Admin Stellar public key |
PORT |
No | 3000 |
HTTP listen port |
NODE_ENV |
No | development |
Runtime mode |
STELLAR_NETWORK |
No | TESTNET |
TESTNET or MAINNET |
STELLAR_HORIZON_URL |
No | Horizon default | Horizon API base URL |
STELLAR_WEBHOOK_SECRET |
No | — | HMAC secret for webhook verification |
REDIS_URL |
No | — | Redis URL; caching disabled if absent |
ALLOWED_ORIGINS |
No | — | Comma-separated CORS allowlist |
SENDGRID_API_KEY |
No | — | Email notifications |
TWILIO_ACCOUNT_SID |
No | — | SMS notifications |
TWILIO_AUTH_TOKEN |
No | — | SMS notifications |
LOG_LEVEL |
No | info |
trace│debug│info│warn│error│fatal |
See .env.example for format descriptions and example values.
| Path | Purpose |
|---|---|
src/app.module.ts |
Root module — all imports and global middleware |
src/main.ts |
Bootstrap — CORS, ValidationPipe, graceful shutdown |
src/config/ |
Joi-validated env config (ConfigModule, ConfigService) |
src/escrow/ |
Core escrow CRUD, state machine, dispute endpoints |
src/stellar/ |
Stellar contract calls (auto-release, delivery, dispute resolution) |
src/webhooks/ |
Horizon webhook receiver with HMAC verification and DB cursor |
src/workers/ |
AutoReleaseWorker (5 min) and TrackingPollWorker (10 min) |
src/cache/ |
CacheService (Redis) and CacheModule |
src/prisma/ |
PrismaService — in-memory mock for dev/tests |
src/notifications/ |
SendGrid + Twilio dispatch with retry |
src/auth/ |
SEP-10 challenge, JWT issuance, JwtGuard |
src/common/ |
Guards, filters, middleware, logger |
prisma/schema.prisma |
Prisma data model |
prisma/migrations/ |
Versioned SQL migrations |