Flywheel

A non-custodial wallet and aggregated liquidity protocol. Users delegate assets to the Flywheel Wallet; the Flywheel Solver fulfills intents automatically using the Aggregated Liquidity Pool (user-delegated assets + Flywheel Treasury). Rewards from intent fulfillment are split 50% to Users and 50% to the Flywheel Treasury. User funds are always protected.

Source of truth for flows: .context/sequence-diagrams.md

Project Structure

Flywheel/
├── .context/              # Project-wide context; sequence-diagrams.md is canonical for flows
├── frontend/              # Flywheel Wallet UI (Next.js/React, TypeScript)
├── backend/               # ClearNode, Flywheel Solver, KMS (Node.js/TypeScript)
├── contracts/             # Smart contracts (Foundry) — Custody, Adjudicator
└── lif-rust/              # LiFi integration microservice (Rust, mocked in MVP)

Architecture Overview

Flywheel aligns with Yellow / Nitrolite (ERC-7824) for state channels and custody. When the liquidity layer can fulfill (pool has funds on the target chain), transfers are settled from the pool. The MVP runs on Sepolia and Base Sepolia with LiFi components mocked.

• Flywheel Wallet (App): User-facing app for delegate and withdraw. Users grant the Flywheel Solver permission via a Session Key (Yellow) so the Solver can fulfill intents without repeated signatures.
• ClearNode: Yellow Nitrolite session and state-channel coordination; real-time updates.
• Flywheel Solver: Fulfills intents using the Aggregated Liquidity Pool (LP + Treasury); registers credits; allocates rewards 50% Users / 50% Treasury.
• Aggregated Liquidity Pool: User-delegated assets + Flywheel Treasury. Pool liquidity is used for payouts when available.
• Flywheel Treasury: Receives 50% of intent-fulfillment rewards; part of available liquidity for the Solver; system owners may withdraw Treasury only—never user funds.

Core Technologies

• Yellow / Nitrolite (ERC-7824): State channels, Custody Contract, Adjudicator (conclude / transfer).
• Session Key (Yellow): One-time user grant (EIP-712) so the Solver can fulfill intents automatically (app-scoped, allowances, expiry).

MVP Scope

• Yellow / Nitrolite implemented on Sepolia and Base Sepolia (state channels, Custody, Adjudicator, ClearNode).
• LiFi system components mocked: No real LiFi API or solver integration.
• Goal: Validate delegation, deposit, pool fulfillment, reward split (50/50), and withdrawal.

Sub-Projects

Frontend (Flywheel Wallet)

Next.js/React UI for the Flywheel Wallet.

Tech Stack: TypeScript, React, Next.js, TailwindCSS

Key Features: Delegate to pool (Session Key grant), unified balance, withdraw, real-time updates via ClearNode.

Docs: frontend/.context/
Run: frontend/README.md

Backend

ClearNode, Flywheel Solver, and KMS.

Tech Stack: TypeScript, Node.js, PostgreSQL, Redis

Key Components: ClearNode (Nitrolite RPC/WebSocket), Flywheel Solver (intent fulfillment, pool), KMS (Session Keys), state persistence.

Docs: backend/.context/
Run: backend/README.md

Contracts

Custody and Adjudicator (Nitrolite/ERC-7824); user and Treasury asset security.

Tech Stack: Solidity, Foundry

Key Contracts: Custody (Nitrolite), Adjudicator (Nitro), Force Withdrawal escape hatch.

Docs: contracts/.context/
Run: cd contracts && forge build && forge test

lif-rust

LiFi API integration and intent/order encoding; mocked for MVP.

Tech Stack: Rust, Axum, Alloy

API: GET /health, POST /lifi/quote, POST /intent/build, POST /intent/calldata

Docs: lif-rust/README.md, lif-rust/ARCHITECTURE.md
Run: cd lif-rust && cargo run

Communication Matrix

From	To	Method
Frontend	Backend/ClearNode	WebSocket + RPC
Frontend	Contracts	JSON-RPC (viem/ethers)
Backend	lif-rust	REST (mocked)
Backend	Contracts	JSON-RPC

Security Model

• Non-custodial: Users retain control; Force Withdrawal via last signed state to Adjudicator.
• Session Key: App-scoped, allowances, expiry; Solver can only fulfill intents per user grant.
• User funds protected: Only Treasury may be withdrawn by system owners; user funds never used for owner withdrawals.
• Adjudicator: Validates off-chain state and on-chain payouts (conclude / transfer).

Documentation

• Flows (canonical): .context/sequence-diagrams.md
• Project context: .context/project-context.md
• Diagrams: .context/diagrams.md

Sub-projects have .context/ folders with role definitions, system design, tech stack, security, and testing.

License

TBD