Fastr Wallet Infra

Full-stack infrastructure for an Account Abstraction wallet:

• Backend API: Fastify + Drizzle + PostgreSQL + Redis + ERC-4337 services
• Frontend app: Next.js + Zustand + Tailwind + Web3Auth MPC
• Shared runtime: multi-chain (Ethereum, Polygon, Base, Arbitrum), price feeds, WebSocket updates

Repository Layout

Path	Purpose
.github/workflows/ci.yml	CI pipeline (lint, backend tests, frontend build, docker build)
Backend/	Fastify API, database layer, AA services, integration tests
Frontend/	Next.js app, auth + wallet stores, transaction UX, design system
docker-compose.yml	Local orchestration for PostgreSQL, Redis, backend, frontend

Detailed folder docs:

• Backend/README.md
• Backend/src/README.md
• Frontend/README.md
• Frontend/app/README.md
• Frontend/components/README.md
• Frontend/hooks/README.md
• Frontend/lib/README.md
• .github/workflows/README.md
• Docs/ARCHITECTURE.md

Runtime Architecture (See Docs/ARCHITECTURE.md for diagrams)

1. Authentication flow (email OTP + JWT + MPC)

1. Frontend login screen calls POST /api/v1/auth/send-otp.
2. User submits OTP to POST /api/v1/auth/verify.
3. Backend validates OTP or provider token (Google/Apple), upserts user, returns JWT.
4. Frontend stores JWT and initializes MPC session via web3auth-mpc.ts.
5. If no wallet exists, frontend auto-creates one for the active chain.

2. Wallet and balance flow

1. Frontend calls GET /api/v1/wallets and GET /api/v1/balances.
2. Backend resolves wallet rows from PostgreSQL.
3. Native balances are fetched from chain RPC clients (viem).
4. Fiat conversion is fetched from CoinGecko and cached in Redis/memory.

3. Send transaction flow (AA — Frontend-First Signing)

1. Frontend send modal validates recipient/amount and calls POST /api/v1/transactions/estimate-gas.
2. On submit, frontend creates a SmartAccountClient via permissionless.js + Web3Auth MPC signer.
3. UserOperation is signed client-side using MPC (private key never leaves the browser).
4. Frontend submits the signed UserOp to Pimlico bundler and logs the result via POST /api/v1/transactions/log.
5. Backend persists the transaction record and triggers any configured webhooks.

4. Realtime price flow

1. Frontend connects to /ws with JWT.
2. Backend enforces WebSocket auth timeout and per-IP rate limiting.
3. Client subscribes to prices; backend pushes initial + periodic snapshots.

API Surface (Current)

Auth

• POST /api/v1/auth/send-otp — Send email OTP
• POST /api/v1/auth/verify — Verify OTP / Google / Apple token
• POST /api/v1/auth/refresh — Rotate refresh token (httpOnly cookie)
• GET /api/v1/auth/profile — Get authenticated user profile
• PUT /api/v1/auth/preferences — Update display currency (USD/INR)
• POST /api/v1/auth/logout — Logout + blacklist tokens

Wallets and Balances

• POST /api/v1/wallets — Create wallet
• GET /api/v1/wallets — List user wallets
• GET /api/v1/wallets/:id — Get wallet by ID
• GET /api/v1/wallets/:id/balance — Get wallet balance
• GET /api/v1/balances — Get all balances

Transactions

• GET /api/v1/wallets/:walletId/transactions — Transaction history
• GET /api/v1/transactions/recent — Recent transactions
• GET /api/v1/transactions/:hash — Transaction by hash
• POST /api/v1/transactions/estimate-gas — Gas estimation
• POST /api/v1/transactions/log — Log a frontend-signed transaction
• POST /api/v1/transactions/send — Legacy send (disabled, use frontend signing)

ENS

• POST /api/v1/resolve-ens — Resolve ENS name to address (cached)

API Keys

• POST /api/v1/api-keys — Create API key
• GET /api/v1/api-keys — List API keys
• DELETE /api/v1/api-keys/:id — Revoke API key

Pricing and Chains

• GET /api/v1/prices — Get prices for a token
• GET /api/v1/prices/all — Get all supported prices
• GET /api/v1/prices/gas — Get gas price
• GET /api/v1/chains — List supported chains

WebSocket

• GET /ws — Real-time price feed (JWT auth required)

Documentation

• GET /api/docs — Swagger/OpenAPI interactive documentation

Data Model (Backend)

Core tables in Backend/src/db/schema.ts:

• users
• wallets
• transactions
• tokens
• balances
• api_keys

Relations:

• user -> many wallets
• wallet -> many transactions
• wallet -> many balances
• balance -> token

Local Development

Prerequisites

• Node.js 20+
• npm (backend) and pnpm (frontend)
• Docker (for PostgreSQL and Redis)

Start services

docker-compose up -d postgres redis

Backend

cd Backend
npm install
npm run db:migrate
npm run dev

Frontend

cd Frontend
pnpm install
pnpm dev

App URLs:

• Frontend: http://localhost:3000
• Backend: http://localhost:4000
• Health check: http://localhost:4000/health

Environment Files

Use examples:

• Backend/.env.example
• Frontend/.env.example

Key runtime settings:

• Backend requires JWT_SECRET.
• Backend expects DATABASE_URL unless USE_MOCK_DB=true.
• AA flow needs PIMLICO_API_KEY for bundler/paymaster calls.
• Frontend requires NEXT_PUBLIC_API_URL and NEXT_PUBLIC_WEB3AUTH_CLIENT_ID.

Testing and CI

Backend

• Unit/integration tests: cd Backend && npm test
• Coverage: cd Backend && npm run test:coverage

Frontend

• Typecheck/build validation: cd Frontend && pnpm typecheck && pnpm build

CI

ci.yml runs:

1. Lint/typecheck both apps
2. Backend tests with PostgreSQL + Redis services
3. Frontend build
4. Optional docker publish on push to main/master

Deployment

See DEPLOYMENT.md for comprehensive setup, deployment, and operations documentation including:

• Local development setup
• Docker Compose deployment
• Cloud deployment guides (AWS, Railway, Render, Fly.io, Vercel)
• Third-party service configuration
• Security hardening checklist
• Troubleshooting guide

Current Notes

• Transaction signing is handled entirely on the frontend (MPC + permissionless.js). The backend is a data/config layer.
• Auth tokens use short-lived JWTs (15min) with httpOnly cookie refresh tokens (7 days) and rotation.
• ENS resolution is implemented with Redis caching.
• Currency toggle (USD/INR) is wired to the Zustand store and reflected across the UI.
• Swap feature is marked as "In Development" with a placeholder page.

License

MIT