Mint Flow - Web3 Wallet & Token Minting Platform

Production-ready Web3 application demonstrating wallet management and token minting on Ink Sepolia testnet using Gelato infrastructure.

Live Demo

• Frontend: https://smart-wallet-token-minter-frontend-gamma.vercel.app (Vercel)
• Backend API: https://smart-wallet-token-minter-production.up.railway.app (Railway)
• API Documentation: https://smart-wallet-token-minter-production.up.railway.app/docs (Swagger/OpenAPI)

Quick Start

Prerequisites

• Node.js: v22.7.0
• Package Manager: pnpm
• Docker: For PostgreSQL + Redis

Installation & Setup

# 1. Clone repository
git clone git@github.com:AlexGavrilov939/smart-wallet-token-minter.git
cd mint-flow

# 2. Start infrastructure
docker-compose up -d

# 3. Install dependencies
cd backend && pnpm install
cd ../frontend && pnpm install

# 4. Configure environment variables
cp backend/.env.example backend/.env
# Configure frontend environment variables (see Frontend section below)

# 5. Run database migrations
cd backend && pnpm db:migrate

# 6. Start servers
# Terminal 1: Backend
cd backend && pnpm dev

# Terminal 2: Frontend
cd frontend && pnpm dev

Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001/api/v1
• OpenAPI Docs: http://localhost:3001/docs

Architecture & Design Decisions

Backend: Hexagonal Architecture (Ports & Adapters)

Why this pattern?

• Testability: Business logic isolated from infrastructure (easy to mock)
• Flexibility: Swap adapters (database, blockchain client) without touching business rules
• Scalability: Clear separation enables independent scaling of layers
• Maintainability: Changes to external services don't affect core business logic

Structure:

Domain Layer (Ports) → Application Layer (Use Cases) → Infrastructure Layer (Adapters)

Frontend: Feature-Sliced Design

Why this pattern?

• Modularity: Features are independent and removable
• Scalability: Easy to add new features without affecting existing ones
• Code Organization: Clear structure improves developer experience

Key Technical Decisions

Decision	Rationale
NestJS + Fastify	Type-safe, modular backend with high performance
Drizzle ORM	Type-safe queries, excellent DX, lightweight
Zod Validation	Runtime type checking, auto-generate OpenAPI schemas
Bull Queue	Reliable background jobs for webhook delivery
Next.js 15 App Router	Server Components, improved performance
Dynamic.xyz	Best-in-class email-to-wallet WaaS solution

API Endpoints

All endpoints are documented at /docs with OpenAPI 3.0 specification.

Method	Endpoint	Description
POST	/api/v1/wallets	Register wallet (email + address)
POST	/api/v1/mint	Mint tokens
GET	/api/v1/mints	List mint requests
POST	/api/v1/webhooks	Register webhook URL
GET	/api/v1/webhooks	List webhook subscriptions
GET	/api/v1/webhooks/deliveries	Webhook delivery logs

Testing

# Backend unit tests
cd backend && pnpm test

# Backend E2E tests
cd backend && pnpm test:e2e

# Frontend tests
cd frontend && pnpm test

# Performance tests
cd backend && pnpm test:load

Coverage: 141 automated tests (82 unit + 59 E2E)

Technical Features

Feature	Implementation
Next.js + TypeScript + Tailwind	✅ Next.js 15, App Router, Tailwind CSS
Gelato Smart Wallet SDK	✅ Direct contract calls via ethers.js
Token Minting	✅ ERC-20 mint, status tracking
OpenAPI at /docs	✅ Auto-generated from Zod schemas
Zod Validation	✅ All endpoints + environment
PostgreSQL + Drizzle ORM	✅ Type-safe queries, migrations
Biome Linting	✅ Strict rules configured
Docker Compose	✅ PostgreSQL + Redis
Unit + E2E Tests	✅ 141 tests passing
Webhook System	✅ Subscriptions + delivery tracking

Bonus Features

• ✅ CI/CD Pipeline (GitHub Actions)
• ✅ Performance Testing (k6 load tests)
• ✅ Monitoring (Sentry integration)
• ✅ Security (Rate limiting, input sanitization)

Project Structure

mint-flow/
├── backend/                    # NestJS (Hexagonal Architecture)
│   ├── src/
│   │   ├── modules/           # Business modules
│   │   │   ├── wallets/       # Wallet registration
│   │   │   ├── minting/       # Token minting
│   │   │   └── webhooks/      # Webhook system
│   │   └── infra/             # Database, monitoring
│   └── test/                  # Unit + E2E tests
│
├── frontend/                  # Next.js 15 (Feature-Sliced)
│   ├── app/                   # App Router pages
│   ├── features/              # Auth, minting, webhooks
│   └── tests/                 # Component + E2E tests
│
└── docker-compose.yml         # PostgreSQL + Redis

Tech Stack

Backend

• Framework: NestJS 10 + Fastify
• Database: PostgreSQL 15 + Drizzle ORM
• Validation: Zod
• Blockchain: ethers.js v6
• Jobs: Bull Queue (Redis)
• Docs: OpenAPI 3.0 (Swagger)

Frontend

• Framework: Next.js 15 (App Router, React 19)
• Styling: Tailwind CSS
• Web3: Dynamic.xyz SDK
• State: React Query
• HTTP: Axios

DevOps

• Containers: Docker + Docker Compose
• Linting: Biome
• Testing: Jest + Supertest + Playwright
• CI/CD: GitHub Actions
• Deployment: Vercel + Railway

Environment Configuration

Backend (backend/.env)

DATABASE_URL=postgresql://postgres:postgres_password_dev@localhost:5432/mintflow_dev
GELATO_API_KEY=your_api_key
GELATO_SIGNER_PRIVATE_KEY=0x...
INK_SEPOLIA_RPC_URL=https://rpc-gel-sepolia.inkonchain.com
MINT_TOKEN_ADDRESS=0xb816FD8246E872aA712Bc3c7D6bE2e0Dc0B26f3F

Frontend (frontend/.env.local)

Create a .env.local file in the frontend directory with:

NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=your_dynamic_env_id
NEXT_PUBLIC_CHAIN_ID=763373
NEXT_PUBLIC_MINT_TOKEN_ADDRESS=0xb816FD8246E872aA712Bc3c7D6bE2e0Dc0B26f3F

See backend/.env.example for complete backend configuration.

Blockchain Details

• Network: Ink Sepolia Testnet (Chain ID: 763373)
• Contract: ERC-20 MintToken
• Address: 0xb816FD8246E872aA712Bc3c7D6bE2e0Dc0B26f3F
• Explorer: https://explorer-sepolia.inkonchain.com

---

Production-grade Web3 demo showcasing wallet management and token minting with Gelato, featuring clean architecture and modern development patterns.