skewtape 0.0.1 → 0.1.5
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
package/src/download.ts
ADDED
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Files from a bundle: a download that resumes and checks its sha256, and the
|
|
3
|
+
* check of a whole folder against its CHECKSUMS.sha256. The History snapshot
|
|
4
|
+
* and the monthly deltas ship behind links that work for an hour: a Builder or
|
|
5
|
+
* Pro key asks for them (sk.download.file and sk.download.bundle, through POST
|
|
6
|
+
* /v1/downloads/{bundle}/url), and the dashboard hands them out too. This
|
|
7
|
+
* module takes the link itself.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createHash } from "node:crypto";
|
|
11
|
+
import { createReadStream, createWriteStream } from "node:fs";
|
|
12
|
+
import { mkdir, readFile, rename, stat, unlink } from "node:fs/promises";
|
|
13
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
14
|
+
import { Readable } from "node:stream";
|
|
15
|
+
import { pipeline } from "node:stream/promises";
|
|
16
|
+
|
|
17
|
+
import { ChecksumError, SkewtapeError } from "./errors.js";
|
|
18
|
+
|
|
19
|
+
export interface DownloadOptions {
|
|
20
|
+
/** The expected sha256 (hex); the file is checked after the download and a wrong one is deleted. */
|
|
21
|
+
sha256?: string | undefined;
|
|
22
|
+
/** Called after each chunk with the bytes so far and the total when known. */
|
|
23
|
+
onProgress?: ((done: number, total: number | undefined) => void) | undefined;
|
|
24
|
+
/** The fetch to use (the global one by default). The file host never sees the API key. */
|
|
25
|
+
fetch?: typeof fetch | undefined;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
async function sha256Of(path: string): Promise<string> {
|
|
29
|
+
const hash = createHash("sha256");
|
|
30
|
+
await pipeline(createReadStream(path), hash);
|
|
31
|
+
return hash.digest("hex");
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
async function sizeOf(path: string): Promise<number> {
|
|
35
|
+
try {
|
|
36
|
+
return (await stat(path)).size;
|
|
37
|
+
} catch {
|
|
38
|
+
return 0;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// The file's size from a 416's Content-Range header, "bytes */N".
|
|
43
|
+
function unsatisfiedTotal(resp: Response): number | undefined {
|
|
44
|
+
const range = resp.headers.get("content-range") ?? "";
|
|
45
|
+
if (!range.startsWith("bytes */")) return undefined;
|
|
46
|
+
const n = Number(range.slice("bytes */".length));
|
|
47
|
+
return Number.isFinite(n) ? n : undefined;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function totalSize(resp: Response, have: number): number | undefined {
|
|
51
|
+
const range = resp.headers.get("content-range");
|
|
52
|
+
if (range && range.includes("/")) {
|
|
53
|
+
const n = Number(range.slice(range.lastIndexOf("/") + 1));
|
|
54
|
+
return Number.isFinite(n) ? n : undefined;
|
|
55
|
+
}
|
|
56
|
+
const length = resp.headers.get("content-length");
|
|
57
|
+
if (length) {
|
|
58
|
+
const n = Number(length);
|
|
59
|
+
return Number.isFinite(n) ? have + n : undefined;
|
|
60
|
+
}
|
|
61
|
+
return undefined;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Whether dest already holds the file whose sha256 (hex) is given. */
|
|
65
|
+
export async function holds(dest: string, sha256: string): Promise<boolean> {
|
|
66
|
+
return (await exists(dest)) && (await sha256Of(dest)) === sha256.toLowerCase();
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Download url to dest, resuming a partial download (dest plus .part) with a
|
|
71
|
+
* Range request, and verify sha256 when given. A dest that exists with the
|
|
72
|
+
* expected sha256 is not downloaded again; a .part that already holds the
|
|
73
|
+
* whole file (the host answers 416 to the range) goes straight to the check.
|
|
74
|
+
* Returns dest.
|
|
75
|
+
*/
|
|
76
|
+
export async function downloadFile(url: string, dest: string, options: DownloadOptions = {}): Promise<string> {
|
|
77
|
+
const fetchFn = options.fetch ?? fetch;
|
|
78
|
+
const expected = options.sha256?.toLowerCase();
|
|
79
|
+
if (expected && (await sizeOf(dest)) > 0 && (await sha256Of(dest)) === expected) return dest;
|
|
80
|
+
await mkdir(dirname(dest), { recursive: true });
|
|
81
|
+
const part = `${dest}.part`;
|
|
82
|
+
let have = await sizeOf(part);
|
|
83
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
84
|
+
const resp = await fetchFn(url, { headers: have ? { Range: `bytes=${have}-` } : {} });
|
|
85
|
+
if (have && resp.status === 416) {
|
|
86
|
+
// 416 on a resume: the .part is whole when the file's size (Content-Range: bytes */N)
|
|
87
|
+
// is what it holds; otherwise it is longer than the file or another file's, so start over.
|
|
88
|
+
await resp.body?.cancel();
|
|
89
|
+
if (unsatisfiedTotal(resp) === have) break;
|
|
90
|
+
await unlink(part).catch(() => undefined);
|
|
91
|
+
have = 0;
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
if (have && resp.status === 200) have = 0; // the server ignored the range: start over
|
|
95
|
+
else if (have && resp.status !== 206) throw new SkewtapeError(`download ${url}: HTTP ${resp.status} on resume`, { status: resp.status });
|
|
96
|
+
else if (!have && resp.status !== 200) throw new SkewtapeError(`download ${url}: HTTP ${resp.status}`, { status: resp.status });
|
|
97
|
+
if (!resp.body) throw new SkewtapeError(`download ${url}: no body`, { status: resp.status });
|
|
98
|
+
const total = totalSize(resp, have);
|
|
99
|
+
let done = have;
|
|
100
|
+
const progress = options.onProgress;
|
|
101
|
+
const counted = Readable.from(countChunks(resp.body, (n) => {
|
|
102
|
+
done += n;
|
|
103
|
+
progress?.(done, total);
|
|
104
|
+
}));
|
|
105
|
+
await pipeline(counted, createWriteStream(part, { flags: have ? "a" : "w" }));
|
|
106
|
+
break;
|
|
107
|
+
}
|
|
108
|
+
if (expected) {
|
|
109
|
+
const actual = await sha256Of(part);
|
|
110
|
+
if (actual !== expected) {
|
|
111
|
+
await unlink(part).catch(() => undefined);
|
|
112
|
+
throw new ChecksumError(dest, expected, actual);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
await rename(part, dest);
|
|
116
|
+
return dest;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async function* countChunks(body: ReadableStream<Uint8Array>, onChunk: (n: number) => void): AsyncGenerator<Uint8Array> {
|
|
120
|
+
const reader = body.getReader();
|
|
121
|
+
for (;;) {
|
|
122
|
+
const { done, value } = await reader.read();
|
|
123
|
+
if (done) return;
|
|
124
|
+
onChunk(value.byteLength);
|
|
125
|
+
yield value;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Check every file a bundle's CHECKSUMS.sha256 lists ("<sha256> <path>", one
|
|
131
|
+
* per line). Returns the paths checked; throws ChecksumError on the first
|
|
132
|
+
* mismatch and SkewtapeError on a listed file that is missing or on a path
|
|
133
|
+
* that leaves the folder (absolute, or with a .. segment).
|
|
134
|
+
*/
|
|
135
|
+
export async function verifyChecksums(folder: string, checksums = "CHECKSUMS.sha256"): Promise<string[]> {
|
|
136
|
+
const text = await readFile(join(folder, checksums), "utf8");
|
|
137
|
+
const checked: string[] = [];
|
|
138
|
+
for (const raw of text.split("\n")) {
|
|
139
|
+
const line = raw.trim();
|
|
140
|
+
if (!line || line.startsWith("#")) continue;
|
|
141
|
+
const space = line.indexOf(" ");
|
|
142
|
+
const digest = line.slice(0, space).toLowerCase();
|
|
143
|
+
const rel = line.slice(space + 1).trim().replace(/^\*/, "");
|
|
144
|
+
if (isAbsolute(rel) || rel.split(/[\\/]+/).includes("..")) throw new SkewtapeError(`${checksums} names ${rel}, a path outside the folder`);
|
|
145
|
+
const path = join(folder, rel);
|
|
146
|
+
if ((await sizeOf(path)) === 0 && !(await exists(path))) throw new SkewtapeError(`${path}: listed in ${checksums} and missing`);
|
|
147
|
+
const actual = await sha256Of(path);
|
|
148
|
+
if (actual !== digest) throw new ChecksumError(path, digest, actual);
|
|
149
|
+
checked.push(path);
|
|
150
|
+
}
|
|
151
|
+
return checked;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
async function exists(path: string): Promise<boolean> {
|
|
155
|
+
try {
|
|
156
|
+
await stat(path);
|
|
157
|
+
return true;
|
|
158
|
+
} catch {
|
|
159
|
+
return false;
|
|
160
|
+
}
|
|
161
|
+
}
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Errors, one class per thing the caller can act on, built from the API's
|
|
3
|
+
* error envelope: {"error": {"code", "message", "docs_url", "request_id",
|
|
4
|
+
* "plan", "resets_at", "upgrade_url", "block_reason_code"}}.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
export interface ErrorFields {
|
|
8
|
+
status?: number | undefined;
|
|
9
|
+
code?: string | undefined;
|
|
10
|
+
docsUrl?: string | undefined;
|
|
11
|
+
requestId?: string | undefined;
|
|
12
|
+
plan?: string | undefined;
|
|
13
|
+
resetsAt?: string | undefined;
|
|
14
|
+
upgradeUrl?: string | undefined;
|
|
15
|
+
blockReasonCode?: string | undefined;
|
|
16
|
+
retryAfter?: number | undefined;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** An error from the API or from this client. message is the API's own sentence. */
|
|
20
|
+
export class SkewtapeError extends Error {
|
|
21
|
+
readonly status: number | undefined;
|
|
22
|
+
readonly code: string | undefined;
|
|
23
|
+
readonly docsUrl: string | undefined;
|
|
24
|
+
readonly requestId: string | undefined;
|
|
25
|
+
readonly plan: string | undefined;
|
|
26
|
+
readonly resetsAt: string | undefined;
|
|
27
|
+
readonly upgradeUrl: string | undefined;
|
|
28
|
+
readonly blockReasonCode: string | undefined;
|
|
29
|
+
/** The server's Retry-After in seconds, when it sent one. */
|
|
30
|
+
readonly retryAfter: number | undefined;
|
|
31
|
+
|
|
32
|
+
constructor(message: string, fields: ErrorFields = {}) {
|
|
33
|
+
super(message);
|
|
34
|
+
this.name = new.target.name;
|
|
35
|
+
this.status = fields.status;
|
|
36
|
+
this.code = fields.code;
|
|
37
|
+
this.docsUrl = fields.docsUrl;
|
|
38
|
+
this.requestId = fields.requestId;
|
|
39
|
+
this.plan = fields.plan;
|
|
40
|
+
this.resetsAt = fields.resetsAt;
|
|
41
|
+
this.upgradeUrl = fields.upgradeUrl;
|
|
42
|
+
this.blockReasonCode = fields.blockReasonCode;
|
|
43
|
+
this.retryAfter = fields.retryAfter;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
override toString(): string {
|
|
47
|
+
const parts = [this.message];
|
|
48
|
+
if (this.code) parts.push(`[${this.code}]`);
|
|
49
|
+
if (this.requestId) parts.push(`(request ${this.requestId})`);
|
|
50
|
+
return parts.join(" ");
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** An order route() refuses to build (route.ts, route-hyperliquid.ts). Nothing was signed or sent. */
|
|
55
|
+
export class RouteError extends SkewtapeError {
|
|
56
|
+
constructor(message: string) {
|
|
57
|
+
super(message);
|
|
58
|
+
this.name = "RouteError";
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The client cannot be built: no API key, or a bad option. */
|
|
63
|
+
export class ConfigurationError extends SkewtapeError {}
|
|
64
|
+
/** 400 invalid_request: a parameter the API refuses. */
|
|
65
|
+
export class InvalidRequestError extends SkewtapeError {}
|
|
66
|
+
/** 401 unauthorized: no valid API key; or 429 lookup_rate_limited: too many invalid keys from this address, never retried, since the fix is the key. */
|
|
67
|
+
export class AuthenticationError extends SkewtapeError {}
|
|
68
|
+
/** 403 forbidden_plan: the request needs another plan; .plan names it. */
|
|
69
|
+
export class ForbiddenPlanError extends SkewtapeError {}
|
|
70
|
+
/** 403 blocked: the data policy withholds the venue's data; .blockReasonCode says why. */
|
|
71
|
+
export class BlockedError extends SkewtapeError {}
|
|
72
|
+
/** 404 not_found. */
|
|
73
|
+
export class NotFoundError extends SkewtapeError {}
|
|
74
|
+
/** 429 rate_limited after the retries. */
|
|
75
|
+
export class RateLimitError extends SkewtapeError {}
|
|
76
|
+
/** 429 quota_exceeded: the plan's monthly quota; .resetsAt says when. */
|
|
77
|
+
export class QuotaExceededError extends SkewtapeError {}
|
|
78
|
+
/** 5xx: the API failed; retry later, quoting .requestId to support. */
|
|
79
|
+
export class ServerError extends SkewtapeError {}
|
|
80
|
+
/** A downloaded file's sha256 is not the one expected. */
|
|
81
|
+
export class ChecksumError extends SkewtapeError {
|
|
82
|
+
constructor(
|
|
83
|
+
readonly path: string,
|
|
84
|
+
readonly expected: string,
|
|
85
|
+
readonly actual: string,
|
|
86
|
+
) {
|
|
87
|
+
super(`${path}: sha256 ${actual} is not the expected ${expected}`);
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const byCode: Record<string, new (message: string, fields?: ErrorFields) => SkewtapeError> = {
|
|
92
|
+
invalid_request: InvalidRequestError,
|
|
93
|
+
unauthorized: AuthenticationError,
|
|
94
|
+
lookup_rate_limited: AuthenticationError,
|
|
95
|
+
forbidden_plan: ForbiddenPlanError,
|
|
96
|
+
blocked: BlockedError,
|
|
97
|
+
not_found: NotFoundError,
|
|
98
|
+
rate_limited: RateLimitError,
|
|
99
|
+
quota_exceeded: QuotaExceededError,
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/** The Retry-After header as seconds, when it is a number. */
|
|
103
|
+
export function retryAfterSeconds(headers: Headers): number | undefined {
|
|
104
|
+
const raw = headers.get("retry-after");
|
|
105
|
+
if (raw === null) return undefined;
|
|
106
|
+
const n = Number(raw);
|
|
107
|
+
return Number.isFinite(n) ? Math.max(n, 0) : undefined;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function str(v: unknown): string | undefined {
|
|
111
|
+
return typeof v === "string" ? v : undefined;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* The error for a non-2xx response: the envelope's code chooses the class, the
|
|
116
|
+
* status decides when the body is not an envelope.
|
|
117
|
+
*/
|
|
118
|
+
export function errorFromResponse(status: number, headers: Headers, body: unknown): SkewtapeError {
|
|
119
|
+
const envelope = body !== null && typeof body === "object" && "error" in body ? (body as { error: unknown }).error : undefined;
|
|
120
|
+
const e = envelope !== null && typeof envelope === "object" ? (envelope as Record<string, unknown>) : {};
|
|
121
|
+
const code = str(e.code);
|
|
122
|
+
const message = str(e.message) ?? `HTTP ${status}${code ? ` ${code}` : ""}`;
|
|
123
|
+
let cls = code ? byCode[code] : undefined;
|
|
124
|
+
if (!cls) {
|
|
125
|
+
if (status === 400) cls = InvalidRequestError;
|
|
126
|
+
else if (status === 401) cls = AuthenticationError;
|
|
127
|
+
else if (status === 404) cls = NotFoundError;
|
|
128
|
+
else if (status === 429) cls = RateLimitError;
|
|
129
|
+
else if (status >= 500) cls = ServerError;
|
|
130
|
+
else cls = SkewtapeError;
|
|
131
|
+
}
|
|
132
|
+
return new cls(message, {
|
|
133
|
+
status,
|
|
134
|
+
code,
|
|
135
|
+
docsUrl: str(e.docs_url),
|
|
136
|
+
requestId: str(e.request_id) ?? headers.get("x-request-id") ?? undefined,
|
|
137
|
+
plan: str(e.plan),
|
|
138
|
+
resetsAt: str(e.resets_at),
|
|
139
|
+
upgradeUrl: str(e.upgrade_url),
|
|
140
|
+
blockReasonCode: str(e.block_reason_code),
|
|
141
|
+
retryAfter: retryAfterSeconds(headers),
|
|
142
|
+
});
|
|
143
|
+
}
|
package/src/exact.ts
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Exact numbers for fees and the backtest: fractions of BigInts, times in
|
|
3
|
+
* microseconds since the epoch, and the formats the Python SDK prints, so
|
|
4
|
+
* both SDKs give the same strings for the same values.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { SkewtapeError } from "./errors.js";
|
|
8
|
+
|
|
9
|
+
function gcd(a: bigint, b: bigint): bigint {
|
|
10
|
+
a = a < 0n ? -a : a;
|
|
11
|
+
b = b < 0n ? -b : b;
|
|
12
|
+
while (b) [a, b] = [b, a % b];
|
|
13
|
+
return a;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** An exact fraction, always reduced, with a positive denominator. */
|
|
17
|
+
export class Rat {
|
|
18
|
+
readonly n: bigint;
|
|
19
|
+
readonly d: bigint;
|
|
20
|
+
|
|
21
|
+
constructor(n: bigint, d: bigint = 1n) {
|
|
22
|
+
if (d === 0n) throw new SkewtapeError("division by zero");
|
|
23
|
+
if (d < 0n) {
|
|
24
|
+
n = -n;
|
|
25
|
+
d = -d;
|
|
26
|
+
}
|
|
27
|
+
const g = gcd(n, d) || 1n;
|
|
28
|
+
this.n = n / g;
|
|
29
|
+
this.d = d / g;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
static of(v: bigint | number): Rat {
|
|
33
|
+
return new Rat(BigInt(v));
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
add(o: Rat): Rat {
|
|
37
|
+
return new Rat(this.n * o.d + o.n * this.d, this.d * o.d);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
mul(o: Rat): Rat {
|
|
41
|
+
return new Rat(this.n * o.n, this.d * o.d);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
cmp(o: Rat): number {
|
|
45
|
+
const l = this.n * o.d;
|
|
46
|
+
const r = o.n * this.d;
|
|
47
|
+
return l < r ? -1 : l > r ? 1 : 0;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
isInt(): boolean {
|
|
51
|
+
return this.d === 1n;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The largest integer at or below. */
|
|
55
|
+
floor(): bigint {
|
|
56
|
+
const q = this.n / this.d;
|
|
57
|
+
return this.n < 0n && this.n % this.d !== 0n ? q - 1n : q;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** floor(x + 1/2): a half rounds toward the larger integer. */
|
|
62
|
+
export function roundHalfUp(x: Rat): bigint {
|
|
63
|
+
return x.add(new Rat(1n, 2n)).floor();
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** An exact fraction as a decimal string when it ends ("0.58", "-3"), else "n/d". */
|
|
67
|
+
export function fractionStr(x: Rat): string {
|
|
68
|
+
let den = x.d;
|
|
69
|
+
let twos = 0;
|
|
70
|
+
let fives = 0;
|
|
71
|
+
while (den % 2n === 0n) {
|
|
72
|
+
den /= 2n;
|
|
73
|
+
twos++;
|
|
74
|
+
}
|
|
75
|
+
while (den % 5n === 0n) {
|
|
76
|
+
den /= 5n;
|
|
77
|
+
fives++;
|
|
78
|
+
}
|
|
79
|
+
if (den !== 1n) return `${x.n}/${x.d}`;
|
|
80
|
+
const places = Math.max(twos, fives);
|
|
81
|
+
const abs = x.n < 0n ? -x.n : x.n;
|
|
82
|
+
const scaled = abs * (10n ** BigInt(places) / x.d);
|
|
83
|
+
const sign = x.n < 0n ? "-" : "";
|
|
84
|
+
if (places === 0) return `${sign}${scaled}`;
|
|
85
|
+
const digits = scaled.toString().padStart(places + 1, "0");
|
|
86
|
+
const whole = digits.slice(0, -places);
|
|
87
|
+
const frac = digits.slice(-places).replace(/0+$/, "");
|
|
88
|
+
return frac ? `${sign}${whole}.${frac}` : `${sign}${whole}`;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const DECIMAL = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
|
|
92
|
+
const FRACTION = /^([+-]?\d+)\s*\/\s*(\d+)$/;
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* An exact fraction from a decimal string ("0.40", "1e-7"), an "n/d" string,
|
|
96
|
+
* a bigint or a number (read as its shortest decimal, as String gives it).
|
|
97
|
+
*/
|
|
98
|
+
export function parseRat(value: unknown, what: string): Rat {
|
|
99
|
+
if (value instanceof Rat) return value;
|
|
100
|
+
if (typeof value === "bigint") return new Rat(value);
|
|
101
|
+
if (typeof value === "number") {
|
|
102
|
+
if (!Number.isFinite(value)) throw new SkewtapeError(`${what}: ${value} is not finite`, { code: "bad_trade" });
|
|
103
|
+
return parseRat(String(value), what);
|
|
104
|
+
}
|
|
105
|
+
if (typeof value !== "string") throw new SkewtapeError(`${what}: ${String(value)} is not a number`, { code: "bad_trade" });
|
|
106
|
+
const s = value.trim();
|
|
107
|
+
const f = FRACTION.exec(s);
|
|
108
|
+
if (f) return new Rat(BigInt(f[1]!), BigInt(f[2]!));
|
|
109
|
+
const m = DECIMAL.exec(s);
|
|
110
|
+
if (!m || (m[2] === "" && (m[3] === undefined || m[3] === ""))) throw new SkewtapeError(`${what}: ${value} is not a number`, { code: "bad_trade" });
|
|
111
|
+
const digits = `${m[2] ?? ""}${m[3] ?? ""}` || "0";
|
|
112
|
+
const exp = Number(m[4] ?? "0") - (m[3]?.length ?? 0);
|
|
113
|
+
let r = exp >= 0 ? new Rat(BigInt(digits) * 10n ** BigInt(exp)) : new Rat(BigInt(digits), 10n ** BigInt(-exp));
|
|
114
|
+
if (m[1] === "-") r = new Rat(-r.n, r.d);
|
|
115
|
+
return r;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** A raw integer amount from a bigint, a safe integer number or a digit string. */
|
|
119
|
+
export function parseInt64(value: unknown, what: string): bigint {
|
|
120
|
+
if (typeof value === "bigint") return value;
|
|
121
|
+
if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
|
|
122
|
+
if (typeof value === "string" && /^[+-]?\d+$/.test(value.trim())) return BigInt(value.trim());
|
|
123
|
+
throw new SkewtapeError(`${what}: ${String(value)} is not an integer`, { code: "bad_trade" });
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
const ISO = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:?\d{2})?$/i;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* A time as microseconds since the epoch, from a Date or an ISO 8601 string
|
|
130
|
+
* (no offset read as UTC); microseconds are kept, which a Date would drop.
|
|
131
|
+
*/
|
|
132
|
+
export function parseMicros(value: unknown, what: string): bigint {
|
|
133
|
+
if (value instanceof Date) {
|
|
134
|
+
if (Number.isNaN(value.getTime())) throw new SkewtapeError(`${what}: not a time`, { code: "bad_trade" });
|
|
135
|
+
return BigInt(value.getTime()) * 1000n;
|
|
136
|
+
}
|
|
137
|
+
if (typeof value !== "string") throw new SkewtapeError(`${what}: ${String(value)} is not a time`, { code: "bad_trade" });
|
|
138
|
+
const m = ISO.exec(value.trim());
|
|
139
|
+
if (!m) throw new SkewtapeError(`${what}: ${value} is not a time`, { code: "bad_trade" });
|
|
140
|
+
const ms = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6] ?? "0"));
|
|
141
|
+
const frac = (m[7] ?? "").padEnd(6, "0").slice(0, 6);
|
|
142
|
+
let micros = BigInt(ms) * 1000n + BigInt(frac || "0");
|
|
143
|
+
const zone = m[8];
|
|
144
|
+
if (zone && zone.toUpperCase() !== "Z") {
|
|
145
|
+
const sign = zone.startsWith("-") ? -1n : 1n;
|
|
146
|
+
const digits = zone.slice(1).replace(":", "");
|
|
147
|
+
const minutes = BigInt(Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2, 4)));
|
|
148
|
+
micros -= sign * minutes * 60_000_000n;
|
|
149
|
+
}
|
|
150
|
+
return micros;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Microseconds since the epoch as the Python SDK prints a UTC time: seconds, then six digits when there are microseconds, then Z. */
|
|
154
|
+
export function isoMicros(micros: bigint): string {
|
|
155
|
+
const ms = Number(micros / 1000n - (micros < 0n && micros % 1000n !== 0n ? 1n : 0n));
|
|
156
|
+
const base = new Date(ms).toISOString().slice(0, 19);
|
|
157
|
+
const rem = ((micros % 1_000_000n) + 1_000_000n) % 1_000_000n;
|
|
158
|
+
return rem === 0n ? `${base}Z` : `${base}.${rem.toString().padStart(6, "0")}Z`;
|
|
159
|
+
}
|
package/src/fees.ts
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fees from the schedule: the row in force for a fill and the fee it gives,
|
|
3
|
+
* exactly as Skewtape computes them (tape's internal/fees,
|
|
4
|
+
* docs.skewtape.com/fees). The fee is kept as an exact fraction until it is
|
|
5
|
+
* rounded, as the row says, to a step given in millionths of a dollar; a
|
|
6
|
+
* minimum, when the row has one, raises a fee that is above zero after
|
|
7
|
+
* rounding. conformance/fees.json pins every case, and the tests run all of it.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { SkewtapeError } from "./errors.js";
|
|
11
|
+
import { Rat, parseInt64, parseMicros } from "./exact.js";
|
|
12
|
+
|
|
13
|
+
export const COLLATERAL_MICROS_DECIMALS = 6;
|
|
14
|
+
export const FALLBACK_CATEGORY = "*";
|
|
15
|
+
const MICROS_PER_UNIT = 1_000_000n;
|
|
16
|
+
|
|
17
|
+
/** A fee that cannot be computed: an unknown formula or rounding, a missing parameter, a size out of range. */
|
|
18
|
+
export class FeeError extends SkewtapeError {}
|
|
19
|
+
|
|
20
|
+
/** One row of the fee schedule, read from the API's Fee or the same shape. */
|
|
21
|
+
export interface FeeRow {
|
|
22
|
+
venue: string;
|
|
23
|
+
category: string;
|
|
24
|
+
/** Microseconds since the epoch. */
|
|
25
|
+
effectiveFrom: bigint;
|
|
26
|
+
effectiveTo: bigint | null;
|
|
27
|
+
formula: string;
|
|
28
|
+
rounding: string;
|
|
29
|
+
takerParams: Record<string, bigint>;
|
|
30
|
+
makerRebateParams: Record<string, bigint>;
|
|
31
|
+
minFeeMicros: bigint | null;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** What a fee row can be given as: the API's Fee (snake_case) or a FeeRow. */
|
|
35
|
+
export type FeeRowInput = FeeRow | Record<string, unknown>;
|
|
36
|
+
|
|
37
|
+
function intMap(v: unknown): Record<string, bigint> {
|
|
38
|
+
if (v === null || v === undefined) return {};
|
|
39
|
+
if (typeof v !== "object") throw new FeeError(`${String(v)} is not a parameter map`);
|
|
40
|
+
const out: Record<string, bigint> = {};
|
|
41
|
+
for (const [k, x] of Object.entries(v as Record<string, unknown>)) out[k] = parseInt64(x, k);
|
|
42
|
+
return out;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** A FeeRow from the API's Fee, its JSON, or a FeeRow. */
|
|
46
|
+
export function feeRowOf(row: FeeRowInput): FeeRow {
|
|
47
|
+
if ("effectiveFrom" in row && typeof row.effectiveFrom === "bigint") return row as FeeRow;
|
|
48
|
+
const r = row as Record<string, unknown>;
|
|
49
|
+
if (r.effective_from === undefined || r.effective_from === null) throw new FeeError("a fee row needs effective_from");
|
|
50
|
+
const min = r.min_fee_micros;
|
|
51
|
+
return {
|
|
52
|
+
venue: String(r.venue),
|
|
53
|
+
category: String(r.category),
|
|
54
|
+
effectiveFrom: parseMicros(r.effective_from, "effective_from"),
|
|
55
|
+
effectiveTo: r.effective_to === null || r.effective_to === undefined || r.effective_to === "" ? null : parseMicros(r.effective_to, "effective_to"),
|
|
56
|
+
formula: String(r.formula),
|
|
57
|
+
rounding: String(r.rounding),
|
|
58
|
+
takerParams: intMap(r.taker_params),
|
|
59
|
+
makerRebateParams: intMap(r.maker_rebate_params),
|
|
60
|
+
minFeeMicros: min === null || min === undefined || min === "" ? null : parseInt64(min, "min_fee_micros"),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** A millionth-of-a-dollar amount in raw units at decimals. */
|
|
65
|
+
export function microsToRaw(micros: bigint, decimals: number): bigint {
|
|
66
|
+
if (decimals < 0 || decimals > 18 || !Number.isInteger(decimals)) throw new FeeError(`decimals ${decimals} out of range`);
|
|
67
|
+
if (decimals >= COLLATERAL_MICROS_DECIMALS) return micros * 10n ** BigInt(decimals - COLLATERAL_MICROS_DECIMALS);
|
|
68
|
+
const factor = 10n ** BigInt(COLLATERAL_MICROS_DECIMALS - decimals);
|
|
69
|
+
if (micros % factor !== 0n) throw new FeeError(`${micros} micros is not representable at ${decimals} decimals`);
|
|
70
|
+
return micros / factor;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* A fee formula's value for size shares against notional collateral (any one
|
|
75
|
+
* unit for both), exact, before rounding and any minimum: the one port of
|
|
76
|
+
* tape's internal/fees formulas, which takerFeeRaw and sk.quote both use.
|
|
77
|
+
*/
|
|
78
|
+
export function exactFee(formula: string, params: Record<string, bigint>, size: bigint, notional: bigint): Rat {
|
|
79
|
+
switch (formula) {
|
|
80
|
+
case "quadratic": {
|
|
81
|
+
const rate = params.rate_micros;
|
|
82
|
+
if (rate === undefined) throw new FeeError("quadratic needs rate_micros");
|
|
83
|
+
if (rate < 0n) throw new FeeError("rate_micros must be >= 0");
|
|
84
|
+
if (rate === 0n || notional === 0n || notional === size) return new Rat(0n);
|
|
85
|
+
return new Rat(rate * notional * (size - notional), size * MICROS_PER_UNIT);
|
|
86
|
+
}
|
|
87
|
+
case "complement": {
|
|
88
|
+
const rate = params.rate_micros;
|
|
89
|
+
if (rate === undefined) throw new FeeError("complement needs rate_micros");
|
|
90
|
+
if (rate < 0n) throw new FeeError("rate_micros must be >= 0");
|
|
91
|
+
return new Rat(rate * (size - notional), MICROS_PER_UNIT);
|
|
92
|
+
}
|
|
93
|
+
case "flat_bps": {
|
|
94
|
+
const bps = params.bps;
|
|
95
|
+
if (bps === undefined) throw new FeeError("flat_bps needs bps");
|
|
96
|
+
if (bps < 0n) throw new FeeError("bps must be >= 0");
|
|
97
|
+
return new Rat(notional * bps, 10_000n);
|
|
98
|
+
}
|
|
99
|
+
case "zero":
|
|
100
|
+
return new Rat(0n);
|
|
101
|
+
default:
|
|
102
|
+
throw new FeeError(`unknown formula ${formula}`);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function roundFee(exact: Rat, mode: string, step: bigint): bigint {
|
|
107
|
+
if (exact.n < 0n) throw new FeeError("negative fee");
|
|
108
|
+
if (step <= 0n) step = 1n;
|
|
109
|
+
if (mode === "none") {
|
|
110
|
+
if (!exact.isInt()) throw new FeeError("rounding none needs an integer fee");
|
|
111
|
+
return exact.n;
|
|
112
|
+
}
|
|
113
|
+
if (mode !== "down" && mode !== "up" && mode !== "nearest") throw new FeeError(`unknown rounding ${mode}`);
|
|
114
|
+
const den = exact.d * step;
|
|
115
|
+
let q = exact.n / den;
|
|
116
|
+
const r = exact.n % den;
|
|
117
|
+
if (mode === "up" && r !== 0n) q += 1n;
|
|
118
|
+
else if (mode === "nearest" && 2n * r >= den) q += 1n;
|
|
119
|
+
return q * step;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The taker fee in raw units for sizeRaw shares against notionalRaw
|
|
124
|
+
* collateral, both at decimals, under row: the formula exactly, rounded to
|
|
125
|
+
* round_step_micros (1 raw unit without one), then raised to min_fee_micros
|
|
126
|
+
* when it is above zero and below it.
|
|
127
|
+
*/
|
|
128
|
+
export function takerFeeRaw(row: FeeRowInput, sizeRaw: bigint, notionalRaw: bigint, decimals: number): bigint {
|
|
129
|
+
return takerFeeOf(feeRowOf(row), sizeRaw, notionalRaw, decimals);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** A fee's terms alone: what takerFeeOf reads of a row. */
|
|
133
|
+
export type FeeTerms = Pick<FeeRow, "formula" | "rounding" | "takerParams" | "minFeeMicros">;
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* takerFeeRaw over a fee's terms alone, for callers that hold no whole row:
|
|
137
|
+
* sk.quote computes its fees with it at 6 decimals.
|
|
138
|
+
*/
|
|
139
|
+
export function takerFeeOf(fee: FeeTerms, sizeRaw: bigint, notionalRaw: bigint, decimals: number): bigint {
|
|
140
|
+
if (sizeRaw <= 0n) throw new FeeError("size_raw must be positive");
|
|
141
|
+
if (notionalRaw < 0n || notionalRaw > sizeRaw) throw new FeeError("notional_raw must be between 0 and size_raw");
|
|
142
|
+
const exact = exactFee(fee.formula, fee.takerParams, sizeRaw, notionalRaw);
|
|
143
|
+
const stepMicros = fee.takerParams.round_step_micros ?? 0n;
|
|
144
|
+
let rounded = roundFee(exact, fee.rounding, stepMicros > 0n ? microsToRaw(stepMicros, decimals) : 1n);
|
|
145
|
+
if (fee.minFeeMicros !== null && rounded > 0n) {
|
|
146
|
+
const min = microsToRaw(fee.minFeeMicros, decimals);
|
|
147
|
+
if (rounded < min) rounded = min;
|
|
148
|
+
}
|
|
149
|
+
return rounded;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* The maker's fee on venues that charge makers (maker_fee_rate_micros in
|
|
154
|
+
* maker_rebate_params, quadratic, with the row's rounding and step); zero
|
|
155
|
+
* elsewhere. A rebate share is data about the venue, not a fee, and is not
|
|
156
|
+
* applied.
|
|
157
|
+
*/
|
|
158
|
+
export function makerFeeRaw(row: FeeRowInput, sizeRaw: bigint, notionalRaw: bigint, decimals: number): bigint {
|
|
159
|
+
const r = feeRowOf(row);
|
|
160
|
+
const rate = r.makerRebateParams.maker_fee_rate_micros ?? 0n;
|
|
161
|
+
if (rate === 0n) return 0n;
|
|
162
|
+
const params: Record<string, bigint> = { rate_micros: rate };
|
|
163
|
+
if (r.takerParams.round_step_micros !== undefined) params.round_step_micros = r.takerParams.round_step_micros;
|
|
164
|
+
return takerFeeRaw({ ...r, formula: "quadratic", takerParams: params, makerRebateParams: {} }, sizeRaw, notionalRaw, decimals);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function inForce(r: FeeRow, at: bigint): boolean {
|
|
168
|
+
return r.effectiveFrom <= at && (r.effectiveTo === null || at < r.effectiveTo);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* The row in force for a fill of venue at time at (microseconds, a Date or
|
|
173
|
+
* an ISO string): the market's fee_category if a row has it, else the row
|
|
174
|
+
* with category *; of several, the latest effective_from. Undefined when no
|
|
175
|
+
* row applies.
|
|
176
|
+
*/
|
|
177
|
+
export function selectFeeRow(rows: Iterable<FeeRowInput>, venue: string, category: string | null | undefined, at: bigint | Date | string): FeeRow | undefined {
|
|
178
|
+
const t = typeof at === "bigint" ? at : parseMicros(at, "at");
|
|
179
|
+
const all = [...rows].map(feeRowOf);
|
|
180
|
+
const wanted = category && category !== FALLBACK_CATEGORY ? [category, FALLBACK_CATEGORY] : [FALLBACK_CATEGORY];
|
|
181
|
+
for (const cat of wanted) {
|
|
182
|
+
let best: FeeRow | undefined;
|
|
183
|
+
for (const r of all) {
|
|
184
|
+
if (r.venue === venue && r.category === cat && inForce(r, t) && (best === undefined || r.effectiveFrom > best.effectiveFrom)) best = r;
|
|
185
|
+
}
|
|
186
|
+
if (best) return best;
|
|
187
|
+
}
|
|
188
|
+
return undefined;
|
|
189
|
+
}
|