skewtape 0.0.1 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +182 -0
- package/dist/cjs/backtest.d.ts +146 -0
- package/dist/cjs/backtest.js +410 -0
- package/dist/cjs/client.d.ts +255 -0
- package/dist/cjs/client.js +447 -0
- package/dist/cjs/download.d.ts +33 -0
- package/dist/cjs/download.js +160 -0
- package/dist/cjs/errors.d.ts +76 -0
- package/dist/cjs/errors.js +159 -0
- package/dist/cjs/exact.d.ts +36 -0
- package/dist/cjs/exact.js +168 -0
- package/dist/cjs/fees.d.ts +68 -0
- package/dist/cjs/fees.js +196 -0
- package/dist/cjs/geoblock.d.ts +48 -0
- package/dist/cjs/geoblock.js +78 -0
- package/dist/cjs/index.d.ts +31 -0
- package/dist/cjs/index.js +98 -0
- package/dist/cjs/kalshi.d.ts +261 -0
- package/dist/cjs/kalshi.js +416 -0
- package/dist/cjs/keccak.d.ts +10 -0
- package/dist/cjs/keccak.js +84 -0
- package/dist/cjs/msgpack.d.ts +15 -0
- package/dist/cjs/msgpack.js +112 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/paginated.d.ts +26 -0
- package/dist/cjs/paginated.js +51 -0
- package/dist/cjs/quote-math.d.ts +146 -0
- package/dist/cjs/quote-math.js +446 -0
- package/dist/cjs/quote.d.ts +108 -0
- package/dist/cjs/quote.js +307 -0
- package/dist/cjs/route-hyperliquid.d.ts +228 -0
- package/dist/cjs/route-hyperliquid.js +387 -0
- package/dist/cjs/route.d.ts +297 -0
- package/dist/cjs/route.js +516 -0
- package/dist/cjs/stream.d.ts +99 -0
- package/dist/cjs/stream.js +529 -0
- package/dist/cjs/version.d.ts +6 -0
- package/dist/cjs/version.js +9 -0
- package/dist/esm/backtest.d.ts +146 -0
- package/dist/esm/backtest.js +403 -0
- package/dist/esm/client.d.ts +255 -0
- package/dist/esm/client.js +441 -0
- package/dist/esm/download.d.ts +33 -0
- package/dist/esm/download.js +155 -0
- package/dist/esm/errors.d.ts +76 -0
- package/dist/esm/errors.js +142 -0
- package/dist/esm/exact.d.ts +36 -0
- package/dist/esm/exact.js +158 -0
- package/dist/esm/fees.d.ts +68 -0
- package/dist/esm/fees.js +185 -0
- package/dist/esm/geoblock.d.ts +48 -0
- package/dist/esm/geoblock.js +74 -0
- package/dist/esm/index.d.ts +31 -0
- package/dist/esm/index.js +30 -0
- package/dist/esm/kalshi.d.ts +261 -0
- package/dist/esm/kalshi.js +404 -0
- package/dist/esm/keccak.d.ts +10 -0
- package/dist/esm/keccak.js +80 -0
- package/dist/esm/msgpack.d.ts +15 -0
- package/dist/esm/msgpack.js +109 -0
- package/dist/esm/paginated.d.ts +26 -0
- package/dist/esm/paginated.js +47 -0
- package/dist/esm/quote-math.d.ts +146 -0
- package/dist/esm/quote-math.js +437 -0
- package/dist/esm/quote.d.ts +108 -0
- package/dist/esm/quote.js +297 -0
- package/dist/esm/route-hyperliquid.d.ts +228 -0
- package/dist/esm/route-hyperliquid.js +376 -0
- package/dist/esm/route.d.ts +297 -0
- package/dist/esm/route.js +507 -0
- package/dist/esm/stream.d.ts +99 -0
- package/dist/esm/stream.js +524 -0
- package/dist/esm/version.d.ts +6 -0
- package/dist/esm/version.js +6 -0
- package/package.json +48 -1
- package/src/backtest.ts +490 -0
- package/src/client.ts +595 -0
- package/src/download.ts +161 -0
- package/src/errors.ts +143 -0
- package/src/exact.ts +159 -0
- package/src/fees.ts +189 -0
- package/src/generated/schema.d.ts +2500 -0
- package/src/geoblock.ts +90 -0
- package/src/index.ts +146 -0
- package/src/kalshi.ts +563 -0
- package/src/keccak.ts +82 -0
- package/src/msgpack.ts +83 -0
- package/src/paginated.ts +51 -0
- package/src/quote-math.ts +555 -0
- package/src/quote.ts +324 -0
- package/src/route-hyperliquid.ts +457 -0
- package/src/route.ts +631 -0
- package/src/stream.ts +539 -0
- package/src/version.ts +6 -0
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fee-aware P&L for a list of trades the caller supplies, over the history
|
|
3
|
+
* Skewtape records (story E4).
|
|
4
|
+
*
|
|
5
|
+
* This is arithmetic on history. Each trade is priced at its own price, or at
|
|
6
|
+
* the last recorded fill or candle at or before its time; the fee the schedule
|
|
7
|
+
* in force charges is taken off; every position is then valued at the outcome
|
|
8
|
+
* its market resolved to, or, still open, at the last recorded price at or
|
|
9
|
+
* before asOf. Nothing is read from after asOf. It forecasts nothing, suggests
|
|
10
|
+
* no trade and optimises nothing: the result is what these trades come to on
|
|
11
|
+
* the record, before and after fees.
|
|
12
|
+
*
|
|
13
|
+
* Amounts are exact bigints in raw units (a position's at its fill decimals,
|
|
14
|
+
* totals at the largest decimals among the positions); prices are exact
|
|
15
|
+
* fractions, shown as decimal strings when they end. conformance/backtest.json
|
|
16
|
+
* pins the arithmetic, and the Python and TypeScript SDKs pass the same vectors.
|
|
17
|
+
*
|
|
18
|
+
* import { runBacktest } from "skewtape";
|
|
19
|
+
* const result = runBacktest(trades, { asOf, fees, markets, resolutions, fills });
|
|
20
|
+
* console.log(result.totals.pnl_raw, result.totals.fees_raw);
|
|
21
|
+
*
|
|
22
|
+
* sk.backtest(trades) fetches the fees, markets, resolutions and price history
|
|
23
|
+
* for the trades first, then runs the same function.
|
|
24
|
+
*/
|
|
25
|
+
import { SkewtapeError, type ErrorFields } from "./errors.js";
|
|
26
|
+
import { type FeeRowInput } from "./fees.js";
|
|
27
|
+
export declare const CANDLE_MICROS: Record<string, bigint>;
|
|
28
|
+
/** A backtest that cannot run as asked; code says why: bad_trade, after_as_of, price_missing, fee_row_missing, decimals_mismatch. */
|
|
29
|
+
export declare class BacktestError extends SkewtapeError {
|
|
30
|
+
constructor(message: string, code: string, fields?: ErrorFields);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* One trade to replay. side is buy or sell (of token_id), role taker (the
|
|
34
|
+
* default) or maker. The size is size (shares, a decimal) or size_raw (raw
|
|
35
|
+
* units at decimals); the price is price (0 to 1), or notional_raw (raw
|
|
36
|
+
* units, exact), or neither, and then the history prices it. decimals and
|
|
37
|
+
* fee_category default to the history's and the market's.
|
|
38
|
+
*/
|
|
39
|
+
export interface Trade {
|
|
40
|
+
venue: string;
|
|
41
|
+
market_id: string;
|
|
42
|
+
token_id: string;
|
|
43
|
+
side: "buy" | "sell" | string;
|
|
44
|
+
ts: Date | string;
|
|
45
|
+
size?: string | number | bigint;
|
|
46
|
+
size_raw?: number | bigint | string;
|
|
47
|
+
price?: string | number;
|
|
48
|
+
notional_raw?: number | bigint | string;
|
|
49
|
+
role?: "taker" | "maker" | string;
|
|
50
|
+
decimals?: number;
|
|
51
|
+
fee_category?: string;
|
|
52
|
+
}
|
|
53
|
+
type Row = Record<string, unknown>;
|
|
54
|
+
/** One trade as replayed: size, notional and fee in raw units at decimals, the price and its source, the fee row used, the cash it moved. */
|
|
55
|
+
export interface TradeResult {
|
|
56
|
+
index: number;
|
|
57
|
+
venue: string;
|
|
58
|
+
market_id: string;
|
|
59
|
+
token_id: string;
|
|
60
|
+
side: string;
|
|
61
|
+
role: string;
|
|
62
|
+
ts: string;
|
|
63
|
+
decimals: number;
|
|
64
|
+
size_raw: bigint;
|
|
65
|
+
notional_raw: bigint;
|
|
66
|
+
price: string;
|
|
67
|
+
price_source: "given" | "notional" | "fill" | "candle";
|
|
68
|
+
fee_raw: bigint;
|
|
69
|
+
fee_category: string | null;
|
|
70
|
+
fee_row_effective_from: string | null;
|
|
71
|
+
cash_raw: bigint;
|
|
72
|
+
}
|
|
73
|
+
/** One (venue, market, token) position and its value at asOf; value_raw and pnl_raw are null when nothing values it. */
|
|
74
|
+
export interface PositionResult {
|
|
75
|
+
venue: string;
|
|
76
|
+
market_id: string;
|
|
77
|
+
token_id: string;
|
|
78
|
+
decimals: number;
|
|
79
|
+
shares_raw: bigint;
|
|
80
|
+
bought_raw: bigint;
|
|
81
|
+
sold_raw: bigint;
|
|
82
|
+
fees_raw: bigint;
|
|
83
|
+
cash_raw: bigint;
|
|
84
|
+
status: "resolved" | "voided" | "open";
|
|
85
|
+
outcome: string | null;
|
|
86
|
+
payout: string | null;
|
|
87
|
+
mark_price: string | null;
|
|
88
|
+
value_raw: bigint | null;
|
|
89
|
+
value_source: "resolution" | "void_payout" | "mark" | null;
|
|
90
|
+
pnl_raw: bigint | null;
|
|
91
|
+
pnl_before_fees_raw: bigint | null;
|
|
92
|
+
}
|
|
93
|
+
/** Every valued position summed at decimals; fees_raw is their fees (the fee impact), fees_paid_raw every trade's. */
|
|
94
|
+
export interface Totals {
|
|
95
|
+
decimals: number;
|
|
96
|
+
pnl_raw: bigint;
|
|
97
|
+
pnl_before_fees_raw: bigint;
|
|
98
|
+
fees_raw: bigint;
|
|
99
|
+
fees_paid_raw: bigint;
|
|
100
|
+
realized_pnl_raw: bigint;
|
|
101
|
+
unrealized_pnl_raw: bigint;
|
|
102
|
+
complete: boolean;
|
|
103
|
+
}
|
|
104
|
+
/** fee_row_missing, oversold, trade_after_resolution, outcome_unmatched, voided_unsettled or no_mark, with a sentence. */
|
|
105
|
+
export interface BacktestWarning {
|
|
106
|
+
code: string;
|
|
107
|
+
message: string;
|
|
108
|
+
trade: number | null;
|
|
109
|
+
position: [string, string, string] | null;
|
|
110
|
+
}
|
|
111
|
+
export interface BacktestResult {
|
|
112
|
+
as_of: string;
|
|
113
|
+
trades: TradeResult[];
|
|
114
|
+
positions: PositionResult[];
|
|
115
|
+
totals: Totals;
|
|
116
|
+
warnings: BacktestWarning[];
|
|
117
|
+
}
|
|
118
|
+
export interface BacktestOptions {
|
|
119
|
+
asOf: Date | string;
|
|
120
|
+
fees: Iterable<FeeRowInput>;
|
|
121
|
+
markets?: Iterable<Row>;
|
|
122
|
+
resolutions?: Iterable<Row>;
|
|
123
|
+
fills?: Iterable<Row>;
|
|
124
|
+
candles?: Iterable<Row>;
|
|
125
|
+
/** Fills or candles first when both price a time. fills by default. */
|
|
126
|
+
prefer?: "fills" | "candles";
|
|
127
|
+
/** A decimal per share that settles a voided market; without it a voided position stays unvalued. */
|
|
128
|
+
voidPayout?: string | number;
|
|
129
|
+
/** error (the default) refuses a trade no fee row covers; zero counts its fee as zero and warns. */
|
|
130
|
+
onMissingFee?: "error" | "zero";
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Replay trades over the history given and value every position at asOf. See
|
|
134
|
+
* the module comment; the arithmetic is the Python SDK's, vector for vector.
|
|
135
|
+
*/
|
|
136
|
+
export declare function runBacktest(trades: Iterable<Trade | Row>, options: BacktestOptions): BacktestResult;
|
|
137
|
+
/**
|
|
138
|
+
* Whether a market's resolution events settle its positions at asOf, so they
|
|
139
|
+
* need no mark: resolved to an outcome, or voided (valued by voidPayout, or
|
|
140
|
+
* left unvalued with a warning). sk.backtest reads the asOf window only for
|
|
141
|
+
* markets this is false for.
|
|
142
|
+
*/
|
|
143
|
+
export declare function settledAt(rows: Iterable<Row>, asOf: Date | string): boolean;
|
|
144
|
+
/** A result with every bigint as a number, for JSON: the shape of the Python SDK's to_dict(). An amount past 2^53 stays a decimal string. */
|
|
145
|
+
export declare function backtestToJSON(result: BacktestResult): unknown;
|
|
146
|
+
export {};
|
|
@@ -0,0 +1,403 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fee-aware P&L for a list of trades the caller supplies, over the history
|
|
3
|
+
* Skewtape records (story E4).
|
|
4
|
+
*
|
|
5
|
+
* This is arithmetic on history. Each trade is priced at its own price, or at
|
|
6
|
+
* the last recorded fill or candle at or before its time; the fee the schedule
|
|
7
|
+
* in force charges is taken off; every position is then valued at the outcome
|
|
8
|
+
* its market resolved to, or, still open, at the last recorded price at or
|
|
9
|
+
* before asOf. Nothing is read from after asOf. It forecasts nothing, suggests
|
|
10
|
+
* no trade and optimises nothing: the result is what these trades come to on
|
|
11
|
+
* the record, before and after fees.
|
|
12
|
+
*
|
|
13
|
+
* Amounts are exact bigints in raw units (a position's at its fill decimals,
|
|
14
|
+
* totals at the largest decimals among the positions); prices are exact
|
|
15
|
+
* fractions, shown as decimal strings when they end. conformance/backtest.json
|
|
16
|
+
* pins the arithmetic, and the Python and TypeScript SDKs pass the same vectors.
|
|
17
|
+
*
|
|
18
|
+
* import { runBacktest } from "skewtape";
|
|
19
|
+
* const result = runBacktest(trades, { asOf, fees, markets, resolutions, fills });
|
|
20
|
+
* console.log(result.totals.pnl_raw, result.totals.fees_raw);
|
|
21
|
+
*
|
|
22
|
+
* sk.backtest(trades) fetches the fees, markets, resolutions and price history
|
|
23
|
+
* for the trades first, then runs the same function.
|
|
24
|
+
*/
|
|
25
|
+
import { SkewtapeError } from "./errors.js";
|
|
26
|
+
import { Rat, fractionStr, isoMicros, parseInt64, parseMicros, parseRat, roundHalfUp } from "./exact.js";
|
|
27
|
+
import { COLLATERAL_MICROS_DECIMALS, feeRowOf, makerFeeRaw, selectFeeRow, takerFeeRaw } from "./fees.js";
|
|
28
|
+
export const CANDLE_MICROS = { "1m": 60000000n, "1h": 3600000000n, "1d": 86400000000n };
|
|
29
|
+
/** A backtest that cannot run as asked; code says why: bad_trade, after_as_of, price_missing, fee_row_missing, decimals_mismatch. */
|
|
30
|
+
export class BacktestError extends SkewtapeError {
|
|
31
|
+
constructor(message, code, fields = {}) {
|
|
32
|
+
super(message, { ...fields, code });
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
const TRADE_FIELDS = new Set(["venue", "market_id", "token_id", "side", "ts", "size", "size_raw", "price", "notional_raw", "role", "decimals", "fee_category"]);
|
|
36
|
+
function keyOf(venue, marketId, tokenId) {
|
|
37
|
+
return JSON.stringify([venue, marketId, tokenId]);
|
|
38
|
+
}
|
|
39
|
+
function wrap(run) {
|
|
40
|
+
try {
|
|
41
|
+
return run();
|
|
42
|
+
}
|
|
43
|
+
catch (err) {
|
|
44
|
+
if (err instanceof BacktestError)
|
|
45
|
+
throw err;
|
|
46
|
+
if (err instanceof SkewtapeError)
|
|
47
|
+
throw new BacktestError(err.message, "bad_trade");
|
|
48
|
+
throw err;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
function optMicros(v) {
|
|
52
|
+
if (v === null || v === undefined || v === "")
|
|
53
|
+
return null;
|
|
54
|
+
return wrap(() => parseMicros(v, "time"));
|
|
55
|
+
}
|
|
56
|
+
function lastAtOrBefore(rows, t) {
|
|
57
|
+
if (!rows || rows.length === 0)
|
|
58
|
+
return undefined;
|
|
59
|
+
let lo = 0;
|
|
60
|
+
let hi = rows.length;
|
|
61
|
+
while (lo < hi) {
|
|
62
|
+
const mid = (lo + hi) >> 1;
|
|
63
|
+
if (rows[mid].at <= t)
|
|
64
|
+
lo = mid + 1;
|
|
65
|
+
else
|
|
66
|
+
hi = mid;
|
|
67
|
+
}
|
|
68
|
+
return lo ? rows[lo - 1] : undefined;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Replay trades over the history given and value every position at asOf. See
|
|
72
|
+
* the module comment; the arithmetic is the Python SDK's, vector for vector.
|
|
73
|
+
*/
|
|
74
|
+
export function runBacktest(trades, options) {
|
|
75
|
+
const asOf = wrap(() => parseMicros(options.asOf, "as_of"));
|
|
76
|
+
const prefer = options.prefer ?? "fills";
|
|
77
|
+
if (prefer !== "fills" && prefer !== "candles")
|
|
78
|
+
throw new BacktestError(`prefer is fills or candles, not ${String(prefer)}`, "bad_trade");
|
|
79
|
+
const onMissingFee = options.onMissingFee ?? "error";
|
|
80
|
+
if (onMissingFee !== "error" && onMissingFee !== "zero")
|
|
81
|
+
throw new BacktestError(`onMissingFee is error or zero, not ${String(onMissingFee)}`, "bad_trade");
|
|
82
|
+
const voidPayout = options.voidPayout === undefined || options.voidPayout === null ? null : wrap(() => parseRat(options.voidPayout, "void_payout"));
|
|
83
|
+
if (voidPayout && (voidPayout.n < 0n || voidPayout.cmp(new Rat(1n)) > 0))
|
|
84
|
+
throw new BacktestError("void_payout is between 0 and 1", "bad_trade");
|
|
85
|
+
const feeRows = wrap(() => [...options.fees].map(feeRowOf));
|
|
86
|
+
const marketBy = new Map();
|
|
87
|
+
for (const m of options.markets ?? [])
|
|
88
|
+
marketBy.set(JSON.stringify([String(m.venue), String(m.market_id)]), m);
|
|
89
|
+
const resBy = new Map();
|
|
90
|
+
for (const r of options.resolutions ?? []) {
|
|
91
|
+
const k = JSON.stringify([String(r.venue), String(r.market_id)]);
|
|
92
|
+
resBy.set(k, [...(resBy.get(k) ?? []), r]);
|
|
93
|
+
}
|
|
94
|
+
const byFill = new Map();
|
|
95
|
+
for (const f of options.fills ?? []) {
|
|
96
|
+
if (f.blocked === true)
|
|
97
|
+
continue;
|
|
98
|
+
if (f.size_raw === undefined || f.size_raw === null || f.notional_raw === undefined || f.notional_raw === null)
|
|
99
|
+
continue;
|
|
100
|
+
const size = wrap(() => parseInt64(f.size_raw, "fill size_raw"));
|
|
101
|
+
const notional = wrap(() => parseInt64(f.notional_raw, "fill notional_raw"));
|
|
102
|
+
if (size <= 0n)
|
|
103
|
+
continue;
|
|
104
|
+
const k = keyOf(String(f.venue), String(f.market_id), String(f.token_id));
|
|
105
|
+
byFill.set(k, [...(byFill.get(k) ?? []), { at: wrap(() => parseMicros(f.ts, "fill ts")), price: new Rat(notional, size), decimals: typeof f.decimals === "number" ? f.decimals : null, source: "fill" }]);
|
|
106
|
+
}
|
|
107
|
+
const byCandle = new Map();
|
|
108
|
+
for (const c of options.candles ?? []) {
|
|
109
|
+
const len = CANDLE_MICROS[String(c.res)];
|
|
110
|
+
if (len === undefined || c.close === null || c.close === undefined)
|
|
111
|
+
continue;
|
|
112
|
+
const k = keyOf(String(c.venue), String(c.market_id), String(c.token_id));
|
|
113
|
+
const end = wrap(() => parseMicros(c.ts, "candle ts")) + len;
|
|
114
|
+
byCandle.set(k, [...(byCandle.get(k) ?? []), { at: end, price: wrap(() => parseRat(c.close, "candle close")), decimals: typeof c.decimals === "number" ? c.decimals : null, source: "candle" }]);
|
|
115
|
+
}
|
|
116
|
+
for (const table of [byFill, byCandle])
|
|
117
|
+
for (const rows of table.values())
|
|
118
|
+
rows.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
|
|
119
|
+
const historyPrice = (k, t) => {
|
|
120
|
+
const [first, second] = prefer === "fills" ? [byFill, byCandle] : [byCandle, byFill];
|
|
121
|
+
return lastAtOrBefore(first.get(k), t) ?? lastAtOrBefore(second.get(k), t);
|
|
122
|
+
};
|
|
123
|
+
const anyDecimals = (k) => {
|
|
124
|
+
for (const table of [byFill, byCandle])
|
|
125
|
+
for (const p of table.get(k) ?? [])
|
|
126
|
+
if (p.decimals !== null)
|
|
127
|
+
return p.decimals;
|
|
128
|
+
return null;
|
|
129
|
+
};
|
|
130
|
+
const parsed = [];
|
|
131
|
+
let i = 0;
|
|
132
|
+
for (const raw of trades) {
|
|
133
|
+
const t = raw;
|
|
134
|
+
const unknown = Object.keys(t).filter((k) => !TRADE_FIELDS.has(k));
|
|
135
|
+
if (unknown.length)
|
|
136
|
+
throw new BacktestError(`a trade has unknown fields ${JSON.stringify(unknown.sort())}`, "bad_trade");
|
|
137
|
+
const missing = ["venue", "market_id", "token_id", "side", "ts"].filter((k) => t[k] === undefined || t[k] === null || t[k] === "");
|
|
138
|
+
if (missing.length)
|
|
139
|
+
throw new BacktestError(`a trade needs ${JSON.stringify(missing)}`, "bad_trade");
|
|
140
|
+
if (t.side !== "buy" && t.side !== "sell")
|
|
141
|
+
throw new BacktestError(`trade ${i}: side is buy or sell, not ${t.side}`, "bad_trade");
|
|
142
|
+
const role = t.role ?? "taker";
|
|
143
|
+
if (role !== "taker" && role !== "maker")
|
|
144
|
+
throw new BacktestError(`trade ${i}: role is taker or maker, not ${role}`, "bad_trade");
|
|
145
|
+
if ((t.size === undefined || t.size === null) === (t.size_raw === undefined || t.size_raw === null))
|
|
146
|
+
throw new BacktestError(`trade ${i}: give size or size_raw, one of them`, "bad_trade");
|
|
147
|
+
if (t.price !== undefined && t.price !== null && t.notional_raw !== undefined && t.notional_raw !== null)
|
|
148
|
+
throw new BacktestError(`trade ${i}: give price or notional_raw, not both`, "bad_trade");
|
|
149
|
+
const at = i;
|
|
150
|
+
parsed.push({ i, t, ts: wrap(() => parseMicros(t.ts, `trade ${at} ts`)) });
|
|
151
|
+
i++;
|
|
152
|
+
}
|
|
153
|
+
parsed.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : a.i - b.i));
|
|
154
|
+
const warnings = [];
|
|
155
|
+
const missingFee = [];
|
|
156
|
+
const withheld = [];
|
|
157
|
+
const results = [];
|
|
158
|
+
const positions = new Map();
|
|
159
|
+
for (const { i: idx, t, ts } of parsed) {
|
|
160
|
+
if (ts > asOf)
|
|
161
|
+
throw new BacktestError(`trade ${idx} at ${isoMicros(ts)} is after as_of ${isoMicros(asOf)}`, "after_as_of");
|
|
162
|
+
const role = t.role ?? "taker";
|
|
163
|
+
const k = keyOf(t.venue, t.market_id, t.token_id);
|
|
164
|
+
const hasPrice = t.price !== undefined && t.price !== null;
|
|
165
|
+
const hasNotional = t.notional_raw !== undefined && t.notional_raw !== null;
|
|
166
|
+
let hist;
|
|
167
|
+
if (!hasPrice && !hasNotional) {
|
|
168
|
+
hist = historyPrice(k, ts);
|
|
169
|
+
if (!hist)
|
|
170
|
+
throw new BacktestError(`trade ${idx}: no price given and no fill or candle of ${t.venue} ${t.market_id} ${t.token_id} at or before ${isoMicros(ts)}`, "price_missing");
|
|
171
|
+
}
|
|
172
|
+
const decimals = t.decimals ?? (hist && hist.decimals !== null ? hist.decimals : anyDecimals(k)) ?? COLLATERAL_MICROS_DECIMALS;
|
|
173
|
+
let sizeRaw;
|
|
174
|
+
if (t.size_raw !== undefined && t.size_raw !== null) {
|
|
175
|
+
sizeRaw = wrap(() => parseInt64(t.size_raw, `trade ${idx} size_raw`));
|
|
176
|
+
}
|
|
177
|
+
else {
|
|
178
|
+
const shares = wrap(() => parseRat(t.size, `trade ${idx} size`)).mul(new Rat(10n ** BigInt(decimals)));
|
|
179
|
+
if (!shares.isInt())
|
|
180
|
+
throw new BacktestError(`trade ${idx}: size ${String(t.size)} has more places than ${decimals} decimals hold`, "bad_trade");
|
|
181
|
+
sizeRaw = shares.n;
|
|
182
|
+
}
|
|
183
|
+
if (sizeRaw <= 0n)
|
|
184
|
+
throw new BacktestError(`trade ${idx}: the size must be positive`, "bad_trade");
|
|
185
|
+
let notionalRaw;
|
|
186
|
+
let price;
|
|
187
|
+
let source;
|
|
188
|
+
if (hasNotional) {
|
|
189
|
+
notionalRaw = wrap(() => parseInt64(t.notional_raw, `trade ${idx} notional_raw`));
|
|
190
|
+
price = new Rat(notionalRaw, sizeRaw);
|
|
191
|
+
source = "notional";
|
|
192
|
+
}
|
|
193
|
+
else {
|
|
194
|
+
price = hasPrice ? wrap(() => parseRat(t.price, `trade ${idx} price`)) : hist.price;
|
|
195
|
+
source = hasPrice ? "given" : hist.source;
|
|
196
|
+
notionalRaw = roundHalfUp(price.mul(new Rat(sizeRaw)));
|
|
197
|
+
}
|
|
198
|
+
if (notionalRaw < 0n || notionalRaw > sizeRaw || price.n < 0n || price.cmp(new Rat(1n)) > 0)
|
|
199
|
+
throw new BacktestError(`trade ${idx}: the price must be between 0 and 1`, "bad_trade");
|
|
200
|
+
const market = marketBy.get(JSON.stringify([t.venue, t.market_id]));
|
|
201
|
+
const category = t.fee_category !== undefined && t.fee_category !== null ? t.fee_category : market ? (market.fee_category ?? null) : null;
|
|
202
|
+
const row = selectFeeRow(feeRows, t.venue, category, ts);
|
|
203
|
+
let fee;
|
|
204
|
+
if (!row) {
|
|
205
|
+
if (onMissingFee === "error") {
|
|
206
|
+
missingFee.push(idx);
|
|
207
|
+
if (category === null && market && market.blocked === true)
|
|
208
|
+
withheld.push(idx);
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
fee = 0n;
|
|
212
|
+
warnings.push({ code: "fee_row_missing", message: `no fee row covers ${t.venue} category ${category} at ${isoMicros(ts)}: its fee is counted as zero`, trade: idx, position: null });
|
|
213
|
+
}
|
|
214
|
+
else {
|
|
215
|
+
fee = wrap(() => (role === "taker" ? takerFeeRaw : makerFeeRaw)(row, sizeRaw, notionalRaw, decimals));
|
|
216
|
+
}
|
|
217
|
+
let pos = positions.get(k);
|
|
218
|
+
if (!pos) {
|
|
219
|
+
pos = { venue: t.venue, market_id: t.market_id, token_id: t.token_id, decimals, shares: 0n, bought: 0n, sold: 0n, fees: 0n, cash: 0n };
|
|
220
|
+
positions.set(k, pos);
|
|
221
|
+
}
|
|
222
|
+
if (pos.decimals !== decimals)
|
|
223
|
+
throw new BacktestError(`trade ${idx}: ${decimals} decimals, where this position's other trades have ${pos.decimals}`, "decimals_mismatch");
|
|
224
|
+
let cash;
|
|
225
|
+
if (t.side === "buy") {
|
|
226
|
+
cash = -notionalRaw - fee;
|
|
227
|
+
pos.shares += sizeRaw;
|
|
228
|
+
pos.bought += notionalRaw;
|
|
229
|
+
}
|
|
230
|
+
else {
|
|
231
|
+
cash = notionalRaw - fee;
|
|
232
|
+
pos.shares -= sizeRaw;
|
|
233
|
+
pos.sold += notionalRaw;
|
|
234
|
+
if (pos.shares < 0n)
|
|
235
|
+
warnings.push({ code: "oversold", message: `trade ${idx} sells more ${t.token_id} than the trades before it bought`, trade: idx, position: null });
|
|
236
|
+
}
|
|
237
|
+
pos.fees += fee;
|
|
238
|
+
pos.cash += cash;
|
|
239
|
+
const state = resolutionState(resBy.get(JSON.stringify([t.venue, t.market_id])) ?? [], ts);
|
|
240
|
+
if (state && (state.event_type === "resolved" || state.event_type === "voided")) {
|
|
241
|
+
warnings.push({ code: "trade_after_resolution", message: `trade ${idx} is after its market's ${String(state.event_type)} event`, trade: idx, position: null });
|
|
242
|
+
}
|
|
243
|
+
results.push({
|
|
244
|
+
index: idx,
|
|
245
|
+
venue: t.venue,
|
|
246
|
+
market_id: t.market_id,
|
|
247
|
+
token_id: t.token_id,
|
|
248
|
+
side: t.side,
|
|
249
|
+
role,
|
|
250
|
+
ts: isoMicros(ts),
|
|
251
|
+
decimals,
|
|
252
|
+
size_raw: sizeRaw,
|
|
253
|
+
notional_raw: notionalRaw,
|
|
254
|
+
price: fractionStr(price),
|
|
255
|
+
price_source: source,
|
|
256
|
+
fee_raw: fee,
|
|
257
|
+
fee_category: row ? row.category : null,
|
|
258
|
+
fee_row_effective_from: row ? isoMicros(row.effectiveFrom) : null,
|
|
259
|
+
cash_raw: cash,
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
if (missingFee.length) {
|
|
263
|
+
const why = withheld.length ? ` (the data policy withholds the fee_category of the markets of trades ${JSON.stringify(withheld)})` : "";
|
|
264
|
+
throw new BacktestError(`no fee row covers trades ${JSON.stringify(missingFee)}${why}: pass fee_category on the trade, the fee rows that apply, or onMissingFee "zero"`, "fee_row_missing");
|
|
265
|
+
}
|
|
266
|
+
const outPositions = [];
|
|
267
|
+
for (const [k, pos] of positions) {
|
|
268
|
+
const market = marketBy.get(JSON.stringify([pos.venue, pos.market_id]));
|
|
269
|
+
const state = resolutionState(resBy.get(JSON.stringify([pos.venue, pos.market_id])) ?? [], asOf);
|
|
270
|
+
const event = state ? String(state.event_type) : null;
|
|
271
|
+
let status = "open";
|
|
272
|
+
let outcome = null;
|
|
273
|
+
let payout = null;
|
|
274
|
+
let mark = null;
|
|
275
|
+
let valueSource = null;
|
|
276
|
+
let value = null;
|
|
277
|
+
const tuple = [pos.venue, pos.market_id, pos.token_id];
|
|
278
|
+
if (event === "resolved" && state.outcome !== null && state.outcome !== undefined) {
|
|
279
|
+
outcome = String(state.outcome);
|
|
280
|
+
const token = tokenForOutcome(outcome, market, pos.token_id);
|
|
281
|
+
if (token === null) {
|
|
282
|
+
status = "resolved";
|
|
283
|
+
warnings.push({ code: "outcome_unmatched", message: `${pos.venue} ${pos.market_id} resolved to ${outcome}, which no outcome of the market names: pass the market`, trade: null, position: tuple });
|
|
284
|
+
}
|
|
285
|
+
else {
|
|
286
|
+
status = "resolved";
|
|
287
|
+
payout = new Rat(token === pos.token_id ? 1n : 0n);
|
|
288
|
+
valueSource = "resolution";
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
else if (event === "voided") {
|
|
292
|
+
status = "voided";
|
|
293
|
+
if (voidPayout === null) {
|
|
294
|
+
warnings.push({ code: "voided_unsettled", message: `${pos.venue} ${pos.market_id} was voided: pass void_payout to value it`, trade: null, position: tuple });
|
|
295
|
+
}
|
|
296
|
+
else {
|
|
297
|
+
payout = voidPayout;
|
|
298
|
+
valueSource = "void_payout";
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
if (payout !== null) {
|
|
302
|
+
value = roundHalfUp(payout.mul(new Rat(pos.shares)));
|
|
303
|
+
}
|
|
304
|
+
else if (status === "open") {
|
|
305
|
+
const hist = historyPrice(k, asOf);
|
|
306
|
+
if (!hist) {
|
|
307
|
+
warnings.push({ code: "no_mark", message: `no fill or candle of ${pos.venue} ${pos.market_id} ${pos.token_id} at or before as_of values this open position`, trade: null, position: tuple });
|
|
308
|
+
}
|
|
309
|
+
else {
|
|
310
|
+
mark = hist.price;
|
|
311
|
+
valueSource = "mark";
|
|
312
|
+
value = roundHalfUp(mark.mul(new Rat(pos.shares)));
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
const pnl = value === null ? null : pos.cash + value;
|
|
316
|
+
outPositions.push({
|
|
317
|
+
venue: pos.venue,
|
|
318
|
+
market_id: pos.market_id,
|
|
319
|
+
token_id: pos.token_id,
|
|
320
|
+
decimals: pos.decimals,
|
|
321
|
+
shares_raw: pos.shares,
|
|
322
|
+
bought_raw: pos.bought,
|
|
323
|
+
sold_raw: pos.sold,
|
|
324
|
+
fees_raw: pos.fees,
|
|
325
|
+
cash_raw: pos.cash,
|
|
326
|
+
status,
|
|
327
|
+
outcome,
|
|
328
|
+
payout: payout === null ? null : fractionStr(payout),
|
|
329
|
+
mark_price: mark === null ? null : fractionStr(mark),
|
|
330
|
+
value_raw: value,
|
|
331
|
+
value_source: valueSource,
|
|
332
|
+
pnl_raw: pnl,
|
|
333
|
+
pnl_before_fees_raw: pnl === null ? null : pnl + pos.fees,
|
|
334
|
+
});
|
|
335
|
+
}
|
|
336
|
+
const top = outPositions.reduce((m, p) => Math.max(m, p.decimals), outPositions.length ? 0 : COLLATERAL_MICROS_DECIMALS);
|
|
337
|
+
const scaled = (p, v) => v * 10n ** BigInt(top - p.decimals);
|
|
338
|
+
const valued = outPositions.filter((p) => p.pnl_raw !== null);
|
|
339
|
+
const sum = (ps, f) => ps.reduce((s, p) => s + scaled(p, f(p)), 0n);
|
|
340
|
+
const totals = {
|
|
341
|
+
decimals: top,
|
|
342
|
+
pnl_raw: sum(valued, (p) => p.pnl_raw),
|
|
343
|
+
pnl_before_fees_raw: sum(valued, (p) => p.pnl_before_fees_raw),
|
|
344
|
+
fees_raw: sum(valued, (p) => p.fees_raw),
|
|
345
|
+
fees_paid_raw: sum(outPositions, (p) => p.fees_raw),
|
|
346
|
+
realized_pnl_raw: sum(valued.filter((p) => p.value_source !== "mark"), (p) => p.pnl_raw),
|
|
347
|
+
unrealized_pnl_raw: sum(valued.filter((p) => p.value_source === "mark"), (p) => p.pnl_raw),
|
|
348
|
+
complete: valued.length === outPositions.length,
|
|
349
|
+
};
|
|
350
|
+
results.sort((a, b) => a.index - b.index);
|
|
351
|
+
return { as_of: isoMicros(asOf), trades: results, positions: outPositions, totals, warnings };
|
|
352
|
+
}
|
|
353
|
+
/** The market's resolution event in force at t: the highest seq whose time (resolved_at, else created_at) is at or before t. */
|
|
354
|
+
function resolutionState(rows, t) {
|
|
355
|
+
let best;
|
|
356
|
+
let bestSeq = -Infinity;
|
|
357
|
+
for (const r of rows) {
|
|
358
|
+
const at = optMicros(r.resolved_at) ?? optMicros(r.created_at);
|
|
359
|
+
if (at === null || at > t)
|
|
360
|
+
continue;
|
|
361
|
+
const seq = Number(r.seq ?? 0);
|
|
362
|
+
if (best === undefined || seq > bestSeq) {
|
|
363
|
+
best = r;
|
|
364
|
+
bestSeq = seq;
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
return best;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Whether a market's resolution events settle its positions at asOf, so they
|
|
371
|
+
* need no mark: resolved to an outcome, or voided (valued by voidPayout, or
|
|
372
|
+
* left unvalued with a warning). sk.backtest reads the asOf window only for
|
|
373
|
+
* markets this is false for.
|
|
374
|
+
*/
|
|
375
|
+
export function settledAt(rows, asOf) {
|
|
376
|
+
const state = resolutionState([...rows], parseMicros(asOf, "asOf"));
|
|
377
|
+
const event = state ? String(state.event_type) : null;
|
|
378
|
+
return (event === "resolved" && state.outcome !== null && state.outcome !== undefined) || event === "voided";
|
|
379
|
+
}
|
|
380
|
+
/** The token an outcome names: a token_id of the market, else the one outcome whose label it is; with no market, only the position's own token. */
|
|
381
|
+
function tokenForOutcome(outcome, market, tokenId) {
|
|
382
|
+
if (!market)
|
|
383
|
+
return outcome === tokenId ? outcome : null;
|
|
384
|
+
const outcomes = market.outcomes ?? [];
|
|
385
|
+
const tokens = outcomes.map((o) => String(o.token_id));
|
|
386
|
+
if (tokens.includes(outcome))
|
|
387
|
+
return outcome;
|
|
388
|
+
const labelled = outcomes.filter((o) => String(o.label) === outcome).map((o) => String(o.token_id));
|
|
389
|
+
return labelled.length === 1 ? labelled[0] : null;
|
|
390
|
+
}
|
|
391
|
+
/** A result with every bigint as a number, for JSON: the shape of the Python SDK's to_dict(). An amount past 2^53 stays a decimal string. */
|
|
392
|
+
export function backtestToJSON(result) {
|
|
393
|
+
const conv = (v) => {
|
|
394
|
+
if (typeof v === "bigint")
|
|
395
|
+
return v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v.toString();
|
|
396
|
+
if (Array.isArray(v))
|
|
397
|
+
return v.map(conv);
|
|
398
|
+
if (v !== null && typeof v === "object")
|
|
399
|
+
return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, conv(x)]));
|
|
400
|
+
return v;
|
|
401
|
+
};
|
|
402
|
+
return conv(result);
|
|
403
|
+
}
|