PlanChangeManager

Handles subscription plan upgrades (immediate with proration) and downgrades (scheduled for next billing cycle).

Purpose

PlanChangeManager provides three plan change paths: scheduling a downgrade for the next billing cycle, performing an immediate upgrade with prorated payment, and upgrading from a free trial to a paid plan.

Downgrades are deferred to the next renewal cycle to avoid mid-cycle disruption. The scheduled plan is stored on the subscription row and applied by SubscriptionManager during renewal. Upgrades are immediate: a new subscription row is created, the old one is cancelled, payment is recorded, and a fresh challenge is started (resetting positions and balance to match the new plan's capital).

The manager also provides a read-only proration preview for UI display, calculating the prorated cost based on remaining days in the current billing cycle.

Edge Cases & Error Handling

• Upgrade idempotency check via txHash must come before other validations (on retry, the subscription is already upgraded)
• Failed challenge creation after upgrade triggers full rollback: payment deleted, new subscription deleted, old subscription restored (including its scheduled plan)
• Upgrading clears any scheduled downgrade and logs it
• Trial upgrade preserves referral wallet from the trial subscription
• Proration uses PLAN_PRICES constant and calculateProratedUpgradeAmount() pure function

See Also

• SubscriptionManager
• PaymentHistoryManager
• ResetCreditsManager