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
- One strategy = one JSON (portable, hashable, saved to
st_master, importable / exportable). Every UI form is just an editor for this JSON. - 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. - Rules are stored per 1 lot; lots x lot size (dated) is applied only at P&L time.
- Explicit conventions: credit = negative combined premium; CE long / short follows buy-sell and CE-PE; all times IST; bar timestamps floored to the minute.
- Deterministic fills on 1-min OHLC (section 4), configurable, documented, so results are reproducible and comparable.
- Spot, futures or synthetic (implied) ATM as an explicit choice.
2. Feature matrix and phase
2.1 Instruments and timing
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| NSE index options: NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY | x | x | x | P1 |
| BSE: SENSEX, BANKEX | x | x | P1 | |
| Futures legs | x | x | x | P1 |
| Stock options / stock futures (NIFTY 500) | x | x | P3 | |
| MCX (crude, gold...) | x | P3 | ||
| Intraday (same-day entry and exit) | x | x | x | P1 |
| BTST / next-day exit | x | x | P1 | |
| Positional by expiry, entry / exit N trading days before expiry (DTE) | x | x | P1 | |
| Entry time, exit time, last-entry time ("no re-entry after"), stop-monitoring time | x | x | x | P1 |
| Run-on weekdays, date range, expiry-day-only, DTE filter | x | x | x | P1 |
| Budget / RBI-policy days filter | x | P2 | ||
| Intraday start at 09:16 option (skip 09:15 bar) | x | P1 |
2.2 Legs and strike selection
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Buy/Sell, CE/PE/FUT, lots, expiry weekly / next weekly / monthly / next monthly | x | x | x | P1 |
| ATM +/- n strikes (ITM/OTM n), fixed strike | x | x | x | P1 |
| ATM +/- %, "% of ATM" | x | x | P1 | |
| Closest premium; premium >= / <= / range | x | x | x | P1 |
| Straddle width (multiplier of ATM straddle) | x | x | x | P1 |
| Closest premium as % of ATM straddle | x | x | x | P1 |
| ATM from spot / futures / synthetic (strike + CE - PE) | x | x | x | P1 spot+fut, P2 synthetic |
| Delta / delta range / nearest delta; IV, theta based | x | x | P2 (needs greeks) | |
| Strike step override, max depth, ITM/OTM/both side for premium searches | x | P1 | ||
| Risk-on / risk-off strike shift on re-execution | x | P2 | ||
| Hedge leg: static (add a leg) | x | x | x | P1 |
| Hedge leg: dynamic (distance from ATM + max premium) | x | x | P2 | |
| Per-leg start time / idle leg | x | P1 |
2.3 Entry conditions
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Enter at start time | x | x | x | P1 |
| Leg wait and trade (+/- points or %) | x | x | x | P1 |
| Combined wait and trade | x | P2 | ||
| Range breakout on underlying (window, buffer, high / low) | x | x | x | P2 - done |
| Range breakout on leg premium / opposite-side SL | x | x | x | P2 - done (opposite-side SL not yet) |
| Strategy range breakout (straddle premium), rolling straddle breakout | x | P2 | ||
| Combined-premium entry, crossover; underlying-level entry | x | P2 - combined premium done | ||
| Premium gap between CE and PE (straddle balance) | x | P2 | ||
| Gap-up / gap-down, previous-day high / low, day-change filters | x | P2 | ||
| Quantity by exposure / max lots | x | P3 | ||
| Indicator-based entry (AlgoTest "Indicator") | x | P3 |
2.4 Leg risk rules
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Stop loss, target: % of premium, points | x | x | x | P1 |
| SL / target on underlying (points, %, level), on strike | x | x | P1 | |
| SL / target on delta / theta | x | x | P2 | |
| Absolute premium SL / target | x | P1 | ||
| Trail SL (step + move, points or %) | x | x | x | P1 |
| Profit lock + trail (rupees) on legs | x | P2 | ||
| Move SL to cost (all legs / after trail) | x | x | x | P1 |
| Square-off mode: only the hit leg, or whole strategy | x | x | x | P1 |
| Monitoring: realtime (bar high/low) vs minute-close (bar close, n-min candles) | x | P1 | ||
| SL wait seconds | x | not modelled (use minute-close) |
2.5 Re-entry and adjustment actions
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Re-entry on SL / target at original price (RE COST) | x | x | x | P2 - done |
| Re-execute leg ASAP (fresh strike), with max count | x | x | x | P2 - done |
| Momentum re-entry, reverse variants, lazy leg | x | P2 | ||
| Re-execute at opposite leg's premium (straddle re-balance) | x | P2 | ||
| Execute / square-off other leg on event (adjustments), duplicate and execute | x | P2 | ||
| Pyramiding / keep leg running | x | P2 | ||
| Journey (chained re-entries) | x | P3 | ||
| Re-execute portfolio on SL / target / complete (incl. at entry price) | x | P3 | ||
| Re-entry trigger on SL price / entry price + buffer | x | P3 |
2.6 Portfolio risk rules
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Overall SL / target in MTM rupees | x | x | x | P1 |
| Overall SL / target as % of premium | x | x | x | P1 |
| Overall SL / target on underlying move or band | x | P2 | ||
| Overall momentum entry | x | P3 | ||
| Profit lock + trail, protect-the-profits (portfolio) | x | x | x | P2 |
| Combined SL trail | x | P2 | ||
| CE-side / PE-side combined P&L limits | x | P2 | ||
| SqOff only loss-making legs on combined SL | x | P2 | ||
| CE vs PE premium-difference exit | x | P3 | ||
| Overall re-entry / re-execute on SL or target | x | x | P3 | |
| Strategy-group and account-level max profit / loss | x | P3 |
2.7 Costs, data and results
| Feature | S | A | X | Phase |
|---|---|---|---|---|
| Slippage % (default 0.5 %), brokerage, STT, exchange charges, GST, stamp duty (effective-dated) | x | ? | n/a | P1 |
| Variable lot sizes by date | x | x | x | P1 |
| P&L, equity curve, drawdown, win rate, profit factor, avg win / loss, streaks | x | x | P1 | |
| Day-wise, month-wise, weekday-wise, leg-wise tables, trade log | x | x | P1 | |
| Margin / capital based return % | x | x | P2 | |
| Save / load strategy, templates (straddle, strangle, condor, spreads...) | x | x | x | P1 |
| Import / export strategy file, PDF report | x | x | P2 | |
| Payoff graph for the strategy at entry | x | x | P2 | |
| Compare runs, parameter sweep / optimiser | P3 | |||
| Live / paper trading hand-off | x | x | out of scope | |
| Broker plumbing: orders, retries, slicing, users, roles | x | out 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)
| Situation | Rule (default, configurable) |
|---|---|
| Entry | Open of the entry-time bar (or close of the previous bar); optional skip of 09:15 (start 09:16) |
| SL / target touched in a bar | SL 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 bar | SL first (conservative); option target_first |
| Minute-close monitoring | evaluate on bar close, fill at that close |
| Trail SL | updated at bar close, effective from next bar |
| Two legs hit in the same bar | process in leg order; move-SL-to-cost applies from the next bar |
| Exit time | open 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 levels | computed 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 strike | spot 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 / target | fill.gap_fill: open (default) or level (StockMock) |
| BTST on expiry day | skipped (timing.skip_expiry_day, default true; StockMock does the same) |
| Missing bar for a contract | carry previous close; flag the day; if no bar at entry, skip the leg and flag |
| Expiry day | contract 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
- Fill defaults in section 4 (SL-first, trigger-price fill, gap fill at open): accept?
- Default slippage 0.5 % per fill and a brokerage of Rs 20 per order: right for your broker?
- FINNIFTY / MIDCPNIFTY: do we have 1-min option data for them, or NIFTY / BANKNIFTY / SENSEX / BANKEX only?
- Do you want to compare against StockMock results as the validation target (same strategy, same period) - and for AlgoTest too?
- Greeks (delta strikes, delta SL): Phase 2 via Black-Scholes from bar prices - OK?
8. Data availability (checked locally 17 Oct 2026)
| Underlying | Index option 1-min bars | Verdict |
|---|---|---|
| NIFTY | 2016-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 |
| BANKNIFTY | 2016-06 to 2026-07-13 | Full (2025 has fewer contracts: monthly-only era) |
| FINNIFTY | 2021-01 to 2026-07-13 | Thin in 2021-22 (under 2M bars a year), good from 2023 |
| MIDCPNIFTY | 2022 to 2026-07-13 | 2022 is nearly empty (7k bars), 2023 partial, usable from 2024 |
| SENSEX / BANKEX | only the Fyers store locally (2023, 2025, 2026 folders, sparse); the vendor store eodieod/ is not on this machine | Not 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.