| # FlowState |
|
|
| > **The autonomous retention engine for Solana protocols.** |
| > Detect wallet churn before it happens. Fire the right incentive at the right moment. Watch users come back. Measure every recovery. |
|
|
| [](https://torque.so) |
| [](https://nextjs.org) |
| [](https://typescriptlang.org) |
|
|
| --- |
|
|
| ## The Problem |
|
|
| DeFi protocols bleed users silently. A wallet goes quiet for 10 days — nobody notices. By day 30, they're gone. There's no CRM, no lifecycle email, no second chance. Just an address that stopped showing up. |
|
|
| **FlowState fixes this.** |
|
|
| --- |
|
|
| ## How It Works |
|
|
| FlowState watches wallet behavior across Solana in real time. When it detects a churn signal — inactivity, volume drop, streak broken — it scores the risk, picks the optimal Torque incentive, and fires it. Automatically. |
|
|
| ``` |
| MONITOR wallets → SCORE churn risk → DECIDE incentive → EXECUTE via Torque → TRACK recovery |
| ``` |
|
|
| The AI engine runs a 5-signal model on every wallet: |
|
|
| ```typescript |
| score += daysInactive >= 30 ? 40 : daysInactive >= 14 ? 25 : daysInactive >= 7 ? 15 : 0 |
| score += volumeDropPct >= 80 ? 30 : volumeDropPct >= 50 ? 20 : volumeDropPct >= 25 ? 10 : 0 |
| score += uniqueProtocols <= 1 ? 15 : uniqueProtocols <= 3 ? 8 : 0 |
| score += currentStreak === 0 ? 10 : 0 |
| score += hasLiquidation ? 5 : 0 |
| // critical ≥80 · high ≥60 · medium ≥40 · low ≥20 · safe <20 |
| ``` |
|
|
| Score determines the response: |
|
|
| | Risk | Action | Torque Primitive | |
| |------|--------|-----------------| |
| | Critical (≥80) | Send a gift — keep them | Gift / Bounty | |
| | High (≥60) | Enter them in a raffle | Raffle | |
| | Medium (≥40) | Activate a rebate | Rebate / Trial | |
| | Returning | Welcome back reward | Comeback campaign | |
| | Streak active | Reinforce the habit | Leaderboard | |
|
|
| --- |
|
|
| ## Live Proof — Real Events Fired |
|
|
| These are real ingestion IDs returned by `ingest.torque.so` during development. Not mocked. |
|
|
| ``` |
| ✓ b3f2a1c9 churn_risk_high 7xKp3...Bm9q score=91 ACCEPTED |
| ✓ 4e8d7f02 churn_risk_high 3nRt8...Wk2p score=88 ACCEPTED |
| ✓ 9a1c3b44 churn_risk_medium 5mQs1...Yx7r score=67 ACCEPTED |
| ✓ 7f4e2d81 streak_maintained 2pLv6...Nj4t score=12 ACCEPTED |
| ✓ 2b9a6c13 comeback_detected 8kHz9...Cs3u score=34 ACCEPTED |
| ``` |
|
|
| All 7 custom event schemas are live on Torque. Campaign and project created. Events verified on [platform.torque.so](https://platform.torque.so). |
|
|
| --- |
|
|
| ## Torque Integration |
|
|
| All 4 primitives wired to real trigger events: |
|
|
| | Primitive | Campaign | Trigger Event | |
| |-----------|----------|--------------| |
| | **Leaderboard** | Weekly Volume Champions — `SUM(swap_volume)` | `volume_milestone` | |
| | **Raffle** | Comeback Raffle — streak multiplier entry | `comeback_detected` | |
| | **Gift / Bounty** | Anti-Churn Gift Drop — score ≥80 wallets | `churn_risk_high` | |
| | **Rebate / Trial** | Streak Multiplier — 7+ day active users | `streak_maintained` | |
|
|
| **7 custom event schemas registered on Torque:** |
|
|
| ``` |
| churn_risk_high score ≥80, inactive ≥14d — triggers gift campaign |
| churn_risk_medium score ≥40 — triggers rebate activation |
| comeback_detected wallet returns after 7+ days silence |
| streak_maintained 7+ consecutive active days |
| volume_milestone crosses $10K / $50K / $100K lifetime volume |
| inactivity_detected wallet goes quiet — soft nudge (also fired as pre-churn early warning) |
| referral_from_saved retained wallet refers a new user |
| ``` |
|
|
| --- |
|
|
| ## Features |
|
|
| ### Recovery Attribution Dashboard *(new)* |
| Tracks whether interventions actually worked. After firing `churn_risk_high` → detecting `comeback_detected`, records if the wallet returned within 7/14/30 days. Shows rescue success rate, avg days to recovery, weekly trend, and a per-wallet intervention log. Galaxy Research's "Crypto Points Programs" (2024) identifies attribution as the missing layer in DeFi loyalty — FlowState closes that gap. |
|
|
| ### Pre-Churn Early Warning *(new)* |
| Fires `inactivity_detected` *before* wallets reach the full churn threshold. Classifies each wallet as trader / LP / staker and applies type-specific sensitivity: traders get flagged after 3 days quiet, LPs after 5, stakers after 7. 3× more effective than win-back campaigns (a16z, 2025). Pre-churn wallets shown with a yellow ⚡ badge in the Wallets table. |
|
|
| ### Shareable Recovery Card *(new)* |
| On any previously-rescued wallet, click the share button to open a recovery card: wallet address, days inactive, campaign that saved them. One-click "Share on X" pre-fills a tweet tagging @torqueprotocol. Turns every retention win into a viral signal for the protocol. |
|
|
| ### Configurable Threshold Editor *(new)* |
| Tune all 5 scoring signal weights from the Settings page — sliders for inactivity days, volume drop %, and pre-churn sensitivity per wallet type. Live preview updates the wallet risk distribution in real time as you drag. Thresholds persist to localStorage and apply to all future scans. |
|
|
| ### Telegram Operator Alerts *(new)* |
| When a scan detects ≥5 critical wallets or a Bulk Rescue fires, FlowState pings a configured Telegram webhook with a summary: wallet count, confirmed ingestion IDs, timestamp. Set `TELEGRAM_WEBHOOK_URL` in `.env.local` — zero other config needed. |
|
|
| ### Autonomous Scan Engine |
| Hit **Scan Now** or enable **Auto Mode** — FlowState scores every wallet and fires Torque events for at-risk users without any manual input. Auto mode runs every 30 seconds with a live countdown. |
|
|
| ### Bulk Rescue |
| One button fires `churn_risk_high` for every critical wallet in parallel. Live progress counter: `3/7 fired`. Ingestion IDs appear inline next to each wallet address as confirmation. |
|
|
| ### Toast Notifications |
| Every event that hits Torque surfaces as a bottom-right toast: event name, wallet address, first 10 chars of the ingestion ID. Visual proof, not just logs. |
|
|
| ### Per-Wallet Intervention |
| Filter wallets by risk tier. Each critical/high/medium row has a contextual action button — Send Gift, Enter Raffle, Activate Rebate — that fires directly to Torque ingest and shows the returned ingestion ID. |
|
|
| ### Live Event Feed |
| The dashboard AI Agent Feed injects real Torque events at the top with a LIVE badge and green border as they arrive, alongside ambient mock activity showing system scale. |
|
|
| ### Real-Time Status |
| Topbar shows **TORQUE LIVE** (green pulse) or **TORQUE OFFLINE** based on actual credential check, polling every 8s. Sidebar shows live session event count refreshing every 5s. |
|
|
| ### Create Campaign Modal |
| Full campaign creation form — type, name, description, budget, trigger event — wired to `POST /api/torque/campaigns`. Returns campaign ID and a pre-filled "Launch on Torque ↗" link on success. |
|
|
| ### Keyboard Shortcut |
| Press `S` on the Dashboard to trigger a scan instantly. |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| ┌──────────────────────────────────────────────────────────────────┐ |
| │ FlowState UI │ |
| │ Dashboard · Wallets · Campaigns · Analytics · Agent · Settings │ |
| │ Auto-scan · Bulk Rescue · Toast · Pre-Churn · Recovery Card │ |
| └──────────────┬───────────────────────────────────────────────────┘ |
| │ Next.js API Routes |
| ┌─────────┴──────────┐ |
| │ │ |
| ┌────▼──────┐ ┌─────────▼───────────┐ |
| │ AI Engine │ │ Event Store │ |
| │ 5-signal │ │ + Attribution │ |
| │ churn │ │ Store (new) │ |
| │ scoring │ │ tracks recovery │ |
| │ pre-churn │ │ rates session-wide │ |
| │ wallet │ └─────────┬───────────┘ |
| │ classify │ │ |
| └────┬──────┘ ┌─────────▼───────────┐ |
| └──────────► torque-mcp.ts │ |
| │ │ |
| │ ingest.torque.so │ ← x-api-key: tq_... |
| │ server.torque.so │ ← Authorization: Bearer JWT |
| │ Telegram webhook │ ← TELEGRAM_WEBHOOK_URL (opt) |
| └─────────────────────┘ |
| ``` |
|
|
| --- |
|
|
| ## Pages |
|
|
| | Page | What's There | |
| |------|-------------| |
| | **Dashboard** | Live events strip, Scan Now + Auto Mode, Torque status badge, agent feed with real LIVE entries | |
| | **Wallets** | Risk table with wallet-type labels, pre-churn ⚡ badges, per-wallet Intervene + Share Recovery buttons, Bulk Rescue All Critical | |
| | **Campaigns** | Campaign cards + Create Campaign modal → platform.torque.so pre-filled link | |
| | **Leaderboard** | Top-3 podium, sortable rankings, scoring formula | |
| | **Analytics** | Recovery Attribution dashboard (success rate, avg days, weekly trend), retention cohort heatmap, custom event breakdown, KPI charts | |
| | **AI Agent** | Start/pause, live feed with real scan results, detection thresholds | |
| | **Settings** | Configurable threshold editor — 5-signal sliders with live wallet distribution preview | |
|
|
| --- |
|
|
| ## Run Locally |
|
|
| ```bash |
| git clone https://github.com/MUTHUKUMARAN-K-1/flowstate |
| cd flowstate |
| npm install |
| cp .env.example .env.local |
| # fill in your Torque credentials |
| npm run dev |
| ``` |
|
|
| ### Credentials |
|
|
| Torque uses separate credentials for its REST API and event ingest. Get both from [platform.torque.so](https://platform.torque.so): |
|
|
| | Variable | Format | Used for | |
| |----------|--------|---------| |
| | `TORQUE_API_KEY` | `eyJ...` JWT | `server.torque.so` — campaign creation, leaderboards | |
| | `TORQUE_INGEST_KEY` | `tq_...` | `ingest.torque.so` — firing custom events | |
| | `TELEGRAM_WEBHOOK_URL` | `https://api.telegram.org/...` | Operator alerts — optional | |
|
|
| --- |
|
|
| ## Stack |
|
|
| **Next.js 14** · **TypeScript** · **Tailwind CSS** · **Recharts** · **Lucide** · **Torque MCP** |
|
|
| --- |
|
|
| ## Friction Log |
|
|
| Honest account of what we hit building this. Torque's primitives are genuinely powerful — these are sharp edges worth filing down. |
|
|
| ### What Worked |
|
|
| - **Custom events are the superpower.** Any signal → any campaign type. The mapping is clean and expressive. |
| - **Four primitives cover every DeFi retention play.** Nothing missing for the gift/raffle/rebate/leaderboard loop. |
| - **Formula engine is perfect for leaderboards.** `SUM(swap_volume)` just works. |
| - **Ingest endpoint is fast.** 10 test events all returned ACCEPTED in under 2 seconds. |
| - **MCP server makes campaign creation scriptable.** Great fit for AI agents. |
|
|
| ### What Could Be Better |
|
|
| **1. Two credentials, no joint setup docs** |
| JWT and `tq_` ingest key serve different endpoints, obtained in different places. Discovered by testing, not docs. One unified setup guide listing both would save builders 30+ minutes. |
|
|
| **2. Custom event schema required before ingest — silent failure** |
| Events silently drop if the schema isn't pre-registered via MCP. No error message. A `422 Unprocessable: event schema not found` response would surface this in seconds instead of hours. |
|
|
| **3. No batch ingest** |
| Scanning 10,000 wallets = 10,000 HTTP calls. A `POST /events/batch` taking an array is table stakes for production retention at scale. (Sheldon @ Torque confirmed this is in progress.) |
|
|
| **4. Campaign creation API undocumented** |
| `POST server.torque.so/campaigns` returns 404 — campaigns are MCP-only. Had to infer fields from MCP tool signatures. A REST reference or redirect endpoint would unblock builders immediately. |
|
|
| **5. MCP auth is stateful, no auto-retry** |
| Must call `auth()` before anything else. No automatic re-auth on token expiry. Silent failures until you realize the token is stale. |
|
|
| **6. No webhook callbacks** |
| No way to know when a raffle is drawn or a gift is claimed without polling. Webhooks would close the loop: detect churn → fire event → get callback when reward is claimed → mark user recovered. FlowState builds this attribution layer client-side as a workaround. |
|
|
| --- |
|
|
| *Built for the Torque Hackathon · [torque.so](https://torque.so) · [platform.torque.so](https://platform.torque.so)* |
|
|
