feat: #76 Add event capacity and waitlist management

[jayteemoney]

Summary

• Adds waitlist functionality for sold-out events in the event_manager Soroban contract
• Users can join an ordered waitlist when an event reaches capacity and are automatically promoted (first-in, first-out) when a ticket becomes available
• Adds return_ticket so individual buyers can return tickets before an event ends, triggering automatic promotion
• cancel_event now emits a waitlist_cleared notification so frontends can alert waitlisted users

Requirements fulfilled

Requirement	Implementation
Waitlist data structure	DataKey::Waitlist(u32) → Vec<Address> per event
join_waitlist(event_id)	Added; returns 1-based queue position
Automatic promotion on ticket availability	return_ticket frees a slot and calls try_promote_from_waitlist
Notification mechanism (event emission)	waitlist_joined, waitlist_promoted, waitlist_cleared, ticket_returned
Waitlist position query	get_waitlist_position(event_id, buyer) returns position or 0

New public functions

Function	Description
join_waitlist(buyer, event_id)	Join waitlist for sold-out event; returns position
get_waitlist_position(event_id, buyer)	Query position (0 = not listed)
get_waitlist(event_id)	Return full ordered waitlist
return_ticket(buyer, event_id, tier_index)	Return a ticket for a refund + auto-promote from waitlist

New storage / errors / events

Storage: DataKey::Waitlist(u32) — ordered Vec<Address> per event

Errors: EventNotSoldOut = 21, AlreadyOnWaitlist = 22, EventCanceled = 23

Events: waitlist_joined, waitlist_promoted, waitlist_cleared, ticket_returned

Test results

running 50 tests
... (all waitlist tests) ...
test test::test_join_waitlist_success ... ok
test test::test_join_waitlist_multiple_users_queue_order ... ok
test test::test_join_waitlist_event_not_sold_out ... ok
test test::test_join_waitlist_cancelled_event ... ok
test test::test_join_waitlist_duplicate_prevention ... ok
test test::test_get_waitlist_position_not_on_list ... ok
test test::test_waitlist_promotion_on_ticket_return ... ok
test test::test_waitlist_promotion_multiple_waiters ... ok
test test::test_return_ticket_not_a_buyer ... ok
test test::test_return_ticket_cancelled_event ... ok
test test::test_cancel_event_clears_waitlist_notification ... ok
test test::test_join_waitlist_nonexistent_event ... ok
test result: ok. 50 passed; 0 failed; 0 ignored

Closes #76

[drips-wave]

@jayteemoney Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits