| name | checkout-batch-flow |
| description | Implement/review one-transaction checkout() batching (feed → commit → buyRelics → applyRelics → monthly action) with deterministic validation, canonical ordering, and exact payment reconciliation (refund extra). |
Checkout Batch Flow (1 Tx, Canonical Order)
When to use
- Editing
checkout(CheckoutParams) in contracts or the UI that builds the cart.
- Touching pricing, fees, stock, slots, or monthly action constraints.
Goal (Definition of Done)
- ✅ Batch execution matches “manual” sequence semantics.
- ✅ Deterministic ordering and revert reasons.
- ✅ Payment reconciliation:
msg.value >= totalCost, refund extra.
Canonical execution order (must not change)
payFeedCost(dayId) if includeFeedcommitDaily(dayId, commitHash) if presentbuyRelics(scope=id/dayId/monthId, batch)applyRelics(scope, batch)setMonthlyBet/adjust if includeMonthlyAction (enforce 1 action/day)
Validation rules
- Validate
dayId always; validate monthId iff monthly action is included.
- All arrays must have consistent lengths (ids/qty, ids/targets).
- Enforce phase gates:
- feed/commit/reveal/draw/claim constraints remain valid even in batch.
- Stock rules:
- No reservation. If stock changed since UI quote, tx may revert.
- Slot rules:
- Slot compatibility checks must run before applying.
Payment reconciliation
- Compute
totalCost = feedCost (optional) + sum(relicCosts + fees).
- Require
msg.value >= totalCost.
- Refund
msg.value - totalCost to sender (safe pattern).
- Emit events as if actions were executed individually.
Deterministic errors (frontend mapping)
Standardize revert selectors/messages:
INVALID_PHASE, INVALID_DAY, INVALID_MONTHINSUFFICIENT_PAYMENT, INSUFFICIENT_STOCK, INSUFFICIENT_SLOTSINVALID_ARRAY_LENGTH, INVALID_TARGET, MONTHLY_RATE_LIMIT
Testing checklist
- Equivalence: manual sequence vs checkout() produces same state/events.
- Insufficient payment reverts.
- Stock change reverts (no reservation).
- Slot incompatibility reverts deterministically.
- Refund correctness.
