Market, Contracts, and Logistics¶

Design Goals¶

The economy should feel regional, physical, and reactive. Goods should not teleport across the world for free, and prices should respond to actual scarcity.

Regional Market Model¶

Each major town hosts a regional exchange. At launch there is one exchange: Trevalkaan. Village branch boards can feed orders into it but do not host their own exchanges — their goods must be physically transported to Trevalkaan to enter the regional price system.

The Trevalkaan exchange supports:

Sell orders — a player or NPC posts a quantity of an item at an asking price; any buyer can fill it
Buy orders — a player or NPC posts a quantity wanted at a maximum price; any seller can fill it
Auctions — a single lot, time-limited, open bidding with anti-sniping rules
Direct trade window — two-party confirmed swap, no board involved
Warehouse storage — items held in secure storage for a daily fee; a player does not need to be online to sell from warehouse hold

Why Regional Matters¶

Regional separation makes climate, travel, and town condition meaningful. Village fish does not instantly normalize with Trevalkaan fish prices — it must be transported, and that transport takes time and carries risk. Desert salt, tundra furs, coastal fish, and forest herbs from future expansion regions will each have local price bands before supply chains smooth them into the Trevalkaan index.

Price Model¶

Each market category in Trevalkaan tracks a rolling price index rather than raw spot chaos.

instant_index = base_price × scarcity_multiplier × route_multiplier × event_multiplier × tax_multiplier × liquidity_multiplier

next_index = current_index × 0.70 + instant_index × 0.30

Scarcity multiplier — derived from the town reserve band for the relevant reserve class (food, fuel, medicine, building, water):

Reserve band	Scarcity multiplier
Prosperous	0.80
Growing	0.90
Stable	1.00
Strained	1.30
Failing	1.75

Route multiplier — rises when the routes supplying this item are disrupted (bandit pressure, washed roads, escort losses, event-driven closures):

Route state	Multiplier
Open	1.00
Disrupted (minor)	1.15
Disrupted (major)	1.40
Blocked	1.80

Event multiplier — applied by the event system for short-window spikes:

Event type	Typical multiplier	Duration
Festival (luxury food, crafted goods)	1.25–1.50	Event duration
Plague (medicine)	1.60–2.00	Until event resolves
Bridge collapse (timber, stone)	1.40–1.70	Until route restored
Monster surge (weapons, armor)	1.20–1.35	While active

Daily movement cap: Outside of crisis states, the index cannot move more than ±15% per day. Crisis events can override the cap temporarily.

Liquidity multiplier — small towns (villages) cannot match a prosperous city's buy depth even at the same price. The liquidity multiplier reflects how much volume the local market can actually absorb or supply before price pressure kicks in.

Sell and Buy Orders¶

A sell order or buy order posts to the exchange and remains active until filled, expired, or cancelled.

Fee: A 3% listing fee is charged on sell orders at posting time. The fee is not refunded on cancellation. Buy orders carry no listing fee but do lock the offered coin in escrow until the order is filled or cancelled.

Order lifetime: Default 7 real days. Player can extend once for another 7 days at a flat 1% fee.

Partial fills: Sell and buy orders may be partially filled. A 50-unit sell order can be partially filled by a buyer who only wants 20 units. The remaining 30 stay listed.

Pickup: Items from filled orders are held in the exchange warehouse for up to 72 hours before expiring. If the buyer does not collect within 72 hours, the item is returned to the seller's warehouse hold and the coin is returned to the buyer minus the listing fee.

Trade Skill and Market Access¶

The Trade skill governs how many orders a character can hold open simultaneously, what fees they pay, and which advanced exchange features they can access. It is the primary skill for operating as a merchant rather than a casual seller.

Negotiation is a related but distinct skill. Negotiation reduces NPC service prices and caravan hire costs; Trade governs exchange mechanics, fees, and order limits. A character who wants to operate a serious market presence needs Trade. A character who wants to buy goods cheaply from NPCs and negotiate caravan rates needs Negotiation.

Simultaneous Order Limits¶

Trade Band	Active Sell Orders	Active Buy Orders	Auction Listings
Untrained	2	0	0
Familiar	4	1	0
Practiced	6	3	1
Skilled	10	6	2
Veteran	15	10	3
Expert	20	15	5
Master	30	25	10

An Untrained character can still sell things — they can list 2 sell orders at any one time. They simply cannot place buy orders at all until Familiar, and cannot use the auction system until Practiced.

Fee Reductions by Trade Band¶

The base sell order listing fee is 3%. The base auction seller fee is 5% of final price. Trade skill reduces both:

Trade Band	Sell Order Listing Fee	Auction Seller Fee
Untrained	4% (surcharge — poor understanding of exchange norms)	Not eligible
Familiar	3% (base)	Not eligible
Practiced	2.5%	5% (base)
Skilled	2%	4%
Veteran	1.5%	3.5%
Expert	1%	2.5%
Master	0.5%	2%

Buy orders and direct trade carry no fee regardless of Trade band.

Unlocks by Trade Band¶

Trade Band	Unlocks
Familiar	Buy orders (1 simultaneously). Can read settlement history for the last 5 sales of any item type.
Practiced	Auction listings (1 at a time). Bulk orders — a single order can span up to 5× the normal per-order quantity cap.
Skilled	Extended order lifetime — default 14 days instead of 7 for all new orders. Can read the full order book depth (all active orders at all prices, not just the best offer).
Veteran	Standing buy orders — a buy order at Veteran can be set to auto-renew for up to 28 days without a reposting fee. The escrow is extended automatically on renewal.
Expert	Can read market price index history for the past 30 days (instead of 10 sales). Auction reserve price is not shown to bidders even if partially filled — maintains negotiation position.
Master	Demand-contingent orders — an order can be set to auto-activate when a specific settlement supply band changes (e.g., post a buy order for 50 grain bundles automatically when Trevalkaan food reserve enters Strained). The order is held dormant until the trigger condition is met.

Price Alerts¶

Any character at any Trade band can subscribe to price alerts. An alert is a passive notification that fires on the next daily tick when a specified condition is met.

Setting an alert: - The player selects a commodity from the exchange UI - They set one of three threshold conditions: - Price rises above X — useful for sellers waiting for a favorable window - Price falls below X — useful for buyers watching for a dip - Item appears on the market — useful for rare items that sell infrequently - The alert is stored against the character and persists until triggered or manually cleared

Alert behavior: - Alerts fire on the next daily tick after the condition is first met — not in real time - A maximum of 5 active alerts per character at any Trade band; the limit does not scale with rank - Triggering an alert delivers a single board notification at the next check-in; the item is not reserved or locked in any way — the alert only informs, it does not act

Design intent: Price alerts let casual players who check in once per day participate in market timing without needing real-time access or high Trade rank. They are intentionally less powerful than the Demand-contingent orders that Trade Master unlocks (which can automatically post orders, not just notify).

Appraisal and Trade¶

The Appraisal skill is a companion to Trade. Trade governs exchange access and fees; Appraisal governs the ability to identify item quality, read hidden properties, and price non-standard goods accurately.

Without Appraisal, a character posting an auction cannot fully disclose all item properties — only the base quality tier is visible to bidders. The exchange requires full disclosure if Appraisal data is available; this means a skilled appraiser is effectively required to get the best auction price for complex crafted goods.

At Appraisal Practiced and above, the character can request an appraisal report from any item in their inventory. At Skilled and above, they can appraise items on behalf of other players for a fee.

Auctions¶

Auctions are used for rare items, unique crafted goods, and high-value lots where open competition determines the real price.

Structure: - Duration: 24 or 48 hours (seller's choice at listing) - Reserve price: optional minimum; if not met, the lot is not sold and 1% of the reserve price is charged as a listing fee - Minimum bid increment: 5% of current highest bid (rounded up to nearest coin) - Anti-sniping: any bid in the final 10 minutes extends the auction by 10 minutes; a bid with 3 minutes remaining extends it to 13 minutes from the current time, and so on until no bid arrives in a full 10-minute window

Auction fees: - If sold: 5% of final price taken from the seller's proceeds - If unsold (reserve not met): 1% of reserve price as a listing fee - Buyer pays no fee

Inspection: All auction lots must include item quality tier, identified properties, and durability if applicable. Hidden-stat auctions are not permitted — the exchange requires the Appraisal entry to be disclosed if the seller possesses it.

Settlement history: The last 10 sale prices for any item type are visible to any player in the exchange UI. This is the primary price discovery tool for items that do not appear frequently.

Direct Trade¶

Direct player trade is always available and carries no fee. The interface must:

show both parties' offered items simultaneously before either confirms
lock the trade contents for a 10-second review window before confirmation
require both parties to confirm in the same window to settle
apply no server-side taxes (guild tax rules do not apply to direct trade)

Direct trade is the appropriate channel for social and guild-internal exchanges. The exchange board is the appropriate channel for open market activity.

Player Contracts¶

A player who meets the threshold (domain skill competence at Practiced or above, plus Trevalkaan Civic Standing of Contributor or higher — see reputation-and-standing.md) may post contracts on the Adventurers Hall player contract board.

Contract types:

Type	What the claimant must do	Proof
Hunt	Kill a named creature type or species in a valid zone	Creature token(s) in inventory at submission
Gather	Collect a named material to a specified quantity	Material in inventory matching spec at submission
Delivery	Carry a specified item to a named NPC or drop point	Item delivered within the time window
Escort	Guard a named cargo route leg	Escorted entity reached destination at or above condition threshold
Survey	Map a specified zone above minimum coverage	Map data logged for the zone above threshold

Escrow: Coin is locked at posting time. On successful completion the coin transfers to the claimant. On expiry without completion, coin returns to the poster minus a 5% posting fee. The fee is never refunded even if no one claimed the order.

Duration: 1–7 days, set by the poster. Longer windows increase visibility but increase posting fee by 0.5% per additional day beyond day 1.

Rank gate: The poster can specify a minimum Hall rank. Any character at or above that rank can claim.

Logistics Layer¶

Physical transport is what makes regional prices meaningful.

Caravan Shipments¶

Bulk goods moving between Trevalkaan and a village, or between Trevalkaan and a march ring site, travel as a shipment. A shipment is a cargo record attached to an expedition.

Shipment rules: - A player physically carries the shipment as part of a Caravan or Escort expedition - The cargo is locked into the expedition snapshot at departure - If the expedition fails, the cargo is lost (partial recovery depending on failure severity) - On successful delivery, the cargo is released at the destination's warehouse or NPC receiving point - NPC caravan legs exist as a baseline flow, but player-run shipments are faster, cheaper at normal conditions, and more reliable during crises

Shipment transit time is determined by the expedition resolution model — it is the expedition duration, not a separate timer.

Pack Animal and Wagon Capacity¶

The Back slot expedition pack governs personal carry capacity. Wagons expand cargo capacity significantly but require the Caravan Handling skill and draft animal care costs (mount feed is consumed throughout the journey).

Transport type	Cargo slots	Speed	Notes
Personal pack (expedition pack)	15–35 (by quality)	Full expedition speed	No additional handling required
Pack animal (donkey, mule)	+20–30	Road speed or slower	Requires Animal Handling Familiar+
Light wagon	+60	Road speed only	Requires Caravan Handling Practiced+; impassable on wilderness trails
Heavy wagon	+120	Road speed, reduced	Requires Caravan Handling Skilled+; impassable on non-road terrain

Warehouse Storage¶

Trevalkaan's exchange warehouse holds items for a daily storage fee of 1 coin per 5 item slots used. Items held in warehouse do not expire from the player's inventory. Sell orders can be posted directly against warehouse-held stock without the player being present.

Villages do not have exchange warehouses. Goods stored in village NPC storage are held specifically for the delivery system (crafters hall commissions, village aid orders) and cannot be listed on the Trevalkaan exchange without physical transport.

NPC Demand Integration¶

Town needs appear in the market as real demand pressure through the daily settlement tick. When Trevalkaan's food reserve enters Strained band, the settlement tick raises the staple food buy price index and may generate NPC standing buy orders at elevated prices, drawing supply in from the market.

NPC standing orders are automatically generated by the settlement tick and appear as buy orders on the exchange. They do not expire during the reserve crisis that generated them, but they are cancelled when the reserve band recovers to Stable.

Dynamic events act as short-lived demand multipliers via the event multiplier in the price model. A plague spikes medicine prices and may generate an emergency NPC buy order above the normal index. A bridge collapse raises timber and stone prices and generates a standing order for construction materials.

Common materials stay economically alive through this mechanism. Timber, cloth, leather, salt, fuel, wax, rope, barrels, and iron fittings all have reserve classes that generate NPC demand pressure during crises.

Technical Model¶

Core Market Records¶

Store:

market_order — sell and buy order records; includes quantity, price, expiry, fill state
market_fill — individual fill events against an order; partial fills create multiple records
auction_lot — single-lot auction state; includes reserve, current bid, extension count
auction_bid — individual bids per lot with timestamp for anti-sniping check
contract_post — player-authored contract; includes escrow reference and proof requirements
contract_escrow — locked coin record tied to a contract or auction bid
shipment — cargo record attached to an expedition; resolved on expedition settlement
warehouse_hold — items held in exchange warehouse with daily fee tracking

Coordinators¶

Use one exchange coordinator for Trevalkaan. That coordinator handles order matching, fill settlement, auction timing, anti-sniping extension logic, and anti-duplication locking. Use optimistic concurrency with version fields on market_order to prevent double-fill races.

Price Index Records¶

Store a market_price_index record per item type per settlement. Update it on the daily settlement tick. The rolling formula uses snapshot fields for current index, instant index, and the five contributing multipliers — store them separately so diagnostics and the event system can read contributing factors without re-running the formula.

Shipment Flow¶

When a player accepts a caravan or escort expedition, the cargo is locked into a shipment record with the expedition id. Settlement of the shipment happens at expedition resolution:

Full success: cargo released at destination warehouse or NPC point
Partial failure: cargo recovered at a percentage (expedition resolver determines this)
Full failure: cargo lost; expedition result log records the loss for dispute review

Events can modify route multipliers mid-expedition only if the expedition resolver re-evaluates at the route segment level. This creates situations where a road that closed during the expedition affects the final outcome without breaking the async model.

Contract Validation¶

Contract completion references server-validated sources only. A gather contract counts items only if they came from valid extraction sources that match the zone and material spec. A survey contract completes only if the route or site entry was genuinely discovered or confirmed by the expedition resolver. The proof system is identical to the Hall order proof system — see work-order-board.md.

Client Screens¶

The market is accessible from the Trevalkaan location hub. Characters who are not physically in Trevalkaan can view the market in read-only mode (browse prices, check their own listings) but cannot post, bid, or collect while away. Full participation requires the character to be present or to have items pre-staged in warehouse hold.

Route: /location/trevalkaan/market

Tabs¶

Tab	Who can use	Description
Browse	Anyone	View all active sell orders; search, filter, sort
Buy Orders	Trade ≥ Familiar	View and post buy orders
Auctions	Trade ≥ Practiced	View and bid on active auctions
My Listings	Anyone	Your active orders, their fill status, and pending coin
Warehouse	Anyone	Items in warehouse hold; collect or extend hold

Browse Tab¶

Search bar — free-text search by item name. Results filter as-you-type, minimum 2 characters.

Category filter — collapsible category tree matching market_category schema field: - Food → Raw / Preserved / Meals - Materials → Metal / Cloth / Leather / Wood / Stone / Reagents - Gear → Weapons / Armor / Tools / Accessories - Consumables → Medicine / Rations / Buffs - Maps & Knowledge - Other

Sort options (single active sort): - Price: Low to High (default) - Price: High to Low - Quantity: Most - Recently posted

Shortage badge — if a market category is in a Strained or Failing reserve band for the current town, a small amber warning tag appears next to the category label: Shortage: Food. This is driven by the KV town snapshot and updates on next snapshot refresh.

Sell order row (each result):

[Item icon] [Item name]        [Quantity available]   [Price per unit]   [Post date]   [Buy button]

Clicking an item name expands an inline detail panel showing: - Full item description - 7-day price sparkline (from market_price_index history) - Current market index vs. this listing's price (above/below index indicator) - All active sell orders for this item sorted by price

Partial buy — the Buy button opens a quantity selector modal. Player selects quantity (up to the order's available units), sees total cost and any applicable taxes, then confirms. Confirmation is irreversible; coin is deducted immediately.

Buy Orders Tab¶

Lists all active buy orders posted to the market. Sellers can fulfill a buy order by delivering matching items to the exchange warehouse.

Post Buy Order button opens a modal: 1. Search and select item 2. Enter desired quantity 3. Enter maximum price per unit (shown alongside current market index for reference) 4. Confirm — coin is locked in escrow immediately

A buy order displays to sellers as:

[Item icon] [Item name]    Wants: [quantity]    Max price: [price]    Posted: [date]    Fulfill button

A seller who fulfills a buy order delivers items directly from their inventory. The escrow coin releases to the seller; items transfer to the buyer's warehouse hold.

Auctions Tab¶

Lists active auction lots, sorted by time remaining (soonest ending first).

Auction lot card:

[Item icon] [Lot name and description]
Current bid: [amount]   Reserve: [met / not met]   Ends: [countdown]   Bids: [count]
[Place Bid button]

Placing a bid opens a modal with the current bid shown and a minimum increment. The player enters their bid amount (≥ current bid + minimum increment). If the bid arrives within 5 minutes of the auction end time, the end time extends by 5 minutes (anti-sniping rule, applied once per extension event).

A player with an active bid sees a Your bid indicator on the lot card. If outbid, a notification fires in the message log: "You have been outbid on [item name]."

My Listings Tab¶

Shows all sell orders, buy orders, and auctions posted by the current character.

Sell order row:

[Item name]   Posted: [qty]   Filled: [qty]   Remaining: [qty]   Status   Expires   [Cancel]

Status options: Active / Partially Filled / Expired / Pending Pickup

Cancelling a sell order returns unsold items to warehouse hold. The 3% listing fee is not refunded.

Pending Coin — a summary row at the top shows coin awaiting collection from filled orders. A single "Collect All" button triggers the coin transfer in one action.

Order extension — an Extend button appears on orders with ≤ 24 hours remaining. Extension costs 1% of the order's total ask value (calculated on the extended portion only). One extension per order.

Warehouse Tab¶

Shows items held in exchange warehouse hold.

Hold row:

[Item icon] [Item name]   Qty   Daily fee   Days held   Expires in   [Collect] [Move to Market]

Collect — transfers the item stack to the character's inventory (must be at the market location).

Move to Market — opens the Post Sell Order modal prefilled with this item. Skips the step of collecting to inventory first.

Storage fee is shown as a cumulative daily debit. The Warehouse tab displays total outstanding fees and the date they were last settled. Fees deduct automatically on the daily settlement tick.

Items not collected within 72 hours of a sell order fill expire from warehouse hold. Items not collected within the warehouse storage period (default 14 days) expire and are lost. A 48-hour expiry warning appears in the message log.

Post Sell Order Flow¶

Accessible from Browse tab ("Post New Listing" button) or Warehouse tab ("Move to Market"):

Select item — if posting from inventory, a filtered inventory picker appears. If posting from warehouse, item is pre-selected.
Set quantity — slider + input, bounded to available stack
Set price per unit — number input with market index shown alongside for reference: "Current index: 42 coin"
Preview — shows total potential revenue, listing fee (3%), and net-of-fee amount
Confirm — order posted; listing fee deducted immediately; item moved from inventory/warehouse to order hold

town-simulation-and-supply.md — reserve bands, settlement tick, NPC demand formulas
gathering-and-resource-ecology.md — raw material sources and yield model
agriculture-food-and-water.md — farming output and food supply chain
guilds-clans-and-town-control.md — guild tax rules and town treasury flow
exploration-cartography-and-resource-discovery.md — map sales and knowledge economy
work-order-board.md — unified board item and proof-of-completion model
tech/expedition-acceptance-and-settlement-model.md — expedition settlement that resolves shipments