Project: BeatDApp

BeatDApp is a blockchain-based music rights management platform that uses smart contracts for transparent royalty distribution.

Project Overview

The music industry has long suffered from opaque royalty accounting. Artists frequently wait 6–18 months for payments, intermediaries capture 30–50% of revenue, and rights ownership is tracked across fragmented databases. BeatDApp solves this by putting music rights on-chain: each song becomes a set of NFT-based ownership tokens, and every stream triggers an automated, transparent royalty payment via smart contract.

Architecture Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                                 FRONTEND LAYER                               │
│  ┌─────────────────────┐  ┌──────────────────────┐  ┌─────────────────────┐ │
│  │ React Application   │  │ MetaMask Wallet      │  │ IPFS Audio Player   │ │
│  │                     │  │ Integration          │  │ (Decentralized      │ │
│  │ - Artist Dashboard  │  │                      │  │  streaming)         │ │
│  │ - Rights Explorer   │  │ - Sign transactions  │  │                     │ │
│  │ - Royalty Viewer    │  │ - View balances      │  │ - CID-based lookup  │ │
│  │ - Track Uploader    │  │ - Switch networks    │  │ - Encrypted chunks  │ │
│  └──────────┬──────────┘  └──────────┬───────────┘  └──────────┬──────────┘ │
└─────────────┼────────────────────────┼─────────────────────────┼────────────┘
              │                        │                         │
              ▼                        ▼                         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                 SERVICE LAYER                                │
│  ┌─────────────────────┐  ┌──────────────────────┐  ┌─────────────────────┐ │
│  │ Node.js API         │  │ IPFS Node            │  │ Streaming Oracle    │ │
│  │                     │  │                      │  │                     │ │
│  │ - User management   │  │ - Audio file storage │  │ - Stream count      │ │
│  │ - Metadata indexing │  │ - Metadata JSON      │  │   aggregation       │ │
│  │ - Event indexing    │  │ - CID generation     │  │ - Oracle feeds to   │ │
│  │ - Auth/JWT          │  │ - Pinning service    │  │   smart contract    │ │
│  └──────────┬──────────┘  └──────────┬───────────┘  └──────────┬──────────┘ │
└─────────────┼────────────────────────┼─────────────────────────┼────────────┘
              │                        │                         │
              ▼                        ▼                         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               BLOCKCHAIN LAYER                               │
│                                                                              │
│  ┌──────────────────────────┐  ┌─────────────────────────────────────────┐  │
│  │  Ethereum (Sepolia)      │  │  Smart Contracts                        │  │
│  │                          │  │                                         │  │
│  │  ┌──────────────────┐    │  │  ┌─────────────────────────────────┐   │  │
│  │  │ RoyaltyDistributor│   │  │  │ RightsNFT (ERC-721)             │   │  │
│  │  │                  │◄───│──│──│ - Mint ownership tokens         │   │  │
│  │  │ - Track balances │    │  │  │ - Fractional ownership shares   │   │  │
│  │  │ - Distribute pay │    │  │  │ - Transfer/split rights         │   │  │
│  │  │ - Oracle input   │    │  │  │ - Royalty claim rights          │   │  │
│  │  └──────────────────┘    │  │  └─────────────────────────────────┘   │  │
│  │                          │  │                                         │  │
│  │  ┌──────────────────┐    │  │  ┌─────────────────────────────────┐   │  │
│  │  │ StreamingOracle  │    │  │  │ BeatToken (ERC-20)              │   │  │
│  │  │                  │◄───│──│──│ - Platform utility token        │   │  │
│  │  │ - Aggregate data │    │  │  │ - Royalty payment denomination  │   │  │
│  │  │ - Verify streams │    │  │  │ - Staking rewards               │   │  │
│  │  │ - Trigger payout │    │  │  │ - Governance voting             │   │  │
│  │  └──────────────────┘    │  │  └─────────────────────────────────┘   │  │
│  │                          │  │                                         │  │
│  └──────────────────────────┘  └─────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Technology Stack

Smart Contracts

Royalty Distribution Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/security/Pausable.sol";

/**
 * @title BeatDApp Royalty Distributor
 * @author John Ian Medilo (j1-medilo06)
 * @notice Manages music rights as ERC-721 NFTs with automated royalty distribution.
 * Each track is minted as an NFT. Ownership can be fractionalized.
 * Streaming data from a trusted oracle triggers royalty payments.
 */
contract RoyaltyDistributor is ERC721, ERC721Enumerable, Ownable, ReentrancyGuard, Pausable {
    // ============ Structs ============
    
    struct Track {
        string title;
        string artistName;
        string ipfsMetadataHash;   // IPFS CID for track metadata JSON
        string ipfsAudioHash;      // IPFS CID for audio file
        uint256 totalShares;       // Total fractional shares (10000 = 100%)
        uint256 streamCount;       // Lifetime verified streams
        uint256 totalRoyalties;    // Total wei distributed
        bool exists;
    }
    
    struct OwnershipShare {
        uint256 shares;            // Share amount (out of track.totalShares)
        uint256 claimedRoyalties;  // Total wei already claimed
    }
    
    // ============ State ============
    
    uint256 public nextTokenId;
    uint256 public platformFeeBasisPoints = 500; // 5% platform fee
    address public streamingOracle;
    address public feeRecipient;
    
    // tokenId => Track
    mapping(uint256 => Track) public tracks;
    
    // tokenId => owner => shares
    mapping(uint256 => mapping(address => OwnershipShare)) public ownershipShares;
    
    // tokenId => accumulated royalties per share (in wei, scaled)
    mapping(uint256 => uint256) public royaltiesPerShare;
    
    // ============ Events ============
    
    event TrackRegistered(
        uint256 indexed tokenId,
        string title,
        string artistName,
        address indexed artist,
        string ipfsAudioHash
    );
    event SharesAllocated(uint256 indexed tokenId, address indexed recipient, uint256 shares);
    event StreamsRecorded(uint256 indexed tokenId, uint256 newStreams, uint256 payment);
    event RoyaltiesClaimed(uint256 indexed tokenId, address indexed recipient, uint256 amount);
    event OracleUpdated(address indexed newOracle);
    
    // ============ Modifiers ============
    
    modifier onlyOracle() {
        require(msg.sender == streamingOracle, "RD: caller is not the oracle");
        _;
    }
    
    modifier trackExists(uint256 _tokenId) {
        require(tracks[_tokenId].exists, "RD: track does not exist");
        _;
    }
    
    // ============ Constructor ============
    
    constructor(
        address _initialOwner,
        address _feeRecipient
    ) ERC721("BeatDApp Rights", "BDR") Ownable(_initialOwner) {
        feeRecipient = _feeRecipient;
        nextTokenId = 1;
    }
    
    // ============ Core Functions ============
    
    /**
     * @notice Register a new music track and mint the rights NFT.
     * @param _title Track title
     * @param _artistName Artist display name
     * @param _ipfsMetadataHash IPFS CID for metadata JSON
     * @param _ipfsAudioHash IPFS CID for audio file
     * @param _totalShares Total fractional shares (typically 10000)
     * @return tokenId The newly minted token ID
     */
    function registerTrack(
        string calldata _title,
        string calldata _artistName,
        string calldata _ipfsMetadataHash,
        string calldata _ipfsAudioHash,
        uint256 _totalShares
    ) external whenNotPaused returns (uint256 tokenId) {
        require(bytes(_title).length > 0, "RD: empty title");
        require(bytes(_ipfsAudioHash).length > 0, "RD: empty audio hash");
        require(_totalShares > 0, "RD: zero shares");
        
        tokenId = nextTokenId++;
        
        tracks[tokenId] = Track({
            title: _title,
            artistName: _artistName,
            ipfsMetadataHash: _ipfsMetadataHash,
            ipfsAudioHash: _ipfsAudioHash,
            totalShares: _totalShares,
            streamCount: 0,
            totalRoyalties: 0,
            exists: true
        });
        
        // Artist receives initial 100% ownership
        ownershipShares[tokenId][msg.sender] = OwnershipShare({
            shares: _totalShares,
            claimedRoyalties: 0
        });
        
        _safeMint(msg.sender, tokenId);
        
        emit TrackRegistered(tokenId, _title, _artistName, msg.sender, _ipfsAudioHash);
    }
    
    /**
     * @notice Split ownership shares with a collaborator (e.g., co-writer, producer).
     * @param _tokenId The track NFT
     * @param _recipient New share holder
     * @param _shares Amount of shares to transfer
     */
    function allocateShares(
        uint256 _tokenId,
        address _recipient,
        uint256 _shares
    ) external trackExists(_tokenId) {
        require(ownerOf(_tokenId) == msg.sender, "RD: not track owner");
        require(_recipient != address(0), "RD: zero address");
        require(_shares > 0, "RD: zero shares");
        
        OwnershipShare storage senderShare = ownershipShares[_tokenId][msg.sender];
        require(senderShare.shares >= _shares, "RD: insufficient shares");
        
        // Claim pending royalties before transfer
        _claimRoyalties(_tokenId, msg.sender);
        
        senderShare.shares -= _shares;
        ownershipShares[_tokenId][_recipient].shares += _shares;
        
        // Update claimed baseline to prevent double-claim
        ownershipShares[_tokenId][_recipient].claimedRoyalties = 
            royaltiesPerShare[_tokenId] * ownershipShares[_tokenId][_recipient].shares;
        
        emit SharesAllocated(_tokenId, _recipient, _shares);
    }
    
    /**
     * @notice Called by the streaming oracle to record streams and deposit royalties.
     * @param _tokenId Track that was streamed
     * @param _newStreams Number of new verified streams
     */
    function recordStreams(
        uint256 _tokenId,
        uint256 _newStreams
    ) external payable onlyOracle trackExists(_tokenId) whenNotPaused {
        require(_newStreams > 0, "RD: zero streams");
        require(msg.value > 0, "RD: no payment attached");
        
        Track storage track = tracks[_tokenId];
        track.streamCount += _newStreams;
        
        // Deduct platform fee
        uint256 fee = (msg.value * platformFeeBasisPoints) / 10000;
        uint256 royaltyAmount = msg.value - fee;
        
        // Accumulate royalties per share
        if (track.totalShares > 0) {
            royaltiesPerShare[_tokenId] += (royaltyAmount * 1e18) / track.totalShares;
        }
        
        track.totalRoyalties += royaltyAmount;
        
        // Transfer fee
        (bool feeSent, ) = feeRecipient.call{value: fee}("");
        require(feeSent, "RD: fee transfer failed");
        
        emit StreamsRecorded(_tokenId, _newStreams, royaltyAmount);
    }
    
    /**
     * @notice Claim accumulated royalties for a specific track ownership.
     * @param _tokenId Track NFT to claim from
     */
    function claimRoyalties(uint256 _tokenId) 
        external 
        nonReentrant 
        trackExists(_tokenId) 
    {
        _claimRoyalties(_tokenId, msg.sender);
    }
    
    function _claimRoyalties(uint256 _tokenId, address _claimer) internal {
        OwnershipShare storage share = ownershipShares[_tokenId][_claimer];
        require(share.shares > 0, "RD: no shares");
        
        uint256 accumulated = (royaltiesPerShare[_tokenId] * share.shares) / 1e18;
        uint256 pending = accumulated - share.claimedRoyalties;
        require(pending > 0, "RD: no pending royalties");
        
        share.claimedRoyalties = accumulated;
        
        (bool sent, ) = _claimer.call{value: pending}("");
        require(sent, "RD: royalty transfer failed");
        
        emit RoyaltiesClaimed(_tokenId, _claimer, pending);
    }
    
    /**
     * @notice View pending royalties without claiming.
     */
    function pendingRoyalties(uint256 _tokenId, address _claimer) 
        external 
        view 
        trackExists(_tokenId) 
        returns (uint256) 
    {
        OwnershipShare storage share = ownershipShares[_tokenId][_claimer];
        if (share.shares == 0) return 0;
        uint256 accumulated = (royaltiesPerShare[_tokenId] * share.shares) / 1e18;
        return accumulated - share.claimedRoyalties;
    }
    
    // ============ Admin Functions ============
    
    function setStreamingOracle(address _oracle) external onlyOwner {
        require(_oracle != address(0), "RD: zero address");
        streamingOracle = _oracle;
        emit OracleUpdated(_oracle);
    }
    
    function setPlatformFee(uint256 _basisPoints) external onlyOwner {
        require(_basisPoints <= 3000, "RD: fee max 30%");
        platformFeeBasisPoints = _basisPoints;
    }
    
    function pause() external onlyOwner {
        _pause();
    }
    
    function unpause() external onlyOwner {
        _unpause();
    }
    
    // ============ Overrides ============
    
    function _beforeTokenTransfer(
        address from,
        address to,
        uint256 tokenId,
        uint256 batchSize
    ) internal override(ERC721, ERC721Enumerable) {
        super._beforeTokenTransfer(from, to, tokenId, batchSize);
    }
    
    function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC721, ERC721Enumerable)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
    
    // Allow contract to receive ETH
    receive() external payable {}
}

Security Considerations

Pre-Deployment Audit Recommendations

Testing with Hardhat and Foundry

Hardhat Test Suite

// test/RoyaltyDistributor.test.js
const { expect } = require("chai");
const { ethers } = require("hardhat");

describe("RoyaltyDistributor", function () {
  let distributor, owner, artist, collaborator, oracle, listener, feeRecipient;
  
  beforeEach(async function () {
    [owner, artist, collaborator, oracle, listener, feeRecipient] = await ethers.getSigners();
    
    const RoyaltyDistributor = await ethers.getContractFactory("RoyaltyDistributor");
    distributor = await RoyaltyDistributor.deploy(owner.address, feeRecipient.address);
    await distributor.waitForDeployment();
    
    // Set oracle
    await distributor.setStreamingOracle(oracle.address);
  });
  
  describe("Track Registration", function () {
    it("Should mint a new track NFT with full artist ownership", async function () {
      const tx = await distributor.connect(artist).registerTrack(
        "Summer Vibes",
        "DJ Test",
        "QmMetadataHash123",
        "QmAudioHash456",
        10000
      );
      
      await expect(tx)
        .to.emit(distributor, "TrackRegistered")
        .withArgs(1, "Summer Vibes", "DJ Test", artist.address, "QmAudioHash456");
      
      expect(await distributor.ownerOf(1)).to.equal(artist.address);
      
      const share = await distributor.ownershipShares(1, artist.address);
      expect(share.shares).to.equal(10000);
    });
    
    it("Should reject registration with empty title", async function () {
      await expect(
        distributor.connect(artist).registerTrack("", "DJ Test", "hash", "audio", 10000)
      ).to.be.revertedWith("RD: empty title");
    });
  });
  
  describe("Royalty Distribution", function () {
    beforeEach(async function () {
      await distributor.connect(artist).registerTrack(
        "Test Track", "Artist", "QmHash", "QmAudio", 10000
      );
    });
    
    it("Should distribute royalties proportional to shares", async function () {
      // Oracle records 1000 streams with 1 ETH payment
      await distributor.connect(oracle).recordStreams(1, 1000, { value: ethers.parseEther("1.0") });
      
      // Artist has 100% shares, should receive 0.95 ETH (after 5% fee)
      const pending = await distributor.pendingRoyalties(1, artist.address);
      expect(pending).to.equal(ethers.parseEther("0.95"));
    });
    
    it("Should correctly split royalties after share allocation", async function () {
      // Artist gives 30% to collaborator
      await distributor.connect(artist).allocateShares(1, collaborator.address, 3000);
      
      // Oracle records streams
      await distributor.connect(oracle).recordStreams(1, 1000, { value: ethers.parseEther("1.0") });
      
      // Artist (70%): 0.665 ETH, Collaborator (30%): 0.285 ETH
      expect(await distributor.pendingRoyalties(1, artist.address))
        .to.equal(ethers.parseEther("0.665"));
      expect(await distributor.pendingRoyalties(1, collaborator.address))
        .to.equal(ethers.parseEther("0.285"));
    });
    
    it("Should prevent reentrancy attacks on claim", async function () {
      await distributor.connect(oracle).recordStreams(1, 100, { value: ethers.parseEther("0.1") });
      
      // Normal claim should succeed
      await expect(distributor.connect(artist).claimRoyalties(1))
        .to.emit(distributor, "RoyaltiesClaimed");
      
      // Double claim should fail (no pending royalties)
      await expect(distributor.connect(artist).claimRoyalties(1))
        .to.be.revertedWith("RD: no pending royalties");
    });
  });
  
  describe("Access Control", function () {
    it("Should only allow oracle to record streams", async function () {
      await distributor.connect(artist).registerTrack("T", "A", "h", "a", 10000);
      
      await expect(
        distributor.connect(listener).recordStreams(1, 100, { value: 100 })
      ).to.be.revertedWith("RD: caller is not the oracle");
    });
    
    it("Should allow owner to update oracle address", async function () {
      await expect(distributor.setStreamingOracle(collaborator.address))
        .to.emit(distributor, "OracleUpdated")
        .withArgs(collaborator.address);
    });
    
    it("Should prevent non-owner from updating oracle", async function () {
      await expect(
        distributor.connect(artist).setStreamingOracle(collaborator.address)
      ).to.be.revertedWithCustomError(distributor, "OwnableUnauthorizedAccount");
    });
  });
});

Foundry Fuzz Tests

// test/RoyaltyDistributor.fuzz.t.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "forge-std/Test.sol";
import "../src/RoyaltyDistributor.sol";

contract RoyaltyDistributorFuzzTest is Test {
    RoyaltyDistributor public distributor;
    address public owner = address(1);
    address public feeRecipient = address(2);
    address public oracle = address(3);
    address public artist = address(4);
    
    function setUp() public {
        distributor = new RoyaltyDistributor(owner, feeRecipient);
        vm.prank(owner);
        distributor.setStreamingOracle(oracle);
    }
    
    /// @notice Fuzz test: royalties should always match total deposits minus fees
    function testFuzz_RoyaltyAccounting(
        uint96 _payment,
        uint256 _streams,
        uint16 _feeBps
    ) public {
        vm.assume(_payment > 0.001 ether);
        vm.assume(_streams > 0 && _streams < 1e12);
        vm.assume(_feeBps <= 3000);
        
        // Setup
        vm.prank(owner);
        distributor.setPlatformFee(_feeBps);
        
        vm.prank(artist);
        distributor.registerTrack("Fuzz", "Artist", "hash", "audio", 10000);
        
        // Record streams
        uint256 fee = (uint256(_payment) * _feeBps) / 10000;
        uint256 expectedRoyalty = uint256(_payment) - fee;
        
        vm.deal(oracle, _payment);
        vm.prank(oracle);
        distributor.recordStreams{value: _payment}(1, _streams);
        
        // Claim and verify
        uint256 balanceBefore = artist.balance;
        vm.prank(artist);
        distributor.claimRoyalties(1);
        
        // Artist has 100%, should receive expected royalty (within 1 wei for rounding)
        assertApproxEqAbs(
            artist.balance - balanceBefore,
            expectedRoyalty,
            1,
            "Royalty mismatch"
        );
    }
    
    /// @notice Invariant: total claimed royalties should never exceed total deposits
    function invariant_ClaimedNotExceedDeposits() public {
        // Implementation would track all deposits and claims
        // This is a placeholder for the invariant testing pattern
    }
}

Deployment Guide

Deploy to Sepolia Testnet

# .env
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
PRIVATE_KEY=0xyour-private-key-without-0x
ETHERSCAN_API_KEY=your-etherscan-api-key

# Deploy
npx hardhat run scripts/deploy.js --network sepolia

// scripts/deploy.js
const { ethers, run } = require("hardhat");

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log("Deploying with account:", deployer.address);
  
  const balance = await ethers.provider.getBalance(deployer.address);
  console.log("Account balance:", ethers.formatEther(balance), "ETH");
  
  // Deploy
  const RoyaltyDistributor = await ethers.getContractFactory("RoyaltyDistributor");
  const distributor = await RoyaltyDistributor.deploy(
    deployer.address,  // owner
    deployer.address   // fee recipient (change for production)
  );
  await distributor.waitForDeployment();
  
  const address = await distributor.getAddress();
  console.log("RoyaltyDistributor deployed to:", address);
  
  // Wait for block confirmations before verification
  console.log("Waiting for block confirmations...");
  await distributor.deploymentTransaction().wait(5);
  
  // Verify on Etherscan
  console.log("Verifying contract...");
  await run("verify:verify", {
    address: address,
    constructorArguments: [deployer.address, deployer.address]
  });
  
  console.log("Deployment complete!");
  console.log("Contract:", address);
  console.log("Owner:", deployer.address);
}

main().catch(console.error);

Mainnet Deployment Checklist

Terraform Infrastructure

# terraform/main.tf
# AWS infrastructure for BeatDApp Node.js API and IPFS pinning

terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
  backend "s3" {
    bucket         = "beatdapp-terraform-state"
    key            = "infrastructure.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

provider "aws" {
  region = var.aws_region
  default_tags {
    tags = {
      Project     = "beatdapp"
      ManagedBy   = "terraform"
      Repository  = "github.com/j1-medilo06/beatdapp"
    }
  }
}

# ECS service for Node.js API (similar pattern to PokerLab)
# IPFS pinning via Pinata API gateway
# Secrets stored in AWS Secrets Manager

GitHub Repository