Skip to content

ClawdHQ/RoyaltyStream

BranchesTags

Repository files navigation

RoyaltyStream 🎵

Artists register music once. Every play event triggers AI agents to detect it, look up the on-chain split table, and fire micro-payments to every rights-holder in seconds — no PRO middleman, no 18-month wait.

Built for the Hedera Hello Future Apex Hackathon 2026 — AI & Agents track ($18,500) + Hashgraph Online bounty ($4,000).

License: MIT Hedera Testnet

The Problem

Stat Source
$1.3B in music royalties go unclaimed annually IFPI 2024
12–18 months average PRO payout cycle MMA 2018
EU Article 17 + US MMA create active regulatory pressure EU/US Law

Traditional Performing Rights Organisations (PROs) act as black-box intermediaries: artists wait 18 months and receive opaque statements. RoyaltyStream replaces the PRO with AI agents and Hedera smart contracts.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    User / Platform                      │
│  Next.js 14 App  │  Webhook (Spotify/Last.fm)           │
└────────┬─────────┴──────────────┬────────────────────────┘
         │                        │
         ▼                        ▼
┌─────────────────┐   ┌──────────────────────┐
│   Fastify API   │   │  PlayDetectionAgent  │  ← Spotify/Last.fm polling
│   + WebSocket   │   │  (LangChain + HOL)   │
└────────┬────────┘   └──────────┬───────────┘
         │                       │ HCS-10
         ▼                       ▼
┌─────────────────────────────────────────────┐
│            Hedera Consensus Service         │
│  PLAY_EVENTS | PAYMENTS | DISPUTES | AGENTS │
└────────┬────────────────────────────────────┘
         │
         ▼
┌──────────────────────┐
│  DistributionAgent   │  ← reads splits → calls RoyaltyVault.distribute()
│  (LangChain + HOL)   │
└──────────┬───────────┘
           │
           ▼
┌────────────────────────────────────┐
│    Hedera Smart Contract Service   │
│  RightsRegistry  │  RoyaltyVault   │
│  DisputeRegistry                   │
└────────────────────────────────────┘

Hedera Services Used

Service Purpose Testnet ID
HCS — Consensus Service Play events, payment confirmations, A2A agent messages 0.0.8351753, 0.0.8351754, 0.0.8351755, 0.0.8351756
HTS — Token Service ROYALTY_CREDITS (RCRD) fungible token + RIGHTS_NFT collection 0.0.8351758, 0.0.8351760
Smart Contract Service RightsRegistry, RoyaltyVault, DisputeRegistry (Solidity 0.8.24) 0.0.8351767, 0.0.8351768, 0.0.8351770
Mirror Node Transaction history, balance queries, pagination testnet.mirrornode.hedera.com
Hedera Agent Kit LangChain tools for all 4 AI agents @hashgraph/hedera-agent-kit
HOL Registry All 4 agents registered, HCS-10 A2A messaging @hashgraphonline/standards-sdk

HOL Compliance Checklist

  • Agent registered on HOL Registry via @hashgraphonline/standards-sdk
  • Agent reachable via HCS-10 protocol — all 4 agents publish/subscribe on AGENT_REGISTRY_TOPIC
  • Natural language user chat interface — /agent page with ArtistAdvisorAgent
  • A2A communication — minimum two agents: PlayDetectionAgent → DistributionAgent → ArtistAdvisorAgent → DisputeResolutionAgent
  • Agent triggers actions within RoyaltyStream's own smart contracts — DistributionAgent calls RoyaltyVault.distribute()

HOL Use Cases:

  • Agents subscribing to other agents' outputs: DistributionAgent subscribes to PlayDetectionAgent's PLAY_EVENTS_TOPIC feed
  • Agent DAOs / guilds: Label modelled as agent guild managing splits for its entire roster

Monorepo Structure

royaltystream/
├── packages/
│   ├── contracts/          # Solidity 0.8.24 — RightsRegistry, RoyaltyVault, DisputeRegistry
│   ├── agents/             # 4 LangChain agents + Hedera clients (HCS, HTS, Mirror Node)
│   ├── indexer/            # HCS listener + Mirror Node poller
│   ├── api/                # Fastify REST + WebSocket + Prisma + PostgreSQL
│   └── web/                # Next.js 14 App Router frontend
├── scripts/
│   ├── setup-testnet.ts    # Create HCS topics + HTS tokens
│   ├── hol-register.ts     # Register all agents on HOL Registry
│   └── simulate-plays.ts   # Test play event simulation
├── deployments/            # Contract addresses (gitignored except example.json)
└── .env.example

Quick Start

Prerequisites

  • Node.js ≥ 18, pnpm ≥ 8
  • PostgreSQL database
  • Hedera testnet operator account (get one free)
  • OpenAI API key (or OpenRouter API key for Gemini 2.5 Flash Lite fallback)

1. Clone & Install

git clone https://github.com/ClawdHQ/RoyaltyStream
cd RoyaltyStream
cp .env.example .env
# Fill in HEDERA_OPERATOR_ID, HEDERA_OPERATOR_KEY, DATABASE_URL,
# and either OPENAI_API_KEY or OPENROUTER_API_KEY
pnpm install

2. Setup Hedera Testnet Resources

# Creates HCS topics + HTS tokens, outputs IDs to add to .env
ts-node scripts/setup-testnet.ts

3. Deploy Smart Contracts

pnpm contracts:deploy
# Outputs contract addresses — add to .env

4. Register HOL Agents

ts-node scripts/hol-register.ts
# Outputs HOL agent DIDs — add to .env

5. Run the Stack

# Terminal 1: API server
pnpm api:start

# Terminal 2: Agent indexer
cd packages/indexer && pnpm dev

# Terminal 3: Web frontend
pnpm web:dev

# Optional: Simulate play events
ts-node scripts/simulate-plays.ts --isrc USRC11600897 --plays 1000

6. Open the app

AI Agents

Agent HOL Capabilities A2A Role
PlayDetectionAgent play-detection, isrc-matching, hcs-publishing Publisher → DistributionAgent
DistributionAgent royalty-calculation, hts-transfer, hcs-10-messaging Subscriber + Publisher
DisputeResolutionAgent dispute-analysis, evidence-evaluation, arbitration On-demand via ArtistAdvisor
ArtistAdvisorAgent natural-language, portfolio-management, analytics User-facing, files disputes

Example Agent Conversations

User: "Register my song 'Midnight Drive', ISRC: USRC11600897, split 70/20/10"
Agent: → calls RegistrationTool → registers on RightsRegistry → mints Rights NFT → publishes to HCS
       ✓ Work registered. ISRC: USRC11600897, HCS seq#42, HashScan: https://hashscan.io/testnet/...

User: "How much did I earn last month?"
Agent: → calls RoyaltyHistoryTool → queries Mirror Node for account transactions
       ✓ Last month: 2.847 HBAR across 12 payments (Spotify: 1.8ℏ, Apple Music: 0.9ℏ, Last.fm: 0.1ℏ)

User: "Someone is claiming my ISRC"
Agent: → calls HCSMessageTool → sends HCS-10 REQUEST to DisputeResolutionAgent
       ✓ Dispute filed. Dispute ID: 7, DisputeResolutionAgent notified via HCS-10

Smart Contracts

Contract Address Purpose
RightsRegistry 0.0.8351767 ISRC → holders → basisPoints
RoyaltyVault 0.0.8351768 Atomic HBAR distribution
DisputeRegistry 0.0.8351770 On-chain dispute filing

All contracts verified on HashScan. Events emitted on every state change.

API Reference

POST /api/auth/register           # Create artist + Hedera account
POST /api/auth/login              # JWT authentication
POST /api/auth/connect-wallet     # HashConnect wallet link
POST /api/works                   # Register work on-chain
GET  /api/works/:isrc             # Work + splits (auth)
PUT  /api/works/:isrc/splits      # Update splits (auth)
GET  /api/works/:isrc/verify      # PUBLIC — no auth required
GET  /api/royalties               # Payment history
GET  /api/royalties/summary       # Earnings by period/platform/work
POST /api/royalties/withdraw      # Initiate withdrawal
POST /api/agents/chat             # Chat with ArtistAdvisorAgent
GET  /api/agents/status           # All agent statuses + DIDs
POST /api/webhooks/play-event     # HMAC-verified webhook endpoint
GET  /api/admin/metrics           # TPS, accounts, volume

WebSocket: ws://localhost:3001/ws
Events: payment:received | play:detected | agent:action

Environment Variables

See .env.example for the full list. Required for testnet:

  • HEDERA_OPERATOR_ID, HEDERA_OPERATOR_KEY
  • HCS_*_TOPIC IDs (from setup-testnet.ts)
  • CONTRACT_* addresses (from deploy.ts)
  • OPENAI_API_KEY (primary) or OPENROUTER_API_KEY (fallback)
  • DATABASE_URL

LLM provider behavior:

  • If OPENAI_API_KEY is set, agents use OpenAI (gpt-4o, and gpt-4o-mini for memory summarization).
  • If OPENAI_API_KEY is missing and OPENROUTER_API_KEY is set, agents use OpenRouter with google/gemini-2.5-flash-lite.
  • Optional OpenRouter metadata/envs: OPENROUTER_BASE_URL (default https://openrouter.ai/api/v1), OPENROUTER_APP_NAME, OPENROUTER_SITE_URL.

TPS Strategy

Every play event generates 2–4 HTS transfers (artist, label, producer, platform). TPS scales automatically with usage — we never manufacture transactions. Every new artist creates a new Hedera account, contributing to the Success metric.

Business Model

Revenue Stream Rate
Platform fee 2% of distributed royalties
Registration fee 0.1 HBAR per work
Enterprise API $499/month

Market size: $35B global music publishing industry. Targeting the $1.3B unclaimed royalties gap first.

Submission Checklist

  • Public GitHub repo with daily commit history
  • README with architecture diagram and Hedera service list
  • HOL compliance checklist
  • Smart contracts: RightsRegistry, RoyaltyVault, DisputeRegistry
  • 4 AI agents with HOL registration
  • HCS-10 A2A messaging (4 flows)
  • Mirror Node integration with pagination
  • HashScan deep-links on all transactions
  • /verify/:isrc public page (no auth)
  • Agent reasoning visible in chat UI
  • Live deployed demo URL (deploy to Vercel + Railway)
  • YouTube demo video (5 min)
  • Pitch deck PDF
  • 3+ beta users with real transactions

License

MIT — see LICENSE

About

Artists register music once. Every play event triggers AI agents to detect it, look up the on-chain split table, and fire micro-payments to every rights-holder in seconds.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages