Transactions

Full MarketManager.buyItem cycle — states, rollback, and error strings.

Compatible with: GrzybcioRynek 1.0.3Minecraft 26.2Web 0.1.0

Based on GrzybcioRynek 1.0.3 and web 0.1.0 source.

Purchase is GUI only: Detail (slot 11) → Confirm. There is no /market buy. Payment: Vault by UUID. Class: MarketManager.buyItem. Transaction: MarketTransaction (UUID string).

transactions.logging: true logs steps to the server console.

States (`TransactionState`)

CREATED → LISTING_RESERVED → MONEY_WITHDRAWN → SELLER_PAID → ITEM_DELIVERED → COMPLETED
                                                                              ↘ ROLLED_BACK
                                                                              ↘ FAILED

State	Meaning
`CREATED`	TX object created, listing still in storage
`LISTING_RESERVED`	Listing removed from market (`removeListing`)
`MONEY_WITHDRAWN`	Price withdrawn from buyer
`SELLER_PAID`	Seller paid `price - fee`
`ITEM_DELIVERED`	Item added to inventory / overflow to mailbox
`COMPLETED`	Saved in `market-data.yml`; history, ratings, refund
`ROLLED_BACK`	Rollback or admin refund
`FAILED`	Error with `error` field

Purchase cycle

Reserve ID — reservedListings.add(listingId). Second buyer: buy.listing-locked.
Validation (under globalLock):
- listing exists — else buy.not-available
- not own — buy.own-listing
- AntiAbuseManager.canPurchase
- price finite and > 0
- VaultHook.has(buyer, price) — buy.not-enough-money
- recreateItem is not AIR — buy.not-available
- InventoryUtil.canFit — buy.inventory-full
TX UUID, state CREATED.
Remove listing → LISTING_RESERVED. Error: LISTING_REMOVE_FAILED. Favorites for that ID cleared.
Buyer withdraw → MONEY_WITHDRAWN. Error: WITHDRAW_FAILED, restore listing.
Seller deposit (price - fee) → SELLER_PAID. Error: SELLER_DEPOSIT_FAILED, refund buyer money, restore listing.
Fee to market-fee.sink-account if non-empty. Failed sink = warning in log, transaction does not fail.
addItem to buyer; remainder → mailbox purchase-overflow → ITEM_DELIVERED.
COMPLETED, addTransaction (always, regardless of history.enabled), markPurchased, buy.success, seller notification (buy.seller-notified / pending-sales when offline).
TransactionCompletedEvent. When ratings.enabled — rating prompt on chat.
finally: clear ID reservation.

Rollback (`rollbackBuy`)

Called on exception when TX is not yet committed.

State at exception	Action
`ITEM_DELIVERED` or `COMPLETED`	Leave as `COMPLETED`, save TX. Do not reverse money (avoid minting money + item).
`SELLER_PAID`	Claw-back from seller, refund buyer, restore listing → `ROLLED_BACK`. If claw-back fails: `ROLLBACK_SELLER_WITHDRAW_FAILED`, no buyer refund.
`MONEY_WITHDRAWN`	Refund buyer + restore listing → `ROLLED_BACK`
`LISTING_RESERVED`	Restore listing → `ROLLED_BACK`
Other	`EXCEPTION_AFTER_<STATE>` → `FAILED`
Exception in rollback	`ROLLBACK_FAILED:<msg>`

Error strings (`transaction.error`)

String	When
`LISTING_REMOVE_FAILED`	Failed to remove listing
`WITHDRAW_FAILED`	Vault did not withdraw buyer money
`SELLER_DEPOSIT_FAILED`	Vault did not deposit to seller
`ROLLBACK_SELLER_WITHDRAW_FAILED`	Seller claw-back failed
`ROLLBACK_FAILED:<msg>`	Exception in rollback
`EXCEPTION_AFTER_<STATE>`	Exception in unhandled state
`REFUND:<timestamp>`	Admin `/market admin refund` (then state `ROLLED_BACK`)

Admin refund

/market admin refund <tx-id> [reclaim] — only COMPLETED without a prior REFUND:.

Withdraws sellerReceived from seller (or nothing when 0).
Deposits that amount to buyer (or full price when sellerReceived was 0).
Option reclaim: tries to take item from buyer (if online) and puts a copy in seller mailbox with reason admin-refund.

History vs flag

Every completed TX is saved always. history.enabled only disables the /market history command. history.retention-days removes only records in state COMPLETED older than the threshold. ROLLED_BACK / FAILED remain.

What is missing

Buy command.
Partial stack purchase.
Vault nick fallback — deposit by UUID.

Expiration

Mailbox