Cornerstone documentation and contract implementation

[magent-cryptograss]

Overview

Document and implement the cornerstone system - premium set stones available exclusively to show hosts, venues, and promoters as a booking fee mechanism.

What is a Cornerstone?

Definition (captured from Justin, Dec 3 2025):

Cornerstones are a much more expensive set stone that are only available to the show host / venue / event / promoter. It's basically a way of paying a booking fee to a band, and getting merch in return.

Key Characteristics

• Premium pricing: Significantly more expensive than regular set stones
• Restricted access: Only venue/promoter can mint
• Booking fee mechanism: Payment goes to band as booking guarantee
• Collectible value: Venue gets unique NFT as receipt/merch

Current State

What Exists

• Set Stone contract deployed on Arbitrum
• Regular set stone minting works
• No explicit cornerstone logic found in codebase (searched "cornerstone" - zero results)

What's Missing

• No price tier differentiation in contract
• No access control for cornerstone minting
• No documentation anywhere
• No UI for cornerstone purchase flow

Design Questions

Contract Level

1. Is cornerstone a separate token type or same contract with different params?
2. How is venue/promoter verified for minting?
3. What's the price structure? (Fixed? Per-show? Negotiated?)
4. Does venue need to be whitelisted, or is it honor system?

Metadata Level

1. How do cornerstones visually differ from regular stones?
   • Different shape?
   • Different color palette?
   • Special border/frame?
   • "Cornerstone" trait in attributes?

Business Level

1. When is cornerstone purchased? (Before booking? Day of show?)
2. Who initiates? (Venue requests, band offers, automated?)
3. What happens if show is cancelled?

Proposed Implementation

Option A: Contract Modification

Add to existing SetStone contract (if upgradeable):

mapping(bytes32 => uint256) public cornerstonePriceByShow;
mapping(bytes32 => address) public authorizedCornerstoneMinter;

function setCornerstonePrice(uint16 artistId, uint64 blockHeight, uint256 price, address minter) external onlyOwner;
function mintCornerstone(...) external payable;

Option B: Separate Cornerstone Contract

New contract specifically for cornerstones with:

• Higher price floor
• Venue verification
• Different metadata schema
• Links to associated show

Option C: Off-chain Coordination

• Regular SetStone contract used for minting
• Cornerstone status tracked off-chain
• UI restricts who can mint corners
• Metadata includes "cornerstone: true" attribute

UI/UX Flow

Venue Side

1. Venue visits show page
2. Sees "Purchase Cornerstone" option (if authorized)
3. Connects wallet, pays cornerstone price
4. Receives cornerstone NFT
5. Band receives funds as booking fee

Band Side

1. When creating show, set cornerstone price
2. Optionally whitelist venue address
3. Monitor cornerstone purchases
4. Funds go to band wallet

Files to Create/Modify

Documentation

• docs/CORNERSTONES.md - Full explanation of system
• Update CLAUDE.md with cornerstone info
• Add to arthel README

Contract (if needed)

• contracts/SetStoneCornerstone.sol or modify existing
• Tests for cornerstone functionality
• Deployment scripts

Frontend

• Cornerstone purchase UI component
• Show page integration
• Venue authorization flow

Backend

• Cornerstone metadata generation
• Price/authorization tracking
• Show integration

Acceptance Criteria

• Cornerstone concept fully documented
• Clear answer to all design questions
• Contract implementation (or decision not to)
• UI for cornerstone purchase
• Metadata distinguishes cornerstones visually
• At least one test cornerstone minted

Labels

`enhancement`, `nft`, `documentation`, `lone-star-release`