@forgezero/runtime 0.1.14 → 0.1.16

package/dist/finance/transfers.js

@@ -1,292 +0,0 @@
-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

@@ -1,190 +0,0 @@
-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";