Black Market

Status: 📐 Design-only. No black-market service code exists yet. The BLACK_MARKET enum value lives in models/station.py:StationType and is referenced by the haggling-personality enum, but no contraband logic, no Federation scan service, and no illegal-commodity catalog have been built. Every section below describes the target design.

Overview

The black market is the parallel trading layer for goods the Terran Federation has criminalised. It runs out of hidden or semi-hidden hubs in Frontier-zone fringes, Fringe Alliance space, and certain nebula-shrouded clusters. Two kinds of player rely on it:

1. Smugglers moving illegal commodities — weapons, restricted tech, contraband substances — at large margins.
2. Outlaws with Federation reputation too low to dock at lawful ports, using the black market as their fallback supplier of legal goods at penalty pricing.

Black-market activity carries faction-reputation consequences and active detection risk. It is not an alternate trading lane that runs parallel to legal trade — it is opposed to it.

Locations

Black-market venues attach to the existing port-class system as Class-0 Black Market stations (a sub-classification of Class-0; distinct from the Class-0 Sol-style hubs that sell colonists). Additional venue types:

Venue	Where	Discovery
Class-0 Black Market station	Frontier zone, Fringe Alliance territory	Faction missions, NPC tip-offs
Hidden sector	Sectors with no entry in standard navigation tables	Mission rewards, exploration scans
Abandoned outpost	Decommissioned OUTPOST stations now repurposed	Random encounter, faction intel
Nebula-shrouded cluster	Sectors with NEBULA special type that occlude long-range scans	Local rumour, mapping missions

Discovery is gated. A new player does not see black-market stations on the galaxy map. Access opens by:

• Reaching Neutral (0–24) reputation with the Fringe Alliance — unlocks contraband access at their hubs.
• Completing pirate or smuggler-faction missions that reveal hidden sector coordinates.
• Buying intel from NPC fixers at any Class-0 Black Market station once the first one is found.

Status: 📐 Design-only — no station type, sector flag, or discovery flow is implemented.

Illegal goods catalog

Contraband sits outside the standard commodity table (see trading.md § Pricing model). Each entry has its own base price, margin multiplier, and faction-rep impact per transaction.

Commodity	Margin vs. base	Federation rep	Other faction effects
Weapons (military-grade)	+200%	−150 per transaction	Mercantile Guild −10; Pirates +15
Stolen goods (laundered cargo)	+100%	−50 per transaction	Mercantile Guild −25 (originator faction)
Restricted tech (embargoed exotic_technology)	+150%	−100 per transaction	Nova Scientific Institute −75; Astral Pioneers −10
Slaves / bondservants (off-channel colonists)	+250%	−300 per transaction	Astral Pioneers −150; Frontier Coalition −50
Contraband substances (exotic biotech, prohibited drugs)	+180%	−100 per transaction	Nova Scientific Institute −50

The legacy spec only enumerated the headline category ("weapons, contraband"); the five-row breakdown above is design extrapolation consistent with the faction system.

Status: 📐 Design-only. Target enum: services/gameserver/src/core/illegal_commodities.py.

Pricing

Black-market prices ignore the standard supply/demand formula in trading.md. Instead:

black_market_price = base_price × category_multiplier × personality_modifier

• base_price is the legitimate-economy reference price for the commodity (or the Federation seizure-value, for items with no legal market).
• category_multiplier is the table value above (2.00 for weapons, 2.50 for slaves, etc.).
• personality_modifier comes from the haggling roll. Black Market is a distinct trader personality (suspicious, opportunistic, responds to shared-risk and discretion appeals); see ./haggling.md for the personality model. Haggling weighs more here than at lawful ports — successful negotiation can shift price by ±25% versus ±10% at Federation ports.

Status: 📐 Design-only.

Detection mechanics

The Federation runs egress scans on traffic leaving sectors flagged as black-market venues, and (with lower probability) on traffic entering Federation-controlled space carrying contraband.

Detection probability function (target: sector_security_service.py:detect_contraband):

P(detected) = base_rate
            + cargo_factor      # contraband mass / total cargo capacity, weighted by category severity
            + reputation_factor # lower Federation rep → more scrutiny
            + sector_security   # sector's security_level field, 0.0 (Frontier) to 1.0 (Federation core)
            + patrol_factor     # +0.10 per Federation patrol ship in sector
            − stealth_factor    # −0.25 if Stealth Systems equipment installed
clamped to [0.0, 0.95]

Failed scan consequences (escalating with severity):

Severity	Consequences
Light (stolen goods only)	Fine of 2× cargo value; cargo confiscation
Moderate (restricted tech, contraband substances)	Fine + confiscation + Federation rep −100
Severe (weapons, slaves)	Fine + confiscation + rep −300 + temporary ban from Federation stations

A successful evasion has no effect — the player keeps cargo and reputation. Repeat scanning is gated by a per-sector cooldown so that traversing the same sector twice does not double-roll.

Status: 📐 Design-only. Target service: services/gameserver/src/services/sector_security_service.py.

Faction reputation impact

Every black-market transaction triggers reputation deltas on commit. Targets below assume the moderate category; weapons and slaves apply the larger numbers in the contraband catalog above.

Faction	Per-transaction delta	Notes
Terran Federation	−50 to −300	Severity by commodity (see catalog)
Mercantile Guild	−10	Penalises grey-market competition with legal trade
Frontier Coalition	+5	Aligned with autonomy from Federation oversight
Fringe Alliance	+25	Their economy depends on this lane
Astral Pioneers	0 to −150	Slaves attract their full wrath; everything else is neutral
Nova Scientific Institute	0 to −75	Restricted tech and contraband substances; otherwise neutral
Pirates	+15	Mutual interest in undermining Federation control

Reputation hooks fire on transaction commit. See ../gameplay/faction-lore.md for the broader faction-reputation system.

Status: 📐 Design-only. Target service: services/gameserver/src/services/faction_service.py (existing — black-market hooks land here).

Stealth routes

Routing through obscuring sector types reduces detection probability. The sector_security and patrol_factor terms drop in:

• NEBULA sectors — occlude long-range scans (sector_security × 0.5 inside).
• ASTEROID_FIELD sectors — break line-of-sight for patrol ships (patrol_factor × 0.5).
• BLACK_HOLE sectors — patrol ships avoid them (patrol_factor = 0); cargo damage risk applies separately.

Stealth Systems equipment (target: ship-systems spec) provides a flat −25% on P(detected) while installed. Its presence is itself flaggable in higher-security sectors, so equipping Stealth in Federation core space is a separate risk vector.

Recommended traversal: enter the black-market venue → load contraband → exit through a NEBULA-tagged warp link → traverse Frontier-zone hops with low security level → only cross into Federation space after the cargo is sold or laundered.

Status: 📐 Design-only.

Payment and laundering

Black-market transactions settle in standard credits — there is no separate currency. The accounting flag is on the transaction record, not the credits themselves: every black-market trade writes a flagged_origin: true marker that Federation Security can subpoena via the contraband detection service.

Laundering routes flagged credits through legitimate trades to obscure origin:

• Run multiple legal trade hops before approaching Federation space.
• Use a Class-4/5 distribution-collection pair to break the audit trail (each leg removes the flag with diminishing probability).
• Federation forensics (target: contraband_service.py:trace_credit_origin) walks transaction history backwards. Each laundering hop reduces traceability by ~30%; three clean hops effectively launder the credits.

Status: 📐 Design-only — laundering is a stretch goal that depends on a transaction-graph store that does not yet exist.

Source map

All paths below are target locations. None of these files exist today.

Concern	Target file
Black-market detection / scan rolls	services/gameserver/src/services/contraband_service.py
Illegal goods enum	services/gameserver/src/core/illegal_commodities.py
Federation scan logic	services/gameserver/src/services/sector_security_service.py
Faction-reputation hooks (existing service, new code paths)	services/gameserver/src/services/faction_service.py
Black-market trader personality	services/gameserver/src/models/station.py:TraderPersonalityType.BLACK_MARKET (enum exists; behaviour does not)
Black-market station type	services/gameserver/src/models/station.py:StationType.BLACK_MARKET (enum exists; spawn / trading-pattern logic does not)

Status

📐 Design-only — entire system. Nothing here is shipped. The two enum values in models/station.py are the only surviving footprint; venue spawning, contraband catalog, pricing engine, detection rolls, scan consequences, laundering — all unbuilt.

Related

• ./haggling.md — Black Market trader personality (extreme haggling difficulty, prefers risk/discretion appeals).
• ./trading.md — main trading flow that the black market deviates from.
• ../gameplay/faction-lore.md — faction reputation system and per-faction modifiers.
• ../galaxy/sectors.md — special sector types (NEBULA, ASTEROID_FIELD, BLACK_HOLE) that hide black-market activity from scans.