ChainSettle — Backend Repo

NestJS API for milestone-based supply chain escrow on Stellar

This is Repo 2 of 3 in the ChainSettle project:

Repo	Description
chainsetttle-contract	Soroban smart contract (Rust)
chainsetttle-backend ← you are here	NestJS REST API + event poller
chainsetttle-frontend	React + Freighter wallet UI

---

What This Backend Does

The backend is the bridge between the Stellar blockchain and the frontend. It does NOT hold user funds or sign transactions on behalf of users — all fund movements are handled by the on-chain contract. The backend:

• Stores off-chain metadata about shipments and users (PostgreSQL via Prisma)
• Polls Stellar RPC every 5 seconds for contract events and updates local state
• Sends in-app and email notifications to relevant parties when milestones change
• Provides a clean REST API for the frontend to query shipment state
• Issues JWT tokens via a Stellar address signature (no passwords)
• Exposes Swagger docs at /docs

---

Architecture

┌─────────────────────────────────────────────────────┐
│                NestJS Application                    │
│                                                     │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │  Auth   │ │Shipments │ │Milestones│ │ Events │  │
│  │ Module  │ │  Module  │ │  Module  │ │ Module │  │
│  └─────────┘ └──────────┘ └──────────┘ └────────┘  │
│                                          ↑          │
│                                    Cron (5s poll)   │
│  ┌──────────────────┐  ┌──────────────────────────┐ │
│  │  PrismaService   │  │     StellarService        │ │
│  │  (PostgreSQL)    │  │  (Soroban RPC client)     │ │
│  └──────────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────────┘
         ↕                          ↕
   PostgreSQL DB           Stellar Testnet/Mainnet
                           (ChainSettle Contract)

---

Module Overview

Module	Responsibility
AuthModule	Stellar address challenge-response auth → JWT
ShipmentsModule	CRUD for shipment records, sync from chain
MilestonesModule	Milestone state updates, proof hash storage
EventsModule	Stellar event poller (cron), event dispatch
NotificationsModule	In-app + email notifications via Nodemailer
HealthModule	/health endpoint for DB + service liveness
PrismaModule	Shared global DB client (PostgreSQL)
StellarModule	Shared global Stellar RPC client + utilities

---

API Endpoints

All endpoints are prefixed with /api/v1. Protected routes require Authorization: Bearer <JWT>.

Auth

Method	Path	Description
GET	/auth/nonce?address=G...	Get challenge nonce for a Stellar address
POST	/auth/login	Submit signed nonce, receive JWT

Shipments

Method	Path	Auth	Description
POST	/shipments	✓	Register on-chain shipment in DB
GET	/shipments	✓	List shipments (filter by buyer, supplier, status)
GET	/shipments/:id	✓	Full shipment detail + milestones + events
POST	/shipments/:id/sync	✓	Force sync shipment from Stellar chain

Milestones

Method	Path	Auth	Description
GET	/shipments/:id/milestones	✓	List all milestones for a shipment
GET	/shipments/:id/milestones/:index	✓	Get single milestone

Events (on-chain audit log)

Method	Path	Auth	Description
GET	/events	✓	List chain events (filter by shipmentId)

Notifications

Method	Path	Auth	Description
GET	/notifications	✓	Get user notifications
PATCH	/notifications/:id/read	✓	Mark notification as read
PATCH	/notifications/read-all	✓	Mark all as read

Health

Method	Path	Auth	Description
GET	/health	—	Database + service health check

---

Project Structure

chainsetttle-backend/
├── .env.example                     ← copy to .env and fill in values
├── .gitignore
├── nest-cli.json
├── package.json
├── tsconfig.json
├── README.md
│
├── prisma/
│   └── schema.prisma                ← Database schema (User, Shipment, Milestone, etc.)
│
└── src/
    ├── main.ts                      ← App bootstrap (Swagger, CORS, pipes, guards)
    ├── app.module.ts                ← Root module
    │
    ├── common/
    │   ├── prisma/
    │   │   ├── prisma.module.ts
    │   │   └── prisma.service.ts    ← PrismaClient wrapper
    │   ├── stellar/
    │   │   ├── stellar.module.ts
    │   │   └── stellar.service.ts   ← RPC client, event fetching, utilities
    │   ├── filters/
    │   │   └── http-exception.filter.ts  ← Standardised error responses
    │   ├── interceptors/
    │   │   └── transform.interceptor.ts  ← Wraps all responses in { success, data, timestamp }
    │   ├── guards/
    │   │   └── jwt-auth.guard.ts
    │   └── decorators/
    │       └── current-user.decorator.ts
    │
    └── modules/
        ├── auth/
        │   ├── auth.module.ts
        │   ├── auth.controller.ts
        │   ├── auth.service.ts      ← Nonce generation + JWT issuance
        │   ├── jwt.strategy.ts
        │   └── dto/login.dto.ts
        │
        ├── shipments/
        │   ├── shipments.module.ts
        │   ├── shipments.controller.ts
        │   ├── shipments.service.ts
        │   ├── shipments.service.spec.ts ← Unit tests
        │   └── dto/create-shipment.dto.ts
        │
        ├── milestones/
        │   ├── milestones.module.ts
        │   ├── milestones.controller.ts
        │   └── milestones.service.ts  ← DB updates triggered by chain events
        │
        ├── events/
        │   ├── events.module.ts
        │   ├── events.controller.ts
        │   └── events.service.ts    ← Stellar RPC poller (cron every 5s)
        │
        ├── notifications/
        │   ├── notifications.module.ts
        │   ├── notifications.controller.ts
        │   └── notifications.service.ts ← In-app + email via Nodemailer
        │
        └── health/
            ├── health.module.ts
            └── health.controller.ts

---

Prerequisites

• Node.js v20+
• pnpm (recommended) or npm
• PostgreSQL 15+
• Stellar CLI (only needed if deploying the contract)

---

Setup

1. Install dependencies

npm install
# or
pnpm install

2. Set up environment variables

cp .env.example .env

Edit .env with your values:

• DATABASE_URL — your PostgreSQL connection string
• JWT_SECRET — a long random string
• CHAINSETTTLE_CONTRACT_ID — the deployed contract ID from chainsetttle-contract
• SMTP_* — email credentials (use Gmail app password or any SMTP)

3. Set up the database

# Create and apply migrations
npx prisma migrate dev --name init

# Generate Prisma client
npx prisma generate

# (Optional) seed initial data
# npx prisma db seed

4. Start the development server

npm run start:dev

API available at: http://localhost:3000/api/v1 Swagger docs at: http://localhost:3000/docs

---

Running Tests

# Unit tests
npm run test

# Unit tests with coverage
npm run test:cov

# Watch mode
npm run test:watch

---

Authentication Flow

ChainSettle uses a Sign-In With Stellar pattern — no passwords:

1. Frontend → GET /auth/nonce?address=GABC...
   ← { nonce: "chainsetttle:GABC...:1234567890:abc123" }

2. User signs the nonce with Freighter wallet
   (Keypair.sign on the frontend)

3. Frontend → POST /auth/login
   { stellarAddress, signedNonce, signature }
   ← { accessToken: "eyJ..." }

4. All subsequent requests:
   Authorization: Bearer eyJ...

The backend verifies the signature against the public key, then issues a JWT. Wire up the Keypair.verify() call in auth.service.ts before production.

---

Stellar Event Polling

The EventsService runs a cron job every 5 seconds using @nestjs/schedule. It:

1. Calls stellar.fetchContractEvents(lastProcessedLedger) via the Soroban RPC
2. Routes each event to the correct handler (e.g. handleMilestoneConfirmed)
3. Updates Prisma DB records to reflect the new state
4. Triggers notifications to relevant Stellar addresses
5. Saves the raw event to chain_events for audit trail
6. Advances lastProcessedLedger cursor

For production, persist lastProcessedLedger in the DB (or Redis) so it survives restarts.

---

Response Format

All responses are wrapped by the global TransformInterceptor:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-05-17T12:00:00.000Z"
}

Errors follow a standardised format from HttpExceptionFilter:

{
  "success": false,
  "statusCode": 404,
  "timestamp": "2026-05-17T12:00:00.000Z",
  "path": "/api/v1/shipments/SHIP-999",
  "message": "Shipment SHIP-999 not found"
}

---

Production Checklist

• Set NODE_ENV=production
• Use a strong JWT_SECRET (32+ random chars)
• Swap in-memory nonce store for Redis
• Persist lastProcessedLedger in DB (not memory) for crash recovery
• Enable HTTPS (reverse proxy — nginx or Caddy)
• Set up Prisma connection pooling (PgBouncer)
• Wire up real Stellar Keypair.verify() in auth.service.ts
• Set CORS_ORIGIN to your production frontend URL
• Add rate limiting tuning for production traffic
• Deploy via Docker (Dockerfile not included — straightforward to add)

---

Environment Variables Reference

Variable	Required	Description
NODE_ENV	Yes	development or production
PORT	No	API port (default: 3000)
DATABASE_URL	Yes	PostgreSQL connection string
JWT_SECRET	Yes	Secret for signing JWTs
JWT_EXPIRES_IN	No	Token expiry (default: 7d)
STELLAR_NETWORK	Yes	testnet or mainnet
STELLAR_RPC_URL	Yes	Soroban RPC endpoint
CHAINSETTTLE_CONTRACT_ID	Yes	Deployed contract address
USDC_TOKEN_ADDRESS	Yes	USDC SAC address
SMTP_HOST	No	Email SMTP host
SMTP_USER	No	SMTP username
SMTP_PASS	No	SMTP password
CORS_ORIGIN	No	Allowed frontend origin
EVENT_POLLING_INTERVAL_MS	No	Cron interval in ms (default: 5000)

---

License

MIT