A Kotlin Multiplatform library that is the shared brain of the DMarket P2P trade-tracker. One Kotlin codebase compiles to:
- JavaScript — consumed by the MV3 web extension (shipping today),
- an iOS XCFramework (target enabled on request),
- an Android AAR (target enabled on request).
It is the seller plugin core of DMarket's new P2P flow, where skins stay in users' Steam
inventories (not in DMarket custody). It heartbeats to the backend, executes device-leased
directives (create_offer / cancel_offer / report_inventory), watches both Steam trade axes,
and reports raw Steam status codes — plus TLSN proofs for decisive transitions on
proof_required deals. The buyer has no plugin (DMarket FE + Steam UI only). It contains no
UI — each open-source client provides its own native UI and links this core.
This is a clean-room implementation. The Steam JWT it uses is device-only and never sent to the DMarket backend — that audit boundary is why the clients are open-source.
- At a glance
- Architecture — the bulk of this document
- Build & run
- Installing
- Usage
- Testing
- Current limitations (v1)
- Docs
- License
| Language | Kotlin 2.4.10, Kotlin Multiplatform |
| Targets | JS (web extension — shipping) · iOS XCFramework · Android AAR (both on request) |
| Modules | :domain (pure, zero-IO) · :core (IO + platform glue) · :headless-js (the JS facade over :core's headless tracker, npm @dmarket/p2p-tracker-headless, not published yet) · :sdk-node (the Node shell over it, not published yet) · :debug-harness (dev-only, unpublished) |
| Backend contract | /exchange/v1/p2p/ext/ — heartbeat, trade-events, notary, trade-actions, inventory |
| Version | VERSION_NAME in gradle.properties (source of truth) |
| Coverage gate | :domain ≥70% (koverVerify), currently ~90%+ |
| HTTP | Ktor multiplatform (OkHttp / Darwin / JS-fetch per target) |
| License | MIT |
The system-level architecture & contract — the backend (
p2pTemporal service, exchange-gateway, notary) plus every FE/client and how they fit together — is tracked separately. This README covers this library's implementation of the client (seller-plugin) side.
The library is a small, strictly-layered core built around one idea: all decisions are a pure function; all side effects are ports. Everything below follows from that.
- Purity at the center. The decision logic (
:domain) performs no IO, reads no clock, and touches no platform API. It takes an immutable snapshot in and returns an immutable plan out. This is the audited surface, and it is unit-testable with zero mocks. - Side effects at the edge. Everything impure — HTTP, secure storage, OS scheduling, time — sits
behind a port (an interface in
:domain) and is implemented by an adapter (anactual/ class in:core, per platform). - The dependency arrow points inward.
:coredepends on:domain;:domaindepends on nothing platform-specific. Purity is compiler-enforced — there is no Ktor, nokotlinx-io, nochrome.*reachable from:domain. - The backend decides; the plugin executes. Every heartbeat returns
active_tracking[](deals to watch) anddirectives[](one-shot, device-leased commands). The client never decides what to create or cancel — it executes what the backend leases to it and reports each outcome. It forwards raw Steam status codes from both trade axes; the backend maps them and owns the deal state machine and the money. - Security by construction. The Steam credential is reachable only through Steam-facing ports;
no marketplace method can accept it. The two Steam write surfaces each build exactly one fixed
URL, so a confirm/
mobileconfendpoint cannot be reached even by mistake. See Credentials & the audit boundary.
┌─────────────────────────────────────────────────────────────┐
│ consumers: MV3 web extension · iOS app · Android app │
└───────────────┬─────────────────────────────────────────────┘
│ links / imports
┌───────────────▼─────────────────────────────────────────────┐
│ :core — IO + platform glue (depends on :domain) │
│ Ktor clients · loop driver · credential providers · │
│ expect/actual adapters · JS facade │
└───────────────┬─────────────────────────────────────────────┘
│ depends on (inward only)
┌───────────────▼─────────────────────────────────────────────┐
│ :domain — pure, zero-IO (depends on nothing platform) │
│ model · engine · policy · game · port (interfaces) · wire │
└─────────────────────────────────────────────────────────────┘
:headless-js — core's headless tracker as an ES module for Node.js hosts
(its own npm package); depends on :core; :core never depends on it
:sdk-node — the headless client: core's headless tracker on Node.js
depends on :headless-js; nothing depends on it
:debug-harness — dev-only: conformance probes + Chrome console
depends on :core; nothing depends on it; never published
| Module | What lives there | Purity |
|---|---|---|
:domain |
model/ (immutable types, enums, value-class ids, Deal/P2PDealState/Directive/TrackedDeal/TradeStatusReport), engine/ (the pure DirectivePlanner + TrackerTick + DecisiveTransitions + ProofFreshness + TerminalClassification), policy/ (CadencePolicy, ExponentialBackoff), game/ (GameAdapter, Cs2GameAdapter, GameRegistry), port/ (interfaces only), wire/ (@Serializable DTOs + mappers + TrackerJson), net/ (NetworkRedaction), config/ (TrackerConfig tunables). |
Pure, zero-IO. No Ktor, no platform APIs. Compiler-enforced. The audited surface. |
:core |
Ktor MarketplaceClient + SteamReadClient; the TradeTrackerLoop driver; SteamCredentialProvider / MarketplaceCredentialProvider + session refreshers; HeadlessTracker, the loop composed for a host with no browser (pushed Trading API key and Steam session, held in memory; proofs through a host-run prover, each notary upgrade signed with the key); expect/actual adapters (Scheduler, CredentialVault, Clock, HTTP engine); the @JsExport JS facade. |
IO + platform glue. Depends on :domain only. |
:headless-js |
:core's HeadlessTracker for a Node.js host, published on its own as @dmarket/p2p-tracker-headless: createHeadlessTracker({dataDir, …}), start / cycle / stop, pushTradingApiKey / pushSteamToken, trackerState, and the fixed strings a host matches events against. The host gets plain objects keyed by type, events as JSON strings, and a handle that is an empty frozen object; the pushed key and token stay inside the library, and so do the file store for each account's loop state (dataDir) and the prover processes: each proof runs in a prover-child.mjs forked from the package, whose pkg/ and transport/ carry the same pinned prover as @dmarket/p2p-tracker-core. Types are the package's handwritten index.d.ts. |
commonMain holds the prover IPC, its backoff and output redaction; jsMain the facade and the Node actuals. Built from this module alone: the extension's package carries none of it. Not published yet. |
:sdk-node |
The tracker for a trader's bot host on Node.js, with no browser and no UI, one process per Steam account. The loop, the pushed secrets and their rules are :core's HeadlessTracker: the bot pushes the DMarket Trading API key and a Steam access token with the web or web:community audience, both stay in memory, every DMarket call is signed with the key, a key for another DMarket account is refused with 409 DMARKET_KEY_ACCOUNT_CHANGED (switching accounts is a restart), and the Steam writes carry the session in explicit headers. The heartbeat says foreground: true only while the token has 40 minutes left, 10 more than a create needs, so a deal accepted while DMarket still counts the seller present gets its create; without a usable token it goes on with foreground: false and touches nothing on Steam. It beats 5 s inside the ttl DMarket advertises (not below 30 s), and reads Steam no more often than the browser does. State lives in <dataDir>/<linkedSteamId>/; steamWrites: false in the config sends no offer write; a create that never reached Steam is never reported FAILED, and one Steam did not answer (or answered EResult 16) is settled from the account's sent offers instead; a cancel is read from Steam's answer on any HTTP status and, when that leaves it open, from its offer's state, and one Steam did not answer whose offer cannot be read reports nothing; a 429 is honoured with Retry-After and a jittered backoff. This module is the shell around it: a local, bearer-protected management API (PUT /v1/dmarket/key, PUT /v1/steam/session, GET /v1/health), health with a closed problem vocabulary graded by severity (down — DMARKET_KEY_MISSING, DMARKET_AUTH_FAILED, CLOCK_SKEW, DMARKET_UNREACHABLE, STEAM_NOT_LINKED — answers 503; degraded and info (SDK_UPDATE_DUE) answer 200), structured logs, the config file and the entry point. Each TLSN proof runs the extension's wasm prover in a process forked per proof (prover in the config): the Steam token goes to it over IPC, the notary upgrade is signed with the key when the process asks and carries no bearer, a process that does not connect within 30 s or still proves 240 s after is killed, and an out-of-memory kill takes the process, not the SDK. |
commonMain is platform-free and unit-tested on the JVM and Node; jsMain holds the Node actuals (file storage for non-secret state, the HTTP listener, the entry point). Not published yet. |
:debug-harness |
Two things, split by whether they need a browser: C1ReportProbes + SecretRedaction (commonMain, platform-free, unit-tested) — the client half of a contract conformance check, one callable probe per report/write endpoint, so a backend can be verified against the real client and deserializer; and a dev-only Chrome MV3 debug console (createDebugSession / DebugSession, jsMain) that exposes those plus the live browser paths (scrape / refresh / vault / Steam + DMarket reads and writes). |
Dev-only. Never published (no publish config; the extension's npm package is built from :core alone, the headless one from :headless-js) and nothing depends on it, so none of this reaches a consumer. Must not expand :core's audited @JsExport surface. Diagnostics redact secrets by default — see below. |
:domain declares what the runtime needs as interfaces in
port/; :core provides the how
per platform. Each port has a web actual/implementation today and a safe default (usually a no-op),
so unimplemented platform seams keep compiling. The composition root
(TradeTrackerCore.createLoop)
wires the chosen adapters into a TradeTrackerLoop. See the ports table.
All decisions are two pure functions in
engine/. The runtime gathers
inputs through ports, calls the engine, and is then a dumb executor of the returned plan.
ports (IO) pure core (no IO, no clock) ports (IO)
┌───────────┐ heartbeat ┌──────────────────────────────────────┐ plan ┌───────────┐
│ heartbeat │ ──────────▶ │ DirectivePlanner.plan(hb, handled) │ ─────▶ │ execute + │
│ + observe │ │ • create / cancel / inventory scans │ │ report │
└───────────┘ observed │ TrackerTick.reduce(now, tracking, │reports └───────────┘
──────────▶ │ observed, reported) │ ─────▶ /trade-events
│ • changed-code reports + proofs │ + /notary
└──────────────────────────────────────┘
DirectivePlanner.plan(heartbeat, handled)filters the heartbeat'sdirectives[]down to what this tick should execute, partitioned into aDirectivePlan(creates/cancels/inventoryScans). It enforces single-flight — adirective_idalready in thehandledset is never re-executed — and classifies the rest: a malformed payload or an action this build does not know is never executed, but is answered on/trade-actions(malformed/unsupported) so its device lease is released instead of being re-served on every heartbeat.TrackerTick.reduce(now, activeTracking, observed, reported)is the pure change-detector for the watch loop: per tracked deal it compares the freshly observed raw Steam codes (both axes) against the last-reported baseline (ReportedStatus) and emits aReportPlan— oneTradeStatusReportper changed axis (raw code, no verdict — the backend maps it) plus aProofIntentwhen the deal isproof_requiredand the code is decisive (DecisiveTransitions— see its KDoc for the enforced places and the codes that reach them).ProofFreshness.due(tracking, progress)is the second, independent reason a proof is minted: the backend stamps aprove_aftermark on a deal's watch entry when its protection hold expires, and releases the payout only against a proof attested at or after it. A demand is deliberately not aProofIntentand not aTrackerTickconcern — it exists precisely when nothing changed, it carries no Steam status code (the proven read discovers it), and it is answered regardless ofroleorproof_required. Its per-deal standing — the greatest mark a verified proof satisfied, plus the backoff ladder for a refused one — persists alongside the two guards below.
Both idempotency guards persist behind
TrackerProgressStore
(handled directive_ids + per-deal ReportedStatus), durable across worker respawns.
Because the engine reads nothing but its inputs (not even a clock — now is supplied), a test is
just: construct a heartbeat, call the function, assert on the plan. No mocks, no fakes, no time
control.
TradeTrackerLoop is
the single place that coordinates every port into one full cycle (happy-path phases 2–4):
runOnce():
1. heartbeat POST /heartbeat {device_id, foreground, steam_id}
→ active_tracking[] + directives[] + ttl_seconds
2. execute DirectivePlanner.plan(heartbeat, handled) (pure)
create_offer → SteamOfferCreator (stops at NeedsConfirmation)
cancel_offer → SteamOfferCanceller
report_inventory → SteamInventoryReader → POST /inventory
each outcome → POST /trade-actions (releases the lease)
3. watch+report Steam reads (offerStatuses + recentTransfers) for active_tracking[]
TrackerTick.reduce(now, tracking, observed, reported) (pure)
changed raw codes → POST /trade-events
decisive + proof_required → NotaryProver → POST /notary
4. record persist handled directive_ids + per-deal ReportedStatus
5. reschedule arm the next wake (deal-watch cadence or next heartbeat, whichever is sooner)
Cycles are single-flighted by a mutex, so a scheduled wake and a delivered push can never run a
cycle concurrently (no double execute). Directive execution is additionally gated by
directivesEnabled — a launch gate that stays false until the backend device_id lease is live.
The loop has three entry shapes:
| Entry | Use |
|---|---|
suspend fun runOnce(): TickOutcome |
One full self-contained cycle (heartbeat + directives + watch/report). OS-driven platforms call it once per wake. |
fun start(scope): Job |
A continuous loop reacting to scheduled wakes and pushes from a single consumer. With the default NoOpPushChannel it is poll-only. |
suspend fun wakeFromPush(signal): TickOutcome |
Direct entry for a one-shot OS push callback (APNs/FCM); a push is just a nudge that runs one cycle now. |
On the web, the loop self-drives: startTracker arms a chrome.alarms wake-up that survives
MV3 service-worker teardown, runs one cycle per wake, and re-arms the single named alarm to the next
client-owned time (replace, never stack). See Usage.
The DMarket backend is reached over the trade-tracker REST endpoints (via the
exchange-gateway; base path /exchange/v1/p2p/ext/), modelled by
MarketplaceClient.
The backend derives the account from the Bearer token, so no request carries an account_id.
| Method | Endpoint | Purpose |
|---|---|---|
heartbeat(request) |
POST …/ext/heartbeat |
Presence + device_id; returns active_tracking[] + directives[] + ttl_seconds. The sole presence + work-dispatch call. |
reportTradeStatus(reports) |
POST …/ext/trade-events |
Batch raw steam_status_code ints (no proof); one TradeStatusResult per report. |
submitProof(proof) |
POST …/ext/notary |
A TLSN proof for a decisive transition (proof_required deals only). |
reportDirective(outcome) |
POST …/ext/trade-actions |
Report a directive outcome — a create_offer/cancel_offer result, or a refusal (unsupported/malformed). Either way it releases the Redis lease. |
reportInventory(report) |
POST …/ext/inventory |
The present-asset_ids snapshot; the backend computes the stale diff. |
acceptDeal(id) |
POST /p2p/deals/{id}/accept |
The seller COMMIT (applied=false if too late) — a DMarket app convenience, not part of the tracker's directive loop. |
getDeal(id) |
GET /p2p/deals/{id} |
A single deal snapshot (host convenience). |
The Ktor implementation
(KtorMarketplaceClient)
handles the {code, message} error envelope, 401-refresh-once (via the
authenticator), and 429 Retry-After (RateLimitedException).
- Identity is
deal_id. The canonical tracking key isDealId— the wire isdeal_id-centric. A Steam trade-offer is anOfferId, an item instance anAssetId, a Steam account aSteamId, and the install-scoped directive-lease key is aDeviceId. Ids are strongly typed value classes — never bare strings. The backend derives the account from the Bearer token (no request sends anaccount_id) and owns the deal state machine and the deal↔trade join. - No status decoding on the client. The client reads both Steam axes
(
SteamReadClientofferStatuses+recentTransfers) and forwards the raw codes asTradeStatusReports — the backend maps them and decides every deal transition. The client's only local classification is change-detection (TrackerTick) plus the fixed decisive set (DecisiveTransitions) for proof routing.
Cadence is client-owned, governed by
CadencePolicy:
- The deal-watch poll runs on FE-chosen poll classes clamped to per-surface/mode floors; the
heartbeat cadence is the
ttl_secondsreturned by the last heartbeat response (clamped to the surface floor and a safety ceiling). The loop arms the next wake to whichever is sooner. - Floors are per-surface/mode (asking iOS to wake every 60s while suspended is a lie the OS won't
honour, so the floor wins). The actual wake-up is the platform's own primitive (
chrome.alarms/ WorkManager / BGTaskScheduler) behind theSchedulerport. - Retries use full-jitter exponential backoff
(
ExponentialBackoff), applied in-call by the Ktor clients and tuned viaTrackerConfig.marketplaceRetry.
Two independent credentials flow through the library, kept strictly separate:
1. The Steam JWT — device-only, never transmitted to DMarket. This is the central security invariant and the reason the clients are open-source.
┌──────────────────────────────────────────────────────────────────────────────┐
│ Steam-facing ports ONLY (the JWT lives here, behind the boundary): │
│ SteamReadClient · SteamOfferCreator · SteamOfferCanceller · NotaryProver │
└──────────────────────────────────────────────────────────────────────────────┘
╳ no MarketplaceClient method accepts a SteamCredential ╳
┌──────────────────────────────────────────────────────────────────────────────┐
│ MarketplaceClient (DMarket) — only ever sees a SteamId, never the credential │
└──────────────────────────────────────────────────────────────────────────────┘
The credential is managed by
SteamCredentialProvider,
which composes three ports: a CredentialVault (device-local secure storage), a
SteamSessionScraper (re-acquire a fresh JWT from a logged-in session), and a
SteamSessionRefresher (keep the steamLoginSecure web session alive in the background). Freshness
is keyed on the JWT's exp (with a configurable skew). The vault defaults to the lib-owned
platformCredentialVault() (chrome.storage.local on web, Keychain / Android Keystore on native)
— so the host never sees the plaintext credential.
2. The DMarket marketplace JWT. Managed by
MarketplaceCredentialProvider
and attached via a pluggable
MarketplaceAuthenticator
strategy — how a DMarket request is authenticated is decoupled from the client so each platform
supplies the one path that fits it:
| Authenticator | Platform | Behaviour |
|---|---|---|
CredentialMarketplaceAuthenticator |
Web — the library owns auth | Reads the dm-trade-token cookie and refreshes it through the DMarket refresh API when it nears expiry (DefaultMarketplaceCredentialProvider), attaches it as the Authorization header raw — no Bearer scheme, which is what the gateway parses, and asks for one forced refresh on 401. |
CredentialMarketplaceAuthenticator over a host-supplied provider |
Mobile — the host owns refresh | Same authenticator, different provider: the app plugs its own token layer in through HostTokenMarketplaceCredentialProvider, so the library never runs a second refresh mechanism against the same rotating credential. |
TransportManagedMarketplaceAuthenticator (default) |
A host that authenticates inside its own transport | Attaches nothing and never retries. Note this is not the right choice for the DMarket Android app, which attaches Authorization per Retrofit method rather than via an interceptor. |
When either session is logged out the loop surfaces a signal-only flag — needsReLogin (Steam)
and needsMarketplaceReLogin (DMarket) — and never opens UI itself; the host shows login UI, and the
flag clears on the next successful scrape. Both axes additionally resolve into blockingState (the one
value a host renders): a DMarket logout as DM_SESSION_MISSING, and a Steam session that is
demonstrably gone (the session cookie has been deleted) as STEAM_SESSION_MISSING. A failed Steam
scrape on its own stays signal-only — it is equally what a Steam rate-limit, 5xx or page change looks
like, and must not be shown to the user as "you are signed out".
The only two Steam write surfaces are create and cancel — never confirm. Enforcement
is by encapsulation: each write actual builds only its one fixed URL
(…/tradeoffer/new/send for create, …/tradeoffer/{id}/cancel for cancel), so no
confirm / Guard-code / mobileconf endpoint can be constructed through these ports — there is no
code path that builds one. The hard, build-blocking rules:
- No auto-click of Steam's web Send button (DOM action).
- No Steam Guard / Mobile Authenticator code generation.
- No reading Steam's
identity_secret/shared_secret. - No POSTs to
mobileconfendpoints. - No annotation of non-DMarket trade offers.
These write-path URL suffixes are deliberately kept hardcoded (not in TrackerConfig) precisely
because a remote-tunable write path could reach a forbidden endpoint. The create write surface is
pending DMarket security sign-off.
TLSN proof generation ships behind a host-supplied proving context and stays inert until the
backend flips per-trade proof_required. Tracking itself is fully functional and independent of it:
a deal the backend has not flagged reports exactly as it would with no prover at all.
The notary is off unless the host supplies a proving context, and that is enforced in code, not by
convention. The real prover is selected on one condition: a host proof delegate. TrackerConfig.notary .notaryUrl is no longer part of that gate — it is required and defaults to the deployed production notary
— so what a host controls is whether a prover can run at all. Pass no delegate and the loop gets
NoOpNotaryProver
— no WASM prover runs, no notary socket opens, and the wss:// proxy default is inert. That is the state
of every caller that passes no prover (mobile today) and of Firefox, which cannot host one.
Proxy issuance is opt-in through TrackerConfig.notary.mode = "proxy" (headless/SDK: prover.mode).
For Worker egress, also set transport = "egress" in that same config and point notaryUrl at the
Worker frontend. Transport defaults to "direct"; egress requires proxy mode and egress-capable assets.
See the prover guide for routing and authentication.
It needs proxy-capable prover assets and an enabled, routed notary. It opens only the notary channel;
omitted modes keep MPC. See mode selection and candidate setup.
The prover ships inside the package (pkg/ + transport/, next to the library's ESM entry, taken at
build time from an exact-pinned release of
@dmarket/steam-provenance) but is
import()ed lazily on the first proof, so a build that never enables it never loads the ~10 MB
module. Hosting and bundling notes, the four seams a host outside the browser replaces (asset location,
compiled module, notary socket, target connector), and how the pin is verified and bumped:
core/PROVER.md.
Proof routing is driven by proof_required + the fixed decisive set
(DecisiveTransitions),
not a client capability. That file's KDoc is the authoritative table of enforced places and the Steam
codes that reach them; the codes are deliberately not restated here, because a second copy is what
drifts — and this one had. When a proof_required deal crosses a decisive transition, the loop asks
NotaryProver.proveTransition(binding, source, credential)
for the proof and POSTs it to /notary. A build that supplies no proving context gets
NoOpNotaryProver
instead — a stub presentation, which the backend rejects rather than settling on an unproven
settlement.
CS2 only at v1, but appid=730 is never hardcoded. Everything Steam encodes per-title — the
inventory context id, app-id ownership — lives behind
GameAdapter.
GameRegistry.v1() enables CS2 only; turning on Dota2/TF2/Rust is registering an adapter and
flipping the enabled set — a config change, never an engine edit. The adapter matters for the Steam
trade-creation body (inventory context id); the engine reads no app-id constant.
TrackerConfig is one
typed, host-suppliable bundle of every operationally-tunable / third-party-dependent value the
library would otherwise hardcode — cadence intervals & floors, retry/backoff bounds, credential-freshness
skews, the session-refresh gate, the HTTP timeout, notary concurrency, Steam base URLs & read
endpoints, the (fragile) scraping regexes, cookie names, and the CS2 inventory context id. It is
passed to startTracker / createBrowserLoop; TrackerConfig.defaults() reproduces the in-code
baseline exactly, so omitting it changes nothing. Durations are stored as Int milliseconds to stay
JS-friendly across the export boundary. The Steam write URL suffixes and the locked DMarket
endpoint paths are intentionally not tunable (see Steam write rules).
domain/src/commonMain/kotlin/com/dmarket/p2p/tracker/
model/ immutable types, enums, value-class ids, Deal/P2PDealState, Directive, TrackedDeal, TradeStatusReport
engine/ DirectivePlanner + TrackerTick (the pure engine), DecisiveTransitions, ProofFreshness, TerminalClassification
policy/ CadencePolicy (poll classes + floors), Backoff (ladders/cursor)
game/ GameAdapter, Cs2GameAdapter, GameRegistry
port/ all port interfaces (the audit boundary is declared here)
wire/ @Serializable DTOs + mappers (P2pMappers) + TrackerJson
net/ NetworkRedaction (secret scrubbing for observed HTTP metadata)
config/ TrackerConfig + sub-configs
core/src/commonMain/kotlin/com/dmarket/p2p/tracker/
runtime/ TradeTrackerCore (composition root), TrackerHandle
loop/ TradeTrackerLoop (the driver), TrackerProgressStore, LoopStateStore, LoopConfig
client/ KtorMarketplaceClient, KtorSteamReadClient, MarketplaceAuthenticator, HTTP engine (expect)
credential/ Steam/Marketplace credential providers + session refreshers
adapter/ Clock/Scheduler/CredentialVault defaults + expect declarations + no-op ports
core/src/jsMain/... Chrome actuals (alarms, storage), Fetch* ports, JsApi + Tracker.js (the @JsExport facade)
core/src/{jvm,android,ios}Main/... per-target actuals (HTTP engine, scheduler, vault)
JDK requirement: the Kotlin compiler can't yet parse JDK 25's version string, so Gradle must run on JDK 17–21. Locally:
export JAVA_HOME=$(/usr/libexec/java_home -v 21)(Android Studio's bundled JBR 21 works). The build's own compile/test toolchain is pinned to JDK 17 and auto-provisioned via foojay, independent of the JDK running Gradle.
./gradlew check # all tests (JVM + JS) + spotlessCheck + koverVerify
./gradlew :domain:jvmTest # fast pure-core unit tests (JVM)
./gradlew :domain:jsNodeTest # same suite cross-compiled to JS (Node)
./gradlew spotlessApply # auto-format (ktlint via Spotless) — run before committing
./gradlew :domain:koverHtmlReport
./gradlew :core:jsBrowserProductionLibraryDistribution # ESM + .d.ts for the extension
./gradlew publishToMavenLocal # dry-run publish (real publish is on-request)- iOS / Android targets are deferred (on request) — see the commented blocks in
build-logic/.../dmarket.kmp.library.gradle.kts. The iOS target can only be built on a CI macOS runner with full Xcode. - The dev-only Chrome debug harness:
./gradlew :debug-harness:assembleDebugExtension, then loadtools/debug-extensionunpacked — see tools/debug-extension/README.md.
:debug-harness carries one callable probe per report/write request — reportTradeStatus (plus its
batched form), reportDirective, reportInventory, submitProof — in
C1ReportProbes.
Each issues one request through the real MarketplaceClient and hands back what the real
deserializer read from the reply, so a field the backend renamed or re-cased shows up as a missing
value instead of as a green test. The loop cannot be used for this: it reaches a write endpoint only
once the deal state makes it decide to, which a conformance run has no way to arrange.
Two properties are deliberate. Probes take wire primitives, so a malformed value can be sent on
purpose (the id value classes reject it). And no input is coerced — an unrecognised
action/status/source is refused, naming the accepted set, rather than being replaced with a
default: a typo silently rewritten into a valid-but-different request would be accepted by the backend
and pass, which is worse than no probe at all.
Because the probes take a port rather than a browser, they are driven both from the Chrome console and
from commonTest against a Ktor MockEngine
(C1ReportProbesTest),
which is where the emitted field names are asserted — the half a live run cannot check for itself.
The diagnostic probes print a token's length, decoded JWT claims and a fingerprint — never the token
itself. Those claims are what actually distinguish "wrong scope", "expired" and "transport problem",
so redaction costs no diagnostic power, and the fingerprint keeps "is this the same token?" answerable.
The raw values appear only through createDebugSessionRevealingSecrets(...) (or
startDebugSession(..., revealSecrets = true) for the session log) — a separate entry point, for
hands-on local diagnosis, that nothing automated calls. This is the same rule the production path
follows (NetworkObserver.redactSecrets defaults to true), made the default here too instead of an
exception living in a dev module.
-
Web extension (npm — the shipping target):
npm install @dmarket/p2p-tracker-core
Ships as an ES module with bundled TypeScript types (
.d.ts); the package entry isp2p-tracker-core.mjs. Thelatestdist-tag is the current beta line (1.0.1-beta), so a plainnpm installresolves it; because a SemVer prerelease is not matched by a caret range, pin it explicitly ("@dmarket/p2p-tracker-core": "1.0.1-beta") rather than^1.0.1. Development builds continue to publish under thesnapshotdist-tag (npm install @dmarket/p2p-tracker-core@snapshot). A build of a branch not yet merged publishes as<x.y.z>-SNAPSHOT-<branch>.<n>under its own dist-tag,snapshot-<branch>. -
Android / JVM:
implementation("com.dmarket.p2p:trade-tracker-core:<version>")(trade-tracker-domaintoo) — planned; Maven Central publishing is not wired yet. -
iOS: XCFramework via a SwiftPM binary target — once the iOS target is enabled.
The web build exports a deliberately thin JS facade
(JsApi.kt +
Tracker.js.kt). All Steam
wiring is internal — JS only ever holds an opaque TradeTrackerLoop/handle and never sees the Steam
credential (audit boundary).
The lifecycle is start / stop. After startTracker the library self-drives: it arms a
chrome.alarms wake-up that survives MV3 service-worker teardown, runs one full cycle per wake
(heartbeat + directives + watch/report), and reschedules itself to the next client-owned time
(deal-watch cadence or next heartbeat, whichever is sooner). The single named alarm is re-armed each
cycle (replace, never stack) and cycles are single-flighted — no duplicate runs. Push is delivered
by the host, not the lib: your own push listener hands the raw payload string to
deliverPush(handle, payload), which nudges one cycle and reschedules.
// sw.js — module service worker. Call startTracker SYNCHRONOUSLY at the top level on every boot:
// when an alarm respawns a torn-down worker, only listeners registered during that fresh top-level
// run receive the event.
import { startTracker, stopTracker, deliverPush, subscribeActiveTrackingCount } from "@dmarket/p2p-tracker-core";
// 1. Start the self-driving tracker. No token seeding — the DMarket JWT is scraped automatically
// from the logged-in dmarket.com session (the dm-trade-token cookie).
const handle = startTracker("https://api.dmarket.com");
// 2. Deliver pushes from your OWN handler — the lib only parses the payload.
self.addEventListener("push", (e) => e.waitUntil(deliverPush(handle, e.data.text())));
// 3. (Optional) Track the live number of actively-watched trades (size of active_tracking[]).
// onCount fires immediately with the current value, then on every change; the return unsubscribes.
const unsubscribe = subscribeActiveTrackingCount(handle, (count) => {
console.log(`actively tracking ${count} trades`);
});
// …or read it synchronously (e.g. when a popup mounts): activeTrackingCount(handle)
// 4. Stop it (e.g. on sign-out): clears the alarm + detaches listeners.
// unsubscribe();
// stopTracker(handle);startTracker is the same expect/actual entry on every platform (web chrome.alarms now; iOS
BGTaskScheduler and Android WorkManager when those targets are enabled). Re-login is signal-only;
for finer control, build the loop yourself (below) and poll needsReLogin / needsMarketplaceReLogin.
Exported factory functions:
| Export | Purpose |
|---|---|
startTracker(baseUrl, config?) |
Start the self-driving tracker (the primary entry). Returns an opaque handle. |
stopTracker(handle) |
Stop a tracker started with startTracker (clears the alarm + detaches listeners). |
deliverPush(handle, payloadJson) |
Hand a backend push payload (received by your own push handler) to the tracker — nudges one cycle, reschedules. Returns a Promise. |
startTrackerWithEvents(baseUrl, config?, onEvent, notaryProofDelegate?, clientVersion?) |
Like startTracker, but onEvent(json) receives every loop lifecycle event as a secret-free JSON string (the full firehose). clientVersion is the host's own build (the extension's version) and is what the heartbeat reports; omitted, the heartbeat reports this library's version. |
subscribeActiveTrackingCount(handle, onCount) |
Subscribe to the active-tracking count — the live number of trades being watched (size of active_tracking[]). onCount(n) fires immediately with the current value, then on each change. Returns an unsubscribe () => void. |
activeTrackingCount(handle) |
Read the current active-tracking count synchronously (number; 0 before the first cycle). |
createBrowserLoop(baseUrl, config?, …, clientVersion?) |
Lower-level: a fully-wired TradeTrackerLoop if you want to drive runOnce() yourself. |
createBrowserMarketplaceClient(baseUrl, config?) |
Standalone Ktor marketplace client (fetch engine; scrapes the DMarket JWT from the dm-trade-token cookie). |
createBrowserSteamClient() |
Standalone Steam read client (fetch engine). |
trackerCoreVersion() / enabledGameCount() |
This library's version (VERSION_NAME, generated at build time) / count of enabled games (CS2 only at v1). |
Required MV3 manifest permissions: "storage", "cookies", "alarms" (self-drive wake-up),
"tabs" (background dmarket.com load for marketplace session-refresh), "notifications" (push
display, when enabled), and host_permissions for https://dmarket.com/ (scrape the DMarket JWT
from the dm-trade-token cookie + session-refresh), https://steamcommunity.com (cookie-bearing
scrape + offer create/cancel), https://login.steampowered.com and https://store.steampowered.com
(Steam background session-refresh).
SteamProfileReader
fetches a Steam user's public profile — nickname + avatars (ISteamUser/GetPlayerSummaries) and
account level (IPlayerService/GetSteamLevel) — authorised, like every Steam read here, by the
device session token (no key= Web API key; nothing leaves the device). The Ktor implementation
(KtorSteamProfileReader)
batches summaries (≤100 ids/call), fetches levels in parallel (concurrency-capped), retries HTTP 429
with jittered exponential backoff, and is wrapped by
CachingSteamProfileReader
for a per-id TTL cache (default 5 min) that spares the 100k-calls/day quota.
val reader = CachingSteamProfileReader(
delegate = KtorSteamProfileReader(
httpClient = createSteamHttpClient(requestTimeoutMs = config.steamProfile.requestTimeoutMs.toLong()),
endpoints = config.steamEndpoints,
config = config.steamProfile,
),
clock = SystemClock(),
ttl = config.steamProfile.cacheTtl,
)
val credential = steamCredentialProvider.current() ?: error("not logged in")
// One profile — throws UserNotFoundException if Steam doesn't know the id,
// InvalidSteamId64Exception if the id isn't a 17-digit "7656…" steamID64.
val me = reader.getUserProfile(credential, SteamId("76561198000000001"))
println("${me.nickname} · level ${me.level ?: "private"} · ${me.avatarFullUrl}")
// Many at once — batched summaries + parallel levels, input order preserved,
// unknown ids omitted. A private profile still returns identity with level = null.
val profiles = reader.getUserProfiles(credential, ids)Behaviour: 403 → SteamProfileAuthException (token invalid/rotated); 429 past the retry
budget → SteamRateLimitedException (carries Retry-After); private profile → normal result
with level = null. Tunables live in TrackerConfig.steamProfile
(SteamProfileConfig:
cacheTtlMs, maxConcurrency, batchSize, requestTimeoutMs, maxRetries, retryBaseDelayMs,
retryMaxDelayMs).
Not yet confirmed against live Steam that these two endpoints accept the web-session
access_token(support varies per endpoint) or that they rate-limit with HTTP 429 +Retry-After. The shapes are unit-tested but pending real-world verification; because the endpoint paths and param names are config-driven, a pivot to akey=model is a config + small auth change, not a rewrite. No@JsExportfactory is shipped yet — add acreateBrowserSteamProfileReader()(mirroringcreateBrowserSteamClient()) when a JS consumer needs it.
On platforms without the JS facade you compose the loop yourself through
TradeTrackerCore.createLoop(...),
the composition root. Inject the ports your platform provides; the rest default to no-ops (and the
vault defaults to the lib-owned platformCredentialVault()).
val loop = TradeTrackerCore().createLoop(
config = LoopConfig(
clientVersion = "1.0.0",
surface = RuntimeSurface.AndroidNative,
mode = TrackerMode.Background,
),
marketplace = myMarketplaceClient, // MarketplaceClient (e.g. KtorMarketplaceClient over OkHttp)
steamReader = mySteamReadClient, // SteamReadClient (offerStatuses + recentTransfers)
scraper = mySteamSessionScraper, // SteamSessionScraper
scheduler = myWorkManagerScheduler, // Scheduler (WorkManager / BGTaskScheduler)
deviceId = myDeviceIdStore, // DeviceIdStore — persistent install-scoped device_id (the directive-lease key)
// vault defaults to platformCredentialVault() (Keychain / Android Keystore); override for tests.
// clock / notary / offerCreator / offerCanceller / inventoryReader / sessionRefresher /
// marketplaceCredentials / progress / loopState / pushChannel / eventObserver all default to
// safe no-ops; directivesEnabled defaults to false (the launch gate).
)
val outcome = loop.runOnce() // TickOutcomeNeed just the decision logic with no IO? Call the pure engine directly:
DirectivePlanner.plan(heartbeat, handled): DirectivePlan and
TrackerTick.reduce(now, activeTracking, observed, reported): ReportPlan.
Observing the active-tracking count (Flow). Non-JS hosts get the live count of actively-watched
trades as a Kotlin StateFlow<Int> via
ActiveTrackingCountChannel —
an EventObserver decorator. Wire it in as the loop's eventObserver and collect .count:
val counter = ActiveTrackingCountChannel(delegate = myEventObserver) // delegate optional; still gets the full firehose
val loop = TradeTrackerCore().createLoop(config = …, eventObserver = counter, /* … */)
scope.launch { counter.count.collect { n -> /* render "Activity on DMarket: n" */ } }
// …or read the latest synchronously: counter.count.valuecount is a StateFlow<Int> kept in sync from the loop's own cycle events (CycleCompleted.watching
every cycle, HeartbeatSent.trackingCount each heartbeat); it holds the current value (0 before the
first cycle), replays it to new collectors, and conflates identical counts. On JS the same channel is
reached via the exported subscribeActiveTrackingCount(handle, onCount) / activeTrackingCount(handle)
(above).
| Field | Meaning |
|---|---|
clientVersion |
Semver string of the client build (the extension or the app), not of this library — the library version is pinned by the build. The backend's metric accepts x.y.z with an optional -suffix of up to 12 alphanumerics; anything else is counted as other. |
surface |
WebChrome / WebFirefox / IosNative / AndroidNative — drives cadence floors. |
mode |
Foreground / Background — affects cadence floors. |
tunables |
A TrackerConfig; defaults to TrackerConfig.defaults(). |
| Member | Use |
|---|---|
suspend fun runOnce(): TickOutcome |
One full self-contained cycle (heartbeat + directives + watch/report), so OS-driven platforms call it once per wake. |
fun start(scope): Job |
Continuous loop over scheduled wakes + pushes, from a single consumer — two cycles never run concurrently. With the default NoOpPushChannel this is poll-only. |
suspend fun wakeFromPush(signal): TickOutcome |
Direct entry for a one-shot OS push callback (APNs/FCM); a push is just a nudge that runs one cycle. |
fun nextWakeDelay(): Duration |
The single scheduling source of truth (deal-watch cadence or next heartbeat, whichever is sooner). |
val needsReLogin: Boolean |
true when the last background scrape found no Steam session. Clears on the next successful scrape. Signal-only — the user-facing block is blockingState/STEAM_SESSION_MISSING, which additionally requires the session cookie to be gone. |
val steamSessionMissing: Boolean |
true when there is no Steam web session at all (cookie deleted), so no credential can be acquired. Persisted, so it survives a service-worker respawn; clears on the first cycle that acquires a credential. |
val blockingState: TrackerBlock |
The single highest-priority reason the tracker is blocked, for a host to render exactly one prompt, most actionable first: DM_SESSION_MISSING > STEAM_SESSION_MISSING > STEAM_ACCOUNT_MISMATCH > DM_CONNECTION_ERROR > NONE. |
val needsMarketplaceReLogin: Boolean |
true when no DMarket session can be recovered silently — no token pair at all, a spent refresh token, or a refresh the server refused. A transient failure (5xx / 429 / a broken gateway) deliberately leaves it false. Always false if no MarketplaceCredentialProvider was wired in. |
The DMarket bearer (dm-trade-token) lives ~24 h and is rotated against
POST {base}/marketplace-api/v1/refresh-token with {"RefreshToken": "…"}, which returns a new pair
(AuthToken/RefreshToken plus epoch-second expiries). Two things about that shape drive the design:
- The access token's expiry is inside the token, not on its container. The DMarket web frontend gives
both cookies the refresh token's ~30-day expiry, deliberately, so an idle user is not signed out. So
anything that derives freshness from the cookie sees a fresh token for a month and never refreshes. The
authority is the
expclaim of the JWT (MarketplaceTokenJwt), andMarketplaceTokenStoretherefore does not even report an access expiry. - The server does not
Set-Cookie— the page writes both cookies from the response body. On web the token store is the browser cookie jar, shared with that page, so a refresh that does not write both halves back signs the user out of the website. Writing the pair back is part of the feature, not bookkeeping.
Everything above is implemented once, in commonMain, over two thin ports — so a platform supplies a token
store and gets the whole algorithm (single-flight, a rotation rate limit, a persisted refused-token latch, a
three-way compare-and-swap against the competing writer, and a total status policy in which only a 401 or
a token-less 200 may mean "sign in again").
A host that already refreshes DMarket tokens must not use any of it. Two authorities rotating one shared
credential is strictly worse than either alone. Such a host replaces MarketplaceCredentialProvider outright:
// Android: the app's own :token_manager already does storage, single-flight, rotation and 401 handling.
val marketplaceCredentials: MarketplaceCredentialProvider =
HostTokenMarketplaceCredentialProvider { force ->
// TokenException (no usable pair) → null + lastRefreshFailedLoggedOut, i.e. "show the sign-in prompt".
val data = tokenManager.getTokenData(forceRefresh = force)
MarketplaceCredential(
token = data.authorizationToken,
expiresAt = Instant.fromEpochSeconds(data.authorizationTokenExpirationTimestamp),
)
}
val marketplace = KtorMarketplaceClient(
httpClient = androidMarketplaceClient(hostOkHttp),
baseUrl = baseUrl,
authenticator = CredentialMarketplaceAuthenticator(marketplaceCredentials),
)null from the provider is load-bearing, not advisory: the loop's pre-heartbeat guard and the 401
authenticator are both null checks, so a provider that hands back a token it knows is dead turns one clean
missing-connection verdict into 1 + maxRetries rejected requests on every wake.
Audit boundary. This client reads the durable dm-trade-refresh-token and sends it to DMarket's own
refresh endpoint — and nowhere else: the resolved endpoint is allow-listed to the API-base or site origin
before the request is built. That is a change from earlier versions, which refreshed by loading a
dmarket.com page in a background tab and never touched the refresh token. The Steam side is unchanged and
still never reads Steam's durable steamRefresh_steam. Both DMarket tokens, the refresh request body and the
response are in the redactor's named-secret set, so neither reaches a log line, an exception message or a
crash report.
All interfaces live in domain/.../port/. Each has a web actual and a default; substitute platform implementations as you enable iOS/Android.
| Port | Purpose | Web actual / default |
|---|---|---|
Clock |
Current time (injected for deterministic tests). | SystemClock |
Scheduler |
Platform wake-up scheduling (chrome.alarms / WorkManager / BGTaskScheduler). |
WebExtAlarmsScheduler (web) · CoroutineScheduler (tests/foreground) |
CredentialVault |
Device-local secure storage for the Steam credential. | WebExtStorageCredentialVault (default via platformCredentialVault()) · InMemoryCredentialVault (tests) |
MarketplaceClient |
The /exchange/v1/p2p/ext/ endpoints (heartbeat / trade-events / notary / trade-actions / inventory) + the DMarket app conveniences (accept / getDeal). Never accepts a SteamCredential (audit boundary). |
KtorMarketplaceClient |
DeviceIdStore |
Persistent install-scoped device_id — the directive-lease key sent in every heartbeat. |
WebExtStorageDeviceIdStore (web) |
MarketplaceCredentialProvider |
The DMarket bearer, refreshed when it nears expiry. The one seam a host that already owns token refresh replaces wholesale — see below. | DefaultMarketplaceCredentialProvider (library-owned) · HostTokenMarketplaceCredentialProvider (host-owned) |
MarketplaceTokenStore |
Where the platform keeps the token pair. On web this is the browser cookie jar, shared with the dmarket.com page, which is why the rotated pair must be written back. | FetchMarketplaceCookieTokenStore |
MarketplaceTokenRefreshClient |
POST {base}/marketplace-api/v1/refresh-token. Unauthenticated, no 401 retry, on a transport of its own (the 401 path calls into it). |
KtorMarketplaceTokenRefreshClient |
MarketplaceRefreshStateStore |
Refresh guards that must survive a process restart: the refused-token latch, the rotation rate limit, the transient-failure count. Stores a fingerprint, never the token. | PersistedMarketplaceRefreshStateStore |
SteamReadClient |
Read-only Steam status polling — both axes: offerStatuses (ETradeOfferState) + recentTransfers (ETradeStatus), account-wide batch reads. |
KtorSteamReadClient |
SteamInventoryReader |
Read the seller's own inventory for the report_inventory directive → POST /inventory snapshot. Follows Steam's paging cursor and returns an InventoryScan carrying whether the enumeration was complete, so a truncated read reports scan_complete=false instead of looking like an empty inventory. |
KtorSteamInventoryReader (web) / NoOpSteamInventoryReader |
SteamSessionScraper |
Re-acquire a fresh Steam credential from an already-logged-in session. | KtorSteamSessionScraper |
SteamOfferCreator |
Create a Steam trade for the buyer, stopping at CreatedNeedsConfirmation — never confirms. |
FetchSteamOfferCreator / NoOpSteamOfferCreator |
SteamOfferCanceller |
Cancel a sent offer (the only other write surface). | FetchSteamOfferCanceller / NoOpSteamOfferCanceller |
SteamSessionRefresher / SteamWebSessionGateway |
Keep the steamLoginSecure web session alive in the background. |
DefaultSteamSessionRefresher / FetchSteamWebSessionGateway · NoOpSteamSessionRefresher |
NotaryProver |
Generate a TLSN proof for a decisive transition on a proof_required deal (POST /notary). |
DelegatingNotaryProver when the host supplies a proving context · NoOpNotaryProver (stub presentation) otherwise |
PushChannel |
Backend→client push wake-up (transport-agnostic). | NoOpPushChannel (poll-only) |
The whole point of the pure core is that the decision surface is testable with no test doubles:
- New logic lands in
:domainfirst with table-drivencommonTestcases (construct aHeartbeatResponse, callDirectivePlanner.plan/TrackerTick.reduce, assert on the plan). - Every domain suite runs on both JVM and JS Node (
:domain:jvmTest+:domain:jsNodeTest) — the same Kotlin, two backends. :coreIO is exercised withktor-client-mockround-trips and fake ports.- Coverage gate: ≥70% on
:domain(koverVerify), currently ~90%+. ./gradlew checkruns everything (tests +spotlessCheck+koverVerify).- If a test of pure logic needs a mock, the logic is in the wrong module.
- TLSN proof generation ships behind a host-supplied proving context and stays inert until the
backend flips per-trade
proof_required. A caller that supplies no proving context — mobile today, and Firefox, which cannot host one — getsNoOpNotaryProverand runs client-reported. - Directive execution is off by default:
directivesEnableddefaults tofalseonTradeTrackerCore.createLoop, and the web facade (Tracker.start) enables it. The create write surface is additionally pending DMarket security sign-off. - Push is poll-only by default; the lib parses payloads but owns no push transport (host-delivered
via
deliverPush). - iOS / Android targets are deferred (on request); the web extension is the shipping path.
- CONTRIBUTING.md — module layout, conventions and the checks a change must pass.
- tools/debug-extension/README.md — the dev-only Chrome debug harness.
- core/PROVER.md — the TLSN prover: where it comes from, what the build verifies, how a host must ship it, and how to bump it.
MIT.
Third-party components redistributed inside the npm packages (the TLSN prover WASM, taken from
@dmarket/steam-provenance) are licensed separately — see THIRD_PARTY_NOTICES.md.