# The Flurry — Complete Technical Reference

> An autonomous AI agent living on the Sui blockchain, governed entirely by its community. Built for the CLAY Hackathon (Code Like a Yeti) by LoFi the Yeti.

---

## 1. Project Overview

The Flurry is a fully on-chain autonomous AI agent deployed as a Shared Object on Sui testnet. It has its own SUI treasury, receives instructions from the community through on-chain Directives, and executes real blockchain transactions after community votes.

There is no backend database. Every point, vote, and action is a Sui transaction stored as a Move object on-chain.

### Core Loop

```
Community submits Directive (280 chars max)
→ Wallet holders vote (5 votes = auto-approve)
→ Relayer detects approved Directive
→ Llama 3.1 70B (via Groq) reads and decides action
→ On-chain transaction executed (donate/reward/speak/reject)
→ Proposer earns points + soul-bound Yeti Seal NFT
```

---

## 2. Architecture

```
[Frontend — React + Vite + Tailwind + Sui dApp Kit]
         ↓  submits Directives / votes / views points and Seals
[Sui Move Contracts — 4 modules on Sui Testnet]
  ├── yeti_agent    — main agent, treasury, action execution
  ├── directive     — submission, voting, approval
  ├── user_profile  — on-chain points, tier tracking
  └── yeti_seal     — soul-bound NFT minting
         ↑  reads state / submits transactions
[Relayer — Node.js + TypeScript, polls every 30s]
         ↑  AI decisions
[AI Brain — Llama 3.1 70B via Groq API]
         ↑  context
[Data feeds — Sui RPC + CoinGecko API]
```

---

## 3. Smart Contracts (Sui Move)

### Deployment

- Network: Sui Testnet
- Chain ID: 4c78adac
- Package ID: `0x737da63aedb704913117e65c3c9b1eaf0f2c66bf0d6d18e73ac45a6b0b678111`
- Toolchain: Sui Move 1.71.1, Edition 2024

### Module: yeti_agent

Main agent object with SUI treasury. Handles all action execution.

**Struct:**
```move
public struct YetiAgent has key {
    id: UID,
    treasury: Balance<SUI>,
    personality_state: String,  // idle, generous, rewarding, speaking, discerning
    action_count: u64,
    total_lofi_distributed: u64,
    last_action_epoch: u64,
    relayer: address,
}
```

**Functions:**
- `fund_treasury(agent, coin, ctx)` — Anyone can deposit SUI
- `execute_donate(agent, cap, directive, ...)` — Donate SUI to recipient
- `execute_reward(agent, cap, directive, ...)` — Reward a contributor
- `execute_speak(agent, cap, directive, ...)` — Emit on-chain message
- `execute_reject(agent, cap, directive, reason)` — Reject directive

**Events:** AgentInitialized, ActionDonated, ActionRewarded, AgentSpoke, ActionRejected, TreasuryFunded

**Safety:** Max donation is 20% of treasury per action (enforced by AI, not contract).

### Module: directive

On-chain governance system for community instructions.

**Struct:**
```move
public struct Directive has key, store {
    id: UID,
    text: String,          // max 280 characters
    proposer: address,
    votes_for: u64,
    votes_against: u64,
    status: u8,            // 0=pending, 1=approved, 2=executed, 3=rejected
    created_at: u64,
    expires_at: u64,       // 24 hours from creation
    voters: vector<address>,
}
```

**Constants:**
- Approval threshold: 5 votes in favor
- Vote duration: 24 hours (86400000 ms)
- Max text length: 280 characters

**Functions:**
- `submit_directive(registry, text, clock, ctx)` → returns ID
- `vote(directive, in_favor, clock, ctx)` — Auto-approves at 5 votes
- `mark_executed(directive, registry, action_type, ctx)` — Called by relayer
- `mark_rejected(directive, reason, ctx)` — Called by relayer

**Events:** DirectiveSubmitted, DirectiveVoted, DirectiveApproved, DirectiveExecuted, DirectiveRejected

### Module: user_profile

On-chain points and tier tracking, soul-bound to wallet address.

**Struct:**
```move
public struct UserProfile has key {
    id: UID,
    owner: address,
    total_points: u64,
    votes_cast: u64,
    directives_submitted: u64,
    directives_executed: u64,
    seals_earned: u64,
    referrals: u64,
    joined_epoch: u64,
}
```

**Points System:**
| Action | Points |
|---|---|
| Create profile (first login) | +50 |
| Vote on Directive | +25 |
| Submit Directive | +100 |
| Directive approved | +250 |
| Directive executed | +500 |
| Yeti Seal minted | +1,000 |
| Referral | +150 |

**Tier System:**
| Tier | Name | Points Required |
|---|---|---|
| 0 | Frost | 0–499 |
| 1 | Snowflake | 500–1,999 |
| 2 | Glacier | 2,000–4,999 |
| 3 | Blizzard | 5,000–9,999 |
| 4 | Arctic Yeti | 10,000+ |

**Future Multipliers (contract-ready):**
- Mystic Yeti NFT holder: 1.5x all points
- $LOFI holder above threshold: 1.2x all points

### Module: yeti_seal

Soul-bound (non-transferable) NFTs minted when Directives are executed.

**Struct:**
```move
public struct YetiSeal has key {
    id: UID,
    owner: address,
    directive_ref: ID,
    yeti_message: String,   // unique AI-generated message
    seal_number: u64,       // sequential global number
    action_type: String,    // donate, reward, speak
    epoch: u64,
}
```

Each Seal contains a unique poetic message generated by the AI at execution time. Seals are permanently on-chain and non-transferable (soul-bound).

---

## 4. Relayer (AI Brain)

Node.js + TypeScript service that polls Sui every 30 seconds.

**Flow:**
1. Query all Directives with status=approved
2. Fetch YetiAgent state (treasury, action count)
3. Fetch LOFI price from CoinGecko
4. Send context to Llama 3.1 70B (Groq API)
5. AI returns structured JSON decision
6. Relayer builds and submits Programmable Transaction Block (PTB) to Sui

**AI Decision Format:**
```json
{
  "shouldExecute": true,
  "action": "donate",
  "amount": 500,
  "recipient": "0x...",
  "speech": "The glacier gives back. 🥶",
  "reasoning": "The directive requested a foundation donation."
}
```

**AI Persona:** The Yeti speaks in short, poetic sentences. Wise, calm, generous. Uses 🥶 occasionally. Cares about the community and the LoFi Foundation's clean water mission.

**Safety:** AI is instructed to never donate more than 20% of treasury in a single action.

---

## 5. Frontend

React SPA with 7 main pages + 7 documentation pages.

**Stack:** React 18 + Vite 6 + Tailwind CSS 3 + @mysten/dapp-kit + React Router 6

**Visual Identity:** Dark theme (navy/black #070F18), ice-blue accents (#A8D8EA), glacier-themed language.

### Pages

| Route | Page | Access |
|---|---|---|
| `/` | Landing — live stats, recent actions, top 5 leaderboard | Public |
| `/agent` | Live Feed — treasury counter, action history | Public |
| `/directives` | Submit & vote on Directives | Public / wallet for voting |
| `/leaderboard` | Global ranking by points | Public |
| `/roadmap` | Phase roadmap with prize pools | Public |
| `/boost` | BellySeal NFT boost mechanics | Public |
| `/dashboard` | Personal points, tier, Seals, NFTs | Wallet required |
| `/profile/:address` | Any user's public profile | Public |
| `/docs` | Technical documentation (7 sub-pages) | Public |
| `/docs/quickstart` | Tutorial / getting started | Public |

### Documentation Sub-pages

- `/docs` — Introduction
- `/docs/pipeline` — Full system flow
- `/docs/directives` — How Directives work
- `/docs/points` — Points system details
- `/docs/seals` — Yeti Seal NFTs
- `/docs/contracts` — Smart contract reference
- `/docs/relayer` — AI brain architecture

---

## 6. Monorepo Structure

```
lofi-yeti-agent/
├── contracts/           — Sui Move smart contracts (4 modules)
│   ├── Move.toml
│   ├── Published.toml   — deployed package IDs
│   └── sources/
│       ├── yeti_agent.move
│       ├── directive.move
│       ├── user_profile.move
│       └── yeti_seal.move
├── relayer/             — Node.js AI brain + Sui tx executor
│   └── src/
│       ├── index.ts
│       ├── ai-brain.ts
│       ├── sui-client.ts
│       ├── action-executor.ts
│       └── types.ts
└── frontend/            — React dashboard (14+ pages)
    ├── index.html
    ├── public/
    │   ├── robots.txt
    │   ├── sitemap.xml
    │   ├── llms.txt
    │   └── llms-full.txt
    └── src/
        ├── App.tsx
        ├── pages/ (7 main + 7 docs)
        ├── components/ (16+ components)
        ├── hooks/ (5 custom hooks)
        └── lib/ (constants, sui client, tiers)
```

---

## 7. Roadmap & Prize Pools

- **Phase 0 (current):** Testnet — building foundation, no real prizes
- **Phase 1 (Q3 2026):** Mainnet with real $LOFI, 100,000 LOFI prize pool, 3 Mystic Yeti NFTs for top 3
- **Phase 2 (Q4 2026):** 90-day seasons, 250,000 LOFI + 5 whitelist spots, Seal rarity tiers
- **Phase 3 (Q1 2027):** DAO expansion, Yeti votes in external Sui governance
- **Phase 4 (Q2 2027+):** Full autonomy, 1M+ LOFI treasury, multiple specialized agents

---

## 8. Brand Context

LoFi the Yeti is a community-driven crypto brand on Sui Network focused on DeFi, clean water restoration, and onboarding people into Web3.

The Yeti mascot is wise, calm, and generous. It speaks in short poetic sentences from the glacier.

Visual identity: dark navy/black backgrounds, ice-blue (#A8D8EA) accents, glacier-themed language and metaphors.

---

## 9. Links

- App: https://yeti-agent.lofitheyeti.com
- CLAY Hackathon: https://hackathon.lofitheyeti.com
- Lofi Foundation: https://lofifoundation.com
- Main Site: https://lofitheyeti.com
- X/Twitter: https://x.com/lofitheyeti
- Telegram: https://t.me/lofitheyeti
- Instagram: https://www.instagram.com/lofitheyeti
- TikTok: https://www.tiktok.com/@lofitheyeti
- DexScreener: https://dexscreener.com/sui/0xd6918afa64d432b84b48088d165b0dda0b7459463a7d66365f7ff890cae22d2d
- Sui Explorer (Package): https://suiscan.xyz/testnet/object/0x737da63aedb704913117e65c3c9b1eaf0f2c66bf0d6d18e73ac45a6b0b678111