FREE FLOW

Free Flow — a social, gamified DeFi world on Flow

Free Flow is an interactive, 2D multiplayer experience that turns the Flow blockchain into a living social space. Set against an NYC–skyscraper backdrop, players explore a pixel-art world, see each other move in real time, chat via emotes or voice, and interact with on-chain DeFaI Agents (AI-powered stalls) to do DeFi actions naturally—no command lines, no arcane UIs.

What it is (plain English)

Think “Gather Town meets DeFi on Flow.” You walk up to stalls in a shared 2D world and talk to AI agents like you would a vendor: • “What’s the price of FLOW?” • “Swap USDC → FLOW with 1% max slippage.” • “Stake my tokens and show my rewards.”

The agent understands your request (text or voice), prepares the exact on-chain transaction, and you still sign it from your wallet—keeping full control of funds.

Why it matters

DeFi is powerful but intimidating. Free Flow lowers the barrier by: • Wrapping DeFi in a familiar, playful environment. • Using conversational AI for intent → transaction building. • Keeping everything transparent and user-sovereign: nothing executes without your approval.

Key features • Multiplayer arena: Real-time avatars, usernames, and emotes powered by Socket.io; create or join rooms via short codes for friends/teams. • Interactive stalls (DeFaI Agents): Conversational agents for price checks, swaps, staking, and help. Walk up, speak/type, review the prepared action, sign, done. • Voice in / Voice out: Browser speech recognition for commands; ElevenLabs TTS for natural audio responses. • NYC vibe: Ambient audio and skyscraper-themed scenes for an inviting, game-like feel.

How it works (high level) 1. Explore: Arrow keys to move; proximity prompts appear near stalls. 2. Ask: Speak (Spacebar) or type your intent (e.g., “swap 50 USDC to FLOW”). 3. Plan: The GOAT SDK interprets the request and composes a safe transaction with guardrails (slippage, deadlines). 4. Sign: The dapp shows a human-readable summary; you confirm in your wallet (Privy + Wagmi/Viem). No signature = no action. 5. Confirm: On-chain receipt is linked; TTS can read back results.

Tech stack • Blockchain: Flow (EVM runtime for fast integration; Cadence support is planned for native resources/NFTs). • Frontend: Next.js + TypeScript. • Realtime: Socket.io for multiplayer sync (movement, rooms, emotes). • AI layer: GOAT SDK for tool-use orchestration; token-swap and Coingecko plugins for on-chain and market data actions; ElevenLabs for speech. • Wallet/Auth: Privy for onboarding; Wagmi/Viem for Flow EVM RPC and contract calls.

Contracts & deployment • Flow Testnet (Chain ID 545): Contract address TBD • Flow Mainnet (Chain ID 747): Contract address TBD

Initial agents target Flow EVM contracts (Solidity) for rapid hackathon delivery. The roadmap adds Cadence contracts for resource-oriented assets (e.g., avatar/NFT badges, room passes) and advanced Flow features (account abstraction, sponsored tx).

Security & UX principles • User-sovereign by design: AI agents can only prepare transactions; users must sign. • Safety rails: Min-out, deadlines, and network-aware routing; clear pre-tx summaries; explorer links post-tx. • Privacy-friendly: No custody of keys; no background actions.

What’s novel • DeFi as a place, not a page: Spatial, multiplayer UX makes on-chain activity social and fun. • Voice-driven intents → transactions: Natural language + tool calling reduces cognitive load. • Flow-first experience: Leverages Flow’s low fees and fast finality; EVM compatibility enables instant Solidity reuse, with a path to Cadence-native gameplay assets.

Roadmap • More agents: Lending/borrowing, yield strategy explorer, portfolio coach. • Cadence assets: In-world collectibles/passes (resource-oriented), social badges. • Events & quests: Group missions that teach DeFi concepts through play. • Creator stalls: Let protocols or communities deploy branded agents inside Free Flow.

Free Flow makes decentralized finance approachable, social, and delightful—bringing the next wave of users to on-chain experiences through play.

System architecture (bird’s-eye) • Client (Next.js + TypeScript): Renders the 2D world, handles wallet auth, speech I/O, and calls the Agent API. • Realtime server (Node + Express + Socket.io): Keeps everyone in sync (positions, emotes, room codes) and brokers low-latency messages. • Agent API (same Node app): A POST /message endpoint that runs an AI tool-using loop (GOAT SDK + OpenAI) and returns a natural-language response plus any tool results. • On-chain layer (Flow EVM first): Solidity contracts deployed to Flow EVM (Testnet/Mainnet). Frontend talks to them via wagmi/viem, using addresses/ABIs from constants.ts. • Speech layer: Browser Speech Recognition for input; ElevenLabs TTS for lifelike responses.

⸻

Frontend & world simulation • Next.js + TS for app shell, routing, and performance (SSR where helpful). • Canvas/grid movement: Simple deterministic tick + interpolation to keep avatars smooth with minimal bandwidth. • Proximity prompts: When you overlap a “stall” collider, the UI surfaces actions (talk to agent, open swap panel, etc.). • Controls: Arrows to move; X to emote; Spacebar to push-to-talk (speech → text). • Audio: Ambient loop when you enter; ElevenLabs returns audio buffers streamed to <audio>.

Why Next.js? Zero-config DX, image/static asset optimization, API routes for small helpers, and rapid iteration during a hackathon.

⸻

Realtime multiplayer (Socket.io) • Rooms: Short 5-digit codes create/join isolated instances for squads/friends. • Events: join, move, emote, rename, leave — broadcast with throttling to avoid spam. • State: Server is authoritative for presence; clients own their movement intent. We use lightweight reconciliation so slow peers don’t “rubber band”.

Why Socket.io? Dead-simple, works reliably across browsers, and perfect for sub-second state fan-out.

⸻

Agent pipeline (AI + on-chain tools) • OpenAI (via @ai-sdk/openai) + GOAT SDK runs a tool-calling loop: 1. User intent (“swap 50 USDC → FLOW with 1% slippage”). 2. System prompt injects DeFi guardrails (minOut, deadline, network). 3. Tools exposed to the model: • sendETH() (native transfers) • erc20() (approve/transfer/balance) • coingecko() (prices) • tokenSwap() (custom plugin for routing swaps) 4. The model calls tools as needed. We log each tool call for auditability. 5. The API returns: final narration + tool results → UI shows a readable summary → user reviews and signs.

Wallet + RPC: We use wagmi/viem + Privy. Privy smooths onboarding and keeps auth/wallet UX coherent.

⸻

Flow integration (partner tech) • Partner: Flow • We target Flow EVM first: chain IDs 545 (Testnet) / 747 (Mainnet). • This lets us reuse our Solidity swap/stake logic and keep the same wagmi/viem code paths we use on other EVMs. • Benefits: super low fees, fast finality, and trivial porting from existing EVM code. • Next step (native Flow): Add Cadence contracts for resource-oriented assets (e.g., avatar badges / room passes), integrating via FCL and the Flow Emulator for local dev. This pairs Flow’s UX strengths with our EVM DeFi stalls.

⸻

Smart contracts • Solidity (Flow EVM): • Swap agent: Router-adapter pattern (UniV2-style) taking (amountIn, minOut, path, to, deadline). • Staking agent: Generic interface to stake/withdraw/claim across providers. • (Optional) Router: Registry + dispatcher that routes bytes32 key + bytes data to the right agent (extensible “stall” system). • ABIs & addresses live in constants.ts so the UI/Agent API can call uniformly across chains. • Security rails: • User sovereignty: agents prepare but can’t execute funds movement; user signs every action. • Exact-amount allowances (no infinite approvals), minOut + deadline on swaps, clear post-tx explorer links. • Pausable router (if used) and role-gated agent registration for safe hot-patching.

⸻

Voice in / Voice out • Speech in: Web Speech API (browser), with push-to-talk UX to avoid noisy transcripts. • TTS: ElevenLabs for natural voice. We cache short responses client-side to avoid repeating TTS calls (hacky but effective).

⸻

Dev & deploy workflow • Monorepo style: App + server in one project; a /contracts-evm subworkspace for Hardhat/Foundry (keeps node_modules slim and builds fast). • Env gating: If any key (OpenAI, Coingecko, wallet PK) is missing, the Agent API degrades gracefully to chat-only — no on-chain tools. Helpful during demos. • Testnet first: We deploy to Flow EVM Testnet and wire the constants; UI gets a “Testnet” badge and faucets link.

⸻

Hacky bits we’re (secretly) proud of • Intent patching: If the request targets Rootstock/Flow but the prompt forgot to specify, we append a hint to force the model to set the correct chain flag in tool calls. This prevents accidental mainnet calls elsewhere. • Auto-throttled broadcast: Movement updates are coalesced per tick; clients lerp positions locally for ultra-smooth motion even on shaky Wi-Fi. • TTS streaming shim: ElevenLabs returns audio we chunk into a MediaSource buffer so responses can start speaking before the whole clip is fetched. • One ABI to rule them all: A tiny adapter layer lets the same React hooks talk to Celo/Rootstock/Flow just by swapping a chain enum — no duplicate components.