Project Overview

This is a Node.js + Express backend that demonstrates JWT-based authentication and ERC-4337 Account Abstraction for gasless blockchain transactions. The system uses Biconomy's infrastructure to sponsor gas fees and submit UserOperations via bundlers. This is a prototype/demo system built for hackathon and internship review purposes, showcasing modular backend architecture and blockchain integration patterns. It is not intended for production use.

🛡️ Web3 & Smart Accounts (ERC-4337)

Account Abstraction: Leverages ERC-4337 to provide a seamless user experience through smart contract wallets.

Gasless Transactions: Integrated Biconomy Paymaster and Bundlers to sponsor user transactions, removing the barrier of entry for gas fees.

Programmable Wallets: Robust management of user accounts and transaction records via MongoDB.

🔒 Security & Authentication

Dual-Token Auth: Implements stateless JWT Authentication with a secure Access/Refresh token rotation strategy.

Advanced Safety (Demos):

• ML-Driven Fraud Detection: Simulated machine learning analysis to flag suspicious on-chain activity.
• Biometric Verification: Mocked biometric flows to demonstrate high-assurance identity verification.

Resilient Infrastructure: Basic Rate Limiting to prevent brute-force attacks and API abuse.

⚙️ Developer Experience & Reliability

Type-Safe Validation: Strict input enforcement using Zod schemas to ensure data integrity before it reaches the controller.

Observable Systems: Structured, multi-level logging powered by Winston, capturing detailed service-level events and HTTP requests.

Graceful Lifecycle Management: Automated handling of SIGTERM/SIGINT signals to ensure database connections close cleanly and no data is lost during deployments.

System Architecture

The backend consists of four primary layers:

Authentication Layer: JWT-based stateless authentication with access and refresh tokens. Tokens are verified via middleware on protected routes.

Blockchain Layer: Ethers.js handles RPC interactions. Biconomy SDK manages Account Abstraction wallets, UserOperation construction, and Paymaster/Bundler submission for gasless transactions.

ML Mock Service: A demo service that simulates fraud detection and biometric verification responses. No real machine learning models or biometric cryptography are executed.

Database Layer: MongoDB stores user credentials, wallet addresses, transaction history, and session metadata.

Technology Stack

• Runtime: Node.js
• Framework: Express.js
• Database: MongoDB with Mongoose ODM
• Authentication: JSON Web Tokens (jsonwebtoken)
• Blockchain: Ethers.js, Biconomy SDK (Account Abstraction)
• Validation: Zod
• Logging: Winston
• Security: Helmet, express-rate-limit, bcrypt

Authentication Flow

Registration

1. User submits email and password
2. Password is hashed with bcrypt
3. Server-side wallet is generated (custodial)
4. User record is stored in MongoDB
5. Access and refresh tokens are issued

Login

1. User credentials are validated
2. Biometric verification is simulated via mock service
3. JWT access token (short-lived) and refresh token (long-lived) are returned

Token Refresh

1. Client sends refresh token
2. Server validates token signature and expiry
3. New access token is issued
4. Refresh token is reusable and not rotated

Logout

Logout is client-side only. Tokens are stateless and not blacklisted. Users must delete tokens locally.

Transaction Flow (Gasless via Account Abstraction)

Wallet Creation

Smart contract wallets are deployed using Biconomy's Account Abstraction infrastructure. Wallets are controlled by server-generated private keys (custodial model for demo purposes).

UserOperation Lifecycle

1. User initiates a transaction request
2. Backend constructs an ERC-4337 UserOperation
3. UserOperation includes target address, calldata, and gas estimates
4. Backend signs the UserOperation with the wallet's private key

Paymaster & Bundler Interaction

1. UserOperation is sent to Biconomy Paymaster for gas sponsorship
2. Paymaster signs the operation, agreeing to cover gas costs
3. Signed UserOperation is submitted to Biconomy Bundler
4. Bundler includes the operation in an on-chain bundle transaction
5. Transaction hash and status are returned to the client

Fraud Detection & Biometrics (Demo Mock)

Both fraud detection and biometric verification are implemented as demo mock services. These services simulate ML model responses with hardcoded logic and do not perform real analysis.

Fraud Detection: Returns mock risk scores and flags based on transaction amount thresholds. No real anomaly detection or machine learning models are used.

Biometric Verification: Simulates biometric authentication success/failure. No actual biometric data is processed or verified. This is used purely to unblock frontend authentication flows.

Logging & Monitoring

The backend uses Winston for structured logging:

• HTTP request logs (method, path, status, response time)
• Service-level logs (blockchain operations, auth events)
• Error logs with stack traces
• Logs are output to console and can be configured for file or external service output

Limitations & Demo Notes

This backend has several important limitations:

Mocked Services:

• Fraud detection uses hardcoded logic, not real ML models
• Biometric verification is completely simulated
• No actual biometric cryptography or liveness detection

Custodial Wallets:

• Private keys are generated and stored server-side
• Backend signs all transactions on behalf of users
• This is not suitable for production; users should control their own keys

Stateless Auth Limitations:

• No token blacklisting or revocation
• Logout is purely client-side
• Refresh tokens are reusable and never rotated
• Compromised tokens remain valid until expiry

Incomplete Features:

• OTP verification is scaffolding only
• Push notifications are not implemented
• Activity logs and audit trails are partial
• Some security settings endpoints return mock data

Production Gaps:

• No rate limiting on sensitive operations
• Basic input validation only
• No comprehensive error monitoring
• No secrets rotation strategy

Future Improvements

To move this system toward production readiness:

• Real ML Integration: Implement actual fraud detection models with training pipelines
• Non-Custodial Wallets: Support user-controlled private keys or social recovery mechanisms
• Token Rotation: Implement refresh token rotation and blacklisting
• Enhanced Security: Add 2FA, session management, and anomaly detection
• Biometric SDK: Integrate real biometric verification services
• Monitoring: Add APM, error tracking, and alerting infrastructure
• Testing: Comprehensive unit, integration, and end-to-end test coverage
• Documentation: Full API documentation with request/response schemas

Local Setup

Prerequisites

• Node.js (v16 or higher)
• MongoDB (local or Atlas)
• Biconomy API keys
• Blockchain RPC URL (e.g., Alchemy, Infura)

Installation

npm install

Run Development Server

npm run dev

Run Production Server

npm start

Disclaimer

This is a demonstration backend built for educational and portfolio purposes. It showcases blockchain integration patterns and backend architecture but is not production-ready. The fraud detection and biometric verification features are mocked. Wallets are custodial. This system should not be used to handle real funds or sensitive user data without significant security enhancements.