Routes transactions through liquidity pools when bank servers go down.

---

The Problem

Bank server outages cause failed transactions and lost revenue. When SBI goes down for 30 minutes during peak hours, millions of payments fail. There's no automatic fallback — users just see an error.

The Solution

NexusFlow monitors bank availability in real time and automatically reroutes payments through blockchain liquidity pools when a bank is unreachable. When the bank recovers, outstanding debts are settled back on-chain — no manual intervention needed.

Think of it as a payment rail with a backup parachute.

---

Architecture

                         ┌──────────────────┐
                         │  Bank Simulator   │
                         └────────┬─────────┘
                                  │ HTTP poll (5s)
                                  ▼
┌───────────────┐    Kafka    ┌──────────────────────┐
│   Agent 1     │────────────▶│   Agent 2             │
│  Bank Monitor │ bank_status │  Transaction Router   │──▶ FastAPI
└───────────────┘             └──────────┬────────────┘
                                         │
                               ┌─────────▼──────────┐
                               │   Agent 3           │
                               │  Liquidity Optimizer│──▶ LangGraph
                               └─────────┬──────────┘
                                         │
                               ┌─────────▼──────────┐
                               │  React Frontend     │
                               │  (Vite + TypeScript)│──▶ MetaMask
                               └────────────────────┘

---

How It Works

1. Bank Monitoring (Agent 1)

Continuously polls bank APIs for availability. Publishes status events (up / down) for SBI, Axis Bank, and ICICI to Kafka topics — enabling sub-second failover decisions.

2. Transaction Routing (Agent 2)

The core decision engine. Listens for bank status updates and incoming payment requests from Redis:

• Bank is UP → process normally through the banking rail
• Bank is DOWN → call fallbackPayWithCrossPools() on-chain to route through liquidity pools
• Bank recovers → automatically settles outstanding debts back on-chain

3. Liquidity Optimization (Agent 3)

Calculates dynamic credit scores using a multi-factor pipeline:

• Staking amount — total tokens locked in the pool
• Debt ratio — outstanding vs. available liquidity
• Pool diversification — spread across multiple regional pools

Adjusts collateral requirements in real time based on pool health.

4. Smart Contracts (Solidity)

Contract	Purpose
PoolFactory	Deploys and tracks regional liquidity pools
LiquidityPool	Manages staking, fallback payments, debt, and rewards
LPERC20	LP token for pool share tracking
SimpleStakingToken	ERC20 token used for staking

5. Frontend (React + Vite + TypeScript)

• Connect MetaMask wallet
• View pools with live TVL and APY stats
• Stake tokens and earn rewards
• Initiate fallback payments when banks are down
• Repay on-chain debts
• Manage portfolio across pools

---

Quick Start

Prerequisites

• Node.js 18+
• Python 3.8+
• Docker & Docker Compose
• MetaMask browser extension

One-Click Launch

# Clone and set up
git clone https://github.com/N-S8990/Nexusflow.git
cd Nexusflow
cp .env.example .env

# Compile smart contracts
cd truffle-project && truffle compile && cd ..

# Install frontend dependencies
npm install

# Launch everything
docker-compose up --build

Individual Services

# Terminal 1: Bank Monitor
python agent1/agent.py

# Terminal 2: Transaction Router (FastAPI)
uvicorn agent2.agent:app --port 8000

# Terminal 3: Liquidity Optimizer
python agent3/agent.py

# Terminal 4: Frontend
npm run dev

---

Tech Stack

Layer	Technologies
Frontend	React 19, TypeScript, Vite, Tailwind CSS
Smart Contracts	Solidity 0.8.19, Truffle
Agents	Python, FastAPI, LangGraph
Messaging	Apache Kafka, Redis
Infrastructure	Docker, Docker Compose

---

Key Decisions & Trade-offs

Decision	Why	Trade-off
Kafka over RabbitMQ	Needed ordered event streaming for bank status	Higher operational complexity
LangGraph for credit scoring	Multi-factor scoring with conditional logic	Added dependency
Truffle over Hardhat	Faster prototype iteration	Less mature testing ecosystem
Redis for request queuing	Sub-ms latency for payment routing	In-memory = data loss risk on crash

---

What I Learned

• Event-driven architecture — designing agents that communicate through Kafka topics rather than direct calls
• Blockchain integration — writing Solidity contracts that interact with off-chain systems
• Failover systems — building automatic fallback logic that's transparent to end users
• Multi-agent coordination — managing state across independent services

---

What's Next

• Migrate to Hardhat with automated test suite
• Cross-pool liquidity rebalancing
• Production-grade error handling and retry logic
• Real bank API integration (replacing simulator)
• Circuit breaker pattern for agent health monitoring

---

Status

Working prototype — core payment fallback flow is functional: bank monitoring → transaction routing → pool fallback → debt recovery. Pool optimization logic is basic; contracts need a proper test suite before production deployment.

---

Built by Nirav Sayanja · NIT Rourkela

If bank servers won't be reliable, payments should be.