🎬 Arbitrum One YouTube Oracle & NFT Platform

A comprehensive blockchain platform that combines YouTube engagement tracking with dual minting capabilities: ERC-20 token rewards for engagement growth AND NFT minting from video thumbnails. All data is tracked and persisted via Supabase (fully connected).

🌟 Features

Core Capabilities

• 📊 Real-time Monitoring: Tracks views and subscribers for specified YouTube video/channel
• 🪙 ERC-20 Token Minting: Automatically mints tokens based on engagement growth (youtube-oracle.ts)
• 🎨 NFT Minting: Creates NFTs from video thumbnails via IPFS (nft-minter.ts)
• 📸 Thumbnail Storage: Downloads and stores video thumbnails in multiple qualities
• 📋 Playlist Tracking: Optional playlist image monitoring and download
• 💾 Supabase Integration: PostgreSQL database for all data persistence (⚠️ requires your own setup)
• ⛓️ Arbitrum One: Optimized for low-cost transactions
• 📈 Quota Management: Smart YouTube API quota tracking to avoid limits
• 🔄 Auto-recovery: PM2 process management with auto-restart
• 🔐 Secure: Environment-based configuration, no hardcoded secrets

🪙 ERC-20 Token Minting (Engagement Rewards)

The oracle (youtube-oracle.ts) monitors video metrics and mints ERC-20 tokens based on growth:

View-Based Rewards

Tokens = floor(new_views / 20) × 5

Example: 100 new views = 25 tokens

Subscriber-Based Rewards

Tokens = floor(new_subscribers / 10) × 100

Example: 30 new subscribers = 300 tokens Threshold: Minimum 10 new subscribers required

🎨 NFT Minting (Video Thumbnails)

The NFT minter (nft-minter.ts) creates NFTs from video thumbnails:

Workflow

1. Fetch Thumbnail: Downloads highest quality thumbnail from YouTube
2. Upload to IPFS: Uses thirdweb to upload image to IPFS
3. Create Metadata: Generates ERC-721 metadata with video info
4. Mint NFT: Mints on Arbitrum One with metadata URI
5. Track in Database: Records mint in Supabase

Commands

# Mint NFT from a video thumbnail
npm run nft mint <VIDEO_ID> [RECIPIENT_ADDRESS]

# Mint NFTs for all tracked videos
npm run nft batch

# Check if video already minted
npm run nft check <VIDEO_ID>

📋 Prerequisites

For ERC-20 Token Minting (youtube-oracle.ts)

• Node.js 18+
• Supabase Account (free tier works) - ⚠️ YOU MUST CREATE YOUR OWN
• YouTube Data API v3 Key
• Arbitrum One RPC Access
• ERC-20 Token Contract with mint(address, uint256) function
• Private Key with minting permissions

Additional for NFT Minting (nft-minter.ts)

• Thirdweb Account (for IPFS uploads)
• Thirdweb Client ID and Secret Key
• ERC-721 NFT Contract with mintTo(address, string) function on Arbitrum

🚀 Quick Start

1. Clone & Install

cd /workspace
npm install

2. Setup Supabase Database

⚠️ You need to create a Supabase project and set up the tables!

Get Your Database Password (if you forgot it)

1. Go to your Supabase Dashboard and select your project
2. Click Database → Connection string
3. Reset password if needed and save it

Create Database Tables

1. In Supabase dashboard, go to SQL Editor
2. Click "+ New Query"
3. Open complete-schema.sql from this repo
4. Copy ALL contents (entire file - 229 lines)
5. Paste into SQL Editor and click "Run"
6. Verify in Table Editor - you should see 10 tables:
   • videos, channel_stats, minting_events, thumbnails, oracle_state
   • playlists, playlist_images, nft_mints, holders, airdrops

Update .env with YOUR credentials

SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
SUPABASE_ANON_KEY=eyJhbGci...YOUR_ACTUAL_KEY

📖 See SUPABASE_SETUP_ACTUAL.md for detailed step-by-step instructions

⚠️ The setup-database.ts script doesn't work - use the SQL Editor method above.

3. Get YouTube API Key

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable YouTube Data API v3
4. Create credentials → API Key
5. Copy the API key

4. Configure Environment

Copy .env.example to .env and fill in your values:

cp .env.example .env
nano .env

Required for ERC-20 Token Minting:

# Blockchain (ERC-20 tokens)
PRIVATE_KEY=0xYourPrivateKeyHere
CONTRACT_ADDRESS=0xYourTokenContractAddress

# YouTube
YOUTUBE_API_KEY=AIzaSy...
CHANNEL_ID=UC...
VIDEO_ID=LQAFm01IOT0

# Supabase - GET YOUR OWN from https://supabase.com
SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
SUPABASE_ANON_KEY=eyJhbGci...YOUR_ACTUAL_KEY_HERE

Additional for NFT Minting:

# Thirdweb (for IPFS uploads)
THIRDWEB_CLIENT_ID=your_client_id
THIRDWEB_SECRET_KEY=your_secret_key

# NFT Contract (ERC-721)
NFT_CONTRACT_ADDRESS=0xYourNFTContractAddress
NFT_RECIPIENT_ADDRESS=0xDefaultRecipientAddress

5. Compile TypeScript

npm run build

This generates youtube-oracle.js from youtube-oracle.ts

6. Test Runs

Test ERC-20 Token Oracle:

npm start

You should see:

█████████████████████████████████████████████████████████████
█                                                           █
█  🎬 ARBITRUM ONE YOUTUBE ORACLE  🎬                       █
█                                                           █
█████████████████████████████████████████████████████████████

✅ Environment validated
🌐 Network: Arbitrum One
📹 Video ID: LQAFm01IOT0
💼 Wallet: 0x...
📝 Contract: 0x...
💾 Supabase: ✅ Connected

Test NFT Minting:

npm run nft mint LQAFm01IOT0

You should see the complete workflow: thumbnail fetch → IPFS upload → NFT mint → Supabase record

7. Deploy with PM2

# Create logs directory
mkdir -p logs

# Start with PM2
pm2 start pm2.config.js

# View logs
pm2 logs arbitrum-youtube-oracle

# Monitor
pm2 monit

# Save PM2 configuration
pm2 save

# Setup auto-start on reboot
pm2 startup

📁 Project Structure

/workspace/
├── youtube-oracle.ts        # Main oracle logic (TypeScript)
├── youtube-oracle.js        # Compiled JavaScript
├── abi.json                 # Token contract ABI
├── package.json             # Dependencies
├── tsconfig.json           # TypeScript config
├── pm2.config.js           # PM2 process config
├── supabase-schema.sql     # Database schema
├── .env                    # Your configuration (DO NOT COMMIT)
├── .env.example           # Template configuration
├── README.md              # This file
├── logs/                  # PM2 logs
│   ├── output.log
│   └── error.log
└── thumbnails/           # Downloaded thumbnails
    ├── VIDEO_ID_maxres.jpg
    ├── VIDEO_ID_high.jpg
    └── ...

🔧 Configuration Options

Environment Variables

Variable	Default	Description
RPC_URL	https://arb1.arbitrum.io/rpc	Arbitrum One RPC endpoint
CONTRACT_ADDRESS	-	Token contract address (required)
PRIVATE_KEY	-	Wallet private key (required)
YOUTUBE_API_KEY	-	YouTube Data API key (required)
CHANNEL_ID	-	YouTube channel ID (required)
VIDEO_ID	LQAFm01IOT0	Specific video to track
SUPABASE_URL	-	Supabase project URL (required)
SUPABASE_ANON_KEY	-	Supabase anon public key (required)
CHECK_INTERVAL_MINUTES	45	Minutes between checks
DAILY_QUOTA	10000	YouTube API daily quota
QUOTA_BUFFER	500	Safety buffer before quota limit
SUBSCRIBER_MINT_THRESHOLD	10	Min new subs to trigger mint
SUBSCRIBER_REWARD_PER_10	100	Tokens per 10 subscribers
VIEW_REWARD_DIVISOR	20	View count divisor
VIEW_REWARD_MULTIPLIER	5	Token multiplier
THUMBNAIL_STORAGE_PATH	./thumbnails	Where to save thumbnails
DOWNLOAD_THUMBNAILS	true	Enable thumbnail downloads

Adjusting Reward Rates

Edit .env to change minting rates:

# More generous: 1 token per 10 views
VIEW_REWARD_DIVISOR=10
VIEW_REWARD_MULTIPLIER=1

# More generous: 200 tokens per 10 subscribers
SUBSCRIBER_REWARD_PER_10=200

📊 Database Queries

View Recent Minting Events

SELECT 
  event_type,
  delta,
  tokens_minted,
  tx_hash,
  created_at
FROM minting_events
ORDER BY created_at DESC
LIMIT 10;

Check Subscriber Growth

SELECT 
  subscriber_count,
  recorded_at
FROM channel_stats
ORDER BY recorded_at DESC
LIMIT 20;

Total Tokens Minted

SELECT 
  event_type,
  SUM(tokens_minted::numeric) as total_minted
FROM minting_events
GROUP BY event_type;

🔍 Monitoring

PM2 Commands

# Status
pm2 status

# Logs (live)
pm2 logs arbitrum-youtube-oracle --lines 100

# Restart
pm2 restart arbitrum-youtube-oracle

# Stop
pm2 stop arbitrum-youtube-oracle

# Delete
pm2 delete arbitrum-youtube-oracle

# Info
pm2 info arbitrum-youtube-oracle

Check Supabase

1. Go to Supabase Dashboard
2. Table Editor → View your data
3. Logs → Check for errors

🚨 Troubleshooting

"Missing required environment variables"

• Check that all required variables in .env are filled
• Ensure .env file is in the project root

"Transaction failed"

• Verify wallet has ETH for gas
• Check wallet has minting permissions on contract
• Verify contract address is correct

"YouTube API quota exceeded"

• Oracle will auto-sleep for 4 hours when quota is near limit
• Check current quota: SELECT * FROM oracle_state WHERE key = 'quota_used'
• Reduce CHECK_INTERVAL_MINUTES if hitting limits

"Supabase connection failed"

• Verify SUPABASE_URL and SUPABASE_ANON_KEY
• Check Supabase project is active
• Ensure database schema is created

Thumbnails not downloading

• Check DOWNLOAD_THUMBNAILS=true in .env
• Verify thumbnails/ directory exists and is writable
• Check disk space

🔐 Security Best Practices

1. Never commit .env - It's in .gitignore
2. Rotate keys if exposed
3. Use dedicated wallet with limited funds
4. Monitor transactions regularly
5. Set spending limits on minting wallet
6. Backup Supabase data regularly

📝 Contract Requirements

Your token contract must implement:

function mint(address to, uint256 amount) external;

The oracle wallet must have the MINTER_ROLE or equivalent permission.

🎥 Tracking Different Videos

To track a different video:

1. Get video ID from URL: https://youtube.com/watch?v=VIDEO_ID_HERE
2. Update .env: VIDEO_ID=NEW_VIDEO_ID
3. Restart: pm2 restart arbitrum-youtube-oracle

📈 Scaling

For multiple videos:

• Run multiple oracle instances with different .env configs
• Use different PM2 app names
• Consider shared Supabase database or separate per-video

🤝 Support

• Supabase Docs: https://supabase.com/docs
• YouTube API Docs: https://developers.google.com/youtube/v3
• Ethers.js Docs: https://docs.ethers.org
• Arbitrum Docs: https://docs.arbitrum.io

📄 License

MIT

---

⚠️ Disclaimer: This oracle mints tokens based on public YouTube metrics. Ensure your tokenomics and smart contracts have appropriate safeguards against manipulation.

Built for Arbitrum One 🔵 | Powered by Supabase 💚 | YouTube Data API v3 🎥