From 7a309cfdca4d0d30edea9fb815ab9dbd321fedb4 Mon Sep 17 00:00:00 2001
From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com>
Date: Mon, 12 Oct 2026 18:27:39 +0000
Subject: [PATCH] docs: describe character payments and interrupted item trades

---
 projects/MarketBlock/README.md  | 26 +++++++++++++++++++++++++-
 projects/TrialRooms/README.md   |  2 +-
 projects/TrialRooms/overview.md | 22 +++++++++++++++++++---
 3 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/projects/MarketBlock/README.md b/projects/MarketBlock/README.md
index af6ae60..c8099b2 100644
--- a/projects/MarketBlock/README.md
+++ b/projects/MarketBlock/README.md
@@ -8,10 +8,34 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 See the [shared API versions](../../PLATFORM.md#shared-api-versions) for the matching provider dependency set.
 
+## Character payments
+
+A sale credits the seller's current character pouch through DenarEconomy 0.3.0.
+Realm tax is part of the same ledger posting. Without an active character, the
+sale is refused. Goods are removed only after the ledger confirms payment;
+refused or unavailable payments leave the goods untouched.
+
+Before posting, MarketBlock saves the operation ID, owner account, character,
+gross cents and inventory plan in `plugins/MarketBlock/pending-sales/<owner>.properties`.
+Completed and refused intents are removed. An unavailable payment or interruption
+keeps its intent and blocks new sales for that account until staff reconcile it.
+Repeating the same click does not create another sale.
+
+To reconcile an interrupted sale, stop further sales for that player and inspect
+the saved operation in the DenarEconomy ledger alongside the player's inventory.
+An applied operation already paid the captured character; never credit it again.
+Resolve any outstanding item removal before archiving the intent. An operation
+absent from the ledger has not paid; retain the goods and archive the intent only
+after confirming that state. Do not delete pending files as routine cleanup.
+
+The payment is transactional, but Minecraft inventory saves and ledger commits
+are separate. A crash can leave an applied payment with goods still present;
+this requires reconciliation rather than automatic replay.
+
 ## Build and dependencies
 
 From the MarketBlock source checkout, install the shared plugin versions pinned
-in `pom.xml`, then verify with Java 21:
+in `pom.xml` (TLibs 2.4.0 and DenarEconomy 0.3.0), then verify with Java 21:
 
 ```sh
 python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
diff --git a/projects/TrialRooms/README.md b/projects/TrialRooms/README.md
index 0130cbc..ba719c9 100644
--- a/projects/TrialRooms/README.md
+++ b/projects/TrialRooms/README.md
@@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 TrialRooms builds with Java **21** against
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
-`2.0.1` and DenarEconomy `0.2.1` release artifacts with the shared dependency
+`2.4.0` and DenarEconomy `0.3.0` release artifacts with the shared dependency
 installer. The build also prepares a checksum-verified MythicMobs
 `5.13.1-SNAPSHOT` input from the private ServerAssets repository.
 
diff --git a/projects/TrialRooms/overview.md b/projects/TrialRooms/overview.md
index 87e0403..488a2a2 100644
--- a/projects/TrialRooms/overview.md
+++ b/projects/TrialRooms/overview.md
@@ -100,9 +100,25 @@ health from saturation and cannot damage each other. Leaving through the exit,
 dying, or disconnecting clears the flag.
 
 Items matching a `conversions` line gain "converts on exit" lore when picked up.
-Leaving through the exit removes them and credits their Denar value through
-DenarEconomy. When any player dies, convertible items are removed from their
-drops and inventory.
+Leaving through the exit credits their value to the current character's pouch
+through DenarEconomy. Realm tax is included in the same ledger posting. The loot
+is removed only after payment is applied. With no active character, a refused
+payment or an unavailable ledger, the player still exits and keeps the loot.
+When any player dies, convertible items are removed from their drops and inventory.
+
+Each conversion saves its operation ID, owner account, character, gross cents
+and inventory slots in `plugins/TrialRooms/pending-conversions/<owner>.properties`
+before posting. Completed and refused intents are removed. Interrupted or
+unavailable payments leave the file in place and block further conversions for
+that account. Exit polling cannot start another payment for that pending intent.
+
+Staff must reconcile a pending file against the DenarEconomy ledger and the
+player's inventory before archiving it. An applied operation has already paid the
+captured character: resolve the remaining item removal without crediting again.
+If the operation is absent, confirm that no payment occurred and retain the loot
+before archiving its intent. Do not clear pending files as routine cleanup.
+Minecraft inventory saves and ledger commits are separate; crash recovery is not
+an automatic item-for-money transaction.
 
 ## Commands and permissions