outcometick 1.4.0

package/cli/ot.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// `ot` — the command line the SDK docs tell customers to use.
+//
+//   ot check .                                          validate, free, no data
+//   ot run . --data ./polymarket-data-samples --date …  replay locally
+//   ot submit . --assets btc,eth --from … --to …        send it to the queue
+//
+// The one thing this file must get right is that `ot check` runs the SAME
+// validator the queue runs. The docs promise "if it passes locally it will not
+// be rejected on submit", and that promise only survives if there is exactly
+// one implementation — so check() calls the very modules api/lib/backtest-
+// routes.mjs calls, rather than reimplementing any of it.
+//
+// Written in Node because everything it needs already is: the contract, the
+// validator, both analysers, the engine, the report and the archive writer. A
+// Python submission is still run by the Python harness — the CLI spawns it the
+// same way the worker does.
+
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import process from 'node:process';
+
+import { SDK_VERSION, LIMITS, BacktestRejection } from '../api/lib/backtest-contract.mjs';
+import { checkSubmission, MANIFEST_NAME } from '../api/lib/backtest-manifest.mjs';
+import { analyzeSource } from '../runner/analyze/index.mjs';
+
+const USAGE = `ot ${SDK_VERSION} — outcometick strategy tools
+
+  ot check <dir>
+      Validate the manifest, the entry point, the hook signatures and every
+      import. Touches no data and costs nothing. This is the exact validator
+      the queue runs.
+
+  ot run <dir> --data <archive> [--date <YYYY-MM-DD>] [--out <file>]
+      Replay locally against a cloned sample archive, using the same engine
+      the queue uses. Writes a report archive.
+
+  ot submit <dir> --assets btc,eth --from <day> --to <day> [--venue polymarket]
+      Send it to the queue. Needs OT_BACKTEST_KEY.
+
+  ot status <run_id>
+      Where a submitted run got to, and what it cost. Needs OT_BACKTEST_KEY.
+
+  ot fetch <run_id> [--out <file>]
+      Download a finished run's archive. Needs OT_BACKTEST_KEY.
+
+  Common:
+      --json          machine-readable output
+      --api <url>     API base (default https://outcometick.com)
+
+  Free sample data:
+      git clone https://github.com/Ligengxin96/polymarket-data-samples
+`;
+
+/** Parse argv into {command, dir, flags}. */
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+    const key = a.slice(2);
+    // Boolean flags take no value; everything else consumes the next token.
+    if (key === 'json') { flags.json = true; continue; }
+    const value = rest[i + 1];
+    if (value == null || value.startsWith('--')) {
+      throw new Error(`--${key} needs a value`);
+    }
+    flags[key] = value;
+    i += 1;
+  }
+  return { command, dir: positional[0] ?? '.', flags };
+}
+
+/**
+ * Read a submission directory.
+ *
+ * Only files the manifest could plausibly reference, and only from the top two
+ * levels — a strategy directory that happens to contain a virtualenv or a
+ * .git should not turn into a 400 MB submission attempt. The limits are
+ * enforced properly by the validator; this is about not reading the disk.
+ */
+export async function readSubmission(dir) {
+  const out = [];
+  const walk = async (rel, depth) => {
+    const entries = await readdir(path.join(dir, rel || '.'), { withFileTypes: true });
+    for (const e of entries) {
+      const name = rel ? `${rel}/${e.name}` : e.name;
+      if (e.name.startsWith('.') || e.name === 'node_modules' || e.name === '__pycache__') continue;
+      if (e.isDirectory()) {
+        if (depth > 0) await walk(name, depth - 1);
+        continue;
+      }
+      if (!/\.(py|mjs|js|json|csv)$/.test(e.name)) continue;
+      const full = path.join(dir, name);
+      const s = await stat(full);
+      if (s.size > LIMITS.maxTotalSourceBytes) {
+        throw new Error(`${name} is ${s.size} bytes, over the ${LIMITS.maxTotalSourceBytes} byte submission limit`);
+      }
+      out.push({ name, content: await readFile(full, 'utf8') });
+    }
+  };
+  await walk('', 1);
+  if (!out.some((f) => f.name === MANIFEST_NAME)) {
+    throw new Error(`no ${MANIFEST_NAME} in ${path.resolve(dir)}`);
+  }
+  return out;
+}
+
+/**
+ * Validate a submission exactly as the queue would.
+ *
+ * `scope` is optional: coverage can only be checked against a real range, and
+ * `ot check` on its own is about the manifest and the source. `ot submit`
+ * passes one, and so does the API.
+ */
+export async function validate(files, scope = null) {
+  const checked = checkSubmission({ files, scope });
+  // analyzeSource, not a dispatch of our own: see runner/analyze/index.mjs for
+  // why the two sides sharing this exact function is the whole promise.
+  const analysis = await analyzeSource(checked);
+  return { ...checked, analysis };
+}
+
+/** Print a rejection the way the docs describe the codes. */
+function reportRejection(err, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: false, ...(err.toJSON?.() ?? { code: 'E_RUNTIME', detail: err.message }) })}\n`);
+    return;
+  }
+  const code = err.code ?? 'E_RUNTIME';
+  const detail = err.detail ?? err.message;
+  process.stderr.write(`\n  ${code}\n  ${detail}\n\n`);
+}
+
+async function cmdCheck({ dir, flags }) {
+  const files = await readSubmission(dir);
+  const res = await validate(files);
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      manifest: res.manifest,
+      hooks: res.hookNames,
+      files: res.files.map((f) => ({ name: f.name, bytes: f.bytes })),
+      total_bytes: res.totalBytes,
+      imports: res.analysis.imports,
+    })}\n`);
+    return 0;
+  }
+  const { manifest } = res;
+  process.stdout.write(`\n  ok — ${manifest.language}, entry ${manifest.entry.file}:${manifest.entry.className}\n`);
+  process.stdout.write(`  hooks     ${Object.entries(res.hookNames).map(([k, v]) => `${k} → ${v}`).join(', ')}\n`);
+  process.stdout.write(`  datasets  ${manifest.datasets.join(', ')}\n`);
+  if (manifest.reference.length) process.stdout.write(`  reference ${manifest.reference.join(', ')}\n`);
+  process.stdout.write(`  files     ${res.files.length} / ${LIMITS.maxFiles} · ${(res.totalBytes / 1024).toFixed(1)} / ${LIMITS.maxTotalSourceBytes / 1024} KB\n`);
+  if (manifest.mode === 'session') {
+    process.stdout.write('  mode      session — bills at 3× the market-day rate\n');
+  }
+  process.stdout.write('\n');
+  return 0;
+}
+
+async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 2;
+  }
+  const { command, flags } = parsed;
+
+  if (!command || command === 'help' || flags.help) {
+    process.stdout.write(USAGE);
+    return command ? 0 : 2;
+  }
+  if (command === 'version') {
+    process.stdout.write(`${SDK_VERSION}\n`);
+    return 0;
+  }
+
+  try {
+    if (command === 'check') return await cmdCheck(parsed);
+    if (command === 'run') {
+      const { cmdRun } = await import('./commands/run.mjs');
+      return await cmdRun(parsed);
+    }
+    if (command === 'submit') {
+      const { cmdSubmit } = await import('./commands/submit.mjs');
+      return await cmdSubmit(parsed);
+    }
+    if (command === 'status') {
+      const { cmdStatus } = await import('./commands/status.mjs');
+      return await cmdStatus(parsed);
+    }
+    if (command === 'fetch') {
+      const { cmdFetch } = await import('./commands/fetch.mjs');
+      return await cmdFetch(parsed);
+    }
+    process.stderr.write(`unknown command ${JSON.stringify(command)}\n\n${USAGE}`);
+    return 2;
+  } catch (err) {
+    if (err instanceof BacktestRejection) {
+      reportRejection(err, flags.json);
+      return 1;
+    }
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+}
+
+// Exact identity, not a suffix match. The npm package's bin shim is also called
+// ot.mjs, so `endsWith('/ot.mjs')` was true when it merely IMPORTED this file —
+// and the CLI ran twice, once from the shim and once from here.
+const invokedDirectly = process.argv[1]
+  && pathToFileURL(process.argv[1]).href === import.meta.url;
+if (invokedDirectly) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+
+export { main, USAGE };

package/index.d.ts

@@ -0,0 +1,195 @@
+// Type declarations for the `outcometick` strategy SDK.
+//
+// Hand-written against runner/engine/replay.mjs rather than generated, because
+// the runtime is plain ESM. The value here is that a strategy which
+// type-checks is a strategy the validator will accept: the hook names, the
+// hook arities and the shape of `ctx` are all things the queue rejects on, and
+// finding out at compile time is free while finding out after queueing is not.
+//
+// Anything not declared here does not exist at runtime either. `ctx` is frozen
+// and the SDK deliberately exposes no way to reach the network, the clock or
+// the filesystem — see the docs' "Not supported" list.
+
+export type Side = 'UP' | 'DOWN';
+
+export declare const SIDES: readonly ['UP', 'DOWN'];
+
+/** One level of resting depth: [price, size]. */
+export type Level = [number, number];
+
+/**
+ * The book as of one millisecond, frozen.
+ *
+ * A read-only facade over the engine's live book — mutating what you get back
+ * reaches nothing, and there is no way to see a later state through it.
+ */
+export interface BookView {
+  readonly marketId: string;
+  readonly ts: number;
+  /** Best ask for `side` — what you pay to open. */
+  best(side: Side): number | null;
+  bestBid(side: Side): number | null;
+  best_bid(side: Side): number | null;
+  /** Size available at or better than `bound` (all of it when omitted). */
+  depth(side: Side, bound?: number | null): number;
+  bidDepth(side: Side, bound?: number | null): number;
+  bid_depth(side: Side, bound?: number | null): number;
+  levels(side: Side, n?: number): Level[];
+  bidLevels(side: Side, n?: number): Level[];
+  bid_levels(side: Side, n?: number): Level[];
+  mid(side: Side): number | null;
+}
+
+/** A settlement-stream observation. */
+export interface Tick {
+  ts_ms: number;
+  value: number;
+}
+
+/**
+ * A market, as a hook sees it.
+ *
+ * `outcome` is absent everywhere except `onSettle`. That is not an oversight:
+ * before settlement the official label does not exist yet from the strategy's
+ * point of view, and handing it over early is look-ahead.
+ */
+export interface Market {
+  market_id: string;
+  asset: string;
+  interval: string;
+  strike: number | null;
+  open_ts_ms: number;
+  close_ts_ms: number | null;
+}
+
+/** The current position in this market, marked against the real book. */
+export interface Position {
+  side: Side | null;
+  size: number;
+  avg_price: number | null;
+  unrealized: number | null;
+}
+
+/** A declared reference feed or external series, clamped to `ctx.now`. */
+export interface FeedView<T = Record<string, number>> {
+  /** The most recent row stamped at or before ctx.now, or null. */
+  readonly last: T | null;
+  /** The last `n` rows at or before ctx.now, oldest first. */
+  window(n: number): T[];
+  /** The row in effect at `ts`, which may not be later than ctx.now. */
+  at(ts: number): T | null;
+}
+
+/**
+ * Everything a strategy can do.
+ *
+ * Constructed by the runner and frozen. Every accessor is clamped to the
+ * current event time, so none of it can see the future by construction rather
+ * than by convention.
+ */
+export interface Ctx<P = Record<string, unknown>> {
+  /** Params from the manifest, injected before the first hook. */
+  readonly p: P;
+  /** Current event time in epoch ms. Not the wall clock — there isn't one. */
+  readonly now: number;
+
+  /**
+   * The book as of this millisecond.
+   *
+   * Passing another market's id throws unless the manifest declared session
+   * mode; cross-market reads are what that mode is for.
+   */
+  book(id?: string | null): BookView;
+
+  /** The last `n` ticks already seen, oldest first. Always a copy. */
+  history(n?: number): Tick[];
+
+  position(): Position;
+
+  /** Appended to logs.txt in the archive. Truncated past the log limit. */
+  log(msg: unknown): void;
+
+  /** The only randomness available, seeded and recorded in the report. */
+  random(seed?: number | null): number;
+
+  /** A reference feed declared in the manifest. Throws if undeclared. */
+  ref(name: string): FeedView;
+
+  /** An external series declared in the manifest. Throws if undeclared. */
+  ext(name: string): FeedView;
+
+  /** Rolling helpers over the tick history. Identical across languages. */
+  zscore(value: number, opts?: { window?: number }): number;
+  sma(window?: number): number | null;
+  stdev(window?: number): number;
+  ema(window?: number): number | null;
+
+  /**
+   * Record the strategy's own recompute of the outcome against the official
+   * one. Recorded for the cross-check panel, never enforced — a mismatch is
+   * information, not a failed run.
+   */
+  assert_outcome(market: unknown, outcome: Side): void;
+}
+
+export interface OrderInit {
+  side: Side;
+  /** Contracts. Must be positive. */
+  size: number;
+  /**
+   * A bound in whichever direction protects you: a ceiling when opening, a
+   * floor when reducing. Must be within [0, 1] — a binary outcome token
+   * trades nowhere else.
+   */
+  limit?: number | null;
+  holdS?: number | null;
+  hold_s?: number | null;
+  reduceOnly?: boolean;
+  reduce_only?: boolean;
+  /** Only 'ioc' is modelled; anything else is rejected at construction. */
+  tif?: 'ioc';
+  tag?: string | null;
+}
+
+/**
+ * An order a hook returns.
+ *
+ * Never sent — returned, and matched by the runner against the depth that was
+ * actually resting at that millisecond.
+ */
+export declare class Order {
+  constructor(init: OrderInit);
+  readonly side: Side;
+  readonly size: number;
+  readonly limit: number | null;
+  readonly hold_s: number | null;
+  readonly reduce_only: boolean;
+  readonly tif: 'ioc';
+  readonly tag: string | null;
+}
+
+/**
+ * Base class for a submitted strategy.
+ *
+ * The hooks are intentionally not declared as members: implementing one you
+ * did not list in the manifest does nothing, and listing one you did not
+ * implement is a rejection. Declare them in `outcometick.json` and write them
+ * with these signatures.
+ *
+ *     onMarketOpen(ctx: Ctx, market: Market): void
+ *     onTick(ctx: Ctx, tick: Tick): Order | null
+ *     onBook(ctx: Ctx, book: BookView): Order | null
+ *     onTrade(ctx: Ctx, trade: Tick): Order | null
+ *     onSettle(ctx: Ctx, market: Market, outcome: Side): void
+ */
+export declare class Strategy<P = Record<string, unknown>> {
+  /** Params from the manifest, injected by the runner before the first hook. */
+  p: P;
+}
+
+declare const _default: {
+  Strategy: typeof Strategy;
+  Order: typeof Order;
+  SIDES: typeof SIDES;
+};
+export default _default;

package/index.mjs

@@ -0,0 +1,2 @@
+export { Strategy, Order, SIDES } from './runner/harness/node/sdk/index.mjs';
+export { default } from './runner/harness/node/sdk/index.mjs';

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "outcometick",
+  "version": "1.4.0",
+  "description": "Strategy SDK and CLI for outcometick prediction-market backtests",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://outcometick.com/docs/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outcometick/outcometick-sdk-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/outcometick/outcometick-sdk-ts/issues"
+  },
+  "bin": {
+    "ot": "./bin/ot.mjs"
+  },
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "api",
+    "runner",
+    "cli",
+    "bin",
+    "index.mjs",
+    "index.d.ts",
+    "!**/*.test.mjs",
+    "!**/*.test-d.ts"
+  ],
+  "scripts": {
+    "test": "node --test runner/analyze/*.test.mjs runner/engine/*.test.mjs runner/harness/node/*.test.mjs cli/*.test.mjs"
+  },
+  "dependencies": {
+    "acorn": "^8.18.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "peerDependenciesMeta": {
+    "danfojs-node": {
+      "optional": true
+    },
+    "mathjs": {
+      "optional": true
+    },
+    "decimal.js": {
+      "optional": true
+    }
+  }
+}

package/runner/analyze/index.mjs

@@ -0,0 +1,40 @@
+// Choosing the analyser for a submission's language.
+//
+// This exists as a shared function, in a file both sides can import, because
+// the docs make a promise that only holds if there is ONE of it:
+//
+//     ot check runs the exact validator the queue runs. If it passes locally
+//     it will not be rejected on submit.
+//
+// api/lib/backtest-routes.mjs and cli/ot.mjs both call this. They used to each
+// dispatch on languageId themselves, and the two dispatches were not the same:
+// the server threw for an unrecognised language while the CLI fell through to
+// the JavaScript analyser. With only nodejs and python that difference was
+// invisible, but it would have surfaced the day a third language was added —
+// as `ot check` cheerfully passing a Go strategy it had analysed as JavaScript,
+// followed by a rejection after queueing. Which is precisely the experience the
+// promise above exists to prevent.
+
+import { analyzeJavaScriptSubmission } from './javascript.mjs';
+import { analyzePythonSubmission } from './python.mjs';
+
+/**
+ * Statically analyse a checked submission.
+ *
+ * @param checked  The result of checkSubmission — already validated, so the
+ *                 language is known to be one the contract lists.
+ */
+export async function analyzeSource(checked) {
+  const { languageId, deps } = checked.manifest;
+  if (languageId === 'nodejs') {
+    return analyzeJavaScriptSubmission(checked.files, { deps });
+  }
+  if (languageId === 'python') {
+    return analyzePythonSubmission(checked.files, { deps });
+  }
+  // Fail closed. A language the contract accepts but no analyser covers is a
+  // gap on our side, and running it unanalysed is not the safe reading of it.
+  const err = new Error(`no analyser for ${languageId}`);
+  err.status = 503;
+  throw err;
+}