Add RAR app using pyth entropy

[AdedamolaXL]

Pyth Examples Contribution

Type of Contribution

• New Example Project (Adding a new example to demonstrate Pyth integration)
• Bug Fix (Fixing an issue in existing examples)
• Documentation Update (Improving README, comments, or guides)
• Enhancement (Improving existing functionality or adding features)
• Hackathon Submission (Submitting a project from a hackathon)

Project Information

Project/Example Name: RAR (Random Algorithm Radio)

Pyth Product Used:

• Pyth Price Feeds
• Pyth Entropy
• Multiple Products
• Other: ___________

Blockchain/Platform:

• Ethereum/EVM
• Solana
• Aptos
• Sui
• Fuel
• Starknet
• TON
• Other: ___________

Description

What does this contribution do?

This contribution introduces RAR (Random Algorithm Radio) - a unique music app that demonstrates the innovative use of Pyth Entropy for verifiable randomness in creative applications beyond traditional DeFi use cases.

How does it integrate with Pyth?

RAR integrates with Pyth Network Entropy across multiple layers of the application to provide verifiable randomness for core platform features:

• RandomSeed.sol - Daily Playlist Generation
  • Generates daily seeds that power our algorithmic playlist distribution, ensuring truly random yet verifiable song selection.
• CoinFlip.sol - Gameplay Fairness
  • Ensures transparent and verifiable starting conditions for playlist battles (a novel feature we created)
• PlaylistReputationNFT.sol - Reputation Mechanics
  • Creates unpredictable reputation decay patterns that maintain engagement.

What problem does it solve or demonstrate?

1. Trust in Algorithmic Content Curation

Problem: How do we make algorithms more transparent and reduce the 'echo chambers effect' in content recommendation ?

Pyth Solution:

• Verifiable Randomness for playlist generation ensures no hidden biases
• Transparent Algorithms where users can cryptographically verify randomness sources

2. Fairness in Gamified Experiences

Problem: How do we make music listening more playful and collaborative while making it fair and fun at the same time ?

Pyth Solution:
- Provably Fair Gameplay through on-chain verifiable coin flips (Heads: start with 0 songs; Tails start with 2 songs)
- Transparent Starting Conditions that users can independently verify (We turn the hexadecimal generated string into an ideal 64 song queue)
- No Centralized Control over random outcomes that affect user progression (We use the alphanumeric characters within the string as a source of game mechanic; where alphabets: no song revealed in the song card queue; and numbers: a song is revealed in the song card queue'
- This overall use of a single random seed in different forms makes for an interesting listening experience on RAR ;)

3. Sustainable Engagement in Web3 Applications

Problem: How do we move beyond initial token incentives and continually engage the community ?

Pyth Solution:

• Dynamic reputation systems with unpredictable decay patterns (inspired by pyth NFTGrowth contract)
• Novel game mechanics that use randomness to morph pure playlist creation into a playful duel with the algorithm :)
• We turn playlist saving, likes and dislikes into verifiable on-chain activity that drives music curation

Directory Structure (for new examples)

app/
├── app/                 # Next.js app router pages
├── components/          # Reusable UI components
├── contracts/           # Smart contract ABIs and addresses
├── hooks/               # Custom React hooks
├── lib/                 # Utility libraries
├── services/            # Business logic and API services
└── types/               # TypeScript type definitions

Testing & Verification

How to Test This Contribution

1. Local Development Setup

# Clone and install
git clone [repository-url]
cd rar
bun install

# Set up environment (see .env.example)
cp .env.example .env.local
# Fill in your Supabase and RPC details

# Start development server
npm run dev

2. Basic Functionality Tests

A. Wallet Connection & User Registration

• Navigate to http://localhost:3000
• Connect your wallet (MetaMask recommended with Arbitrum Sepolia)
• Expected: User profile should load with username generation
• Verify: Check browser console for user creation logs

B. Playlist Battle Gameplay

• Click any battle prompt on homepage ("Workout Energy Mix", etc.)
• Expected: Wallet pops up for transaction (CoinFlip contract)
• Approve transaction and wait ~30 seconds for entropy callback
• Expected: Redirect to battle interface with starting songs

C. Test Features:

• Click "Flip to Reveal" card to discover new songs
• Use "Add to Playlist" (-5 eu ) and "Pass Song" (-3 eu)
• Try "Rearrange Playlist" (+2 eu) and "Take a Pause" (+5 eu)
• Submit to gallery when playlist has songs
• NOTE: that eu is short for energy units and is how we manage and ensure the game reaches an end state.

D. Contract Functions

RandomSeed Contract

    requestRandomSeed(): Requests a new random seed for daily playlist generation (requires fee)
    currentSeed(): Returns the current active random seed
    getRequestFee(): Returns the fee required for making a seed request

CoinFlip Contract

    requestRandom(): Requests a random coin flip for gameplay initialization (requires fee)
    getUserResult(address user): Returns the coin flip result for a specific user
    hasUserResult(address user): Checks if a user has a pending or completed coin flip result
    getRequestFee(): Returns the fee required for making a coin flip request

PlaylistReputationNFT Contract

    mintPlaylist(address to, string memory playlistName, string memory playlistId): Mints a new reputation NFT for a playlist
    voteForPlaylist(uint256 tokenId): Increases reputation through community voting
    triggerDecay(uint256 tokenId): Initiates reputation decay with random intensity
    getPlaylistInfo(uint256 tokenId): Returns reputation and metadata for a playlist NFT
    tokensOfOwner(address owner): Returns all token IDs owned by an address
    unlock(uint256 tokenId): Unlocks an NFT after callback completion

Prerequisites

Required Software:

• Node.js: Version 18.0.0 or higher
• Package Manager: Bun (recommended) or npm/yarn
• Git: For version control and cloning

Setup & Run Instructions

# Clone the repository
git clone https://github.com/your-username/rar-pyth-example.git
cd rar-pyth-example

# Install dependencies (Bun recommended for speed)
bun install

Deployment Information (if applicable)

Network: Arbitrum Sepolia

bunx hardhat ignition deploy ignition/modules/App.ts --network arbitrum-sepolia

ARBITRUM_SEPOLIA_RPC_URL=your_arbitrum_rpc_url
WALLET_PRIVATE_KEY=your_wallet_private_key

RANDOM_SEED_ADDRESS=0xA13C674F8A8715E157BA42237A6b1Dff24EE274F
COIN_FLIP_ADDRESS=0x762353AdF1342ba85f6dDEac0446E2DA43ab84bf
PLAYLIST_REPUTATION_NFT_ADDRESS=0x0532d0A87B6013a8A086C37D39BC1EB013abC2f4

Demo Link: https://rar-eight.vercel.app/

Checklist

Code Quality

• Code follows existing patterns in the repository
• Proper error handling implemented
• No hardcoded values (use environment variables where appropriate)

Testing

• Tested locally and works as expected
• All existing functionality still works (no breaking changes)

Additional Context

Screenshots/Demo (if applicable)

Youtube Link

Notes for Reviewers

---

Thank you for contributing to Pyth Examples!