Kosmos API

A decentralized multi-vendor e-commerce marketplace backend built with NestJS and Stellar blockchain integration.

Kosmos API is the backend service powering KosmosShop, a trustless, transparent marketplace where sellers can launch shops and buyers enjoy secure transactions via Stellar blockchain.

🌟 Features

• Multi-Vendor Marketplace - Sellers can create and manage multiple shops
• Stellar Integration - Native blockchain payments with XLM and stablecoins
• Smart Escrow - Soroban smart contracts secure all transactions
• Order Management - Full order lifecycle from creation to fulfillment
• Review System - Immutable, transparent product and seller reviews
• Dispute Resolution - Built-in arbitration for buyer protection
• Real-time Updates - WebSocket support for live order tracking
• Multi-token Support - Accept payments in XLM, USDC, and other Stellar assets
• Analytics - Seller dashboards with sales metrics and insights
• Role-Based Access - Different permissions for buyers, sellers, and admins

🛠️ Tech Stack

• Framework: NestJS (Node.js)
• Language: TypeScript
• Database: PostgreSQL with TypeORM
• Blockchain: Stellar SDK + Soroban Smart Contracts
• Storage: IPFS (Pinata/Estuary)
• Caching: Redis
• Real-time: Socket.io
• Authentication: JWT + Stellar Wallet
• API Docs: Swagger/OpenAPI
• Testing: Jest + Supertest
• Containerization: Docker

📋 Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0 or yarn
• PostgreSQL >= 14
• Redis >= 6.0
• Docker & Docker Compose (optional, for local development)
• Stellar testnet account
• IPFS pinning service account (Pinata/Estuary)

🚀 Quick Start

1. Clone Repository

git clone https://github.com/yourusername/kosmos-api.git
cd kosmos-api

2. Environment Setup

cp .env.example .env

Edit .env with your configuration:

# Application
NODE_ENV=development
PORT=3000
API_URL=http://localhost:3000

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=kosmos_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET=your_super_secret_key
JWT_EXPIRATION=7d

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_CONTRACT_ID=your_contract_id

# IPFS
IPFS_PINATA_API_KEY=your_pinata_api_key
IPFS_PINATA_API_SECRET=your_pinata_api_secret

# Admin Wallet
ADMIN_WALLET_ADDRESS=your_admin_wallet_address
ADMIN_WALLET_SECRET=your_admin_wallet_secret

3. Install Dependencies

npm install

4. Database Setup

npx typeorm migration:generate -n InitialMigration
npx typeorm migration:run
npm run seed

5. Start Development Server

npm run start:dev

Server runs at http://localhost:3000

API documentation at http://localhost:3000/api/docs

🐳 Docker Setup

Using Docker Compose

docker-compose up -d

This starts:

• NestJS API on port 3000
• PostgreSQL on port 5432
• Redis on port 6379

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

📁 Project Structure

src/
├── auth/                 # Authentication & JWT
├── users/               # User profiles & KYC
├── shops/               # Shop management
├── products/            # Product listings
├── orders/              # Order processing
├── payments/            # Payment handling
├── escrow/              # Escrow smart contract
├── reviews/             # Reviews & ratings
├── disputes/            # Dispute resolution
├── stellar/             # Stellar blockchain integration
├── storage/             # IPFS integration
├── websocket/           # Real-time updates
├── common/              # Decorators, guards, pipes
├── app.module.ts        # Root module
└── main.ts              # Entry point

🔐 Authentication

Wallet-Based Authentication

The API uses Stellar wallet-based authentication:

1. Request Challenge - User requests a challenge to sign
2. Sign Challenge - User signs the challenge with their wallet
3. Verify Signature - Backend verifies the signature and issues JWT
4. Get Token - Returns access and refresh tokens
5. Use Token - Include JWT in Authorization header for all requests

Authentication endpoints handle wallet validation and token management.

📚 API Endpoints

Authentication

• POST /auth/request-challenge - Get challenge to sign
• POST /auth/verify-signature - Verify wallet signature
• POST /auth/refresh-token - Refresh access token

Users

• GET /users/profile - Get current user
• PUT /users/profile - Update profile
• GET /users/:userId - Get public profile

Shops

• POST /shops - Create shop
• GET /shops - List shops with filters
• GET /shops/:shopId - Get shop details
• PUT /shops/:shopId - Update shop
• DELETE /shops/:shopId - Delete shop
• GET /shops/:shopId/analytics - Shop analytics
• POST /shops/:shopId/follow - Follow shop

Products

• POST /products - Create product
• GET /products - List products (search, filter)
• GET /products/:productId - Get product details
• PUT /products/:productId - Update product
• DELETE /products/:productId - Delete product
• PUT /products/:productId/inventory - Update stock

Orders

• POST /orders - Create order
• GET /orders - List user orders
• GET /orders/:orderId - Get order details
• PUT /orders/:orderId/status - Update status
• POST /orders/:orderId/confirm-delivery - Confirm delivery

Payments

• GET /payments/:orderId - Get payment info
• POST /payments/webhook/stellar - Stellar webhook

Escrow

• GET /escrow/:orderId - Get escrow details
• POST /escrow/:orderId/release - Release funds
• POST /escrow/:orderId/refund - Refund buyer

Reviews

• POST /reviews - Create review
• GET /products/:productId/reviews - Get reviews
• PUT /reviews/:reviewId - Update review
• DELETE /reviews/:reviewId - Delete review

Disputes

• POST /disputes - Create dispute
• GET /disputes - List disputes
• GET /disputes/:disputeId - Get dispute details
• POST /disputes/:disputeId/evidence - Submit evidence
• POST /disputes/:disputeId/resolve - Resolve dispute

🧪 Testing

# Run all tests
npm run test

# Run specific test file
npm run test src/auth/auth.service.spec.ts

# Watch mode
npm run test:watch

# Coverage
npm run test:cov

# E2E tests
npm run test:e2e

📦 Build & Deploy

Build for Production

npm run build

Start Production Server

npm run start:prod

🔗 Stellar Integration

The API connects to Stellar blockchain for:

• Smart contract interaction via Soroban
• Payment processing and verification
• Transaction building and submission
• Wallet balance checking
• Event listening for blockchain updates

📡 WebSocket Events

Real-time updates are sent via Socket.io for:

• Order creation and status changes
• Payment confirmations
• Dispute notifications
• Review submissions
• New messages

🔒 Security

• Input Validation - All DTOs validated using class-validator
• Rate Limiting - API endpoints protected against abuse
• JWT Expiration - Short-lived access tokens for security
• CORS - Restricted to authorized frontend domains
• SQL Injection Prevention - Using parameterized queries via TypeORM
• Helmet - Security headers on all responses
• Environment Variables - Sensitive data never committed to version control

📊 Database Migrations

# Generate migration
npm run typeorm migration:generate -- -n MigrationName

# Run migrations
npm run typeorm migration:run

# Revert last migration
npm run typeorm migration:revert

🐛 Debugging

Enable Debug Logging

DEBUG=kosmos:*

View Logs

# Production logs
npm run start:prod | grep "error\|warn"

# Docker logs
docker-compose logs -f api

🤝 Contributing

1. Create feature branch: git checkout -b feature/amazing-feature
2. Commit changes: git commit -m 'Add amazing feature'
3. Push to branch: git push origin feature/amazing-feature
4. Open Pull Request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

• Open GitHub issue
• Check existing documentation