fix(#406): timelock admin raffle cancellation to prevent rug of ticket buyers

[Heazzy500]

Overview

This PR closes a security hole in contracts/raffle-instance where an admin could cancel a raffle with sold tickets instantly, returning the prize to the creator while ticket buyers were left to chase individual refunds — an immediate rug of ticket holders.

It introduces a 48-hour timelock for admin-initiated cancellations of raffles that have already sold tickets (matching the factory's TIMELOCK_DELAY_SECONDS). The cancel is now scheduled first (emitting a CancelScheduled event) and only executed after the notice period, while ticket holders may refund immediately the moment a cancel is scheduled.

Related Issue

Closes #406

Changes

🔒 Timelocked Admin Cancellation

• [MODIFY] contracts/raffle-instance/src/lib.rs — cancel_raffle

• When CancelReason::AdminCancelled is used on a raffle with tickets_sold > 0, the cancel is now scheduled instead of executed: status stays Active, the prize stays locked, and PendingAdminCancel (a cancel_at timestamp = now + 48h) is stored.

• Admin cancels of raffles with zero tickets sold remain immediate (no buyers to protect).

• [ADD] contracts/raffle-instance/src/lib.rs — execute_admin_cancel

• Executes a previously scheduled admin cancel, but only after the timelock has elapsed.

• Returns CancelTimelockActive if called before cancel_at, and CancelNotScheduled if no cancel is pending.

• [ADD] contracts/raffle-instance/src/lib.rs — get_pending_cancel

• Read-only getter returning the scheduled cancel_at timestamp (or None) for indexers/UIs.

• [MODIFY] contracts/raffle-instance/src/lib.rs — refund_ticket

• Ticket holders can now refund immediately once a cancel is scheduled, not just after it executes.

• [MODIFY] contracts/raffle-instance/src/lib.rs — wipe_storage

• Cleans up the new PendingAdminCancel key on teardown.

🧱 New State, Events & Errors

• [ADD] contracts/raffle-instance/src/events.rs — CancelScheduled

• Emitted when an admin schedules a cancel; carries creator, scheduled_by, tickets_sold, cancel_at, and timestamp.

• [MODIFY] contracts/raffle-instance/src/lib.rs

• DataKey::PendingAdminCancel — stores the executable-at timestamp while a cancel is pending.

• ADMIN_CANCEL_TIMELOCK_SECONDS = 172_800 (48 hours) — matches the factory's TIMELOCK_DELAY_SECONDS.

• New errors: CancelTimelockActive = 64, CancelNotScheduled = 65.

🧪 Tests

• [ADD] contracts/raffle-instance/src/lib.rs (test module)
• admin_cancel_with_sold_tickets_requires_timelock — scheduling works, exactly one CancelScheduled event fires, executing immediately and 1s before the deadline both fail with CancelTimelockActive, and it succeeds at the deadline.
• ticket_holders_refund_immediately_after_cancel_scheduled — refunds rejected while Active, allowed instantly once scheduled.
• execute_admin_cancel_without_schedule_fails — returns CancelNotScheduled.
• admin_cancel_with_no_tickets_is_immediate — zero-ticket admin cancel stays instant.
• [MODIFY] test_wipe_storage_removes_all_keys — updated to the schedule → wait → execute_admin_cancel flow.

Verification Results

cargo build -p raffle-instance   ✅ Finished (existing repo warnings only)
cargo test  -p raffle-instance   ✅ 20 passed; 0 failed
cargo test  --workspace          ✅ raffle-instance 20/20, raffle-factory 19/19, all green

Acceptance Criteria	Status
Admin-initiated cancellation of raffles with sold tickets requires a timelock	✅
A CancelScheduled event is emitted when an admin schedules a cancel	✅
Ticket holders can refund immediately once a cancel is scheduled (not just after it executes)	✅
Test: scheduling then executing a cancel within the timelock window fails	✅
Admin cancel of a raffle with zero tickets sold stays immediate	✅
Build passes successfully	✅
Test suite passes successfully	✅

🤖 Generated with Claude Code