@forgezero/runtime 0.1.0

package/dist/finance/transfers.js

@@ -0,0 +1,292 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/finance/money.ts
+class MoneyError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MoneyError";
+  }
+}
+var ASSETS = [
+  { code: "USDT", decimals: 6 },
+  { code: "USDC", decimals: 6 },
+  { code: "BTC", decimals: 8 },
+  { code: "ETH", decimals: 18 },
+  { code: "BNB", decimals: 18 },
+  { code: "EUR", decimals: 2 },
+  { code: "USD", decimals: 2 }
+];
+var REGISTRY = new Map(ASSETS.map((asset) => [asset.code, asset]));
+function defineAsset(spec) {
+  if (spec.decimals < 0 || spec.decimals > 30 || !Number.isInteger(spec.decimals)) {
+    throw new MoneyError("UNKNOWN_ASSET", `${spec.code}: decimals must be an integer 0–30.`);
+  }
+  REGISTRY.set(spec.code, spec);
+}
+function assetSpec(code) {
+  const spec = REGISTRY.get(code);
+  if (!spec)
+    throw new MoneyError("UNKNOWN_ASSET", `Unknown asset "${code}". Call defineAsset first.`);
+  return spec;
+}
+var money = (units, asset) => {
+  assetSpec(asset);
+  return { units, asset };
+};
+var zero = (asset) => money(0n, asset);
+function parseAmount(value, asset) {
+  const spec = assetSpec(asset);
+  const text = value.trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) {
+    throw new MoneyError("NOT_FINITE", `"${value}" is not a plain decimal amount.`);
+  }
+  const negative = text.startsWith("-");
+  const [whole, fraction = ""] = text.replace("-", "").split(".");
+  if (fraction.length > spec.decimals) {
+    throw new MoneyError("PRECISION_LOSS", `${asset} has ${spec.decimals} decimals; "${value}" has ${fraction.length}.`);
+  }
+  const padded = fraction.padEnd(spec.decimals, "0");
+  const units = BigInt(whole + padded);
+  return { units: negative ? -units : units, asset };
+}
+function formatAmount(amount, options = {}) {
+  const spec = assetSpec(amount.asset);
+  const negative = amount.units < 0n;
+  const digits = (negative ? -amount.units : amount.units).toString().padStart(spec.decimals + 1, "0");
+  const whole = digits.slice(0, digits.length - spec.decimals);
+  let fraction = spec.decimals === 0 ? "" : digits.slice(digits.length - spec.decimals);
+  if (options.trim && fraction)
+    fraction = fraction.replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
+}
+function sameAsset(a, b) {
+  if (a.asset !== b.asset) {
+    throw new MoneyError("ASSET_MISMATCH", `Cannot combine ${a.asset} and ${b.asset}.`);
+  }
+}
+function add(a, b) {
+  sameAsset(a, b);
+  return { units: a.units + b.units, asset: a.asset };
+}
+function subtract(a, b) {
+  sameAsset(a, b);
+  return { units: a.units - b.units, asset: a.asset };
+}
+var negate = (amount) => ({ units: -amount.units, asset: amount.asset });
+var abs = (amount) => ({
+  units: amount.units < 0n ? -amount.units : amount.units,
+  asset: amount.asset
+});
+var isZero = (amount) => amount.units === 0n;
+var isNegative = (amount) => amount.units < 0n;
+function compare(a, b) {
+  sameAsset(a, b);
+  return a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
+}
+var equals = (a, b) => a.asset === b.asset && a.units === b.units;
+var ROUNDING = ["down", "up", "half-up"];
+function divideRounded(numerator, denominator, mode) {
+  if (denominator === 0n)
+    throw new MoneyError("DIVIDE_BY_ZERO", "Division by zero.");
+  const negative = numerator < 0n !== denominator < 0n;
+  const a = numerator < 0n ? -numerator : numerator;
+  const b = denominator < 0n ? -denominator : denominator;
+  const quotient = a / b;
+  const remainder = a % b;
+  if (remainder === 0n)
+    return negative ? -quotient : quotient;
+  let result = quotient;
+  if (mode === "up")
+    result += 1n;
+  else if (mode === "half-up" && remainder * 2n >= b)
+    result += 1n;
+  return negative ? -result : result;
+}
+function mulRate(amount, rate, mode = "down") {
+  if (!/^-?\d+(\.\d+)?$/.test(rate.trim())) {
+    throw new MoneyError("NOT_FINITE", `"${rate}" is not a plain decimal rate.`);
+  }
+  const [whole, fraction = ""] = rate.trim().replace("-", "").split(".");
+  const scale = 10n ** BigInt(fraction.length);
+  const scaled = BigInt(whole + fraction) * (rate.trim().startsWith("-") ? -1n : 1n);
+  return { units: divideRounded(amount.units * scaled, scale, mode), asset: amount.asset };
+}
+function convert(amount, to, rate, mode = "down") {
+  const from = assetSpec(amount.asset);
+  const target = assetSpec(to);
+  const asTarget = mulRate({ units: amount.units, asset: to }, rate, mode);
+  const shift = target.decimals - from.decimals;
+  if (shift === 0)
+    return asTarget;
+  if (shift > 0)
+    return { units: asTarget.units * 10n ** BigInt(shift), asset: to };
+  return { units: divideRounded(asTarget.units, 10n ** BigInt(-shift), mode), asset: to };
+}
+function allocate(amount, parts) {
+  if (parts < 1)
+    throw new MoneyError("NOT_FINITE", "Cannot allocate into fewer than one part.");
+  const each = divideRounded(amount.units, BigInt(parts), "down");
+  const allocated = Array.from({ length: parts }, () => each);
+  let remainder = amount.units - each * BigInt(parts);
+  const step = remainder < 0n ? -1n : 1n;
+  for (let index = 0;remainder !== 0n; index = (index + 1) % parts) {
+    allocated[index] += step;
+    remainder -= step;
+  }
+  return allocated.map((units) => ({ units, asset: amount.asset }));
+}
+function toStep(amount, step, mode = "down") {
+  const stepUnits = parseAmount(step, amount.asset).units;
+  if (stepUnits <= 0n)
+    throw new MoneyError("NOT_FINITE", "A step must be positive.");
+  return { units: divideRounded(amount.units, stepUnits, mode) * stepUnits, asset: amount.asset };
+}
+var VERSION = "0.1.0";
+
+// src/finance/transfers.ts
+import { Refusal, isRefusal } from "@forgezero/access";
+var DIRECTIONS = ["deposit", "withdrawal"];
+var SCREENING_ORDER = 0;
+
+class PipelineError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PipelineError";
+  }
+}
+function createTransferPipeline(options) {
+  const seen = new Set;
+  for (const stage of options.stages) {
+    if (seen.has(stage.name)) {
+      throw new PipelineError("DUPLICATE_STAGE", `Two stages are named "${stage.name}".`);
+    }
+    seen.add(stage.name);
+  }
+  if (options.requireScreening && !options.stages.some((stage) => stage.order === SCREENING_ORDER)) {
+    throw new PipelineError("NO_SCREENING", "This pipeline requires a screening stage at order 0 and has none. Register one, or set requireScreening to false and accept that transfers are unscreened.");
+  }
+  const ordered = [...options.stages].sort((a, b) => a.order - b.order);
+  const now = options.now ?? Date.now;
+  return {
+    stages: ordered.map((stage) => ({ name: stage.name, order: stage.order })),
+    async run(transfer) {
+      const outcomes = [];
+      let current = transfer;
+      for (const stage of ordered) {
+        if (stage.directions && !stage.directions.includes(current.direction))
+          continue;
+        const startedAt = now();
+        try {
+          const patch = await stage.run(current);
+          if (patch)
+            current = { ...current, context: { ...current.context, ...patch } };
+          const outcome = { stage: stage.name, ok: true, ms: now() - startedAt };
+          outcomes.push(outcome);
+          options.onStage?.(outcome, current);
+        } catch (cause) {
+          const refusal = isRefusal(cause) ? cause : new Refusal(500, "STAGE_FAILED", `The "${stage.name}" check could not complete.`, { stage: stage.name }, true);
+          const outcome = {
+            stage: stage.name,
+            ok: false,
+            ms: now() - startedAt,
+            code: refusal.code
+          };
+          outcomes.push(outcome);
+          options.onStage?.(outcome, current);
+          return { ok: false, transfer: current, stages: outcomes, refusal };
+        }
+      }
+      return { ok: true, transfer: current, stages: outcomes };
+    }
+  };
+}
+var screeningStage = (check = () => true) => ({
+  name: "aml.screening",
+  order: SCREENING_ORDER,
+  async run(transfer) {
+    const allowed = await check(transfer);
+    if (!allowed) {
+      throw new Refusal(451, "SCREENING_REFUSED", "This transfer cannot be processed.", {
+        direction: transfer.direction
+      });
+    }
+    return { screenedAtMs: transfer.atMs };
+  }
+});
+var limitsStage = (limits) => ({
+  name: "limits",
+  order: 10,
+  directions: limits.directions,
+  run(transfer) {
+    if (transfer.amount.units <= 0n) {
+      throw new Refusal(422, "AMOUNT_INVALID", "The amount must be positive.");
+    }
+    if (limits.min && transfer.amount.asset === limits.min.asset && transfer.amount.units < limits.min.units) {
+      throw new Refusal(422, "BELOW_MINIMUM", `The minimum is ${formatAmount(limits.min, { trim: true })} ${limits.min.asset}.`);
+    }
+    if (limits.max && transfer.amount.asset === limits.max.asset && transfer.amount.units > limits.max.units) {
+      throw new Refusal(422, "ABOVE_MAXIMUM", `The maximum is ${formatAmount(limits.max, { trim: true })} ${limits.max.asset}.`);
+    }
+  }
+});
+var balanceStage = (available) => ({
+  name: "balance",
+  order: 20,
+  directions: ["withdrawal"],
+  async run(transfer) {
+    const free = await available(transfer);
+    if (free.units < transfer.amount.units) {
+      throw new Refusal(409, "INSUFFICIENT_BALANCE", "The available balance does not cover this.", {
+        required: formatAmount(transfer.amount, { trim: true }),
+        available: formatAmount(free, { trim: true }),
+        asset: transfer.amount.asset
+      });
+    }
+  }
+});
+var approvalStage = (args) => ({
+  name: "approval",
+  order: 30,
+  directions: ["withdrawal"],
+  async run(transfer) {
+    if (transfer.amount.asset !== args.threshold.asset)
+      return;
+    if (transfer.amount.units < args.threshold.units)
+      return;
+    if (!await args.isApproved(transfer)) {
+      throw new Refusal(409, "AWAITING_APPROVAL", "This transfer is held for review.", {
+        threshold: formatAmount(args.threshold, { trim: true })
+      }, true);
+    }
+  }
+});
+var notFrozenStage = (isFrozen) => ({
+  name: "account.active",
+  order: 5,
+  async run(transfer) {
+    if (await isFrozen(transfer.owner)) {
+      throw new Refusal(423, "ACCOUNT_FROZEN", "This account is suspended. Settle the outstanding invoice to resume.");
+    }
+  }
+});
+export {
+  screeningStage,
+  notFrozenStage,
+  limitsStage,
+  createTransferPipeline,
+  balanceStage,
+  approvalStage,
+  SCREENING_ORDER,
+  PipelineError,
+  DIRECTIONS
+};

package/dist/finance/venues.d.ts

@@ -0,0 +1,190 @@
+import { type Money } from './money';
+/**
+ * Trading venues, market types and symbols — as data.
+ *
+ * A trading system accumulates venue knowledge in the worst possible places:
+ * a lot size hard-coded in an order builder, a minimum notional in a validator,
+ * a symbol spelling in three files that disagree. This declares it once, so
+ * adding a market is data and adding a venue is one adapter.
+ *
+ * ## Why spot, margin and futures share an order model
+ *
+ * They differ in what they settle against, not in what an order IS. All three
+ * take a symbol, a side, a quantity and optionally a price; all three reject
+ * quantities off the lot step and notionals under a minimum. Modelling them
+ * separately means writing the same validation three times and getting it
+ * subtly different — and the difference will be in the one nobody trades often.
+ *
+ * What genuinely differs is expressed as fields on the market: leverage exists
+ * on margin and futures and not on spot, futures carry a contract type and an
+ * expiry. A caller that ignores those still cannot place an invalid order,
+ * because validation reads the market rather than the caller's intent.
+ *
+ * ## Nothing here talks to a venue
+ *
+ * `VenueAdapter` is an interface. This package validates, normalises and
+ * describes; the transport lives with whoever implements the adapter, so a new
+ * venue costs one file and no changes here.
+ */
+export declare const MARKET_TYPES: readonly ["spot", "margin", "futures"];
+export type MarketType = (typeof MARKET_TYPES)[number];
+export declare const ORDER_SIDES: readonly ["buy", "sell"];
+export type OrderSide = (typeof ORDER_SIDES)[number];
+/**
+ * Order types every venue we support implements.
+ *
+ * Deliberately short. A venue-specific type — trailing stops, iceberg, OCO —
+ * belongs behind the adapter, because supporting it here means every other
+ * adapter has to reject it and the rejection is where the bugs live.
+ */
+export declare const ORDER_TYPES: readonly ["market", "limit", "stop-limit"];
+export type OrderType = (typeof ORDER_TYPES)[number];
+/**
+ * How long an order lives.
+ *
+ *   gtc  rests until filled or cancelled
+ *   ioc  fills what it can immediately, cancels the rest
+ *   fok  fills entirely and immediately, or not at all
+ *
+ * `fok` matters for anything that must not partially fill — a hedge leg that
+ * half-executes leaves a position nobody asked for.
+ */
+export declare const TIME_IN_FORCE: readonly ["gtc", "ioc", "fok"];
+export type TimeInForce = (typeof TIME_IN_FORCE)[number];
+export interface VenueSpec {
+    key: string;
+    label: string;
+    /** Market types this venue offers at all. */
+    markets: readonly MarketType[];
+    /**
+     * Requests per minute the venue permits, and how it counts them.
+     *
+     * `weight` means a request costs more than one — Binance charges by response
+     * size, so a naive per-request limiter is wrong by an order of magnitude on
+     * the endpoints that matter.
+     */
+    rateLimit: {
+        perMinute: number;
+        counts: 'requests' | 'weight';
+    };
+    /** Whether the venue supports a caller-supplied idempotency key on orders. */
+    clientOrderIds: boolean;
+    /** One clause: what a caller most needs to know before integrating. */
+    note: string;
+}
+export interface MarketSpec {
+    venue: string;
+    type: MarketType;
+    /** Canonical, venue-independent: `BTC/USDT`. Never a venue's own spelling. */
+    symbol: string;
+    base: string;
+    quote: string;
+    /** Quantity must be a multiple of this. */
+    lotStep: string;
+    /** Price must be a multiple of this. */
+    tickStep: string;
+    /** Smallest order value, in the quote asset. */
+    minNotional: string;
+    /** Margin and futures only. Absent on spot, and that absence is the rule. */
+    maxLeverage?: number;
+    /** Futures only. */
+    contract?: 'perpetual' | 'quarterly';
+}
+export declare const VENUES: readonly VenueSpec[];
+export declare const venue: (key: string) => VenueSpec | undefined;
+export declare const venuesFor: (type: MarketType) => readonly VenueSpec[];
+/**
+ * `BTC/USDT` — one spelling, ours.
+ *
+ * Venues disagree: `BTCUSDT`, `BTC-USDT`, `btc_usdt`. Storing whichever the
+ * venue happened to use means a subscription created against one spelling does
+ * not match an order placed with another, and the mismatch is invisible until
+ * it is a missing position. Normalise on the way in, denormalise in the adapter.
+ */
+export declare const symbolOf: (base: string, quote: string) => string;
+export declare function parseSymbol(symbol: string): {
+    base: string;
+    quote: string;
+};
+export declare class VenueError extends Error {
+    readonly code: 'UNKNOWN_VENUE' | 'UNKNOWN_MARKET' | 'MARKET_UNSUPPORTED' | 'BAD_SYMBOL' | 'LOT_STEP' | 'TICK_STEP' | 'MIN_NOTIONAL' | 'PRICE_REQUIRED' | 'LEVERAGE_UNSUPPORTED' | 'LEVERAGE_TOO_HIGH';
+    constructor(code: 'UNKNOWN_VENUE' | 'UNKNOWN_MARKET' | 'MARKET_UNSUPPORTED' | 'BAD_SYMBOL' | 'LOT_STEP' | 'TICK_STEP' | 'MIN_NOTIONAL' | 'PRICE_REQUIRED' | 'LEVERAGE_UNSUPPORTED' | 'LEVERAGE_TOO_HIGH', message: string);
+}
+export interface OrderRequest {
+    venue: string;
+    type: MarketType;
+    symbol: string;
+    side: OrderSide;
+    orderType: OrderType;
+    /** In the BASE asset. */
+    quantity: Money;
+    /** In the QUOTE asset. Required for anything that is not a market order. */
+    price?: Money;
+    stopPrice?: Money;
+    timeInForce?: TimeInForce;
+    /** Margin and futures only. */
+    leverage?: number;
+    /**
+     * The caller's own idempotency key.
+     *
+     * Not optional in practice for anything automated: without it a retried
+     * submission after a timeout places a second order, and the operator sees one
+     * confirmation for two positions.
+     */
+    clientOrderId?: string;
+    /** Test the order against the venue without it resting. */
+    dryRun?: boolean;
+}
+export type OrderStatus = 'accepted' | 'partial' | 'filled' | 'cancelled' | 'rejected';
+export interface OrderResult {
+    venueOrderId: string;
+    clientOrderId?: string;
+    status: OrderStatus;
+    filledQuantity: Money;
+    averagePrice?: Money;
+    raw?: unknown;
+}
+/** Notional value of an order, in the quote asset. */
+export declare function notionalOf(request: OrderRequest, market: MarketSpec): Money;
+/**
+ * Everything a venue would reject the order for, checked before it is sent.
+ *
+ * Locally rather than by submitting and reading the error, for three reasons: a
+ * round trip costs rate budget the caller may not have, the venue's error codes
+ * are inconsistent between market types, and a rejection after submission has
+ * already consumed an idempotency key.
+ */
+export declare function validateOrder(request: OrderRequest, market: MarketSpec): void;
+/**
+ * What a venue integration provides.
+ *
+ * Deliberately small. Everything that can be decided without the venue —
+ * validation, symbol spelling, step rounding — is decided above, so an adapter
+ * is transport plus translation and nothing else. That is what keeps a second
+ * venue cheap.
+ */
+export interface VenueAdapter {
+    readonly venue: string;
+    /** The venue's own spelling of a canonical symbol. */
+    symbolFor(symbol: string, type: MarketType): string;
+    markets(type: MarketType): Promise<MarketSpec[]>;
+    placeOrder(request: OrderRequest, market: MarketSpec): Promise<OrderResult>;
+    cancelOrder(args: {
+        venueOrderId: string;
+        symbol: string;
+        type: MarketType;
+    }): Promise<void>;
+    openOrders(args: {
+        symbol?: string;
+        type: MarketType;
+    }): Promise<OrderResult[]>;
+    balances(type: MarketType): Promise<Money[]>;
+}
+/**
+ * Validate, then place.
+ *
+ * The one function a caller should use. Validating inside the adapter would
+ * make it every adapter's job, and the third one would get it wrong.
+ */
+export declare function submitOrder(adapter: VenueAdapter, request: OrderRequest, market: MarketSpec): Promise<OrderResult>;
+export declare const VERSION = "0.1.0";