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), three player-facing routes (services/gameserver/src/api/routes/black_market.py), and the player-client SpaceDock contraband UI on tip (SpaceDockInterface.tsx— catalog fetch, buy, sell, detection/heat viabmDetectedforBLACK_MARKETstations). 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, bounty placement, and the pirate/outlaw-outpost shipwright (see below) — greenlit as "go" by ADR-0093 item 34, with bounty/laundering rates provisional-flagged pending a balance-tuning pass (folded from ADR-0093, re-verified 2026-08-07). 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 are a Station.type == StationType.BLACK_MARKET value — orthogonal to (never derived from) the station's StationClass (Class 0–11) trading tier; a black-market station can carry any class. Central Nexus generation seeds these at a BLACK_MARKET_FRONTIER_CHANCE roll (~4%, a "handful" per the seeder's own comment) on ports in Frontier-zone clusters. Additional venue types:
| Venue | Where | Discovery |
|---|---|---|
| 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 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. Venue placement is shipped on two paths: Central Nexus generation seeds the ~4% Frontier-zone roll noted above (nexus_generation_service.py); player-owned (sw2102-bang-generated) regions place black-market venues via an explicit Port.black_market flag on the port manifest (bang schema ≥1.3.5), which bang_import_service.py maps to StationType.BLACK_MARKET — see ../../OPERATIONS/bang-integration.md. Design-only: hidden-sector flags, abandoned-outpost repurposing, nebula-cluster occlusion, and NPC tip-offs and fixer intel.
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's other-faction columns list only the keys that illegal_commodities.py actually applies (Federation plus Mercantile Guild / Pirates / Astral Mining Consortium in the table above). Nova Scientific Institute and Frontier Coalition are seeded in the live faction roster (create_default_factions / ../gameplay/faction-lore.md); they are not missing from the universe. Catalog rows still omit Nova/FC keys — that is a catalog residual, not an unseeded-faction claim. Do not copy comment-only magnitudes from the Python catalog into this table.
Status: 🚧 Partial. The catalog enum, metadata, and gating are shipped in services/gameserver/src/core/illegal_commodities.py. Nova/FC are roster-seeded; their commodity-delta keys are still omitted from that catalog pending a numbered canon pin.
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, and separately when a ship carrying contraband crosses INTO a higher-security sector during normal movement — the transit scan below. These are two independent detection sites sharing one consequence engine.
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 and the temporary Federation-station ban are design-only. The per-sector cooldown is shipped but PROVISIONAL — see Transit scan.
Transit scan¶
Status: ✅ Shipped (WO-K2). A second, independent customs-detection site fires on ordinary ship movement, not just a black-market sale — a ship carrying contraband can be busted mid-transit, with no venue and no sale involved. Shipped in contraband_service.py (scan_in_transit / scan_in_transit_best_effort), wired from services/gameserver/src/services/movement_service.py (_roll_contraband_transit_scan, ~lines 713-800, invoked from the movement paths at ~lines 1185, 1219, 1259).
Trigger conditions (scan_in_transit, contraband_service.py:755-909), evaluated cheapest-first, every gate before any lock is taken:
- Both origin and destination sector ids are known, and the sector actually changed.
- The ship's hold contains at least one enabled
illegal:*line (an unlocked pre-check keeps the overwhelmingly common clean-hold jump off the lock entirely). destination.security_level > origin.security_level— the scan fires only when crossing INTO tighter space, mirroring the brief's directionality; equal or looser security triggers nothing. A missing/NULLsecurity_levelreads as the mid default5on both sides, so an unseeded sector pair can never manufacture a scan.- The per-destination-sector cooldown has not been burned (see below).
Four relocation paths bypass the normal committed-movement hook and are covered by the SAVEPOINT-scoped scan_in_transit_best_effort wrapper instead, so the scan rides the caller's own commit rather than owning one: quantum jump, slipdrive, carrier hangar ride-along, and tractor-tow ride-along.
Detection probability (_transit_detection_probability) reuses the sell-side model's base rate, weights, and clamps verbatim, with only the sector term's polarity flipped (the sell model rewards low-security venues; transit is the opposite — dense customs at the destination's HIGH security):
P(detected) = base_rate (0.05)
+ cargo_term = clamp(total_illegal_value / cargo_capacity, 0, 1)
+ sector_term = clamp(destination_security / 10, 0, 1) <-- flipped vs sell
+ rep_term = clamp(1 − personal_reputation / 1000, 0, 2)
clamped to [0.0, 0.95]
total_illegal_value is scored over the ENTIRE hold, not a single traded line — there is no "commodity being sold" on this path.
Confiscation and fine. Because a transit scan sweeps the whole hold rather than one negotiated sale, consequences key on the single WORST piece of contraband aboard (_worst_held_meta — highest IllegalSeverity, ties broken by highest held value then by a deterministic enum-value tiebreak, never dict-iteration order). The bust itself runs through the SAME _resolve_bust engine the sell-side detection uses (reason="contraband_transit_scan", vs "black_market_bust" for a venue sale, so the two sites stay distinguishable in the reputation history):
- All
illegal:*cargo lines are confiscated (not just the worst one) and stripped fromShip.cargo. - Fine = total confiscated value × the worst commodity's severity multiplier (Light 2×, Moderate 3×, Severe 4× — the same table as a venue sale), clamped to the player's available credits.
- Heat flips per the worst severity aboard: Light/Moderate →
Player.is_suspect; Severe →Player.is_wanted(implies suspect). - Federation (+ other-faction) reputation deltas apply, keyed on the worst commodity's metadata.
- Unlike a clean SALE, a clean (undetected) transit scan does not nudge
personal_reputation— merely surviving a customs check is not a black-market transaction, and nudging here would let a player farm outlaw cred by pacing back and forth across a border.
Per-sector cooldown — 🚧 PROVISIONAL, unratified. One scan is charged per (player, destination sector) pair per traversal — bouncing back and forth across the same border cannot farm repeated rolls, but a genuinely new crossing always scans. The cooldown anchor (Player.last_contraband_scan_at / last_contraband_scan_sector_id) is stamped on BOTH a clean and a busted outcome, in the same transaction as the outcome it guards, so an undetected smuggler cannot re-enter and re-roll until the coin lands their way. The cooldown window itself, TRANSIT_SCAN_COOLDOWN_SECONDS = 900 (15 minutes), is a self-flagged provisional placeholder awaiting a canon ruling (contraband_service.py:183, tagged [OPEN-9] in-code) — it is deliberately short, sized only to outlast an immediate there-and-back bounce, and is expected to change once ratified. Do not treat 900s as a tuned balance number.
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 the catalog's Federation delta plus every other-faction key the catalog actually lists. Frontier Coalition and Nova Scientific Institute are seeded factions; the per-transaction rows for them in the table above are target flavor, not live catalog keys, until a numbered pin adds those keys. Stale Python catalog comments that still deny those factions exist should be ignored — do not copy comment-only magnitudes into this table.
Status: 🚧 Partial. Federation and listed roster-member catalog deltas are shipped via services/gameserver/src/services/faction_service.py (apply_faction_rep_delta). Nova/FC deltas remain omitted from the catalog (not because the factions are unseeded).
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 — greenlit for build. 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; the bounty/laundering/fencing/counterfeit rates in Services offered are implementer-proposed and flagged provisional, pending a balance-tuning pass.
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 Black Market venue pattern above: same idea of an illicit service layer attaching to the existing station 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.
Pirate / outlaw outpost shipwright¶
Status: 📐 Design-only (Cycle-46 WO-CANON-DRAFT-PIRATE-OUTPOST-BLACKMARKET-SHIPWRIGHT). Named only as a parenthetical on the ./docking-slips.md Pirate/outlaw outpost slip row today — this section is the first mechanics kernel so a later build WO has numbers to argue with. All magnitudes below are provisional pending a Max balance pass (same posture as other black-market design-only tables).
Intent¶
Pirate and outlaw outposts are too small for a TradeDock shipyard (0 construction slips on the docking-slips table). The black-market shipwright is a cramped yard that lets Fringe-facing players repair, refit, and — at a steep premium — commission a short list of hulls without entering lawful TradeDock space. It is not a Tier-B/A TradeDock substitute: no Warp Jumper, no Carrier, no specialized slips, no multi-week reservation queue.
Unlock / venue¶
| Gate | Provisional rule |
|---|---|
| Host station | Station typed as pirate/outlaw outpost (or a black-market venue hosted on one) — exact StationType discriminator TBD when outpost typing is unified |
| Player access | Same Fringe-Alliance (OUTLAWS) RECOGNIZED gate as contraband trading; below gate the shipwright UI 404s (existence never leaks) |
| Discovery | Follows black-market venue discovery — no map pin for new players |
Slip inventory (provisional)¶
| Slip class | Count | Notes |
|---|---|---|
| Transient | 6 | Already on docking-slips pirate/outlaw row |
| Long-term mooring | 2 | Already on that row |
| Construction (shipwright) | 2 | Replaces the table's "0 (…future tier)" placeholder when this tier ships |
| Specialized construction | 0 | Never — no Carrier / Warp Jumper |
Hold time for an active build: 3–7 real-time days (vs TradeDock 3–14 / 7–17). Queue depth target: 0–2 reservations; FIFO + deposit, no priority-bump tiers (keep the premium in the price, not the queue).
Catalog (provisional)¶
Buildable hulls — the four cheapest TradeDock standards only:
| Hull | vs TradeDock total_cost | Rationale |
|---|---|---|
| Scout Ship | 1.5× | Escape / scout for outlaws |
| Fast Courier | 1.5× | Smuggler-shaped logistics |
| Light Freighter | 1.6× | Contraband hauling |
| Defender | 1.75× | Escort / pirate-hunting counter |
Explicitly excluded: Cargo Hauler, Colony Ship, Carrier, Warp Jumper (and any future capital hull). Resource bundles mirror TradeDock ratios for the allowed hulls; exotic rares (Lumen / Quantum) are not required for this catalog.
Economics (provisional)¶
- Deposit: 15% of quoted total (vs TradeDock 10%) — non-refundable restocking on cancel before keel.
- Slip rent while building: 3,000 cr/day (between transient and Tier-B construction rates on docking-slips).
- Guest fee: none beyond the Fringe rep gate (outposts are the home yard for this audience).
- Revenue split: same TradeDock / port 40/30/30 fee distribution when the host is player-owned; NPC outlaw hosts sink the owner leg into operating (matches unowned-port realization).
Open questions (do not invent in code)¶
- Is the shipwright a flag on an existing pirate/outlaw outpost, or a distinct
StationType/ venue tab? - Do Federation scans treat an in-progress outlaw build as contraband heat, or only the finished hull's registry?
- Can team treasuries fund builds here (TradeDock yes) or player-only?
Player-facing affordances¶
- ✅ SpaceDock contraband UI at BLACK_MARKET stations —
SpaceDockInterface.tsxfetchesGET /api/v1/trading/black-market/{stationId}, posts buy/sell, and surfaces detection bust feedback viabmDetectedstate;BlackMarketButtonrenders when the docked stationtype === 'BLACK_MARKET'(origin/feat46bce720). - ✅ RECOGNIZED Fringe-Alliance rep gate — server returns 404 below the gate (
contraband_service.py_passes_rep_gate); client treats a failed catalog fetch as closed (no venue leak). - 📐 Shadow-Syndicate fence tab — no player-client fence tab or handshake UI on tip (see Syndicate fence venues).
- 📐 Credit laundering, counterfeit goods, fence bounty placement — design-only per Payment and laundering and Services offered; no player routes or components on tip.
- 📐 Hidden-sector / abandoned-outpost discovery and NPC fixer intel — design-only per Locations; no map pins or fixer UI on tip.
- 📐 Pirate / outlaw outpost shipwright — design-only per Pirate / outlaw outpost shipwright; no shipwright venue on tip.
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 |
| Transit customs scan (movement-path detection, shared bust engine, per-sector cooldown) | services/gameserver/src/services/contraband_service.py (scan_in_transit, scan_in_transit_best_effort, _transit_detection_probability) + services/gameserver/src/services/movement_service.py (_roll_contraband_transit_scan) |
✅ Shipped, 🚧 cooldown window [OPEN-9] provisional |
| 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 |
| Player UI — SpaceDock contraband | services/player-client/src/components/spacedock/SpaceDockInterface.tsx (catalog / buy / sell / bmDetected heat modal; 404 gate surfaced as closed) |
✅ Shipped on tip 46bce720 (LEG-275 closed as already-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 and the tip SpaceDock contraband UI (SpaceDockInterface.tsx). A second, independent detection site — the transit scan — fires on ordinary movement into higher-security space, sharing the same confiscation/fine/heat engine; its per-sector cooldown window is still provisional ([OPEN-9]). 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.