Skip to main content

TBS engine - combined feature matrix and design

Combines StockMock, AlgoTest and Stoxxo. This supersedes the scope section of the StockMock plan (its architecture and milestones still hold). Status: draft for review, 17 Oct 2026. Legend: S StockMock, A AlgoTest, X Stoxxo. P1 / P2 / P3 = build phase.

1. Design principles​

  1. One strategy = one JSON (portable, hashable, saved to st_master, importable / exportable). Every UI form is just an editor for this JSON.
  2. Event-driven, bar-by-bar simulator. Legs have states: IDLE -> WAITING (W&T / breakout / premium condition) -> OPEN -> CLOSED. SL / target / time events run actions that open, close or re-create legs. This one mechanism covers re-entry, re-execute, move-SL-to-cost, adjustments and pyramiding.
  3. Rules are stored per 1 lot; lots x lot size (dated) is applied only at P&L time.
  4. Explicit conventions: credit = negative combined premium; CE long / short follows buy-sell and CE-PE; all times IST; bar timestamps floored to the minute.
  5. Deterministic fills on 1-min OHLC (section 4), configurable, documented, so results are reproducible and comparable.
  6. Spot, futures or synthetic (implied) ATM as an explicit choice.

2. Feature matrix and phase​

2.1 Instruments and timing​

FeatureSAXPhase
NSE index options: NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTYxxxP1
BSE: SENSEX, BANKEXxxP1
Futures legsxxxP1
Stock options / stock futures (NIFTY 500)xxP3
MCX (crude, gold...)xP3
Intraday (same-day entry and exit)xxxP1
BTST / next-day exitxxP1
Positional by expiry, entry / exit N trading days before expiry (DTE)xxP1
Entry time, exit time, last-entry time ("no re-entry after"), stop-monitoring timexxxP1
Run-on weekdays, date range, expiry-day-only, DTE filterxxxP1
Budget / RBI-policy days filterxP2
Intraday start at 09:16 option (skip 09:15 bar)xP1

2.2 Legs and strike selection​

FeatureSAXPhase
Buy/Sell, CE/PE/FUT, lots, expiry weekly / next weekly / monthly / next monthlyxxxP1
ATM +/- n strikes (ITM/OTM n), fixed strikexxxP1
ATM +/- %, "% of ATM"xxP1
Closest premium; premium >= / <= / rangexxxP1
Straddle width (multiplier of ATM straddle)xxxP1
Closest premium as % of ATM straddlexxxP1
ATM from spot / futures / synthetic (strike + CE - PE)xxxP1 spot+fut, P2 synthetic
Delta / delta range / nearest delta; IV, theta basedxxP2 (needs greeks)
Strike step override, max depth, ITM/OTM/both side for premium searchesxP1
Risk-on / risk-off strike shift on re-executionxP2
Hedge leg: static (add a leg)xxxP1
Hedge leg: dynamic (distance from ATM + max premium)xxP2
Per-leg start time / idle legxP1

2.3 Entry conditions​

FeatureSAXPhase
Enter at start timexxxP1
Leg wait and trade (+/- points or %)xxxP1
Combined wait and tradexP2
Range breakout on underlying (window, buffer, high / low)xxxP2 - done
Range breakout on leg premium / opposite-side SLxxxP2 - done (opposite-side SL not yet)
Strategy range breakout (straddle premium), rolling straddle breakoutxP2
Combined-premium entry, crossover; underlying-level entryxP2 - combined premium done
Premium gap between CE and PE (straddle balance)xP2
Gap-up / gap-down, previous-day high / low, day-change filtersxP2
Quantity by exposure / max lotsxP3
Indicator-based entry (AlgoTest "Indicator")xP3

2.4 Leg risk rules​

FeatureSAXPhase
Stop loss, target: % of premium, pointsxxxP1
SL / target on underlying (points, %, level), on strikexxP1
SL / target on delta / thetaxxP2
Absolute premium SL / targetxP1
Trail SL (step + move, points or %)xxxP1
Profit lock + trail (rupees) on legsxP2
Move SL to cost (all legs / after trail)xxxP1
Square-off mode: only the hit leg, or whole strategyxxxP1
Monitoring: realtime (bar high/low) vs minute-close (bar close, n-min candles)xP1
SL wait secondsxnot modelled (use minute-close)

2.5 Re-entry and adjustment actions​

FeatureSAXPhase
Re-entry on SL / target at original price (RE COST)xxxP2 - done
Re-execute leg ASAP (fresh strike), with max countxxxP2 - done
Momentum re-entry, reverse variants, lazy legxP2
Re-execute at opposite leg's premium (straddle re-balance)xP2
Execute / square-off other leg on event (adjustments), duplicate and executexP2
Pyramiding / keep leg runningxP2
Journey (chained re-entries)xP3
Re-execute portfolio on SL / target / complete (incl. at entry price)xP3
Re-entry trigger on SL price / entry price + bufferxP3

2.6 Portfolio risk rules​

FeatureSAXPhase
Overall SL / target in MTM rupeesxxxP1
Overall SL / target as % of premiumxxxP1
Overall SL / target on underlying move or bandxP2
Overall momentum entryxP3
Profit lock + trail, protect-the-profits (portfolio)xxxP2
Combined SL trailxP2
CE-side / PE-side combined P&L limitsxP2
SqOff only loss-making legs on combined SLxP2
CE vs PE premium-difference exitxP3
Overall re-entry / re-execute on SL or targetxxP3
Strategy-group and account-level max profit / lossxP3

2.7 Costs, data and results​

FeatureSAXPhase
Slippage % (default 0.5 %), brokerage, STT, exchange charges, GST, stamp duty (effective-dated)x?n/aP1
Variable lot sizes by datexxxP1
P&L, equity curve, drawdown, win rate, profit factor, avg win / loss, streaksxxP1
Day-wise, month-wise, weekday-wise, leg-wise tables, trade logxxP1
Margin / capital based return %xxP2
Save / load strategy, templates (straddle, strangle, condor, spreads...)xxxP1
Import / export strategy file, PDF reportxxP2
Payoff graph for the strategy at entryxxP2
Compare runs, parameter sweep / optimiserP3
Live / paper trading hand-offxxout of scope
Broker plumbing: orders, retries, slicing, users, rolesxout of scope

3. Phase 1 definition (final)​

Goal: reproduce a typical StockMock / AlgoTest TBS backtest (multi-leg, intraday / BTST / positional-by-DTE, leg and overall SL / target / trail, move-SL-to-cost, costs) on our NSE + BSE 1-min data, with the event-driven core already in place so Phase 2 adds actions, not a rewrite.

P1 contains: all P1 rows above. Specifically:

  • NIFTY / BANKNIFTY / FINNIFTY / MIDCPNIFTY / SENSEX / BANKEX, options and futures legs, spot or futures ATM.
  • Strike rules: offset steps, ATM %, closest premium, premium >= / <= / range (with depth and side), straddle width, % of straddle.
  • Per-leg: SL / target (premium %, points, absolute, underlying), trail SL, per-leg start time and idle legs (engine supports them even if the UI hides them), simple wait-and-trade, static hedge legs.
  • Strategy: entry / exit time, BTST, positional with entry / exit DTE, last-entry time, run-on days, overall SL / target (MTM and % premium), square-off one-leg vs all, move SL to cost, monitoring realtime vs minute-close.
  • Costs and lot sizes by date; metrics and tables; strategy save / load / templates.

Engine hooks that exist in P1 but are only exposed in P2: the actions list on leg events (so re-entry / re-execute are config, not code changes), condition filters, range-window helper.

4. Fill model on 1-minute bars (decisions to confirm)​

SituationRule (default, configurable)
EntryOpen of the entry-time bar (or close of the previous bar); optional skip of 09:15 (start 09:16)
SL / target touched in a barSL evaluated against bar high (short) / low (long); fill at trigger price if bar opened inside, else at open (gap)
SL and target both inside the same barSL first (conservative); option target_first
Minute-close monitoringevaluate on bar close, fill at that close
Trail SLupdated at bar close, effective from next bar
Two legs hit in the same barprocess in leg order; move-SL-to-cost applies from the next bar
Exit timeopen of the exit-time bar (verified against StockMock, see validation page); option exit_at: close
Slippage% of price against the trade. slippage_on: both (default) slips entry and exit; entry matches StockMock, which slips only the entry fill
SL / target levelscomputed from the slipped entry fill, and an SL / target exit fills at the exact level (verified against StockMock)
Square-off-all (other legs)fill.square_off_at: close (default), interp (open + f x (close - open), f = how far the triggering leg got) or stockmock (interp x 0.988, fitted on about 320 StockMock exits)
ATM strikespot at HH:MM:00 = close of the previous bar (fill.atm_at: prev_close, default); entry_bar uses the entry bar price
Gap through SL / targetfill.gap_fill: open (default) or level (StockMock)
BTST on expiry dayskipped (timing.skip_expiry_day, default true; StockMock does the same)
Missing bar for a contractcarry previous close; flag the day; if no bar at entry, skip the leg and flag
Expiry daycontract settles at last available traded price; ITM index options at intrinsic (check data end-of-day)

5. Strategy JSON (sketch)​

{
"name": "920 short straddle",
"underlying": "NIFTY", "atm_from": "spot",
"timing": {"mode": "intraday", "entry": "09:20", "exit": "15:15",
"last_entry": null, "entry_dte": null, "exit_dte": null,
"run_on": ["MON","TUE","WED","THU","FRI"]},
"legs": [
{"id": 1, "segment": "OPT", "side": "SELL", "type": "CE", "lots": 1,
"expiry": "weekly",
"strike": {"rule": "atm_offset", "steps": 0},
"sl": {"basis": "premium_pct", "value": 25},
"target": null,
"trail_sl": {"step": 10, "move": 5, "unit": "pct"},
"wait_trade": null, "start": null, "idle": false,
"monitor": "realtime",
"on_sl": [], "on_target": []}
],
"overall": {"sl": {"basis": "mtm", "value": 5000}, "target": null,
"square_off": "all", "move_sl_to_cost": true},
"costs": {"slippage_pct": 0.5, "brokerage_per_order": 20, "charges": "default"},
"range": {"from": "2022-01-01", "to": "2026-10-16"}
}

on_sl / on_target hold action objects (P2): {"do": "reenter"|"reexecute"|"execute_leg"|"sqoff_leg"|"sqoff_all", "max": 2, ...}.

6. Simulator outline​

for each trading day matching filters:
load day data (spot, futures, chain bars for needed expiry)
state = new Day(spec)
for each minute bar t in [entry_start, exit]:
1. activate legs due at t (start time / idle triggers / W&T hit)
2. evaluate leg SL / target / trail for open legs (monitor mode)
3. evaluate overall SL / target / lock
4. run actions queued by events (open / close / re-create legs)
5. apply move-SL-to-cost if triggered
force-close open legs at exit (or carry to next day for BTST / positional)
emit trades, daily P&L

Positional / BTST: carry state across days and monitor within allowed windows only.

7. Open questions for you​

  1. Fill defaults in section 4 (SL-first, trigger-price fill, gap fill at open): accept?
  2. Default slippage 0.5 % per fill and a brokerage of Rs 20 per order: right for your broker?
  3. FINNIFTY / MIDCPNIFTY: do we have 1-min option data for them, or NIFTY / BANKNIFTY / SENSEX / BANKEX only?
  4. Do you want to compare against StockMock results as the validation target (same strategy, same period) - and for AlgoTest too?
  5. Greeks (delta strikes, delta SL): Phase 2 via Black-Scholes from bar prices - OK?

8. Data availability (checked locally 17 Oct 2026)​

UnderlyingIndex option 1-min barsVerdict
NIFTY2016-06 to 2026-07-13 (about 1,200 to 11,000 contracts per year)Full. 2008-2015 holds the futures only, so no option backtests before Jun 2016
BANKNIFTY2016-06 to 2026-07-13Full (2025 has fewer contracts: monthly-only era)
FINNIFTY2021-01 to 2026-07-13Thin in 2021-22 (under 2M bars a year), good from 2023
MIDCPNIFTY2022 to 2026-07-132022 is nearly empty (7k bars), 2023 partial, usable from 2024
SENSEX / BANKEXonly the Fyers store locally (2023, 2025, 2026 folders, sparse); the vendor store eodieod/ is not on this machineNot usable for a full backtest until the vendor store is synced (Milestone 2 adapter via bseieod/reader.py)

The local store ends on 2026-07-13, so StockMock comparisons should use periods before that.

9. Milestone status (17 Oct 2026)​

M1 (commit a2928a1): spec, strike rules, intraday simulator, costs, NSE loader, CLI; validated against StockMock (see StockMock Validation).

M2: runner with progress / cancel / process-pool workers, metrics (drawdown, streaks, month and weekday tables), BTST and positional trades (sessions joined, DTE scheduling, expiry flags), BSE loader (spot synthesized from put-call parity when the spot store is missing), bt_run / bt_trade tables with migration c3a91d5e7b42, /api/tbs/*, 11 templates, 51 unit tests. Real-data checks: NIFTY month 36 s on 1 worker, 14 s on 4 (identical results); BTST, positional and SENSEX runs complete. Knowledge-base page: TBS Backtester.

Phase 1b UI (done): /tbs page - builder, run with polling, Summary / Equity / Day-wise / Trades tabs.

Validation (done 18 Oct 2026): 1 year NIFTY, 1 year BANKNIFTY, BTST and positional all checked against StockMock - see StockMock Validation.

Next: SENSEX validation once the vendor store is synced, then Phase 2 actions (re-entry / re-execute, range breakout, greeks).

Phase 2 (18 Oct 2026): re-entry / re-execute (asap and at cost, count, reverse, on SL and on target), range breakout (leg premium and underlying, buffer) and combined-premium entry are in the engine, API (seq on trades, migration d5e8a2b91c64), templates and UI. 13 new tests; the validated Phase 1 runs reproduce to the paisa. Still open from the matrix: opposite-side SL on a range, crossover entry, underlying-level entry, momentum / cost / lazy re-entry variants, execute-other-leg actions, portfolio re-execute, delta strikes. Validating Phase 2 against StockMock/AlgoTest needs its own runs.