Full README with project documentation
Browse files
README.md
CHANGED
|
@@ -7,6 +7,50 @@ sdk: static
|
|
| 7 |
pinned: false
|
| 8 |
---
|
| 9 |
|
| 10 |
-
# FlowState
|
| 11 |
|
| 12 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7 |
pinned: false
|
| 8 |
---
|
| 9 |
|
| 10 |
+
# FlowState - AI-Powered Anti-Churn Engine for Solana
|
| 11 |
|
| 12 |
+
The autonomous retention layer for onchain protocols. Powered by Torque MCP.
|
| 13 |
+
|
| 14 |
+
## What It Does
|
| 15 |
+
|
| 16 |
+
FlowState monitors wallet activity across Solana, detects churn signals via a 5-signal AI scoring model, and autonomously fires Torque campaigns (gifts, raffles, rebates, leaderboards) to retain at-risk users.
|
| 17 |
+
|
| 18 |
+
**Flow:** MONITOR (Helius) -> DETECT (AI Scoring) -> DECIDE (Optimal Incentive) -> EXECUTE (Torque MCP) -> LEARN (Track Outcomes)
|
| 19 |
+
|
| 20 |
+
## Torque Integration
|
| 21 |
+
|
| 22 |
+
All 4 primitives used:
|
| 23 |
+
- **Leaderboards** - Weekly Volume Champions ranked by SUM(swap_volume)
|
| 24 |
+
- **Raffles** - Comeback Raffle with streak multipliers
|
| 25 |
+
- **Gifts** - Anti-Churn Gift Drop for critical-risk wallets
|
| 26 |
+
- **Rebates** - Streak Multiplier Rebate (7+ days = 2x)
|
| 27 |
+
|
| 28 |
+
7 custom event types: churn_risk_high, churn_risk_medium, comeback_detected, streak_maintained, volume_milestone, referral_from_saved, inactivity_detected
|
| 29 |
+
|
| 30 |
+
## Pages
|
| 31 |
+
|
| 32 |
+
- **Dashboard** - Live AI Agent feed, KPI stats, protocol performance table
|
| 33 |
+
- **Leaderboard** - Top 3 podium, sortable rankings, scoring formula
|
| 34 |
+
- **Campaigns** - Campaign cards with type badges, AI vs manual, performance metrics
|
| 35 |
+
- **Analytics** - Retention cohort heatmap, custom events breakdown, KPIs
|
| 36 |
+
- **Wallets** - Risk scoring, filterable table, streak tracking
|
| 37 |
+
- **AI Agent** - Start/pause, live feed, config panel, architecture diagram
|
| 38 |
+
|
| 39 |
+
## Run Locally
|
| 40 |
+
|
| 41 |
+
```
|
| 42 |
+
git clone https://huggingface.co/spaces/muthuk1/flowstate
|
| 43 |
+
cd flowstate && npm install && npm run dev
|
| 44 |
+
```
|
| 45 |
+
|
| 46 |
+
## Tech Stack
|
| 47 |
+
|
| 48 |
+
Next.js 14, TypeScript, Tailwind CSS, Recharts, Lucide, Zustand, Torque MCP
|
| 49 |
+
|
| 50 |
+
## Friction Log
|
| 51 |
+
|
| 52 |
+
**Worked Well:** Torque primitives map perfectly to retention. Custom events are the superpower. Formula engine is ideal for leaderboards.
|
| 53 |
+
|
| 54 |
+
**Could Improve:** MCP server discovery needs prominent docs link. Batch event API for 100K+ wallets. Campaign templates for common patterns. Webhook callbacks on campaign events.
|
| 55 |
+
|
| 56 |
+
Built for the Torque Hackathon Track
|