Soundcave Music Streaming Platform Contracts

This repository contains the smart contract implementation for Soundcave's music streaming platform. The contracts use a factory pattern to deploy individual ERC20 tokens with bonding curve pricing for each music track.

Features

• Factory-based Architecture: Each track gets its own dedicated contract (similar to pump.fun)
• ERC20 Token Standard: Tradable tokens for each track
• Bonding Curve Pricing: Four different curve types for dynamic pricing
  • Linear: Price increases linearly with supply
  • Exponential: Price increases more rapidly as supply depletes
  • Logarithmic: Price increases quickly at first, then slows
  • Sigmoid: S-curve with slow, then fast, then slow price increase
• Artist Royalties: Built-in royalty management for music creators (default: 0.5%)
• Platform Fees: Low platform fee on each transaction (1%)
• Affordable Creation: Low deployment cost (approximately $3 USD)

Project Structure

• contracts/: Smart contract source code
  • SoundcaveFactory.sol: Factory contract for deploying individual track contracts
  • SoundcaveTrack.sol: ERC20 token implementation with bonding curve for each track
• test/: Test files for the contracts
  • soundcave-factory.test.ts: Tests for the factory and track contracts
• scripts/: Deployment and utility scripts

Requirements

• Bun v1.2.9 or later
• Hardhat v2.23.0 or later
• Vitest v3.1.3 or later (for testing)

Setup

1. Clone the repository:

git clone https://github.com/your-org/music-streaming-web3
cd music-streaming-web3/blockchain-base

2. Install dependencies:

bun install

3. Set up your environment variables:

cp .env.example .env
# Edit .env with your configuration values

Deployed Contracts

Base Sepolia Testnet

• Factory: 0x9abaf7572adcc0b78a1ebf755e875210b32de7e8

Base Mainnet

• Factory: Coming soon

Testing

Run tests using Hardhat:

bun hardhat test

Run end-to-end tests on Base Sepolia:

bun hardhat run scripts/run-e2e.ts

See E2E-TESTING.md for detailed testing instructions.

Deployment

Local Deployment

bun hardhat run scripts/deploy-factory.ts

Base Sepolia Testnet

bun hardhat run scripts/deploy-factory.ts --network base-sepolia

Base Mainnet

bun hardhat run scripts/deploy-base-mainnet.ts --network base-mainnet

Using the Contracts

Creating a Track

Artists can deploy a new track contract through the factory:

// Get the factory contract
const factory = await getContract({
  address: FACTORY_ADDRESS,
  abi: factoryABI,
});

// Deploy a track with default values
const deploymentFee = await factory.read.deploymentFee();

const tx = await factory.write.deployTrackWithDefaults([
  "Track Name",             // Name
  "SYMBOL",                 // Symbol
  "https://example.com/metadata.json", // Metadata URI
  1000n,                    // Max supply
  parseEther("0.0001"),     // Initial price (0.0001 ETH)
  parseEther("0.001"),      // Final price (0.001 ETH)
  1,                        // Curve type (1 = EXPONENTIAL)
], { value: deploymentFee });

// Get transaction receipt
const receipt = await waitForTransactionReceipt({ hash: tx });

// Get the deployed track address from events
const events = await client.getContractEvents({
  address: FACTORY_ADDRESS,
  abi: factoryABI,
  eventName: 'TrackContractDeployed',
  fromBlock: receipt.blockNumber,
  toBlock: receipt.blockNumber
});

const trackAddress = events[0].args.trackContract;

Buying Tokens

Users can buy tokens from a track contract:

// Get track contract
const track = await getContract({
  address: TRACK_ADDRESS,
  abi: trackABI,
});

// Calculate purchase price for tokens
const amount = 5n;
const price = await track.read.calculatePurchasePrice([amount]);

// Add buffer to ensure transaction succeeds
const priceWithBuffer = (price * 105n) / 100n;

// Buy tokens
const tx = await track.write.buyTokens([amount], { value: priceWithBuffer });
await waitForTransactionReceipt({ hash: tx });

Selling Tokens

Users can sell tokens back to the bonding curve:

// Sell tokens
const amount = 2n;
const tx = await track.write.sellTokens([amount]);
await waitForTransactionReceipt({ hash: tx });

Docker Setup

The API server can be run in a Docker container, which makes it easier to maintain consistency across different environments.

Prerequisites

• Docker and Docker Compose installed on your machine
• Minio container running (the setup script will check for this)

Running with Docker

We've provided simple scripts to run the server in Docker:

# One-step setup and run (recommended)
./setup-and-run.sh

# Or run the individual steps manually:

# 1. Start the server
./start-docker.sh

# 2. Set up Minio buckets
./setup-minio.sh

# 3. Stop the server when done
./stop-docker.sh

The Docker setup will:

1. Create required Docker networks
2. Connect to the existing Minio container
3. Set up required S3 buckets
4. Start the API server on port 4023

You can access the API at http://localhost:4023

License

This project is licensed under the MIT License - see the LICENSE file for details.