@forgezero/runtime 0.1.0

package/dist/finance/money.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Exact amounts, with the asset attached.
+ *
+ * Two mistakes account for almost every money bug, and both are eliminated here
+ * by construction rather than by care:
+ *
+ *   FLOATS      `0.1 + 0.2` is not `0.3`, and a double cannot represent satoshi
+ *               precision above roughly ninety million units at all. The error
+ *               is small, real, and accumulates into a ledger that fails to
+ *               balance by a few units a month with nobody able to say why.
+ *               Amounts here are `bigint` minor units — never a `number`.
+ *
+ *   MIXED UNITS adding BTC to USDT type-checks perfectly if both are numbers.
+ *               The asset travels WITH the amount and every operation refuses a
+ *               mismatch, so the mistake is a thrown error at the point it is
+ *               made rather than a plausible figure somewhere downstream.
+ *
+ * ## Why not a decimal library
+ *
+ * Arbitrary-precision decimals solve the float problem and not the unit one,
+ * and they invite `0.1` back into the code as a literal. Minor units mean the
+ * only representable values are the ones the asset actually has — you cannot
+ * express half a satoshi, because there is no such thing.
+ *
+ * ## Rounding is never implicit
+ *
+ * Every operation that could lose precision takes an explicit mode. A default
+ * would be a decision made once, silently, in whichever direction happened to
+ * suit the first caller — and on the wrong side it is theft in one direction
+ * and a loss in the other.
+ */
+export declare class MoneyError extends Error {
+    readonly code: 'ASSET_MISMATCH' | 'UNKNOWN_ASSET' | 'NOT_FINITE' | 'PRECISION_LOSS' | 'DIVIDE_BY_ZERO';
+    constructor(code: 'ASSET_MISMATCH' | 'UNKNOWN_ASSET' | 'NOT_FINITE' | 'PRECISION_LOSS' | 'DIVIDE_BY_ZERO', message: string);
+}
+/**
+ * How many minor units make one whole unit.
+ *
+ * Declared per asset because it is a property of the asset and not a display
+ * preference: USDT has 6 on most chains, BTC has 8, ETH has 18. Getting it
+ * wrong by one decimal place is a factor-of-ten error in a balance.
+ */
+export interface AssetSpec {
+    code: string;
+    decimals: number;
+    /** What to show a human. `USDT`, `BTC` — never a symbol that collides. */
+    label?: string;
+}
+export declare const ASSETS: readonly AssetSpec[];
+/** Register an asset the built-in table does not carry. */
+export declare function defineAsset(spec: AssetSpec): void;
+export declare function assetSpec(code: string): AssetSpec;
+/** An amount and what it is denominated in. Immutable. */
+export interface Money {
+    /** Minor units. 1 USDT is 1_000_000n at 6 decimals. */
+    readonly units: bigint;
+    readonly asset: string;
+}
+export declare const money: (units: bigint, asset: string) => Money;
+export declare const zero: (asset: string) => Money;
+/**
+ * Parse a human string into exact minor units.
+ *
+ * Refuses more precision than the asset has rather than rounding it away.
+ * "0.0000000001 BTC" is not a very small amount of bitcoin — it is a mistake,
+ * usually a units error, and silently truncating it hides the bug that produced
+ * it.
+ */
+export declare function parseAmount(value: string, asset: string): Money;
+/** Render minor units as a human string. Exact — never a float on the way out. */
+export declare function formatAmount(amount: Money, options?: {
+    trim?: boolean;
+}): string;
+export declare function add(a: Money, b: Money): Money;
+export declare function subtract(a: Money, b: Money): Money;
+export declare const negate: (amount: Money) => Money;
+export declare const abs: (amount: Money) => Money;
+export declare const isZero: (amount: Money) => boolean;
+export declare const isNegative: (amount: Money) => boolean;
+export declare function compare(a: Money, b: Money): -1 | 0 | 1;
+export declare const equals: (a: Money, b: Money) => boolean;
+/**
+ * Rounding modes, named for what they do to the HOLDER of the money.
+ *
+ * `down` truncates toward zero — the safe default for anything a venue will
+ * check, because rounding a quantity up can exceed a balance and get the whole
+ * order rejected.
+ */
+export declare const ROUNDING: readonly ["down", "up", "half-up"];
+export type Rounding = (typeof ROUNDING)[number];
+/**
+ * Multiply by a rate expressed as a decimal string.
+ *
+ * The rate is a STRING, not a number: writing `0.001` as a literal reintroduces
+ * the float this module exists to keep out, and a price like `43210.55` is
+ * exactly the value a double gets subtly wrong.
+ */
+export declare function mulRate(amount: Money, rate: string, mode?: Rounding): Money;
+/**
+ * Convert between assets at a stated rate.
+ *
+ * The rate is "how many units of `to` per one whole unit of `from`", which is
+ * how every venue and price feed quotes it. Doing the decimal adjustment here
+ * rather than at each call site is the point — it is the step that is easy to
+ * get wrong by a factor of a thousand when the two assets differ in precision.
+ */
+export declare function convert(amount: Money, to: string, rate: string, mode?: Rounding): Money;
+/**
+ * Split an amount into parts without losing a unit.
+ *
+ * The remainder is distributed one unit at a time across the first parts rather
+ * than dropped, so the parts always sum back to the original. A split that
+ * loses units is how a ledger drifts by a few cents a day.
+ */
+export declare function allocate(amount: Money, parts: number): Money[];
+/** Round to a venue's step size — a lot size or a tick. Down, so it still fits. */
+export declare function toStep(amount: Money, step: string, mode?: Rounding): Money;
+export declare const VERSION = "0.1.0";

package/dist/finance/money.js

@@ -0,0 +1,176 @@
+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";
+export {
+  zero,
+  toStep,
+  subtract,
+  parseAmount,
+  negate,
+  mulRate,
+  money,
+  isZero,
+  isNegative,
+  formatAmount,
+  equals,
+  defineAsset,
+  convert,
+  compare,
+  assetSpec,
+  allocate,
+  add,
+  abs,
+  VERSION,
+  ROUNDING,
+  MoneyError,
+  ASSETS
+};

package/dist/finance/rates.d.ts

@@ -0,0 +1,178 @@
+import { type Money } from './money';
+/**
+ * What an asset is worth, and how old that answer is.
+ *
+ * The platform keeps its books in USD, so every balance in BTC, ETH or a token
+ * has to be expressed in one unit before it can be added to anything. That
+ * needs a rate, and a rate needs two things people routinely leave out:
+ *
+ *   A SOURCE  a peg is not a quote. USDT is 1 by definition and asking an
+ *             exchange for it introduces an error where none existed — a
+ *             stablecoin trading at 0.9994 would silently revalue every
+ *             balance on the platform by six basis points.
+ *   AN AGE    a rate with no timestamp is a rate that keeps quoting yesterday
+ *             after the feed dies. Nothing here returns a value without also
+ *             saying when it was true, and a caller pricing a withdrawal can
+ *             refuse a stale one.
+ *
+ * ## Why the conversion itself is not implemented here
+ *
+ * `./money` already has `convert`, and the hard part is not
+ * the multiplication — it is the decimal adjustment between assets of different
+ * precision, which is where a factor-of-a-thousand error comes from. That is
+ * written and tested once. This module answers *what rate*, never *how to
+ * apply it*.
+ */
+export declare class RateError extends Error {
+    readonly code: 'NO_RATE' | 'STALE_RATE' | 'BAD_RATE' | 'UNKNOWN_ASSET';
+    readonly asset?: string | undefined;
+    constructor(code: 'NO_RATE' | 'STALE_RATE' | 'BAD_RATE' | 'UNKNOWN_ASSET', message: string, asset?: string | undefined);
+}
+/** The unit the platform keeps its books in. */
+export declare const BASE_ASSET = "USD";
+export declare const RATE_SOURCES: readonly ["peg", "venue", "manual"];
+export type RateSource = (typeof RATE_SOURCES)[number];
+/**
+ * How an asset is priced.
+ *
+ *   peg     fixed by definition and never fetched. USDT is 1.
+ *   venue   quoted live from a chosen source, and therefore has an age.
+ *   manual  an operator typed it. Also has an age, and deliberately so: a
+ *           manual rate somebody set in March is more dangerous than a missing
+ *           one, because it looks maintained.
+ */
+export interface AssetRate {
+    asset: string;
+    source: RateSource;
+    /** USD per ONE whole unit, as a decimal string. Never a float. */
+    usd: string;
+    /** When this was true. Absent only for a peg, which has no such moment. */
+    atMs?: number;
+    /** For `venue`: which market it came from, so a wrong price is traceable. */
+    via?: string;
+}
+export interface AssetEntry {
+    code: string;
+    label: string;
+    decimals: number;
+    /**
+     * Chain this asset lives on, when it is a token.
+     *
+     * Absent for fiat and for a chain's own coin, which is why the field is
+     * optional rather than a string that sometimes says "native" — a sentinel
+     * value in a foreign key is a join nobody can write.
+     */
+    chain?: string;
+    /** Contract address for a token. Absent for a native coin. */
+    contract?: string;
+    enabled: boolean;
+    rate: AssetRate;
+}
+export declare function assertRate(rate: AssetRate): void;
+/** USDT and USDC at exactly 1, by definition rather than by quote. */
+export declare const peg: (asset: string, usd?: string) => AssetRate;
+export interface RateTableOptions {
+    /** How old a quoted rate may be before it is refused. Default 15 minutes. */
+    maxAgeMs?: number;
+    now?: () => number;
+}
+/**
+ * The rates in force, and the one place that decides a quote is too old.
+ *
+ * Staleness is checked on READ rather than swept on a timer. A sweeper that
+ * deletes old rates turns a stale-price incident into a missing-price incident
+ * — the same outage with less information — and it can itself fail, leaving
+ * rates that look fresh because nothing removed them.
+ */
+export declare function createRateTable(options?: RateTableOptions): {
+    set(rate: AssetRate): void;
+    /** The raw entry, however old. For an admin screen that must show staleness. */
+    peek: (asset: string) => AssetRate | undefined;
+    ageOf(asset: string): number | undefined;
+    isStale(asset: string): boolean;
+    /**
+     * The rate, or a refusal that says which problem it is.
+     *
+     * Missing and stale are different failures with different fixes — one is
+     * an unconfigured asset, the other a dead feed — and collapsing them sends
+     * an operator to the wrong screen.
+     *
+     * Every valuation below goes through THIS, so the staleness rule exists in
+     * exactly one place. Two copies of it is two chances for a valuation path
+     * to accept a rate another path would refuse.
+     */
+    require(asset: string): AssetRate;
+    /**
+     * Value an amount in USD.
+     *
+     * Rounded DOWN. A rounding decision on a platform balance should leave the
+     * platform conservative about what it holds — a thousand rounded-up
+     * valuations become a shortfall nobody can locate.
+     */
+    toUsd(amount: Money): Money;
+    /** Sum a mixed bag of assets into one USD figure. */
+    totalUsd(amounts: readonly Money[]): Money;
+    all: () => AssetRate[];
+    clear: () => void;
+};
+export type RateTable = ReturnType<typeof createRateTable>;
+/**
+ * Register an asset so `money` knows its precision.
+ *
+ * Called when an admin adds one. Getting `decimals` wrong is a factor-of-ten
+ * error in every balance of that asset, which is why it is declared per asset
+ * rather than defaulted — there is no safe default.
+ */
+export declare function registerAsset(entry: AssetEntry): void;
+export declare const isRegistered: (code: string) => boolean;
+/**
+ * A rate fetched from a venue.
+ *
+ * The fetcher is injected rather than imported, so this module stays free of a
+ * transport and a test needs no network. The venue adapter already carries the
+ * weight budget, which is the reason not to open a second HTTP path here.
+ */
+export interface RateFetcher {
+    /** USD price of one whole unit, as a decimal string, or undefined if unquoted. */
+    quote(asset: string): Promise<string | undefined>;
+}
+export interface RefreshReport {
+    refreshed: string[];
+    /** Assets whose quote failed. The PREVIOUS rate is left in place — see below. */
+    failed: {
+        asset: string;
+        reason: string;
+    }[];
+    skipped: string[];
+}
+/**
+ * Refresh every quoted asset.
+ *
+ * A failed quote leaves the old rate alone rather than clearing it. Clearing
+ * would turn a brief feed outage into "no rate configured", which reads as a
+ * misconfiguration and sends somebody to the wrong screen — and the old rate is
+ * still visibly ageing, so `require()` refuses it on its own once it passes the
+ * limit. Doing nothing is the correct action; doing nothing SILENTLY is not,
+ * which is why failures are reported.
+ */
+export declare function refreshRates(table: RateTable, fetcher: RateFetcher, args: {
+    assets: readonly AssetEntry[];
+    now?: () => number;
+}): Promise<RefreshReport>;
+/** The refresh as a job spec, for `@forgezero/runtime/jobs`. */
+export declare function rateRefreshJob(args: {
+    table: RateTable;
+    fetcher: RateFetcher;
+    assets: () => readonly AssetEntry[];
+    everyMs?: number;
+    key?: string;
+}): {
+    key: string;
+    everyMs: number;
+    run: () => Promise<{
+        ok: boolean;
+        detail: RefreshReport;
+    }>;
+};
+/** For an admin screen: what each asset is worth and how much to trust it. */
+export declare const describeRate: (rate: AssetRate, ageMs?: number) => string;