Black Market¶
Status: 🚧 Partial. The single-port-class contraband trading loop is shipped: a standalone illicit-commodity catalog (
services/gameserver/src/core/illegal_commodities.py), a server-authoritative trade service with a gated catalog, haggle-priced buy, and sell-with-detection (services/gameserver/src/services/contraband_service.py), and three player-facing routes (services/gameserver/src/api/routes/black_market.py). Built: the RECOGNIZED Fringe-Alliance access gate, thebase_price × category_multiplier × personality_modifierprice, a detection roll, severity-scaled confiscation and fines, theis_suspect/is_wantedheat flip, and Federation plus other-faction reputation deltas. Still design-only: Shadow-Syndicate fence venues, credit laundering, hidden-sector / abandoned-outpost discovery and the broader venue-spawning flow, stealth-route multipliers and Stealth Systems equipment, counterfeit goods, and bounty placement. Per-section markers below distinguish the shipped loop from the design-only remainder.
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:
- Smugglers moving illegal commodities — weapons, restricted tech, contraband substances — at large margins.
- 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 Capital Sector welcome hubs that issue pioneer migration contracts). Additional venue types:
| Venue | Where | Discovery |
|---|---|---|
| Class-0 Black Market station | Frontier zone, Fringe Alliance territory | Faction-rep gating + NPC tip-offs |
| Hidden sector | Sectors with no entry in standard navigation tables | Long-range scans, exploration discovery |
| 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, sector cataloguing |
Discovery is gated. A new player does not see black-market stations on the galaxy map. Access opens by:
- Reaching RECOGNIZED tier (≥ +50 with Fringe Alliance per
../gameplay/factions-and-teams.md#reputation-scale) — unlocks contraband access at Fringe-Alliance hubs. New players default to NEUTRAL and do not have access until they earn into RECOGNIZED through emergent action. - Earning Fringe-Alliance rep through emergent action (smuggling evasion, Suspect cycle survival, Cargo Wreck salvage at fence venues — see
../gameplay/factions-and-teams.md#reputation-triggers) until tip-off thresholds reveal hidden sector coordinates via NPC dialogue. - Buying intel from NPC fixers at any Class-0 Black Market station once the first one is found.
Status: 🚧 Partial. The access gate that opens contraband trading is shipped — a venue qualifies when Station.type == StationType.BLACK_MARKET and the player holds Fringe-Alliance (FactionType.OUTLAWS) reputation at the RECOGNIZED tier or above (services/gameserver/src/services/contraband_service.py _is_black_market_venue / _passes_rep_gate), and the catalog route returns a 404 below the gate so the venue's existence never leaks. Design-only: hidden-sector flags, abandoned-outpost repurposing, nebula-cluster occlusion, NPC tip-offs and fixer intel, and the galaxy-map venue-spawning that places these stations.
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.
Each catalog row carries a base_price, a category_multiplier (the contraband markup applied to base), a legal-severity tier (Light / Moderate / Severe — drives the fine multiplier and heat flip), and per-faction reputation deltas. The shipped values live in services/gameserver/src/core/illegal_commodities.py (ILLEGAL_COMMODITY_CATALOG).
| Commodity | Markup multiplier | Severity | Federation rep | Other faction effects |
|---|---|---|---|---|
| Weapons (military-grade) | ×2.00 | Severe | −150 per transaction | Mercantile Guild −10; Pirates +15 |
| Stolen goods (laundered cargo) | ×2.00 | Light | −50 per transaction | Mercantile Guild −25 |
Restricted tech (embargoed exotic_technology) |
×2.50 | Moderate | −100 per transaction | Astral Mining Consortium −10 |
| Contraband substances (exotic biotech, prohibited drugs) | ×1.80 | Moderate | −100 per transaction | — |
The shipped catalog keys other-faction deltas on factions that exist in the current FactionType roster (Federation, Mercantile Guild, Pirates, Astral Mining Consortium, and the rest). Deltas for factions not yet in the roster — Nova Scientific Institute and Frontier Coalition — are not applied; their rows above describe the target once those factions are seeded.
Status: 🚧 Partial. The catalog enum, metadata, and gating are shipped in services/gameserver/src/core/illegal_commodities.py. The Nova Scientific Institute and Frontier Coalition deltas await those factions joining the roster.
Pricing¶
Black-market prices ignore the standard supply/demand formula in trading.md. Instead:
black_market_price = base_price × category_multiplier × personality_modifier
base_priceis the legitimate-economy reference price for the commodity (or the Federation seizure-value, for items with no legal market).category_multiplieris the table value above (2.00for weapons,2.50for restricted tech,1.80for contraband substances).personality_modifiercomes from the haggling roll. Black Market is a distinct trader personality (suspicious, opportunistic, responds to shared-risk and discretion appeals); see./haggling.mdfor the personality model. Haggling weighs more here than at lawful ports — successful negotiation shifts price by a uniform ±25% (HAGGLE_SWING = 0.25) versus ±10% at Federation ports.
The shipped price is floored at 1 credit per unit so a deep haggle can never zero the price, and the roll is centered on 1.0 so the long-run mean is the posted base_price × category_multiplier. The roll is drawn from a cryptographically secure RNG (secrets.SystemRandom) for anti-cheat parity with the mining and haggling loops — the client cannot pre-compute the multiplier. The catalog endpoint quotes a fresh indicative price per row; the committed buy and sell each re-roll their own price under the row lock, so a quote never reserves a price.
Status: ✅ Shipped — services/gameserver/src/services/contraband_service.py (_unit_price, _personality_modifier).
Detection mechanics¶
The Federation runs a detection roll when a player sells contraband at a black-market venue.
Shipped detection probability function (services/gameserver/src/services/contraband_service.py _detection_probability) — three weighted terms over a base rate, each weight set to 1.0, clamped to [0.0, 0.95]:
P(detected) = base_rate (0.05)
+ cargo_term = clamp(total_illegal_value / cargo_capacity, 0, 1)
+ sector_term = clamp(1 − sector.security_level / 10, 0, 1)
+ rep_term = clamp(1 − personal_reputation / 1000, 0, 2)
clamped to [0.0, 0.95]
| Term | Input | Notes |
|---|---|---|
base_rate |
0.05 | Floor risk on any contraband sale |
cargo_term |
total_illegal_value / cargo_capacity |
Value-density of the whole hot hold (not just the line being sold), using each commodity's base_price; capacity comes from the Ship.cargo JSONB (default 50). Clamped to [0, 1] |
sector_term |
1 − sector.security_level / 10 |
Higher security_level (1–10) lowers risk; a low-security frontier sector raises it. A missing sector or NULL security reads as the mid default 5. Clamped to [0, 1] |
rep_term |
1 − personal_reputation / 1000 |
A more-negative personal_reputation (outlaw cred) raises risk: 1.0 at neutral, below 1 for a lawful player, above 1 for a notorious one. Clamped to [0, 2] so a maxed-out villain still cannot deterministically bust past the 0.95 ceiling on this term alone |
The roll is secrets.SystemRandom().random() < P(detected). The 0.95 ceiling guarantees no automatic capture even with a heavy contraband load in low-security space. A clean (undetected) sale nudges personal_reputation down by 2 (NOTORIETY_NUDGE_PER_SALE), which raises future detection probability through rep_term — heat is self-reinforcing.
This shipped formula is a three-term reduction of the broader detection model. The ship_visibility, transit_history, and evasion_skill terms, and the Stealth Systems multiplier under Stealth routes, have no inputs in the current code and are design-only. The reputation posture that drives rep_term is the personal-reputation axis per ADR-0062 E-F4 — detection keys on personal reputation, while faction reputation handles the transaction's secondary effects (Fringe-Alliance gain, Federation loss per the catalog).
Shipped failed-scan consequences. A detected sale voids the payout: the entire held quantity of all contraband is confiscated, a severity-scaled fine is levied, the catalog's Federation and other-faction rep deltas apply, and the heat flag flips.
| Severity | Shipped consequences |
|---|---|
| Light (stolen goods) | Confiscation of all illegal cargo; fine of 2× confiscated value; Player.is_suspect flips true |
| Moderate (restricted tech, contraband substances) | Confiscation; fine of 3× confiscated value; catalog Federation rep delta; Player.is_suspect flips true |
| Severe (weapons) | Confiscation; fine of 4× confiscated value; catalog Federation rep delta; Player.is_wanted flips true (and is_suspect implicitly) |
The fine is clamped to the player's available credits — credits never go negative, and the unpaid remainder is unrecoverable on this path. A successful evasion keeps cargo and credits. Per-sector scan cooldowns, Stealth Systems, and obscuring-terrain multipliers are design-only (see Stealth routes).
Status: 🚧 Partial. The detection roll, confiscation, severity-scaled fines, and the is_suspect / is_wanted heat flip are shipped in services/gameserver/src/services/contraband_service.py (_detection_probability, _resolve_bust, _apply_heat). The ship_visibility / transit_history / evasion_skill terms, the temporary Federation-station ban, and the per-sector cooldown are design-only.
Faction reputation impact¶
Every black-market transaction triggers reputation deltas on commit. Targets below assume the moderate category; weapons apply the larger numbers in the contraband catalog above.
| Faction | Per-transaction delta | Notes |
|---|---|---|
| Terran Federation | −50 to −150 | 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 Mining Consortium | 0 to −10 | Restricted tech draws their ire; 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 inside the trade transaction. The shipped service applies the catalog's Federation delta plus every other-faction delta through the synchronous, flush-only apply_faction_rep_delta (services/gameserver/src/services/faction_service.py) — the async update_reputation is avoided because it commits mid-transaction and would break the caller-owned transaction. Deltas fire on a buy, on a clean sell, and on a bust. See ../gameplay/faction-lore.md for the broader faction-reputation system.
The shipped hooks apply only to factions in the current FactionType roster; the Frontier Coalition and Nova Scientific Institute rows above await those factions being seeded, at which point their catalog deltas apply automatically.
Status: 🚧 Partial. The Federation and roster-member faction deltas are shipped via services/gameserver/src/services/faction_service.py (apply_faction_rep_delta). The Frontier Coalition and Nova Scientific Institute deltas are design-only pending those factions joining the roster.
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.
Syndicate fence venues¶
Status: 📐 Design-only. Fence sub-ports do not yet spawn, the host-station flag is unset, and no service tab, laundering chain, counterfeit-flagging, or raid event exists in code. The Shadow Syndicate faction itself is 🚧 Partial — referenced in
services/gameserver/src/services/faction_service.pybut without venue infrastructure. Every mechanic below is target-state.
Concept¶
Shadow Syndicate operates through fence venues — sub-port operations embedded inside other-faction host stations rather than running their own visible hubs. A fence is not a station on the galaxy map; it surfaces as an extra tab in the host station's port UI. The tab is gated and is invisible to players outside the gate, so a law-abiding pilot docking at a fence-equipped station sees a normal port and nothing else.
Fences parallel the Class-0 Black Market sub-port pattern above: same idea of an illicit service layer attaching to the existing port-class system, but instead of a dedicated venue type, the operation hides behind a host station's faction storefront.
Visibility gate. The fence tab only renders when a player satisfies both:
Syndicate rep ≥ NEUTRAL— has at least made first contact with the Syndicate.personal_reputation ≤ 0— the player has accumulated enough criminal personal reputation that the Syndicate is willing to deal.
A player who clears the rep gate at any one fence is auto-granted a fence handshake credential, after which the tab appears at every fence venue galaxy-wide on dock. Losing the gate (Syndicate rep drops below NEUTRAL, or personal reputation rises above 0) hides the tab again until the gate is re-cleared. Status: 📐 Design-only.
Host station eligibility¶
Fences attach only to non-aligned or non-Federation-aligned host stations. The galaxy generator decides at world-generation time and stores the result on Station.has_syndicate_fence (see ../../DATA_MODELS/stations.md#station).
| Host faction / type | Eligible? | Notes |
|---|---|---|
| Mercantile Guild stations | Yes | Most common host — fences favour the volume |
| Frontier Coalition stations | Yes | Lighter oversight than Federation space |
| Astral Mining Consortium stations | Yes | Frontier-edge colonies, low-security |
| Independent / unaligned stations | Yes | |
| Terran Federation stations | No | Federation patrol coverage forbids |
| Nova Scientific Institute stations | No | Closed-loop research staff, no fence cover |
| TradeDocks (any faction) | No | NPC-only premium hubs; no embedded fence layer |
Approximately 8% of eligible stations carry a fence at galaxy generation. The flag is permanent for the life of the galaxy unless a Federation raid permanently shutters that fence (see Federation interdiction below). Status: 📐 Design-only.
Services offered¶
A fence venue offers four services through the gated tab. Every service triggers Syndicate-side reputation gain (+rep on commit, per the rep proposal in ../gameplay/factions-and-teams.md#reputation-triggers) and a corresponding hidden penalty against the host station's faction because the fence has parasitised that station's footprint.
| Service | Cost / payout | Faction rep effects | Time cost |
|---|---|---|---|
| Cargo fencing | Pays ~70% of market value, split 65/25/10 (player / fence operator / Syndicate) | Syndicate +5 / 5,000 cr fenced; host faction −1 / 5,000 cr fenced (hidden) | Instant |
| Credit laundering (3-hop chain) | 5% per hop, 15% total | Syndicate +20 per completed laundering chain | 6 real-time hours per hop, 18h end-to-end |
| Counterfeit equipment | Buy at ~60% of market | Syndicate +1 / 5,000 cr spent; Federation −10 per scanned counterfeit transaction | Instant at fence; flag lands on next Federation-port transaction |
| Bounty placement on Heroic+ target | 50,000 cr minimum (placer pays); Syndicate funds the payout | Syndicate +10 on placement; placer identity laundered | Instant placement; bounty open until collected |
Cargo fencing. Accepts any commodity carrying flagged_origin: true (Cargo Wreck salvage during the grace window, contraband moved without laundering, or stolen goods from raids). The fence pays roughly 70% of the legal market price and bypasses the host station's contraband scan, so the cargo never goes near a Federation egress check. The host faction takes a hidden reputation hit because the fence is operating on their dock; the host never sees the transaction.
Credit laundering. Converts flagged credits to clean credits through a 3-hop chain. The player picks two intermediate fence venues from any other fence-equipped stations they have handshake access to; the credits route Origin → Hop A → Hop B → Final, with each leg costing 5% (15% total). Each hop takes 6 real-time hours; the player can continue playing during the chain, but the credits are non-spendable until the chain completes. After the third hop, the resulting credits emerge with flagged_origin cleared. Status: 📐 Design-only — depends on the same transaction-graph store referenced in Payment and laundering above.
Counterfeit equipment. The fence sells fabricated equipment commodity at ~60% of legal market price. The counterfeit passes most port scans but trips a Federation tag on any subsequent transaction at a Federation-controlled port: each scanned counterfeit unit applies Federation rep −10 at sale time. Selling counterfeit at a non-Federation port is silent. Status: 📐 Design-only.
Bounty placement on Heroic+ targets. A player can place a player-bounty on any target at Heroic personal-reputation tier or above (see ../gameplay/ranking.md). The placer pays a 50,000 cr minimum placement fee to the fence; the bounty payout itself is funded by the Syndicate, not the placer. The placer's identity is laundered through the fence — collectors and Federation forensics see "Syndicate-issued bounty" rather than the placer's name. Status: 📐 Design-only.
Access mechanics¶
Entering a fence requires:
- The player is docked at a host station with
has_syndicate_fence = true. - The visibility gate is currently satisfied (Syndicate rep ≥ NEUTRAL AND personal_reputation ≤ 0).
- The player holds the fence handshake credential (auto-granted on first dock at any fence-equipped station with the gate cleared).
Once the handshake is held, the tab appears on every fence venue on dock without re-prompting. The handshake itself is invisible to Federation scans — it is a soft client-side flag, not a cargo manifest entry. Status: 📐 Design-only.
Federation interdiction¶
Federation Bounty Board occasionally raids fences. Raids are an ambient world event, not a player-triggered action.
| Raid mechanic | Value |
|---|---|
| Trigger frequency | ~1 raid per real-time week per fence (independent rolls per venue) |
| Fence closure on raid | 24 real-time hours (tab hidden, all in-progress laundering hops paused) |
| Player ambient hit | −5 personal_reputation for any player docked at the host station during the raid window who does not undock within the first 30 minutes |
| Permanent shutter chance | 5% per raid — has_syndicate_fence flips to false for the life of the galaxy |
| Cargo in transit | Laundering hops in progress at a raided fence resume on closure end; counterfeit inventory mid-purchase reverts to credits |
A raid does not fine the player or confiscate cargo on its own — the ambient hit is the entire mechanic for being seen at the venue. Players paying attention can undock the moment the raid alert fires and avoid the rep loss. Status: 📐 Design-only.
Cross-references¶
../gameplay/factions-and-teams.md#reputation-triggers— Syndicate rep deltas this section feeds.../gameplay/ranking.md— personal reputation tiers (Heroic+ bounty target gate; personal_reputation ≤ 0 visibility gate).../../DATA_MODELS/stations.md#station— thehas_syndicate_fencefield onStation.
Source map¶
| Concern | File | State |
|---|---|---|
| Contraband trade service (gated catalog, haggle buy, sell-with-detection, confiscation, fines, heat flip) | services/gameserver/src/services/contraband_service.py |
✅ Shipped |
| Illegal goods catalog (enum, metadata, severity tiers) | services/gameserver/src/core/illegal_commodities.py |
✅ Shipped |
Player-facing routes (GET /trading/black-market/{station_id}, POST .../buy, POST .../sell) |
services/gameserver/src/api/routes/black_market.py |
✅ Shipped |
| Faction-reputation hooks | services/gameserver/src/services/faction_service.py (apply_faction_rep_delta) |
✅ Shipped |
| Black-market trader personality | services/gameserver/src/models/station.py:TraderPersonalityType.BLACK_MARKET (enum exists; the ±25% haggle swing is applied in contraband_service.py) |
🚧 Partial |
| Black-market station type | services/gameserver/src/models/station.py:StationType.BLACK_MARKET (the access gate reads this; venue-spawning logic is design-only) |
🚧 Partial |
| Stealth-route multipliers, fence venues, laundering, counterfeit, bounty placement | design-only — no file yet | 📐 Design-only |
Status¶
🚧 Partial. The single-port-class contraband trading loop is shipped: the illicit-commodity catalog, the RECOGNIZED Fringe-Alliance access gate, the base_price × category_multiplier × personality_modifier price with a ±25% haggle swing, the detection roll, severity-scaled confiscation and fines, the is_suspect / is_wanted heat flip, and Federation plus other-faction reputation deltas, all behind three player-facing routes. Design-only: galaxy-map venue spawning and hidden-venue discovery, Shadow-Syndicate fence venues, credit laundering, stealth-route multipliers and Stealth Systems equipment, counterfeit goods, and bounty placement.
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.