# V2 Auction House

`AuctionHouse.V2` is the economy-layer auction framework for player-to-player
item sales. It composes inventory containers, currency ledgers, and server
currency authority so listed items, bid holds, buyouts, expiry, and transaction
fees share the same audit trail as the rest of the V2 economy.

## Runtime Surface

- `FV2AuctionHouseConfig` stores the auction house id, server authority id,
  trusted currency source id, fee sink account, default bid increment, default
  fee rate, listing duration bounds, and buyout validation policy.
- `FV2AuctionHouseListingRequest` is the seller-authored input for creating a
  listing from a player inventory item.
- `FV2AuctionHouseListing` tracks seller, buyer, current bidder, escrowed item,
  currency, starting bid, current bid, buyout price, fee rate, timestamps, final
  price, seller proceeds, transaction fees, and state.
- `FV2AuctionHouseState` owns a system escrow inventory and the active or
  historical listing array.
- Result structs return updated auction state, inventories, ledgers, server
  authority results, and typed issues.

## Transaction Rules

1. Listing creation moves the seller item into auction escrow before the listing
   becomes active.
2. Auction escrow uses an existing system `Chest` inventory container and is
   validated before active listings are accepted.
3. Bids are server-authoritative currency holds. A same-bidder increase spends
   only the delta; an outbid refunds the previous bidder before accepting the
   new hold.
4. Buyout settlement transfers the escrowed item to the buyer, refunds any
   previous bidder, spends the buyer's remaining buyout amount, grants seller
   proceeds, and grants transaction fees to the fee ledger.
5. Expired listings either settle to the winning bidder using the already held
   bid amount, or return the unsold escrowed item to the seller.
6. Currency mutation failures and inventory transfer failures return original
   state copies, so partial bid, buyout, and expiry settlement changes are not
   committed.

## Validation Commands

Run these checks when touching auction house behavior:

```bash
python3 V2/ue/Tools/check-v2-auction-house.py
python3 V2/ue/Tools/check-v2-economy-vendor-shop.py
python3 V2/ue/Tools/check-v2-server-currency-authority.py
python3 V2/ue/Tools/check-v2-currency-ledger.py
python3 V2/ue/Tools/check-v2-currency-definition.py
python3 V2/ue/Tools/check-v2-inventory-trading.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Economy/AuctionHouse_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
```