Luqifi

# Liquifi Protocol

> Transform future revenue into instant capital

AI-powered invoice factoring and revenue streaming protocol built on Mantle L2

---

## 🎯 The Problem

$10 trillion is trapped in unpaid B2B invoices globally.

Small and medium businesses face a critical cash flow problem:

- Invoice payment terms: 30-60 days standard

- Traditional invoice factoring: 15-30% APR

- Limited access to affordable working capital

- High fees drain business profitability

Example: A SaaS company earning $50,000/month waits 60 days to get paid. If they need cash now, traditional factoring costs $10,000 annually—just to access their own money.

---

## 💡 The Solution

Liquifi brings invoice factoring on-chain with AI-powered risk management and real-time streaming payments.

### How It Works

1. Tokenize Revenue

- Businesses mint ERC-20 RevenueTokens backed by future cashflows

- Each token represents expected revenue over a specific period

2. AI Risk Scoring

- FastAPI service analyzes revenue stability, payment history, volatility

- Generates deterministic risk score (0-100) in <500ms

- Backend signs score with EIP-712, contracts verify on-chain

- Risk bands: LOW (75+), MEDIUM (55-74), HIGH (<55)

3. Instant Liquidity

- Investors deposit stablecoins into risk-banded YieldPools

- Businesses receive immediate capital (up to 80% LTV)

- Pool capacity adjusts based on risk: LOW=120%, MEDIUM=90%, HIGH=60%

4. Stream Repayments

- As customers pay invoices, revenue streams to YieldPool in real-time

- StreamEngine handles precise per-second payment distribution

- Each stream gets an on-chain NFT receipt with SVG metadata

5. Earn Yield

- Investors earn pro-rata from streamed revenue

- Target APY: 8-12% from real business cashflows

- YieldBackedTokens represent pool shares (ERC-20)

### Value Proposition

| Stakeholder | Benefit |

|-------------|---------|

| Businesses | Get capital 60% cheaper than traditional factoring |

| Investors | Earn 8-12% APY from real-world revenue streams |

| Protocol | Capture fees from transaction volume |

---

## 🏗️ Technical Architecture

### Smart Contracts (Solidity 0.8.30)

Core Contracts:

- StreamEngine - Multi-token streaming with pause/resume/extend/topup

- YieldPool - Share-based yield vault with risk-gated capacity

- RevenueTokenFactory - Factory for creating business revenue tokens

- RiskOracleAdapter - EIP-712 signature verification for AI scores

- StreamVault - Escrow with yield strategy hooks

- StreamDescriptor - On-chain SVG NFT metadata generator

- YieldBackedToken - ERC-20 pool shares

Supporting Contracts:

- LockingStreamVault - Time-locked escrow variant

- MockUSDT - Test token for demonstrations

- StreamManager (legacy) - Original monolithic implementation

- RevenueToken - Individual business token implementation

- YieldPoolFactory - Factory for creating new yield pools

Total: 12 contracts, ~2,500 lines of code

### Frontend (React + TypeScript)

Tech Stack:

- React 18 with TypeScript

- Vite for build tooling

- Wagmi v2 + Viem for Web3 interactions

- TailwindCSS + shadcn/ui components

- Recharts for data visualization

- Framer Motion for animations

Key Features:

- Business Dashboard /business)

- Company registration with profile management

- One-click AI risk score refresh

- Revenue token minting interface

- Active streams visualization with NFT cards

- Real-time stream status updates

- Investor Dashboard /investor)

- YieldPool browser with filtering

- Metrics display: APY, TVL, risk bands, capacity

- Deposit/withdraw interface

- Portfolio tracking with yield history

- Transaction history

- Legacy Console /legacy-console)

- Advanced stream management

- Batch operations support

- Developer tools for testing

### Backend (Node.js + Express)

Responsibilities:

- Business registration and profile storage (JSON file-based)

- AI service integration for risk scoring

- EIP-712 signature generation for risk payloads

- Pool metrics aggregation

- CORS handling for frontend

API Endpoints:

- POST /api/business/register - Register new business

- GET /api/business/:address - Fetch business profile

- GET /api/business/:address/risk-score - Get cached or fresh AI score

- POST /api/risk-oracle/sign - Generate signed risk payload

- GET /api/pools/:address/metrics - Retrieve pool statistics

### AI Service (FastAPI + Python)

Risk Scoring Algorithm:

```python

base_score = 50

score += min(revenue / 10000, 30) # Revenue factor (max +30)

score -= min(volatility * 100, 20) # Volatility penalty (max -20)

score -= missed_payments * 5 # Payment history penalty

score += 5 if verified else 0 # Verification bonus

```

Risk Bands:

- LOW: 75-100 (Pool capacity: 120% of revenue tokens)

- MEDIUM: 55-74 (Pool capacity: 90%)

- HIGH: 0-54 (Pool capacity: 60%)

Performance:

- Response time: <500ms

- Deterministic scoring (same inputs = same output)

- Stateless design for horizontal scaling

---

## 🚀 Deployment

### Live Testnet Deployment (Mantle Sepolia)

| Contract | Address | Explorer |

|----------|---------|----------|

| StreamEngine | 0x60bd590bc841D8558B279F064459a91Afd0d6015 | [View →](https://explorer.sepolia.mantle.xyz/address/0x60bd590bc841D8558B279F064459a91Afd0d6015) |

| YieldPool | 0x9187487Bd77c200d7f1Fa798c797D1a6cC65627D | [View →](https://explorer.sepolia.mantle.xyz/address/0x9187487Bd77c200d7f1Fa798c797D1a6cC65627D) |

| RiskOracleAdapter | 0x49387C2bbF79348e80809eb534542E70ff139fEA | [View →](https://explorer.sepolia.mantle.xyz/address/0x49387C2bbF79348e80809eb534542E70ff139fEA) |

| RevenueTokenFactory | 0x6f0021c43d7b26A8058EC7880df807B65727A33E | [View →](https://explorer.sepolia.mantle.xyz/address/0x6f0021c43d7b26A8058EC7880df807B65727A33E) |

| Mock USDT | 0x5dB24867c863dE8262c12627381199556DF2d546 | [View →](https://explorer.sepolia.mantle.xyz/address/0x5dB24867c863dE8262c12627381199556DF2d546) |

Frontend: [stream-pay-mantle.vercel.app](https://stream-pay-mantle.vercel.app)

Test Flow:

1. Get testnet MNT from [Mantle Faucet](https://faucet.sepolia.mantle.xyz/)

2. Visit /business to register and mint revenue tokens

3. Visit /investor to deposit into yield pools

4. Watch real-time streaming in action

---

## 🎨 Key Innovations

### 1. On-Chain NFT Metadata

Every stream gets an ERC-721 receipt with 100% on-chain SVG metadata—no IPFS, no external storage.

Generated by StreamDescriptor contract:

- Stream ID, sender, recipient

- Token type (USDT/USDC/etc.)

- Amount, rate, duration

- Real-time status (Active/Paused/Inactive)

- Visual progress bar

### 2. EIP-712 Risk Verification

Off-chain AI scoring meets on-chain enforcement:

- AI service calculates risk score

- Backend signs payload with private key

- Contracts verify signature using ecrecover

- Invalid signatures = transaction reverts

- Prevents score manipulation

### 3. Multi-Token Streaming

StreamEngine supports any ERC-20 token:

- USDT, USDC, DAI, or custom tokens

- Per-second precision (±1 second accuracy)

- Gas-efficient batch operations

- Pause/resume/extend without recreating streams

### 4. Risk-Gated Pool Capacity

YieldPools dynamically adjust deposit limits based on risk:

```solidity

uint256 capacity = riskBand == LOW ? 120 :

riskBand == MEDIUM ? 90 : 60;

maxDeposit = (revenueTokenSupply * capacity) / 100;

```

### 5. Composable Architecture

Each contract has single responsibility:

- StreamEngine = streaming logic

- YieldPool = yield distribution

- RiskOracleAdapter = risk verification

- Easy to upgrade individual components

---

## 📊 Performance Metrics

| Metric | Value |

|--------|-------|

| Smart Contracts | 12 contracts, 2,500+ LOC |

| Test Coverage | 29 tests, 100% pass rate |

| Gas - Stream Creation | ~358k gas (~$0.01 on Mantle) |

| Gas - Claim | ~45k gas (~$0.0001) |

| Real-Time Precision | ±1 second |

| Frontend Load Time | <2 seconds |

| AI Scoring Latency | <500ms |

| Backend SLA | <60 seconds for signatures |

---

## 🧪 Testing & Quality Assurance

### Smart Contract Tests (Foundry)

```bash

cd contracts

forge test

```

Test Coverage:

- Stream lifecycle: create, claim, cancel, pause, resume, extend, topup

- Multi-token streaming across different ERC-20s

- Batch operations (create/claim/cancel multiple streams)

- Risk-gated pool capacity enforcement

- EIP-712 signature verification

- NFT metadata generation

- Yield distribution calculations

- Edge cases: zero amounts, expired streams, unauthorized access

Results: 29/29 tests passing

### Backend Tests

```bash

cd backend

npm test

```

Coverage:

- Business registration validation

- Risk score caching logic

- EIP-712 signature generation

- API error handling

### AI Service Tests

```bash

cd ai-service

PYTHONPATH=. pytest

```

Coverage:

- Risk scoring algorithm accuracy

- Input validation

- Edge cases (negative revenue, >100% volatility)

- Response time benchmarks

### Integration Tests

```bash

./test-integration.sh

```

End-to-End Flows:

- Business registers → AI scores → mints token → creates stream

- Investor deposits → stream completes → yield distributes

- Multi-user scenarios with concurrent streams

---

## 💎 Why Mantle L2?

### 1. Ultra-Low Transaction Costs

- Stream creation: ~$0.01 (vs $5+ on Ethereum mainnet)

- Claiming payments: ~$0.0001

- NFT minting: Included in stream creation cost

- Makes micro-payments and frequent streaming economical

### 2. Modular Architecture Benefits

Mantle's separation of execution, consensus, and data availability enables:

- Complex RealFi primitives composition

- Easy integration of off-chain AI with on-chain verification

- Scalability for enterprise payroll/invoicing volumes

### 3. Hackathon Theme Alignment

RealFi Focus:

- ✅ Real-world cashflows tokenized on-chain

- ✅ Solves actual $10T working capital problem

- ✅ Practical use case beyond DeFi speculation

AI Integration:

- ✅ AI risk scoring integrated with smart contracts

- ✅ EIP-712 verification bridges off-chain ML with on-chain trust

- ✅ Deterministic scoring ensures reproducibility

### 4. Performance at Scale

- Batch operations: Process 100+ streams in single transaction

- High throughput: Handle enterprise-level payment volumes

- Low latency: Real-time streaming with <1 second precision

---

## 🗺️ Roadmap & Future Plans

### Phase 1: MVP (Current - Hackathon Submission)

- [x] Core smart contracts deployed

- [x] AI risk scoring service

- [x] Business and investor dashboards

- [x] Testnet deployment on Mantle Sepolia

- [x] Documentation and demo materials

### Phase 2: Mainnet Launch (Q1 2026)

- [ ] Security audit (CertiK/Trail of Bits)

- [ ] Deploy to Mantle mainnet

- [ ] Integrate real stablecoins (USDT, USDC)

- [ ] Partner with 5-10 pilot businesses

- [ ] Liquidity mining incentives for early investors

### Phase 3: Ecosystem Growth (Q2-Q3 2026)

- [ ] Oracle integration (Chainlink/Band) for external revenue verification

- [ ] Multi-chain deployment (Arbitrum, Optimism, Base)

- [ ] Mobile app for on-the-go stream management

- [ ] API for third-party integrations (accounting software, ERPs)

- [ ] Institutional investor onboarding (treasuries, DAOs)

### Phase 4: Advanced Features (Q4 2026+)

- [ ] Credit scoring marketplace (sell risk assessments to other protocols)

- [ ] Secondary market for RevenueTokens

- [ ] Insurance pools for default protection

- [ ] Governance token for protocol decisions

- [ ] Cross-chain streaming via LayerZero/Wormhole

## 🎯 Market Opportunity

### Target Market Segments

Primary (Year 1):

- Crypto-native SaaS businesses ($50k-$500k MRR)

- Web3 service providers (dev shops, marketing agencies)

- DeFi protocols with subscription revenue

Secondary (Year 2-3):

- Traditional SMBs onboarding to Web3

- Freelancer collectives and DAOs

- E-commerce businesses with predictable revenue

Market Size:

- Global invoice factoring market: $3.5 trillion annually

- SMB working capital gap: $10+ trillion trapped

- Target capture: 0.1% = $3.5 billion TVL

### Competitive Advantages

| Feature | Liquifi | Traditional Factoring | DeFi Lending |

|---------|---------|----------------------|--------------|

| Interest Rate | 8-12% APR | 15-30% APR | 5-20% APR |

| Collateral | Revenue tokens | None/Personal guarantee | Crypto over-collateral |

| Settlement | Real-time streaming | 30-60 day batches | Instant liquidation |

| Transparency | On-chain, auditable | Opaque contracts | On-chain |

| Access | Permissionless (AI-gated) | Creditworthiness barrier | Crypto holdings barrier |

| Risk Management | AI + on-chain verification | Manual underwriting | Liquidation bots |

## 👥 Team

Martins O - Full-Stack Developer & Blockchain Engineer

- 5+ years Web2/Web3 development experience

- Tech stack: Solidity, Rust, TypeScript, Python, Java

- GitHub: [Martins-O](https://github.com/Martins-O)

## 🔗 Links

- Live Demo: [stream-pay-mantle.vercel.app](https://stream-pay-mantle.vercel.app)

- GitHub: [github.com/Martins-O/Liquifi](https://github.com/Martins-O/Liquifi)

- Contracts (Mantle Sepolia): See deployment table above

- Documentation: [/docs](./docs)

- Video Demo: [Coming soon]

---

## 🏆 Hackathon Submission Highlights

### Innovation ⭐⭐⭐⭐⭐

- First-of-its-kind: Combines streaming payments + tokenized revenue + AI risk + yield vaults

- On-chain NFTs: Stream receipts with SVG metadata generated entirely on-chain (no IPFS)

- EIP-712 Integration: Off-chain AI scores verified on-chain via cryptographic signatures

- Risk-gated liquidity: Dynamic pool capacity based on AI-assessed creditworthiness

### Technical Excellence ⭐⭐⭐⭐⭐

- Production-ready: 29 passing tests, CI/CD pipeline, comprehensive error handling

- Gas optimized: ~358k gas per stream on Mantle L2 (~$0.01)

- Full-stack: 12 Solidity contracts, React frontend, Node.js backend, Python AI service

- Documentation: 10+ detailed docs covering architecture, deployment, testing

- Live deployment: All contracts deployed and verified on Mantle Sepolia testnet

### Real-World Impact ⭐⭐⭐⭐⭐

- $10 trillion problem: Working capital trapped in B2B receivables globally

- Proven business model: Invoice factoring + payment streaming + DeFi yield

- Immediate value: 60% cost reduction vs traditional factoring

- Scalable: Architecture supports enterprise-level payment volumes

### Mantle L2 Integration ⭐⭐⭐⭐⭐

- Cost efficiency: Ultra-low fees make micro-streaming economical

- RealFi theme: Tokenizing real-world revenue streams on-chain

- AI integration: FastAPI risk service + EIP-712 on-chain verification

- Modular design: Composable primitives leverage Mantle's architecture

---

## 📜 License

MIT License - see [LICENSE](./LICENSE) for details.

---

## 🙏 Acknowledgments

- Mantle Network - For the L2 infrastructure and hackathon opportunity

- OpenZeppelin - For battle-tested smart contract libraries

- Foundry - For exceptional Solidity development tooling

- Wagmi/Viem - For Web3 frontend integration

- shadcn/ui - For beautiful component primitives

---

Built with 💧 for the Mantle Hackathon

Transform future revenue into instant capital

[Try the Demo →](https://liqui-fi.vercel.app/) | [Read the Docs →](./docs) | [View on GitHub →](https://github.com/Martins-O/Liquifi)