🎭 Nouns Explorer

A fully decentralized frontend for discovery and exploration of the Nouniverse

Submission for Protocol Labs Genesis Hackathon - Nouns Track

IPFS Deployment with ENS: HERE

Serverless Next.js Deployment: HERE

Agentic ETL Pipeline: SEE BACKEND

Demo Video: HERE

🌟 Project Overview

Nouns Semantic Explorer is a decentralized frontend that revolutionizes how users discover and interact with Nouns through AI-powered semantic search, real-time auction monitoring, and intelligent similarity matching. Built with cutting-edge embedding technology and deployed on IPFS for complete decentralization.

🚀 Key Features

🔍 AI-Powered Semantic Search

• Character-Weighted Embeddings: Advanced AI model that heavily weights Noun character types and features
• Text & Image Search: Find Nouns by description or upload images to find visually similar ones
• Smart Similarity: Uses sentence-transformers with custom weighting for accurate Noun categorization

📊 Real-Time Auction Explorer

• Live Auction Data: Real-time bidding information via The Graph Protocol
• Countdown Timers: Track auction end times with pixel-perfect UI
• Bid History: Complete transaction history for each auction
• Direct Integration: One-click bidding through Nouns.wtf

🎨 Interactive Visualization

• Semantic Network Graph: D3.js-powered visualization of Noun relationships
• Force-Directed Layout: Clusters similar Nouns based on embedding similarity
• Interactive Exploration: Click nodes to explore detailed Noun information

👛 Personal Portfolio Management

• Wallet Integration: Connect MetaMask to view your Noun collection
• Portfolio Analytics: Estimated values and collection insights
• Smart Discovery: Find similar Nouns to ones you already own

🏗️ Technical Architecture

Frontend Stack

• Next.js 14 with TypeScript
• React 18 with modern hooks
• D3.js for data visualization
• Tailwind CSS with custom pixel-art styling
• Web3 Integration for wallet connectivity

AI/ML Pipeline

• OpenAI GPT-4o for image analysis and categorization
• Sentence Transformers (all-MiniLM-L6-v2) for embeddings
• Character Weighting Algorithm for Noun-specific similarity
• Custom ETL Pipeline for processing 1500+ Nouns

Data Infrastructure

• IPFS Storage via Pinata for decentralized data hosting
• The Graph Protocol for blockchain data indexing
• Ethereum Mainnet integration for live auction data
• Batched Processing for efficient data management

Decentralization Features

• IPFS Deployment Ready - All assets can be served from IPFS
• ENS Compatible - Can be accessed via ENS domains
• Client-Side AI - Embedding generation and similarity calculations
• Censorship Resistant - No centralized dependencies for core functionality

🛠️ Backend Processing Pipeline

Our backend is a crash-safe, agentic ETL pipeline that generates character-specific semantic embeddings for all Noun NFTs on Ethereum, optimized for decentralized storage and semantic search.
It integrates Ethereum smart contract reads, SVG→PNG processing, GPT-4o LLMs for structured categorization, sentence-transformers for vectorization, and IPFS distribution.
The pipeline also supports semantic search queries via the same embedding space.

🚀 Pipeline Overview

📄 Part 1: Crash-Safe Description Generation

• Fetches on-chain SVG metadata from the Nouns DAO contract on Ethereum.
• Decodes and renders SVG into high-res PNG images.
• Calls GPT-4o to produce structured JSON descriptions, emphasizing specific character head types (e.g., "pineapple" not "fruit").
• Builds a concise semantic description weighted toward the head category for better embedding fidelity.

✅ Features:

• Crash-safe incremental saving (.jsonl per Noun)
• Retry logic and resumability
• Progress tracking and ETA display

---

🧬 Part 2: Character-Weighted Embedding Creation

• Reads reviewed semantic descriptions.
• For each Noun:
  • Constructs an embedding text with 5× weighted repetition of the head category.
  • Encodes text using a HuggingFace sentence-transformers model (all-MiniLM-L6-v2) into a vector embedding.
• Batches embeddings into IPFS-ready payloads.
• Uploads batches to IPFS via Pinata.
• Maintains a versioned mapping file of batch_id ↔ IPFS CID.

✅ Features:

• Resumable; incomplete batches are detected and filled before creating new batches.
• Old batch hashes are unpinned when updated.

📦 Artifacts:

• noun_batch_to_ipfs_mapping.jsonl — IPFS mapping of all batches.

---

🌐 Part 3: IPFS Distribution & Versioning

• All batched and embedded Noun metadata are pinned to IPFS.
• Efficient mapping files for retrieval by frontend.
• Supports versioning of batches and clean unpinning of outdated data.
• Optimized for frontend latency with batch-level fetches.

---

🔍 Semantic Search Functionality

On the frontend, user queries are handled by a HuggingFace transformers-based tokenizer and encoder, ensuring queries are embedded into the same vector space as the character-weighted Noun embeddings.

✨ Workflow:

1. User inputs a freeform text search, e.g.:

   "purple vampire with sunglasses"

2. Query is tokenized and embedded client-side using sentence-transformers or equivalent.
3. Frontend computes cosine similarity between query embedding and the stored Noun embeddings.
4. Top-N most similar Nouns are displayed, ranked by semantic closeness.

✅ This ensures the semantic search honors the character-specific weighting introduced during embedding creation, making searches intuitive and precise.

---

🧪 Key Technologies

🧩 Component	🔗 Technology
Ethereum smart contract interaction	web3.py
SVG→PNG rendering	cairosvg + Pillow
Structured categorization	OpenAI GPT-4o
Semantic embeddings	sentence-transformers
Decentralized storage	IPFS via Pinata
Crash-safe logging	.jsonl incremental, resumable
Search embedding on frontend	Same sentence-transformers model for query vectorization

---

📈 Output Data

✅ On-chain verified, character-focused, semantic representations of all Nouns:

• Structured JSON metadata
• Semantic weighted embeddings
• Versioned and distributed via IPFS
• Searchable via cosine similarity in shared vector space

---

🎯 Nouniverse Integration

Smart Contract Integration

• Direct integration with Nouns contracts (0x9c8ff314c9bc7f6e59a9d9225fb22946427edc03)
• Real-time auction data via The Graph
• Wallet-based ownership verification
• OpenSea marketplace integration

Data Sources

• Ethereum Mainnet: Live auction and ownership data
• The Graph: Indexed blockchain data for fast queries
• IPFS: Decentralized storage for AI-generated metadata
• OpenAI: Character analysis and categorization

🌐 Decentralization Strategy

Current Implementation

• Frontend optimized for static deployment
• All AI processing can run client-side
• Data stored on IPFS with redundancy
• No server dependencies for core features

ENS Integration Ready

• Clean, static build output
• IPFS hash-based deployments
• ENS subdomain configuration support
• Immutable frontend guarantees

Censorship Resistance

• No centralized APIs for core functionality
• Client-side embedding calculations
• Distributed data storage
• Wallet-based authentication only

📁 Project Structure

nouns-semantic-explorer/
├── src/
│   ├── app/
│   │   ├── semantic-search/         # AI-powered search interface
│   │   ├── semantic-visualization/  # Interactive D3.js graphs
│   │   ├── auction-explorer/        # Real-time auction monitoring
│   │   ├── my-nouns/               # Personal portfolio management
│   │   └── api/                    # Backend API routes
│   ├── components/
│   │   └── basic-ui.tsx            # Pixel-art styled components
│   └── lib/
│       └── similarity.ts           # Embedding similarity calculations
├── scripts/
│   ├── part1_generate_descriptions.py  # GPT-4o description generation
│   ├── part2_create_embeddings.py      # Semantic embedding creation
│   └── part3_full_etl_pipeline.py      # Complete processing pipeline
└── public/                         # Static assets for IPFS deployment

🎨 Design Philosophy

Pixel-Perfect Aesthetics

• Custom pixel-art UI components inspired by retro gaming
• Consistent 8-bit styling throughout the application
• Animated interactions with authentic pixelated feel
• Accessibility-first design with proper contrast ratios

User Experience

• Progressive loading for large datasets
• Intelligent caching and batching
• Responsive design for all device sizes
• Intuitive navigation and discovery flows

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm/yarn
• MetaMask or compatible Web3 wallet
• Environment variables for API keys

Installation

git clone https://github.com/your-repo/nouns-semantic-explorer
cd nouns-semantic-explorer
npm install
cp .env.example .env.local
# Add your API keys to .env.local
npm run dev

Environment Variables

OPENAI_API_KEY=your_openai_key
PINATA_API_KEY=your_pinata_key
PINATA_SECRET_API_KEY=your_pinata_secret
RPC_URL=your_ethereum_rpc_url
NEXT_PUBLIC_GRAPH_API_KEY=your_graph_api_key

🎯 Hackathon Submission Highlights

Innovation in the Nouniverse

• First semantic search implementation for Nouns
• Novel character-weighted embedding approach
• Real-time auction integration with AI discovery
• Fully decentralized architecture ready for ENS deployment

Technical Excellence

• Advanced AI pipeline processing 1500+ Nouns
• Efficient IPFS storage with batching optimization
• Interactive D3.js visualizations of Noun relationships
• Production-ready code with comprehensive error handling

Decentralization Focus

• IPFS-native architecture
• ENS deployment ready
• Client-side AI processing capability
• Censorship-resistant design principles

User Experience

• Intuitive semantic discovery
• Real-time auction monitoring
• Personal portfolio management
• Pixel-perfect retro aesthetics

🔮 Future Roadmap

Enhanced AI Features

• Real-time trait prediction for new Nouns
• Trend analysis and market insights
• Collaborative filtering recommendations
• Advanced similarity algorithms

Community Features

• Noun collection sharing and curation
• Community-driven categorization
• Social discovery and recommendations
• DAO integration for governance participation

Technical Improvements

• WebAssembly AI processing for better performance
• Progressive Web App capabilities
• Enhanced offline functionality
• Multi-chain Noun derivative support

🏆 Why This Matters for Nouns

Nouns Semantic Explorer represents the future of decentralized frontends in the Nouniverse:

• Discoverability: Makes the vast Noun collection searchable and explorable
• Decentralization: Demonstrates how complex AI applications can run fully decentralized
• Innovation: Pushes the boundaries of what's possible with blockchain-based UIs
• Community: Provides tools for Noun holders to better understand and engage with their collections

This project showcases how cutting-edge AI, decentralized storage, and thoughtful UX design can create powerful tools that enhance the Nouniverse while maintaining the principles of decentralization and censorship resistance.

---

Live App Dployment | Live Stattic IPFS Deployment | IPFS Deployment Info | GitHub

---

---

---

---

do not read past here!

TODO:

MAKE PROMPT MORE DYNAMIC TO INTERPRET THE USERS INPUT AND THEN PUT THAT INTO A FORM THAT IS COMPARABLE TO EMBED DYNAMICALLY SO NOT HARDCODED ALWAYS BY CATEGORY const structuredDescription = a ${category} headed character, wearing glasses, blue shirt with colorful patterns, yellow and orange colors, light gray background

TODO For static version:

Fix semantic view embeddings