SoundBase: Web3 Music Streaming Platform

A decentralized music streaming platform built with Next.js 15.3.1, React 19, and Tailwind CSS v4, featuring both traditional streaming and tokenized audio via a bonding curve economics model.

Project Overview

The SoundBase platform consists of two main components:

1. SoundBase - Traditional audio streaming with S3/MinIO storage
2. SoundCave - Tokenized audio platform with bonding curve economics (similar to pump.fun but for audio)

The platform combines the best of web2 streaming convenience with web3's tokenization and creator economy features.

System Architecture

Frontend (next-soundbase)

• Framework: Next.js 15.3.1 with App Router
• UI: React 19.1 with Tailwind CSS v4 and shadcn/ui components
• State Management: React Context and Hooks
• Authentication: Wallet-based authentication with Smart Wallet support

Backend Services

• API Server: Elysia/Bun server running on port 4023
• Storage: MinIO object storage for traditional streaming media
• IPFS: Pinata for decentralized storage of SoundCave assets

Blockchain Integration (blockchain-base)

• Smart Contracts: ERC-1155 implementation on Base chain
• Economy: Bonding curve token model with multiple curve types
• Development: Hardhat with Solidity 0.8.20
• Networks: Base Sepolia testnet with planned mainnet deployment

Tech Stack

• Runtime: Bun v1.2.9 (with built-in S3Client, Redis)
• Frontend:
  • Next.js 15.3.1
  • React 19.1-beta
  • Tailwind v4 with Motion extension
  • shadcn/UI components
• Backend:
  • Elysia 1.1 (high-performance minimalist framework)
• Blockchain:
  • Solidity 0.8.20
  • OpenZeppelin contracts 5.3.0
  • Hardhat 2.23.0
• Storage:
  • AWS S3/MinIO for regular streaming
  • IPFS via Pinata for decentralized storage
• Wallet Integration:
  • Base Smart Wallet (passkey-based)
  • wagmi/viem for blockchain interactions

Key Features

SoundBase (Traditional Streaming)

• User profiles and personalized recommendations
• High-quality audio streaming
• Artist profiles and dashboards
• Playlist creation and sharing

SoundCave (Tokenized Audio)

• Mint audio tracks as tokens with bonding curve economics
• Multiple curve types (LINEAR, EXPONENTIAL, LOGARITHMIC, SIGMOID)
• Interactive charts showing price dynamics
• Marketplace for buying/selling audio tokens
• Smart Wallet integration for gasless transactions
• IPFS integration for decentralized storage

Repository Structure

Next.js Frontend (/next-soundbase)

• /src/app - Next.js app router pages
• /src/components - React components
• /src/components/ui - UI components (shadcn)
• /src/lib - Utility libraries and services
  • /src/lib/ipfs-storage.ts - IPFS integration via Pinata
  • /src/lib/market-utils.ts - Bonding curve calculations
  • /src/lib/wagmi.ts - Blockchain configuration
• /src/app/api - API routes and proxies
• /public - Static assets

Blockchain Backend (/blockchain-base)

• /contracts - Solidity smart contracts
  • SoundcaveFactory.sol - Factory for deploying track contracts
  • SoundcaveTrackBonded.sol - ERC-1155 implementation with bonding curve
  • SoundBaseSubscription.sol - Subscription model implementation
• /scripts - Deployment and testing scripts
• /test - Contract tests
• /server - API server for blockchain interaction

Getting Started

Prerequisites

• Bun v1.2.9 or later
• Node.js v18.18.0 or later
• Docker (for MinIO)
• Phantom Wallet or Coinbase Wallet browser extension

Frontend Setup

1. Clone the repositories:

   git clone <frontend-repo-url> next-soundbase
   git clone <blockchain-repo-url> blockchain-base

2. Install frontend dependencies:

   cd next-soundbase
   bun install

3. Set up environment variables:

   cp .env.example .env.local
   # Edit .env.local with your Pinata API keys and other configurations

4. Start the development server:

   bun run dev

Blockchain Setup

1. Install dependencies:

   cd blockchain-base
   bun install

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your wallet private key and RPC URLs

3. Compile contracts:

   npx hardhat compile

4. Deploy to testnet:

   bun run scripts/deploy-base-testnet.ts

Development Workflow

For full-stack development, you'll need to run both frontend and backend services:

# Terminal 1: Start MinIO (Docker)
docker run -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001"

# Terminal 2: Start API server
cd blockchain-base
bun run server/index.ts

# Terminal 3: Start frontend
cd next-soundbase
bun run dev

IPFS Content Handling

SoundCave uses IPFS for storing track files, images, and metadata:

1. Upload Flow:

   • Files are uploaded to Pinata through the platform
   • CIDs are stored in smart contracts for provenance
   • Metadata includes track details and references to audio/image files

2. Retrieval Flow:

   • Content is accessed through Pinata's gateway
   • The formatDirectIpfsUrl helper converts IPFS URIs to HTTP URLs
   • Smart Wallet integration enables gasless transactions

Bonding Curve Implementation

SoundCave implements four bonding curve types to model different token economics:

1. LINEAR: Price increases linearly with supply
2. EXPONENTIAL: Price increases exponentially (more dramatic price growth)
3. LOGARITHMIC: Price increases logarithmically (slowing price growth)
4. SIGMOID: S-curve pricing model (slow, then rapid, then slow growth)

The implementation includes slippage protection and mathematically robust pricing models.

Troubleshooting

Common Issues

HTTP 503 Service Unavailable

• Run bun run fix-503 to diagnose and fix common network issues
• Check if the MinIO service is running
• Verify API server is operational with bun check-backend.js

CORS Issues

• For S3/MinIO access issues, check CORS configuration
• Ensure your S3 bucket has proper CORS rules enabled
• Use the proxy endpoints /api/proxy/... for consistent access

Blockchain Connection Issues

• Ensure your wallet is connected to Base Sepolia testnet
• Check RPC endpoint configuration
• Verify smart contract addresses are correct in .env.local

Advanced Configuration

MinIO / S3 Storage

Configure your storage endpoints in .env.local:

NEXT_PUBLIC_MINIO_URL=http://localhost:9000
NEXT_PUBLIC_API_URL=http://localhost:4023

IPFS / Pinata

Set your Pinata credentials:

PINATA_API_KEY=your_api_key
PINATA_API_SECRET=your_api_secret
PINATA_JWT=your_jwt_token

Blockchain

Configure RPC endpoints:

NEXT_PUBLIC_BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
NEXT_PUBLIC_FACTORY_ADDRESS=0xYourFactoryAddress

Performance Considerations

• Use the API proxy for media files to avoid CORS issues
• Implement proper CORS configuration on your S3/MinIO bucket
• Set appropriate cache headers for media files
• Use next/image for optimized image loading

Monitoring and Analytics

• Server logs in ./logs directory
• Performance metrics available at /api/metrics
• Contract analytics on BaseScan