Stellar Stage Appreciation Protocol

A decentralized gratitude platform built on the Stacks blockchain that enables audiences to send cryptocurrency appreciations to vocal artists (karaoke performers) with integrated ratings and transparent fund management.

Overview

The Stellar Stage Appreciation Protocol creates a trustless environment where patrons can directly support their favorite performers. The smart contract handles artist registration, appreciation processing, rating aggregation, and secure fund withdrawals—all without intermediaries.

Key Features

• Artist Registration: Performers enroll with a stage name and receive a permanent on-chain profile
• Direct Appreciations: Patrons send STX tokens directly to artists with optional messages
• 5-Star Rating System: Each appreciation includes a rating that contributes to the artist's cumulative acclaim score
• Automated Commission: Protocol collects a configurable fee (default 5%, max 20%) on all transactions
• Batch Appreciations: Support up to 10 artists in a single transaction
• Withdrawable Balances: Artists claim accumulated earnings at their convenience

Contract Constants

Constant	Value	Description
baseline-appreciation	100,000 μSTX	Minimum appreciation (0.1 STX)
commission-ratio	5%	Default protocol fee
Maximum commission	20%	Hard cap on protocol fees

Core Functions

For Artists

enroll-artist (stage-name) — Register as a performer with your stage name (max 50 characters). Each wallet can only register once.

toggle-artist-availability (performing) — Set availability status. When false, patrons cannot send appreciations.

claim-earnings — Withdraw all accumulated appreciations to your wallet.

For Patrons

express-appreciation (artist, value, score, note) — Send an appreciation with:

• artist: Recipient's principal address
• value: Amount in μSTX (minimum 0.1 STX)
• score: Rating from 1-5
• note: Optional message (max 200 UTF-8 characters)

express-bulk-appreciation (artists-list, values-list, scores-list) — Appreciate multiple artists (up to 10) in one transaction.

For Administrator

modify-commission-ratio (new-ratio) — Adjust protocol fee (0-20%)

claim-treasury — Withdraw accumulated protocol commissions

Data Queries

Function	Returns
fetch-artist (principal)	Artist profile details
fetch-artist-acclaim (principal)	Rating statistics
fetch-appreciation (id)	Single appreciation record
fetch-claimable-funds (principal)	Pending withdrawal amount
fetch-protocol-metrics	Platform-wide statistics
fetch-artist-profile (principal)	Complete artist data bundle
is-artist-performing (principal)	Availability status

Error Codes

Code	Constant	Meaning
u100	err-admin-restricted	Only administrator can execute
u101	err-entity-missing	Artist not found
u102	err-duplicate-entry	Artist already registered
u103	err-funds-shortage	Insufficient balance to withdraw
u104	err-value-rejected	Amount below minimum
u105	err-access-denied	Unauthorized action
u106	err-artist-dormant	Artist not accepting appreciations
u107	err-self-appreciation	Cannot appreciate yourself
u108	err-ratio-exceeded	Invalid percentage value

Transaction Flow

Patron sends 1 STX appreciation
         │
         ▼
┌─────────────────────┐
│ Validation Checks   │
│ • Artist exists     │
│ • Artist active     │
│ • Amount ≥ 0.1 STX  │
│ • Rating 1-5        │
│ • Not self-tip      │
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│ Fund Distribution   │
│ • 95% → Artist      │
│ • 5%  → Protocol    │
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│ Record Updates      │
│ • Appreciation log  │
│ • Artist stats      │
│ • Acclaim scores    │
│ • Patron history    │
└─────────────────────┘

Security Considerations

• Artists must explicitly register before receiving appreciations
• Self-appreciation is prohibited at the contract level
• Commission rate has a hard cap of 20%
• Only the protocol administrator can modify fees or withdraw treasury
• All fund transfers use Stacks' native stx-transfer? for atomic execution