Skip to content

crypticdenis/orcinus

BranchesTags

Repository files navigation

Orcinus -- Crypto Wallet Analytics Platform

Full-stack crypto wallet analytics application for tracking whale activity, analyzing EVM-compatible wallet addresses, and monitoring large-scale cryptocurrency transactions. Built with Node.js/Express, React 18, PostgreSQL, and Redis. Implements JWT + TOTP authentication, multi-chain blockchain queries, and GDPR-compliant data handling.

Table of Contents

Status

Production-ready. All core features implemented, tested, and documented.

Features

Wallet Analysis

  • Multi-chain support: Ethereum, BSC, Polygon, Arbitrum (Etherscan v2 / v1 API)
  • Whale risk scoring (0-100) based on transaction volume, frequency, and patterns
  • Transaction history with chain-aware formatting (last 50 transactions)
  • Market impact analysis via CoinGecko price correlation
  • Community-driven wallet discovery (top searched addresses)
  • Per-user search history with persistent storage

Authentication and Access Control

  • JWT-based stateless authentication with configurable expiry
  • TOTP two-factor authentication (otplib) with QR provisioning and backup codes
  • OAuth 2.0 via Passport.js (Google, Apple -- requires provider credentials)
  • Email verification flow with token-based confirmation
  • Secure password reset with time-limited tokens
  • Progressive account lockout after repeated failed attempts
  • Redis-backed rate limiting (per-user and per-IP)
  • CSRF protection via double-submit cookie pattern

Compliance and Privacy

  • GDPR Article 15 -- Right of Access (full data export as JSON)
  • GDPR Article 17 -- Right to Erasure (account deletion with audit trail)
  • Consent management (cookie preferences, marketing opt-in/out)
  • Data processing activity logging
  • Privacy policy and terms of service pages
  • Automated GDPR cleanup via cron job

Planned (Premium Tier)

  • Real-time wallet watchlist with transaction alerts
  • Extended historical analysis and performance tracking

Architecture

Client (React/Vite)  -->  Nginx (prod)  -->  Express API  -->  PostgreSQL
                                                  |
                                                  +--> Redis (cache, rate limits, sessions)
                                                  +--> Etherscan API (blockchain data)
                                                  +--> CoinGecko API (price data)

The backend follows a layered MVC pattern: routes -> middleware -> controllers -> services/models -> database. Authentication middleware validates JWT tokens on protected routes. Rate limiting and account lockout are enforced at the middleware layer before request handling.

See docs/architecture/ARCHITECTURE.md for the full system design.

Tech Stack

Backend

Component Technology Purpose
Runtime Node.js 18, Express 4 HTTP server, REST API
Database PostgreSQL 14 Persistent storage, auth schema, wallet data
Cache Redis (ioredis) Rate limiting, session cache, temporary tokens
Auth jsonwebtoken, bcryptjs (12 rounds), otplib JWT issuance, password hashing, TOTP
OAuth Passport.js Google and Apple OAuth 2.0 strategies
Blockchain Etherscan API Ethereum (v2), BSC/Polygon/Arbitrum (v1)
Prices CoinGecko API Token price data for market impact analysis
Email Nodemailer Verification, password reset, notifications
Security helmet, express-validator, cors Headers, input validation, CORS policy

Frontend

Component Technology Purpose
Framework React 18, Vite SPA with hot module replacement
Styling Tailwind CSS 3 Utility-first CSS, glassmorphism design system
Charts Chart.js (react-chartjs-2) Transaction and market data visualization
HTTP Axios API client with request/response interceptors
Routing React Router v6 Client-side routing with protected routes
State React Context API Authentication state, user session management

Infrastructure

Component Technology Purpose
Containers Docker, Docker Compose Dev and production environments
Reverse Proxy Nginx Static file serving, API proxying (production)

Quick Start

Docker (recommended)

cd scripts/deployment
docker-compose -f docker-compose.dev.yml up --build

Services will be available at:

  • Frontend: http://localhost:5173
  • Backend API: http://localhost:3000

Manual Setup

Refer to docs/setup/QUICKSTART.md for step-by-step instructions.

Configuration

Create a .env file in the project root:

# Server
NODE_ENV=development
PORT=5000

# PostgreSQL
DATABASE_URL=postgresql://user:password@localhost:5432/whalewatcher
DB_HOST=localhost
DB_PORT=5432
DB_NAME=whalewatcher
DB_USER=<your_db_user>
DB_PASSWORD=<your_db_password>

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Authentication
JWT_SECRET=<generate-a-strong-secret>
JWT_EXPIRE=7d

# Blockchain APIs
ETHERSCAN_API_KEY=<your_etherscan_key>

# Rate Limits
FREE_USER_DAILY_LIMIT=3
PREMIUM_USER_DAILY_LIMIT=100

# Frontend
FRONTEND_URL=http://localhost:5173

All secrets must be rotated before production deployment. The JWT_SECRET should be a cryptographically random string of at least 64 characters.

Documentation

All documentation lives in the docs/ directory:

Category Document Description
Architecture ARCHITECTURE.md System design, data flow, component diagram
Architecture PROJECT_ANALYSIS.md Codebase analysis and technical debt
Auth AUTHENTICATION_COMPLETE.md Full auth flow documentation
Auth EMAIL_AND_2FA_COMPLETE.md Email verification and TOTP setup
Auth OAUTH_INTEGRATION_GUIDE.md Google/Apple OAuth configuration
Compliance GDPR_COMPLIANCE.md GDPR implementation details
Security SECURITY.md Security policies and threat model
Security SECURITY_AUDIT_REPORT.md Audit findings and remediations
Audit IMPLEMENTATION_AUDIT.md Feature completeness audit
Setup QUICKSTART.md Installation and first-run guide
Setup DEPLOYMENT.md Production deployment procedures

Full index: docs/README.md

Project Structure

orcinus/
├── server.js                    # Express entry point, middleware registration, graceful shutdown
├── package.json                 # Backend dependencies
│
├── src/                         # Backend source
│   ├── config/
│   │   ├── config.js            # Environment-based configuration
│   │   ├── database.js          # PostgreSQL pool (SSL, timeouts, pool limits)
│   │   ├── redis.js             # Redis client (reconnect, retry config)
│   │   └── passport.js          # OAuth strategy registration
│   │
│   ├── controllers/
│   │   ├── authController.js    # Login, register, verify email, password reset
│   │   ├── twoFactorController.js  # TOTP setup, verify, backup codes
│   │   ├── oauthController.js   # OAuth callback handlers
│   │   ├── gdprController.js    # Data export, deletion, consent
│   │   ├── walletController.js  # Wallet analysis orchestration
│   │   └── userController.js    # Profile management
│   │
│   ├── middleware/
│   │   ├── auth.js              # JWT verification
│   │   ├── security.js          # Helmet, CORS, CSRF
│   │   ├── accountLockout.js    # Progressive lockout logic
│   │   ├── rateLimiter.js       # Redis-backed rate limiting
│   │   ├── validation.js        # express-validator schemas
│   │   └── errorHandler.js      # Centralized error handling
│   │
│   ├── models/
│   │   ├── userModel.js         # User CRUD, password hashing (bcrypt, 12 rounds)
│   │   ├── walletModel.js       # Wallet data persistence
│   │   ├── transactionModel.js  # Transaction storage
│   │   └── gdprModel.js         # GDPR data operations, processing logs
│   │
│   ├── routes/                  # Express route definitions (mounted in server.js)
│   ├── services/
│   │   ├── blockchainService.js # Multi-chain Etherscan queries, risk scoring
│   │   ├── emailService.js      # Nodemailer templates (verification, reset)
│   │   └── marketImpactService.js  # CoinGecko price correlation
│   │
│   ├── database/
│   │   ├── schema.sql           # Full PostgreSQL schema
│   │   └── migrations/          # Incremental migration scripts
│   │
│   └── scripts/                 # DB init, migrations, GDPR cleanup
│
├── client/                      # Frontend (React 18 + Vite)
│   ├── src/
│   │   ├── App.jsx              # Router, protected routes, 404 handling
│   │   ├── index.css            # Tailwind base, glassmorphism design tokens
│   │   ├── components/
│   │   │   ├── Navbar.jsx
│   │   │   ├── WalletCard.jsx
│   │   │   ├── TransactionChart.jsx
│   │   │   ├── TransactionList.jsx
│   │   │   ├── MarketImpact.jsx
│   │   │   ├── PurchaseTimeline.jsx
│   │   │   └── CookieConsent.jsx
│   │   ├── pages/               # Route-level components
│   │   ├── context/
│   │   │   └── AuthContext.jsx  # JWT state, auto-logout on 401
│   │   └── services/
│   │       └── api.js           # Axios instance, interceptors, API methods
│   │
│   ├── vite.config.js           # Dev server proxy to backend
│   └── tailwind.config.js
│
├── scripts/
│   └── deployment/
│       ├── docker-compose.dev.yml
│       ├── docker-compose.prod.yml
│       └── Dockerfile
│
├── docs/                        # All project documentation
└── tests/

Security Model

Defense-in-depth approach across all layers:

Control Implementation
Password hashing bcryptjs with 12 salt rounds, 12-character minimum with complexity requirements
Token auth JWT with configurable expiry, secure cookie flags in production
Two-factor TOTP (RFC 6238) via otplib, QR provisioning, encrypted backup codes
Account lockout Progressive delays after 5 failed attempts, Redis-tracked
Rate limiting Redis-backed, configurable per-route (auth: 5/15min, API: 100/15min)
CSRF Double-submit cookie pattern on state-changing endpoints
Headers Helmet.js with Content-Security-Policy, X-Frame-Options, HSTS
Input validation express-validator on all endpoints, parameterized SQL queries
XSS React DOM escaping, server-side content sanitization
Secrets Environment variables only, no hardcoded credentials

Full security documentation: docs/security/SECURITY.md

GDPR Compliance

Implements the following data subject rights per EU Regulation 2016/679:

Right Endpoint Implementation
Access (Art. 15) GET /api/gdpr/export Full JSON export of user data
Erasure (Art. 17) DELETE /api/gdpr/delete-account Cascading deletion with audit trail
Rectification (Art. 16) PUT /api/users/profile Profile data updates
Portability (Art. 20) GET /api/gdpr/export Machine-readable JSON format
Consent (Art. 7) POST /api/gdpr/consent Granular cookie and marketing preferences

All data operations are logged in the data_processing_log table. Automated cleanup of expired data runs via cron (scripts/cron-gdpr-cleanup.txt).

See docs/guides/GDPR_COMPLIANCE.md for implementation details.

Contributing

  1. Review the current state in docs/audits/IMPLEMENTATION_AUDIT.md
  2. Understand the architecture via docs/architecture/ARCHITECTURE.md
  3. Follow security guidelines in docs/security/SECURITY.md
  4. Branch from main, use descriptive commit messages
  5. Submit a pull request with a detailed description of changes

License

Proprietary software. All rights reserved.

Contact

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages