How a trade
becomes a result.
Two replay paths answer different execution questions. Follow an order from the strategy's information set through matching, capacity, funding, and the final account.
In this chapter
Choose the evidence first.#
Backtest Lab maintains two execution semantics: trade-tape replay and PML2 order-book replay. Both accept historical input and strategy actions. They share financial accounting, but they do not infer liquidity in the same way.
| Dimension | Trade tape / V3 | Order book / PML2 |
|---|---|---|
| Primary input | Frozen economic trade prints and their source evidence | Snapshots, updates, trades, and lifecycle/source evidence |
| Execution question | What quantity is supported or estimated under this tape model? | What could this order execute against reconstructed visible liquidity? |
| Liquidity representation | Per-print capacity or explicitly modeled supply | Price levels, remaining depth, replenishment, and queue assumptions |
| Useful research | Order-flow signals, longer histories, sensitivity to fill assumptions | Spread, depth, order size, delays, TIF, and maker behavior |
| Principal uncertainty | A print does not reveal the full book or prove a hypothetical order would fill | L2 does not reveal the hypothetical order's exact queue or unobserved liquidity |
| Shared output | Orders, fills, execution evidence, funded account history, and explicitly qualified financial metrics | |
A model profile changes assumptions inside a path. Python and Rust change how the computation runs. Neither is an additional economic framework. Third-party reference engines used for offline comparison are benchmarks, not separate public backtest services.
Advance time, then act.#
- 01 / OBSERVEDeliver historyExpose only events visible by the decision time.
- 02 / DECIDESubmit actionsAccept orders, cancellations, or supported protocol actions.
- 03 / EXECUTEAdvance eventsApply arrival, matching, deadlines, and responses.
- 04 / RECORDUpdate stateRetain execution and account history for the next decision.
The strategy supplies an order's asset, side, quantity, limit, signal time, and lifecycle settings. The engine determines execution. A callback may not replace fills, account balances, or Oracle truth. Warmup observations can build features before the first trading decision without opening positions.
The signal clock, arrival clock, and response clock are distinct. Orders cannot execute before arrival. Strategies cannot react to a fill before its response is delivered. Cancellation does not erase a fill that happened earlier. The trade that generated a signal cannot be reused as its subsequent execution evidence.
For native rolling-flow strategies, the feature window is [now − lookback, now). Equal-time observations do not leak into that decision. Trade groups and message boundaries remain atomic even when a requested processing batch would split them.
Constrain a fill with observed trades.#
The source-based path selects eligible prints for the order's asset, timing, side, and price limit. At an arrival opportunity, it uses same-direction aggressive trades as a taker proxy. A resting remainder subsequently looks for opposite-direction aggressive trades crossing its limit and allocates passive fills at the order's limit. This is an explicit matching assumption, not proof of exchange acceptance.
Participation limits restrict how much of a print can support the simulation. Each source trade has a remaining-capacity record. Orders within the same replay cannot repeatedly claim the original volume. Price buffers, immediate windows, and participation rates belong to the selected profile and are recorded with the result.
allocated quantity ≤ unconsumed capacityThe order's limit, remaining size, lifecycle, and available funding impose additional constraints.
Worked example: two orders, one print
Assume an eligible historical print contains 40 shares at 0.55 collateral/share. The experiment caps participation at 25%, uses no price buffer, and has enough cash. That print provides 10 shares of simulated capacity. Two ordinary partial-fill-capable BUY orders each request 8 shares with a 0.60 limit.
| Order | Requested | Allocated | Capacity remaining |
|---|---|---|---|
| First accepted BUY | 8 shares | 8 shares | 2 shares |
| Second accepted BUY | 8 shares | 2 shares | 0 shares |
The second order's remaining 6 shares follow its lifecycle. An immediate order cancels that remainder; a resting order may remain active for later evidence. A failed FOK allocation must not consume capacity. A funding rejection also leaves the print's capacity untouched.
The result records the source trade IDs and timing that support each allocation. “Source-backed” means the replay can trace its simulated quantity to that evidence. It does not mean an actual order was submitted or filled on the exchange.
A model family changes the inference.#
The trade-tape registry includes source estimators and several research model families. Their outputs answer different questions, so an expected quantity, a random-path fill, and a source-supported fill remain distinguishable.
| Family | Principle | Interpretation |
|---|---|---|
| Source-based | Allocate qualifying historical prints under price, time, and participation constraints. | Traceable historical capacity under a proxy assumption. |
| Probability / learned | Use arrival-time features and fitted parameters to estimate fill probability or quantity. | A conditional forecast; domain and training-window limits apply. |
| Monte Carlo | Sample marked trade opportunities with a recorded seed and model state. | A distribution or a realized research path, not an observed source trade. |
| Synthetic liquidity | Translate past activity and configured assumptions into modeled supply. | Sensitivity analysis; future flow is not existing arrival inventory. |
| Passive touch / resting | Accumulate eligible subsequent opportunities under a passive-fill rule. | Queue/touch assumptions remain explicit; fractional expectations are not literal partial FOK fills. |
| L2-reference supply | Learn conditional depth from offline L2 curves, then infer supply using pre-arrival tape features. | L2 is a training reference, not live book input at inference time. |
A probability model's prediction horizon does not rewrite the order's horizon, latency, or expiry. Features must use the history the model actually requires. Missing history, unsupported order stages, or an out-of-domain input must remain observable in the outcome.
Source capacity and modeled capacity have separate lineage. Modeled events cannot be given invented source-trade IDs. A central scenario also cannot look into the future and choose whichever estimator happens to fill. Calibration status and intended role—central candidate, forecast, or stress bound—must be read from the actual model definition.
Inspect the current model registry → The public page reads live definitions; this chapter describes the mechanisms rather than promising a fixed profile count or a validated default.
Rebuild depth, then match.#
PML2 reconstructs the historical price-level book using admissible snapshots and complete updates. It preserves source/connection identity and the information cutoff, then schedules orders against that evolving state. A latest quote without the necessary baseline and quantities cannot stand in for a valid book.
Taker execution walks the visible ladder
A marketable BUY consumes asks from the best price upward, stopping at its limit or remaining size. A SELL walks bids downward. The profile can constrain usable depth and replenishment, and the replay tracks already consumed capacity. Historical observations are shared inputs; the simulated order does not rewrite the upstream archive.
| Ask price | Visible shares | FAK allocation |
|---|---|---|
| 0.50 | 3 | 3 shares |
| 0.51 | 4 | 4 shares |
| 0.53 | 10 | 0 — outside the limit |
The FAK order fills 7 shares for 3.54 collateral and cancels 3. Its average execution price is approximately 0.505714. Under FOK, the same order fills zero because only 7 of the required 10 shares are available inside its limit. The failed FOK leaves capacity intact.
Maker execution needs a queue model
A resting order has a limit, acceptance order, age, and an assumed quantity ahead. L2 provides aggregate levels, not a full order-by-order queue. Profiles therefore specify queue-ahead and cancellation/replenishment behavior. Queue-derived fills are classified as modeled execution.
After a complete book update, active resting orders are rechecked against remaining visible capacity. They retain maker identity and limit-price accounting rather than being resubmitted as new takers. Book-crossing allocation and subsequent tape allocation share the order's remaining size so the same order cannot fill twice.
Delays and stale books affect the path
Feed, entry, venue, cancellation, and response delays represent different stages. A missing or invalid book can reject admission or wait for fresh data under an explicit submission policy. Waiting shifts the opportunity; it cannot create a fill at the earlier missing timestamp. Maker or gap forecasts are separate estimates and do not manufacture an execution or mutate the account.
The strict, realistic, and optimistic scenario names bundle assumptions about depth, queues, delays, and book validity. Their names are not independent accuracy certifications. Execution-matrix variants combine these settings with TIF and waiting policies for controlled comparison.
An observation window is not an expiry.#
| Contract | Replay meaning | Remaining quantity |
|---|---|---|
| GTC | Continue until filled, effectively cancelled, or terminated by the market. | Remains active if the replay only stops observing. |
| GTD | Expire at the configured time; legacy omitted-expiry input retains its documented convention. | Cancelled at expiry; residual reservations released. |
| FAK / IOC | One immediate execution opportunity; the tape model's opportunity is an explicit proxy window. | Unfilled quantity is cancelled. |
| FOK | All required quantity under the model's admissible capacity, or none. | Failed allocation consumes no capacity. |
| Explicit session orders | Trade-tape research can specify DAY or open/close events where the estimator supports them. | Requires caller-supplied session boundaries; no exchange auction is invented. |
Polymarket's native order types are described in its order lifecycle reference. The framework's additional session contracts are generic research semantics. A shared parser accepting a contract does not imply every estimator can model it; unsupported stages retain MODEL_UNSUPPORTED.
For trade-tape replay, the ordinary observation endpoint includes eligible boundary prints, while explicit cancellation, expiry, market-stop, and replay-cutoff boundaries exclude execution at the boundary. A model's observation limit must not release a still-live GTC reservation. PML2 preserves its own scheduled event ordering and venue lifecycle.
Liquidity and money are separate ledgers.#
The liquidity ledger answers how much source or modeled capacity remains. The financial ledger answers whether the account can afford an order and what it owns after execution. A valid liquidity match does not remove the need for a funding check.
- Reserve before matching. BUY orders reserve cash including the applicable fee allowance. SELL orders reserve inventory. Insufficient funding rejects the order before it consumes liquidity.
- Apply fills under the declared policy. Update cash, shares, cost basis, and fees through the shared accounting implementation.
- Preserve pending state. Unconfirmed execution, remaining quantity, and reservations stay visible. Expected rebates or pending cash cannot finance a new order.
- Release the unused reservation at a valid terminal event. Completion, effective cancellation, expiry, or market termination determines the release.
| Policy / result | How to interpret it |
|---|---|
| Explicit receipts | PML2's default settlement policy verifies receipt identity and time before confirming execution in the account. |
| Source-backed simulation | An explicitly selected policy can book supported simulated fills at fill time. PML2 queue-model fills continue to require their appropriate confirmation. |
| Research model account | A dedicated research path may settle model fills into simulated cash and inventory, labeled RESEARCH_MODEL_AT_FILL_TIME and source_confirmed=false. |
| Provisional valuation | A read-only scenario includes pending changes for analysis. It does not make pending proceeds spendable or change confirmed inventory. |
Worked example: cash is not PnL
With 100 collateral, buying 8 shares at 0.55 spends 4.40. Under an illustrative 25 bps notional fee, the fee is 0.011 and remaining cash is 95.589. If an admissible mark values each share at 0.56, the inventory is worth 4.48.
total PnL = 100.069 − 100 = +0.069This example assumes no external cash flows or other positions. The fee is a research assumption, not a claim about the current exchange fee schedule. Without a valid mark, total equity and PnL remain incomplete.
Cash decreased, yet marked equity increased slightly. This is why the synthetic tutorial's cash trace is labeled as an account event sequence rather than a return curve.
Value inventory; verify redemption.#
Realized PnL, unrealized PnL, total account equity, and cash are separate quantities. A financial report needs the relevant cost basis and marks. The account can be fully valued while still holding unresolved positions; valuation completeness does not imply final settlement.
Explicit historical marks include their observation time and source evidence. Where enabled, a dynamic trade-tape run can carry each asset's last observed trade forward, recording mark age and staleness. A carried mark supports a particular research valuation; it is not a quote at which the position can necessarily be liquidated.
Oracle redemption consumes verified token-specific payouts under the run's cutoff and settlement policy. It checks market/condition identity and final event time, retains exact payout fractions, and uses idempotent operation identities. Scheduled market end, an Oracle proposal, or a later final event cannot authorize earlier cash. Split, merge, and supported negative-risk conversions also use the shared account with explicit asset mappings.
The report separates history_complete, valuation_complete, and settlement status. Missing values stay unknown. Return and drawdown fractions require an equity history; annualized risk metrics additionally require a defined sampling frequency and valid period returns. A raw event trace is not automatically a daily return series, and missing days are not silently bridged.
Compare assumptions on the same evidence.#
A useful model comparison fixes strategy intentions, input range, fees, and starting capital. Each profile or scenario receives its own order state, capacity, account, and random state. Shared read-only market data improves efficiency without letting one scenario consume another's liquidity.
- Execution: compare fill probability, filled quantity, price, timing, and rejected or partial orders.
- Lifecycle: compare waiting, expiry, cancellation, response delivery, and remaining exposure.
- Finance: reconcile cash, fees, positions, cost basis, marks, and payout separately.
- Validity: retain missing-data intervals, out-of-domain decisions, and calibration status in the denominator.
Similar aggregate PnL does not establish matching accuracy. A low-fill or high-fill stress scenario is a sensitivity bound, not a candidate for the best central model. A PML2 replay can provide reference labels for another model, but it is still a simulation; exchange-fill calibration requires actual order lifecycle evidence.
Training, calibration, and evaluation scopes should be separated by time and market. A historical decision that precedes the fitted artifact's training or creation window is a diagnostic replay, not proof that the model was available for that decision.
Change the speed, preserve the contract.#
Python callers, CLI commands, and private HTTP handlers invoke the canonical replay library. Rust kernels accelerate event scheduling, source matching, native sessions, and explicit columnar-flow paths. Python reference paths remain useful for comparison and supported exact-precision cases. A generic strategy callback is not automatically compiled into a native-flow strategy.
The reported backend and readiness describe what actually ran. Explicit native selection must not quietly become a different model when a kernel is unavailable. The fixed-order automatic path can report a documented Python precision fallback for source input outside native numeric limits; it must preserve exact values rather than truncate them.
Long runs process bounded chunks and retain cursor, pending events, order state, source/model capacity, account state, and input identity in checkpoints and journals. Resume checks those identities. A changed strategy, frozen catalog, or incompatible execution contract requires a new run rather than continuing an old experiment under a familiar name.
The public website is a read-only research presentation. Its model metadata routes do not expose job submission, internal account history, database credentials, or arbitrary strategy callbacks.
Read the reason, not just the number.#
| State or field | Meaning |
|---|---|
| FILLED / PARTIAL | The execution model allocated all or some quantity. Check its evidence class and whether that quantity reached the account. |
| NO_FILL / cancellation | No qualifying execution, or a terminal unfilled remainder, under the stated data and contract. |
| OPEN / pending orders | An order remains live or has undelivered events at the observation boundary. Reservations may remain. |
| DATA_NOT_READY | Required data or reconstructable state is unavailable. Do not count it as a valid zero-fill observation. |
| MODEL_UNSUPPORTED / MODEL_DOMAIN_ABSTAIN / UNOBSERVABLE | The estimator cannot support that stage, domain, or information set. Keep the reason visible. |
| Incomplete valuation | Execution may be recorded, but marks or cost evidence do not support a complete financial conclusion. |
The shared account report contains portfolio state, booked ledger entries, equity observations, and metrics. It carries its own hash and completeness fields. Large runs may point to full ledger or equity artifacts instead of embedding every observation; a sampled chart does not replace the complete metric calculation.
Keep the strategy and parameter identity, actual input scope, model version, initial account, fee and delay assumptions, fill evidence, unfilled/rejected reasons, valuation method, residual positions, and source/result hashes together. A finished process is one part of that record, not the entire conclusion.
Return to the inputs.#
- Backtest Lab · Data sources & provenance — original sources, clock semantics, frozen inputs, and coverage.
- Backtest Lab · Interactive tutorials — small synthetic examples of execution and account movements.
- Backtest Lab · Current model definitions — profiles and their reported assumptions/status.
- Polymarket · Order lifecycle — upstream order types and venue behavior.
- Polymarket · Resolution — the upstream outcome-resolution lifecycle.
Repository basis: docs/architecture.md, docs/reference/execution.md, docs/reference/accounting.md, docs/guides/model-comparison.md, and the canonical trade-tape, PML2, order-rule, and accounting implementations. Numerical examples on this page are illustrative arithmetic, not reported historical strategy performance.