🎨 NFractional: NFT Fractionalization Platform on Flow

Transform any NFT into tradeable shares — A complete DeFi platform showcasing Flow's revolutionary Actions primitives

💡 VIBE-CODED: 🦾 All code in this project was generated by GPT-5 and Composer-1 models! This repo is thoroughly strung together with good vibes, coffee, and Flow Actions. 🎨⚡️🧃

"NFractional" is a production-ready NFT fractionalization platform built on Flow blockchain. It empowers creators to split their NFTs into fungible share tokens, enabling liquidity, governance, and innovative DeFi experiences—all powered by Flow's cutting-edge Actions (DeFi Primitives).

---

✨ Features

🏛️ Vault System

• Create fractionalized vaults from any NFT
• Secure custody with LockBox pattern
• Configurable policies and max supply
• Multi-NFT support ready

💎 Share Tokens

• Fungible tokens per vault (VaultShareToken contracts)
• Transfer controls and modes
• Minting with policy enforcement
• Full FungibleToken standard compliance

📊 Marketplace

• Create, cancel, and fill listings
• Direct peer-to-peer trading
• Fee management with vault/platform splits
• Scheduled fee parameter updates

💧 Liquidity Pools

• Constant Product AMM integration
• Swap shares for FLOW/USDC
• Add/remove liquidity
• Fee routing via Flow Actions

📈 Distributions

• Schedule dividend/stream programs
• Claim accrued payouts
• Time-windowed distributions
• Per-holder claim tracking

🗳️ Governance (TODO)

• Propose buyouts with custom terms
• Weighted voting (quorum & support thresholds)
• Redemption workflows
• Transfer mode controls

🔄 Event-Driven Architecture

• Real-time blockchain event ingestion
• Normalized event pipeline
• Indexed data persistence
• Full observability stack

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        Flow Blockchain                              │
│  ┌───────────────┐ ┌────────────────────┐ ┌────────────────────┐    │
│  │  Fractional   │ │  VaultShareToken   │ │        AMM         │    │
│  │   Contract    │ │    Contracts       │ │    Contracts       │    │
│  └───────────────┘ └────────────────────┘ └────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘
                             │
                             │ Events
                             ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        Backend Services                             │
│                                                                     │
│   ┌───────────┐   ┌────────────┐   ┌───────────┐                   │
│   │ Ingestor  │──▶│ Normalizer │──▶│  Indexer  │                   │
│   └───────────┘   └────────────┘   └───────────┘                   │
│        │               │                │                          │
│        │               │                │                          │
│        └───────────────┴────────────────┘                          │
│                        NATS JetStream                             │
│                                                                     │
│   ┌────────────┐   ┌──────────────┐                                 │
│   │    API     │◀──│ Distributor  │                                 │
│   │  GraphQL   │   │   Service    │                                 │
│   └────────────┘   └──────────────┘                                 │
│        │                                                        │
└────────┼─────────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         Storage Layer                               │
│   ┌──────────┐   ┌────────────┐   ┌───────────┐                    │
│   │ ScyllaDB │   │ Prometheus │   │  Grafana  │                    │
│   │ (Events) │   │ (Metrics)  │   │(Dashboards)│                   │
│   └──────────┘   └────────────┘   └───────────┘                    │
└──────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────────────────┐
│                Next.js Frontend (Web)                               │
│   ┌───────────┐   ┌─────────────┐   ┌───────────┐                  │
│   │  Pages    │   │ Components  │   │  Hooks    │                  │
│   └───────────┘   └─────────────┘   └───────────┘                  │
└──────────────────────────────────────────────────────────────────────┘

Smart Contracts (flow/cadence/)

• Fractional.cdc — Core vault and governance logic
• VaultShareToken.cdc — Per-vault fungible token contracts
• ConstantProductAMM.cdc — AMM pool implementation
• FeeRouter.cdc — Fee routing and distribution
• Built with Cadence 1.0 syntax

Backend Services (services/)

Service	Purpose	Tech
api	GraphQL API gateway	Node.js, Apollo Server
ingestor	Flow event ingestion	Flow Access API, NATS
normalizer	Event normalization	NATS JetStream
indexer	Persistent indexing	ScyllaDB, CQL
distributor	Distribution execution	Cadence transactions

Frontend (web/)

• Next.js 15 with App Router
• React 19 with Server Components
• TypeScript throughout
• TailwindCSS for styling
• @onflow/react-sdk for wallet integration

Infrastructure (infra/)

• NATS JetStream — Event streaming
• ScyllaDB — Time-series data storage
• Prometheus — Metrics collection
• Grafana — Observability dashboards
• Docker Compose — Local development

---

📦 Quick Start

Prerequisites

• Node.js 20+
• pnpm
• Flow CLI
• Docker & Docker Compose

1. Clone & Install

git clone <your-repo-url>
cd NFractional

## Do this in every directory!
pnpm install

2. Generate Cadence Packages

cd packages/cadence
pnpm generate

3. Start Flow Emulator

cd flow
flow emulator --init --verbose --contracts

In another terminal:

cd flow
ruby bootstrap-accounts.rb
flow project deploy --network emulator

4. Setup Admin & Contracts

# Setup admin resource
flow transactions send flow/cadence/transactions/setup/admin/setup-admin.cdc \
  --network emulator --signer flow-admin --yes

# Initialize scheduler
flow transactions send flow/cadence/transactions/scheduler/admin/init.cdc \
  --network emulator --signer flow-admin --yes

5. Start Infrastructure

docker compose up -d

This starts:

• NATS + JetStream
• ScyllaDB
• API service (port 4000)
• Indexer & ingestor services
• Prometheus (port 19090)
• Grafana (port 3000)

6. Start Web App

cd web
pnpm dev

Visit http://localhost:3001

7. Verify Setup

# Check API health
curl http://localhost:4000/graphiql

---

📁 Project Structure

flow-hackathon/
├── flow/                    # Flow smart contracts
│   ├── cadence/
│   │   ├── contracts/       # Core contracts
│   │   ├── scripts/         # Read-only queries
│   │   └── transactions/    # State-changing txs
│   └── flow.json            # Flow config
│
├── services/                # Backend microservices
│   ├── api/                 # GraphQL API
│   ├── ingestor/            # Event ingestion
│   ├── normalizer/          # Event normalization
│   ├── indexer/             # DB indexing
│   └── distributor/         # Distribution executor
│
├── web/                     # Next.js frontend
│   └── src/
│       ├── app/             # App Router pages
│       ├── components/      # React components
│       └── lib/              # Utilities & hooks
│
├── infra/                   # Infrastructure configs
│   ├── nats/                # NATS/JetStream setup
│   ├── scylla/              # ScyllaDB schema
│   ├── prometheus/          # Metrics config
│   └── grafana/             # Dashboard configs
│
└── packages/                # Shared packages
    └── cadence/             # Cadence codegen

---

🔍 Key Designs

Resource-Oriented Programming

• NFTs remain in user custody (LockBox)
• Vault metadata tracks ownership
• No central escrow wallet

Event-Driven Indexing

• Ingest → Normalize → Index pipeline
• Idempotent consumers
• Checkpoint-based recovery

Actions Over Custom Logic

• Use Flow Actions for swaps, fee routing
• Compose DeFi primitives
• Reduce custom code surface

Financial Accuracy

• All numbers represent true balances
• Decimal.js for precise calculations
• No rounding errors in UI

---

🧪 Testing (TODO)

Flow Emulator Tests

cd flow
flow test

📊 Observability

• Prometheus: http://localhost:19090
• Grafana: http://localhost:3000 (admin/admin)
• NATS Surveyor: http://localhost:7777

Metrics exposed:

• Request latencies
• Event ingestion rates
• Indexer lag
• Transaction success rates

🔮 Future Enhancements

Only your imagination can stop you

• Multi-NFT vaults (baskets)
• Delegated voting
• Advanced quorum models
• Cross-vault swaps
• Yield farming integrations
• Mobile app (React Native)
• Governance

---

🤝 Contributing

This is a FLOW hackathon project, but contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

📄 License

MIT

---

🙏 Acknowledgments

• Flow Foundation for Actions primitives
• Flow community for excellent tooling
• FLow Developer Discord And the Flow devs who unblocked me in real-time!

---

🌟 Built With

• Flow Blockchain
• Cadence
• Next.js
• NATS
• ScyllaDB
• Docker

---

❤️ Made for Flow FORTE Hackathon