---
title: "Non-Mutating Dry-Run"
description: "The normal pre-trade pipeline mutates by design. The start stage spends rate-limit budget on every call, even rejected ones. The main stage creates."
---
# Non-Mutating Dry-Run
**Probe the pre-trade pipeline without changing any engine state.**
The normal pre-trade pipeline mutates by design. The start stage spends
rate-limit budget on every call, even rejected ones. The main stage creates
reservations and holds. There is no "undo path" that restores the engine to
its exact pre-call state: rollback cancels the reservation but the budget is
already spent.
A dry-run is a completely separate, explicitly non-mutating path in the engine.
It runs the same policy checks against the current engine state and reports
what the equivalent real call *would* produce - verdict, would-be lock, and
would-be account adjustments - while touching nothing. No rate-limit budget is
spent, no reservation or hold is applied, and no account block is recorded.
Repeating a dry-run is idempotent: a second call with the same order and state
produces the same answer.
## What a Dry-Run Returns
The engine returns an inert report object (not a transaction). There is nothing
to commit or roll back.
| Accessor | Meaning |
| --- | --- |
| `is pass` | `true` when all stages would have admitted the order |
| `rejects` | The rejects the pipeline would have collected, or empty/nil |
| `lock` | The [`PreTradeLock`](Pre-Trade-Lock.md) the main stage would have produced |
| `account adjustments` | Per-asset `held`/`available` outcomes the main stage would have reported |
| `account block` | The account block a real call would have recorded in the engine's blocked-accounts registry |
`lock` and `account adjustments` are empty when the start stage would have
rejected (the main stage never runs in that case, exactly as in the real
pipeline). `account block` is reported here but is **not** recorded in the
engine.
## Entry Points
Two entry points mirror the real pre-trade API:
- `start pre trade dry run` - runs only the start
stage in dry-run mode. Use this when you want a fast admission check without
computing a lock or adjustments.
- `execute pre trade dry run` - runs both stages in
dry-run mode. Returns the full report including would-be lock and
adjustments.
## Examples
### Read the Dry-Run Verdict
Go
```go
report, err := engine.ExecutePreTradeDryRun(order)
if err != nil {
panic(err)
}
defer report.Close()
pass, err := report.IsPass()
if err != nil {
panic(err)
}
if pass {
fmt.Println("order would be admitted")
} else {
rejects, err := report.Rejects()
if err != nil {
panic(err)
}
for _, r := range rejects {
fmt.Printf(
"would reject by %s [%d]: %s (%s)\n",
r.Policy,
r.Code,
r.Reason,
r.Details,
)
}
}
```
Python
```python
report = engine.execute_pre_trade_dry_run(order=order)
if report.is_pass:
print("order would be admitted")
else:
for reject in report.rejects:
print(
f"would reject by {reject.policy} "
f"[{reject.code}]: {reject.reason}: {reject.details}"
)
```
JavaScript
```ts
import { Engine } from "@openpit/engine";
import { TradeAmount } from "@openpit/engine/param";
import { type OrderInit } from "@openpit/engine/model";
import { buildOrderValidation } from "@openpit/engine/pretrade/policies";
const engine = Engine.builder().builtin(buildOrderValidation()).build();
const order: OrderInit = {
operation: {
underlyingAsset: "AAPL",
settlementAsset: "USD",
accountId: 99_224_416n,
side: "BUY",
tradeAmount: TradeAmount.quantity("1"),
price: "100",
},
};
const report = engine.executePreTradeDryRun(order);
if (report.isPass) {
console.log("order would be admitted");
} else {
for (const reject of report.rejects) {
console.log(
`would reject by ${reject.policy} [${reject.code}]: ${reject.reason}: ${reject.details}`,
);
}
}
```
C++
```cpp
const openpit::pretrade::DryRunReport report =
engine.ExecutePreTradeDryRun(order);
if (report.Passed()) {
std::cout << "order would be admitted\n";
} else {
for (const openpit::pretrade::Reject& reject : report.Rejects()) {
std::cout << "would reject by " << reject.policy << " ["
<< static_cast(reject.code) << "]: " << reject.reason
<< " (" << reject.details << ")\n";
}
}
```
Rust
```rust
let report = engine.execute_pre_trade_dry_run(order);
if report.is_pass() {
println!("order would be admitted");
} else {
for reject in report.rejects().unwrap().iter() {
eprintln!(
"would reject by {} [{}]: {} ({})",
reject.policy, reject.code, reject.reason, reject.details
);
}
}
```
Go
```go
// Probe without spending any budget or creating any reservation.
probe, err := engine.ExecutePreTradeDryRun(order)
if err != nil {
panic(err)
}
defer probe.Close()
pass, err := probe.IsPass()
if err != nil {
panic(err)
}
if !pass {
return // would have been rejected - skip the real call
}
// The real call now runs with fresh state; the probe had no effect.
reservation, rejects, err := engine.ExecutePreTrade(order)
if err != nil {
panic(err)
}
if rejects != nil {
return
}
defer reservation.Close()
reservation.Commit()
```
Python
```python
# Probe without spending any budget or creating any reservation.
probe = engine.execute_pre_trade_dry_run(order=order)
if not probe.is_pass:
pass # would have been rejected - skip the real call
else:
# The real call now runs with fresh state; the probe had no effect.
result = engine.execute_pre_trade(order=order)
if result:
result.reservation.commit()
```
JavaScript
```ts
import { Engine } from "@openpit/engine";
import { TradeAmount } from "@openpit/engine/param";
import { type OrderInit } from "@openpit/engine/model";
import {
buildRateLimit,
RateLimit,
RateLimitBrokerBarrier,
} from "@openpit/engine/pretrade/policies";
const engine = Engine.builder()
.builtin(
buildRateLimit().brokerBarrier(
new RateLimitBrokerBarrier(new RateLimit(1, 60_000)),
),
)
.build();
const order = (): OrderInit => ({
operation: {
underlyingAsset: "AAPL",
settlementAsset: "USD",
accountId: 99_224_416n,
side: "BUY",
tradeAmount: TradeAmount.quantity("1"),
price: "100",
},
});
// Probe without spending any budget or creating any reservation.
const probe = engine.executePreTradeDryRun(order());
if (!probe.isPass) {
// would have been rejected - skip the real call
} else {
// The real call now runs with fresh state; the probe had no effect.
const result = engine.executePreTrade(order());
if (result.ok) {
const reservation = result.reservation;
if (reservation === undefined) {
throw new Error("accepted execute result is missing its reservation");
}
reservation.commit();
}
}
```
C++
```cpp
// Probe without spending any budget or creating any reservation.
const openpit::pretrade::DryRunReport probe =
engine.ExecutePreTradeDryRun(order);
if (!probe.Passed()) {
return; // would have been rejected - skip the real call
}
// The real call now runs with fresh state; the probe had no effect.
openpit::pretrade::ExecuteResult result = engine.ExecutePreTrade(order);
if (result.Passed()) {
result.reservation->Commit();
}
```
Rust
```rust
// Probe without spending any budget or creating any reservation.
let probe = engine.execute_pre_trade_dry_run(order.clone());
if probe.is_pass() {
// The real call now runs with fresh state; the probe had no effect.
engine.execute_pre_trade(order)?.commit();
}
```
Go
The `DryRunPolicy` interface carries the two dry-run hooks. When a policy
satisfies `DryRunPolicy`, the engine uses the dry-run methods instead of the
normal ones for the dry-run path.
```go
type MyCountingPolicy struct {
count int
}
func (*MyCountingPolicy) Close() {}
func (*MyCountingPolicy) Name() string { return "MyCountingPolicy" }
func (*MyCountingPolicy) PolicyGroupID() model.PolicyGroupID { return model.DefaultPolicyGroupID }
func (p *MyCountingPolicy) CheckPreTradeStart(
_ pretrade.Context,
_ model.Order,
) []reject.Reject {
p.count++ // side effect: spends the real counter budget
return nil
}
func (*MyCountingPolicy) PerformPreTradeCheck(
_ pretrade.Context,
_ model.Order,
_ tx.Mutations,
_ pretrade.Result,
) []reject.Reject {
return nil
}
func (*MyCountingPolicy) ApplyExecutionReport(
_ pretrade.PostTradeContext,
_ model.ExecutionReport,
_ pretrade.PostTradeAdjustments,
_ pretrade.PostTradePnls,
) []reject.AccountBlock {
return nil
}
func (*MyCountingPolicy) ApplyAccountAdjustment(
_ accountadjustment.Context,
_ param.AccountID,
_ model.AccountAdjustment,
_ tx.Mutations,
_ pretrade.AccountOutcomes,
) (pretrade.PolicyAccountAdjustmentResult, []reject.Reject) {
return pretrade.PolicyAccountAdjustmentResult{}, nil
}
// CheckPreTradeStartDryRun is the read-only variant: no counter increment.
func (*MyCountingPolicy) CheckPreTradeStartDryRun(
_ pretrade.Context,
_ model.Order,
) []reject.Reject {
return nil // read current state without spending the budget
}
// PerformPreTradeCheckDryRun is the read-only variant.
func (*MyCountingPolicy) PerformPreTradeCheckDryRun(
_ pretrade.Context,
_ model.Order,
_ tx.Mutations,
_ pretrade.Result,
) []reject.Reject {
return nil
}
```
Python
Defining `check_pre_trade_start_dry_run` or
`perform_pre_trade_check_dry_run` on the policy class opts that hook into
read-only mode on the dry-run path. Methods that are absent fall back to the
normal hooks.
```python
class MyCountingPolicy(openpit.pretrade.Policy):
def __init__(self) -> None:
self._count = 0
@property
def name(self) -> str:
return "MyCountingPolicy"
def check_pre_trade_start(
self,
ctx: openpit.pretrade.Context,
order: openpit.Order,
) -> openpit.pretrade.Rejects:
self._count += 1 # side effect: spends the real counter budget
return () # pass
def check_pre_trade_start_dry_run(
self,
ctx: openpit.pretrade.Context,
order: openpit.Order,
) -> openpit.pretrade.Rejects:
return () # read-only: no increment
```
JavaScript
Define `checkPreTradeStartDryRun` or `performPreTradeCheckDryRun` to provide a
read-only variant of a stateful hook. When either method is absent, the JS
binding falls back to the corresponding normal hook.
```ts
import { Engine } from "@openpit/engine";
import { TradeAmount } from "@openpit/engine/param";
import { type OrderInit } from "@openpit/engine/model";
import { type Policy } from "@openpit/engine/pretrade";
const counterState: { acceptedOrders: number; limit: number } = {
acceptedOrders: 0,
limit: 10,
};
const readOnlyStartPolicy: Policy = {
name: "ReadOnlyStartPolicy",
checkPreTradeStart() {
counterState.acceptedOrders += 1;
return [];
},
checkPreTradeStartDryRun() {
if (counterState.acceptedOrders >= counterState.limit) {
return [
{
code: "RateLimitExceeded",
reason: "counter budget exhausted",
details: "the read-only start check observed a full counter",
scope: "order",
},
];
}
return [];
},
performPreTradeCheck() {
return null;
},
};
const engine = Engine.builder().preTrade(readOnlyStartPolicy).build();
const order: OrderInit = {
operation: {
underlyingAsset: "AAPL",
settlementAsset: "USD",
accountId: 99_224_416n,
side: "BUY",
tradeAmount: TradeAmount.quantity("1"),
price: "100",
},
};
const probe = engine.startPreTradeDryRun(order);
if (!probe.isPass || counterState.acceptedOrders !== 0) {
throw new Error("the dry-run start hook must remain read-only");
}
const real = engine.executePreTrade(order);
if (!real.ok || Number(counterState.acceptedOrders) !== 1) {
throw new Error("the real start hook must apply its side effect");
}
const reservation = real.reservation;
if (reservation === undefined) {
throw new Error("accepted execute result is missing its reservation");
}
reservation.rollback();
```
C++
Define `CheckPreTradeStartDryRun` or `PerformPreTradeCheckDryRun` on the
handler type passed to `CustomPolicy`. Hooks that are absent fall back
to their normal counterparts.
```cpp
class MyCountingPolicy {
public:
explicit MyCountingPolicy(std::uint64_t* count) : m_count(count) {}
[[nodiscard]] std::optional CheckPreTradeStart(
const openpit::Order& order) const {
static_cast(order);
++*m_count; // side effect: spends the real counter budget
return std::nullopt;
}
void PerformPreTradeCheck(const openpit::pretrade::Context& context,
openpit::pretrade::PolicyDecision& decision) const {
static_cast(context);
static_cast(decision);
}
// CheckPreTradeStartDryRun is the read-only variant: no counter increment.
[[nodiscard]] std::optional
CheckPreTradeStartDryRun(const openpit::Order& order) const {
static_cast(order);
return std::nullopt; // read current state without spending the budget
}
// PerformPreTradeCheckDryRun is the read-only variant.
void PerformPreTradeCheckDryRun(
const openpit::pretrade::Context& context,
openpit::pretrade::PolicyDecision& decision) const {
static_cast(context);
static_cast(decision);
}
private:
std::uint64_t* m_count;
};
```
Rust
Override `check_pre_trade_start_dry_run` and/or
`perform_pre_trade_check_dry_run` on the `PreTradePolicy` trait. Methods that
are not overridden delegate to the normal hooks automatically.
```rust
use openpit::pretrade::{
PolicyPreTradeResult, PostTradeContext, PreTradeContext, PreTradePolicy, Rejects,
};
use openpit::Mutations;
struct MyCountingPolicy {
count: std::cell::Cell,
}
impl PreTradePolicy for MyCountingPolicy
where
Sync: openpit::SyncMode,
{
fn name(&self) -> &str {
"MyCountingPolicy"
}
fn check_pre_trade_start(
&self,
_ctx: &PreTradeContext<::StorageLockingPolicyFactory>,
_order: &O,
) -> Result<(), Rejects> {
self.count.set(self.count.get() + 1); // side effect
Ok(())
}
// Dry-run variant: read-only, no counter increment.
fn check_pre_trade_start_dry_run(
&self,
_ctx: &PreTradeContext<::StorageLockingPolicyFactory>,
_order: &O,
) -> Result<(), Rejects> {
Ok(()) // inspect state without spending budget
}
fn perform_pre_trade_check(
&self,
_ctx: &PreTradeContext<::StorageLockingPolicyFactory>,
_order: &O,
_mutations: &mut Mutations,
) -> Result, Rejects> {
Ok(None)
}
fn apply_execution_report(
&self,
_ctx: &PostTradeContext<::StorageLockingPolicyFactory>,
_report: &R,
) -> Option {
None
}
}
```