The Crypto Wallet Risk Analyzer (CWRA) is a sophisticated, multi-layered software ecosystem engineered to provide automated forensic analysis, capital flow monitoring, and standardized risk assessment for cryptocurrency wallet addresses. By operationalizing data ingestion from more than 200 distinct blockchain protocols, the CWRA platform facilitates institutional-grade transparency in decentralized finance (DeFi) environments.
The system addresses the fundamental challenge of blockchain heterogeneity—namely, the inconsistent data structures across Layer 1 (L1) and Layer 2 (L2) networks—by implementing a Statistical Normalization Engine (SNE). This engine transforms raw transaction metadata into a unified cognitive model, allowing for the application of advanced mathematical heuristics and machine learning (ML) classification to determine the security profile of any given actor on a supported network.
This software was developed by Group 24 of the IIT Jodhpur Software Engineering (CSE302) course as a comprehensive solution for blockchain auditing and risk mitigation.
The CWRA platform employs a hybrid scoring model that fuses deterministic heuristics with probabilistic machine learning classification. The final risk score (0-100) is a weighted aggregate representing the forensic risk profile of the target entity.
The heuristic engine evaluates wallets against a predefined set of forensic rules, derived from industry-standard anti-money laundering (AML) and know-your-transaction (KYT) protocols.
- Mathematical Threshold: $50,000 USD (Normalized).
- Logic: Any single transaction event where the valuation (v) satisfies
v > 50000triggers a Whale event. - Forensic Significance: Identifies significant capital reallocation events that could indicate institutional movements or potential market manipulation attempts. Large capital moves on decentralized exchanges often impact liquidity pools, and tracking these "whales" is critical for market stability analysis.
- Mathematical Threshold: Delta (Δ) < 0.05 * Total Volume (V).
- Logic: Detects entities where aggregate transaction volume is high but the net capital flow (the difference between incoming and outgoing assets) is less than 5% of the total volume.
- Forensic Significance: This is a characteristic signature of privacy-preserving mixing protocols (e.g., Tornado Cash). Near-zero net flow indicates that capital is entering and exiting the address in rapid succession for the purpose of transaction obfuscation, a common tactic for asset laundering.
- Mathematical Threshold: Transaction Count (n) > 50 AND Age (t) < 72 hours.
- Logic: Identifies addresses with high-intensity activity within a compressed temporal window since inception.
- Forensic Significance: Associated with "burner" accounts used for automated farming, sybil attacks, or one-time use operational cycles. These wallets are rarely used for long-term storage and are typically discarded after a specific exploit or automated operation is completed.
- Mathematical Threshold: Average Time-Between-Transactions (TBT) < 30s.
- Logic: Flags address activity where the mean temporal gap between consecutive block inclusions is less than the standard human interaction threshold.
- Forensic Significance: Programmatic interaction signatures are distinguishable from human-operated wallets. Rapid-fire transaction bursts are indicative of automated arbitrage, liquidator bots, or algorithmic trading scripts.
- Mathematical Threshold: s_max > 0.8 * Σ s_i.
- Logic: Calculates the exposure to a single counterparty. If a single entity accounts for more than 80% of total volume, a concentration flag is triggered.
- Forensic Significance: Signals extreme liquidity dependency or potential self-dealing in "wash-trading" scenarios, where an actor interacts primarily with their own alternate addresses to fabricate volume.
The platform utilizes a 17-feature vector to classify wallets via a Random Forest ensemble model trained on labeled forensic datasets.
The features used for the ML inference include, but are not limited to:
avg_tx_value: The mean valuation of all transaction events associated with the entity. This acts as a proxy for the entity's economic tier.std_tx_value: The standard deviation of transaction values, representing capital flow volatility. High volatility often accompanies speculative or automated trading.unique_interacted_addresses: A count of distinct counterparties, representing the entity's network topology. Higher counts suggest a highly active and connected wallet.active_days: The temporal span between the first and last recorded transaction. Longevity is a strong signal for legitimate, long-term actors.error_tx_ratio: The ratio of failed transactions (reverted or out-of-gas events) to successful state transitions. Abnormal ratios can indicate malfunctioning bots or high-risk smart contract interactions.net_flow: The absolute difference between total incoming and outgoing asset volume. Legitimate entities usually show a directional trend, while malicious entities often show balanced flow indicative of laundry operations.avg_time_between_tx: The temporal average of transaction frequency.
The system integrates two primary indices for measuring capital distribution:
Herfindahl-Hirschman Index (HHI):
- Formula:
HHI = Σ (s_i)^2, wheres_iis the volume share of the i-th counterparty. - Logic: Originating from antitrust law, the HHI represents the degree of monopoly within a wallet's interactions. An HHI approaching 1.0 indicates extreme transaction centralization towards a single entity.
Gini Coefficient:
- Logic: Utilized to measure wealth disparity and capital inequality within the wallet's interaction history (0.0 = perfect equality, 1.0 = perfect inequality).
- Forensic Significance: A high Gini index indicates that transaction values are highly unequal (e.g., millions of small transactions and one massive transfer), a common pattern in "hub-and-spoke" laundering models.
The CWRA platform is architected as a decoupled, high-availability system comprising three primary services and a persistence layer.
The Backend Service serves as the primary gateway for all client-side and external service orchestration.
- Technical Stack: Node.js v20, Express, Axios, Mongoose.
- Internal Role:
- Implementation of the Covalent GoldRush (Primary) and Tatum (Secondary) failover acquisition logic.
- Coordination of background synchronization jobs via internal asynchronous queues.
- Enlisting Cross-Origin Resource Sharing (CORS) policies to ensure secure browser interactions.
- Handling of JWT-based session validation for institutional users.
The Analytical Engine is optimized for computational efficiency and statistical data transformation.
- Technical Stack: Python 3.11, FastAPI, NumPy, Joblib, Scikit-learn, Pydantic.
- Internal Role:
- Implementation of the Statistical Normalization Engine (SNE).
- Computation of high-order metrics (HHI, Gini, Net Flow).
- Execution of the ML risk model and heuristic ruleset.
- Providing OpenAPI (Swagger) documentation for the analytical endpoints.
The Frontend provides an institutional-grade UX for forensic monitoring.
- Technical Stack: React 18, TypeScript, Vite, Recharts, CSS Modules.
- Design Philosophy: The "VaultOS" design system utilizes a dark-mode, high-contrast palette with glassmorphism effects to project security and institutional reliability.
Persistence is managed via MongoDB Atlas (cloud). Set MONGO_URI in .env with your Atlas connection string. See the Docker Runbook for details.
Stores metadata and synchronization state of analyzed entities.
address: Public identifier of the entity (indexed).chain: Target blockchain network identifier (e.g.,eth-mainnet).syncStatus: Current state (PENDING,SYNCING,SYNCED,FAILED).lastSync: Timestamp of the most recent ledger update.
A normalized database of every interaction tracked by the system.
txHash: Unique transaction identifier (Global Index).value: Standardized decimal asset value (Normalized from Wei/Sato).from/to: Entity identifiers.assetType: Classification of the asset (NATIVE,ERC20,BEP20).source: Data provider identifier (goldrushortatum).
Persistence of the final scoring outputs to minimize computational redundancy.
wallet: Reference to the wallet address public key.score: The final risk index (0-100).tier: Risk classification (e.g., LOW RISK, MEDIUM RISK, HIGH RISK, CRITICAL).flags: List of triggered deterministic forensic alerts.
- Endpoint:
POST /api/wallet/analyze - Description: Initiates a synchronized forensic analysis of an address. Automatically triggers historical synchronization if required.
- Request Payload:
{
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"chain": "eth-mainnet",
"forceSync": false
}- Response Payload:
{
"wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"score": 24.5,
"tier": "LOW RISK",
"tx_count": 142,
"total_volume": 1294092.00,
"hhi": 0.12,
"gini": 0.08,
"flags": ["Whale Activity Detected"]
}- Endpoint:
GET /api/wallet/analyses - Description: Returns all completed scan results from the database, sorted chronologically with the most recent analysis first.
- Response Payload:
[
{
"wallet": "0xd8dA...",
"score": 24.5,
"tier": "LOW RISK",
"updatedAt": "2026-04-14T09:00:00Z"
},
{
"wallet": "0xEA8a...",
"score": 88.2,
"tier": "CRITICAL",
"updatedAt": "2026-04-14T08:30:00Z"
}
]- Endpoint:
GET /api/wallet/transactions - Description: Returns the standardized ledger entries for a target address including sender, receiver, and asset value.
The system utilizes multi-container orchestration to ensure service isolation and network security.
-
Environment Initialization: Clone the repository and initialize the configuration file:
git clone https://github.com/AnmolM-777/crypto-wallet-analyzer.git cd crypto-wallet-analyzer cp .env.example .env -
Credential Provisioning: Input valid API credentials into the
.envfile:GOLDRUSH_API_KEY: Required for primary data ingestion.TATUM_API_KEY: Required for secondary failover protocols.
-
System Launch: Execute the container build and orchestration command:
docker compose up -d --build
-
Verify Services:
docker compose ps curl http://localhost:5000/health # Backend curl http://localhost:8000/health # Python server # Frontend: http://localhost:3000
For the complete Docker workflow (rebuilds, troubleshooting, MongoDB management), see the Docker Runbook.
- Persistence Layer: Ensure MongoDB 7.1+ is operational on
localhost:27017. - Analytical Engine:
cd python-server && pip install -r requirements.txt && python main.py
- Gateway Service:
cd backend && npm install && npm run dev
- Interface:
cd frontend && npm install && npm run dev
| Feature | Implementation | Operational Benefit |
|---|---|---|
| Network Coverage | 200+ Blockchain Protocols | Universal Data Ingestion |
| Data Recency | Real-time Synchronization | Live Forensic Updates |
| Resiliency | Dual-API Failover (GoldRush/Tatum) | 99.9% Data Availability |
| Architecture | Microservices Architecture | Horizontal Scalability |
| Analytical Mode | Heuristic + Machine Learning | High-Precision Classification |
| Design System | VaultOS (Institutional Grade) | Professional-grade Data Visualization |
The CWRA platform is engineered to meet financial monitoring SLOs (Service Level Objectives).
- Transaction Ingestion: Capable of processing 1,000+ entries per minute per worker.
- API Response Latency:
- Cached Analysis Retrieval: < 500ms.
- Real-time Deep Scan (Sync Required): 2-15 seconds depending on transaction depth (Max 25 pages/1250 transactions).
- Database Scalability: Optimized for 10M+ transaction records using shard-ready compound indexing.
- Internal Microservice Latency: < 50ms across the internal Docker network.
- CORS Protection: Enforced Cross-Origin Resource Sharing policies ensure only authorized frontends can interface with the API.
- Failover Redirection: The system implements an automated primary-fallback redirection from Covalent to Tatum infrastructure in the event of API output error or service outages.
- Idempotent Ledgering: All database write operations utilize a hash-based upsert logic, ensuring that transaction duplication does not occur during re-sync events, preserving statistical accuracy.
- Input Sanitization: All wallet addresses and chain identifiers are validated against strict regex patterns before being processed.
- AMC (Asset Macro Concentration): A measure of how much of a wallet's total value is held in one asset class or asset type.
- AML (Anti-Money Laundering): Legal and technical processes used to prevent the illegal generation of income.
- Gini Coefficient: A statistical measure of distribution representing the inequality of capital flow values within a wallet.
- HHI (Herfindahl-Hirschman Index): A metric of counterparty concentration, identifying if a wallet is exclusively interacting with a small number of entities.
- Idempotent Ingestion: Logic ensuring multiple sync events do not duplicate transaction records.
- KYT (Know Your Transaction): Forensic practice of monitoring transactions for financial crime.
- Net Flow: The absolute numerical difference between the total volume of assets entering and exiting the address.
- SNE (Statistical Normalization Engine): The proprietary logic used to standardize blockchain data across different L1/L2 networks.
- Sybil Attack: An exploit where a user creates multiple pseudonymous identities to gain disproportionate influence or rewards.
- Whale: A high-net-worth entity whose large transaction volume significantly impacts market liquidity.
- Gas: The unit of measurement for computational effort required to execute transactions.
- MEV (Maximal Extractable Value): Value extracted from users by reordering or inserting transactions within blocks.
- Burner Wallet: A temporary wallet used for short-term operations to obfuscate identities.
- Chain Gap: The temporal or block-height difference between disparate L1/L2 network states.
Developed by Group 24 of the IIT Jodhpur Software Engineering Department as a foundational project for the CSE302 syllabus.
- Raghav Maheshwari: Principal System Architect (Architecture, API Gateway, Orchestration).
- Anmol Mishra: Lead Data Systems Engineer (Data Engineering, API Integration, Persistence).
- Anhad Singh: Senior Analytical Developer (Mathematical Heuristics, ML Scoring, Risk Engine).
- Vijna Maradithaya: Reliability and QA Engineer (Optimization, Security, Automated Deployment).
| Issue | Potential Root Cause | Resolution Protocol |
|---|---|---|
| Synchronization Failure | Invalid or Rate-limited API Keys | Verify .env credentials and quota status. |
| Internal Communication Error | Docker Network Resolution Failure | Restart orchestration; ensure python-server is accessible. |
| Database Bottlenecks | Missing or Corrupt Indices | Execute db.collection.createIndex() for missing txHash indices. |
| OOM in Python Server | Extremely Deep Forensic Scans | Increase container memory allocation in docker-compose.yml. |
- User action via Institutional Interface.
- Backend validates address regex and chain identifier.
- Ingestion layer fetches transactions from blockchain indexer (Covalent or Tatum).
- Data is normalized and committed to MongoDB using idempotent upsert logic.
- Analytical Engine computes forensic risk indices (HHI, Gini) and ML score.
- Scores are aggregated, flagged with heuristic alerts, and returned to the user.
src/app.js: Application entry point; initializes middleware including CORS, body-parser, and global error handling.src/controllers/wallet.controller.js: Primary request orchestrator. Executes analysis triggers, synchronization monitoring, and data aggregation for the frontend.src/services/goldrush.service.js: The primary data acquisition layer for EVM-compatible chains. Implements block-height cursors and paginated fetch logic.src/services/tatum.service.js: Provides the failover capabilities and access to non-EVM blockchain data for holistic entity monitoring.src/services/ledger.service.js: The core data normalization logic. Handles complex mapping from blockchain payloads to the CWRA Internal Forensic Ledger.src/services/python.service.js: Manages the cross-service bridge to the analytical engine via secure HTTP calls across the internal network.src/models/wallet.model.js: Defines the Mongoose schema for entity metadata, specifically tracking blockchain ID and synchronization status.src/models/ledgerEntry.model.js: Defines the Mongoose schema for individual transaction records; ensures global uniqueness via composite hash indexing.
app/main.py: FastAPI entry point; defines the high-performance endpoints for risk scoring and data standardisation.app/processors/risk_engine.py: The computational heart of the system. Implements the heuristic logic ruleset and 60:40 blended scoring model.app/processors/normalization.py: Statistical preprocessing logic for standardizing asset values (Wei, Satoshis) into forensic decimals.app/db/mongo.py: High-performance Pymongo interface for persisting analysis results directly from the analytical processing layer.
src/services/api.ts: The Axios abstraction layer. Enforces strict TypeScript interfaces on all gateway interactions.src/pages/Dashboard.tsx: High-density oversight center. Renders real-time risk profiles and interactive data visualizations.src/pages/WalletsComparison.tsx: Theoretical Benchmarking module. Supports dual-entity forensic side-by-sides with risk disparity alerting.src/pages/PastAnalyses.tsx: Forensic persistence view. Allows users to retrieve and filter any historic scan from the system database.
- Add the protocol identifier to the
EVM_CHAINSorNON_EVM_CHAINSarrays inbackend/src/services/ledger.service.js. - Update the
python-servernormalization logic if the new chain utilizes a non-account-based model (e.g., UTXOs). - Validate ingestion by running a scan in the staging environment.
- Formally define the new deterministic rule in Section 2 of this document.
- Implement the conditional logic in
python-server/app/processors/risk_engine.py. - Map the new risk flag to the frontend Dashboard alert panel.
- CPU: Dual-core x86_64 or ARM64 processor (2.0 GHz+).
- Memory: 4GB allocated to the Docker daemon. 8GB total memory for native execution.
- Storage: 10GB of SSD storage for ledger persistence.
- CPU: Quad-core x86_64 processor (Intel Xeon/Ryzen 7 or equivalent).
- Memory: 16GB ECC RAM for high-throughput concurrency.
- Storage: 50GB NVMe SSD with high IOPS for rapid database indexing.
- Network: Dedicated 1Gbps uplink for external blockchain data ingestion.
This software serves as a capstone implementation for the CSE302 (Software Engineering) curriculum at IIT Jodhpur. It specifically operationalizes core principles of:
- Object-Oriented Software Design: Solid modular service-oriented architecture using design patterns like Factory and Observer.
- Distributed Computing: Microservices topology and asynchronous job processing for non-blocking analysis.
- Pattern Recognition: Heuristic-ML hybrid models for forensic threat classification.
- Data Engineering: Large-scale NoSQL persistence and statistical normalization strategies.
- Phase 4: Real-time Liquidity Intelligence (Planning): WebSocket implementation for live transaction monitoring.
- Phase 5: DeFi Protocol Forensics (Proposed): Deep-dive analysis for specific protocols (Uniswap, Aave).
- Phase 6: Privacy Audit Integration (Concept): Support for ZK-proof (Zero-Knowledge) proof-of-solvency analysis.
- Caching Layer: Currently, all historical transactions are stored in MongoDB. A future iteration will integrate a Redis caching tier for sub-millisecond access to frequently analyzed wallets.
- Encryption at Rest: While the current setup is secure for local development, production environments should enable TDE (Transparent Data Encryption) for the transaction ledger.
- Rate Limit Elasticity: Future builds will implement dynamic rate limiting based on individual API provider quotas to maximize synchronization efficiency.
The staging environment is designed for internal QA and mathematical model validation. It utilizes a singular MongoDB instance and a shared analytical engine.
- Compute: 8-core CPU, 32GB RAM.
- Storage: 100GB SSD.
The production environment utilizes a distributed MongoDB cluster with active replication. Load balancers (e.g., Nginx) sit in front of the Node.js API Gateway to manage high concurrent user loads.
- Compute: 16-core CPU, 64GB RAM.
- Storage: 500GB NVMe SSD (Raid 10).
Institutional Framework Licensing: MIT License. Copyright 2026 IIT Jodhpur. This project is provided "as is" for academic and professional blockchain research purposes.
""