@forgezero/runtime 0.1.0

package/dist/finance/chain.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Which chains exist, and what it takes to believe a transfer on one.
+ *
+ * Data an admin edits, never a constant. The prior art here got it wrong in a
+ * specific and expensive way: two BSC entries hard-coded in a TypeScript
+ * constant, so listing a token was a deploy. Two exchanges will not share one
+ * chain list and neither will wait for a release to add an asset.
+ *
+ * ## Confirmations are the whole point
+ *
+ * Every other field is bookkeeping. `confirmations` is the number that decides
+ * whether the platform pays out on a transaction that later disappears in a
+ * reorg — credit too early and a deep reorg is a real loss, credit too late and
+ * deposits take an hour nobody understands.
+ *
+ * It is per chain AND per asset value band, because the right depth for a $20
+ * transfer is not the right depth for a $2 million one. A single number is
+ * either too slow for small deposits or too shallow for large ones, and it is
+ * always the large one that costs money.
+ */
+export declare class ChainError extends Error {
+    readonly code: 'UNKNOWN_CHAIN' | 'UNKNOWN_ASSET' | 'BAD_ADDRESS' | 'BAD_CONFIRMATIONS';
+    constructor(code: 'UNKNOWN_CHAIN' | 'UNKNOWN_ASSET' | 'BAD_ADDRESS' | 'BAD_CONFIRMATIONS', message: string);
+}
+export declare const ADDRESS_SCHEMES: readonly ["evm", "bitcoin", "tron", "solana"];
+export type AddressScheme = (typeof ADDRESS_SCHEMES)[number];
+/**
+ * How many confirmations a value band needs.
+ *
+ * Bands are open-ended upward: the last one applies to everything above its
+ * threshold. Ordered by `aboveUsd` ascending, and the lookup takes the LAST
+ * match — so adding a deeper band for larger amounts cannot accidentally
+ * shadow a shallower one.
+ */
+export interface ConfirmationBand {
+    /** Applies to transfers worth at least this much, in USD. */
+    aboveUsd: number;
+    confirmations: number;
+}
+export interface ChainSpec {
+    key: string;
+    label: string;
+    scheme: AddressScheme;
+    /** EVM chain id. Absent for non-EVM chains, which have no such concept. */
+    chainId?: number;
+    /** The chain's own coin — the one gas is paid in. */
+    nativeAsset: string;
+    /** Seconds between blocks. Used to estimate how long a deposit will take. */
+    blockSeconds: number;
+    /**
+     * Ordered ascending by `aboveUsd`, first band starting at 0.
+     *
+     * The depth for a $20 transfer is not the depth for a $2 million one, and a
+     * single number is always wrong for one end.
+     */
+    confirmations: readonly ConfirmationBand[];
+    /** `https://bscscan.com/tx/` — the trailing slash is part of it. */
+    explorerTx: string;
+    explorerAddress: string;
+    enabled: boolean;
+}
+export interface ChainAsset {
+    chain: string;
+    asset: string;
+    /** Absent for the chain's native coin. Present for every token. */
+    contract?: string;
+    /** Minimum worth depositing. Below this, gas to sweep it exceeds its value. */
+    minDeposit: string;
+    enabled: boolean;
+}
+/**
+ * Is this a plausible address on this chain?
+ *
+ * Shape only — it cannot tell a real address from a well-formed one that
+ * nobody holds. That limit is worth stating, because the check people want is
+ * "will this arrive", and no offline check answers it. What this does prevent
+ * is a withdrawal to an address from the WRONG chain, which is the common and
+ * unrecoverable mistake: an EVM address pasted into a Bitcoin withdrawal is
+ * refused here rather than broadcast into nothing.
+ */
+export declare function validateAddress(address: string, chain: ChainSpec): void;
+export declare function assertChain(chain: ChainSpec): void;
+/**
+ * How deep to wait for a transfer of this value.
+ *
+ * Takes the LAST matching band, so bands added later for larger amounts cannot
+ * shadow the ones below them.
+ */
+export declare function confirmationsFor(chain: ChainSpec, usdValue: number): number;
+/** Roughly how long that will take. For a screen that says "about 4 minutes". */
+export declare const estimatedSeconds: (chain: ChainSpec, usdValue: number) => number;
+export declare function createChainRegistry(args: {
+    chains: readonly ChainSpec[];
+    assets: readonly ChainAsset[];
+}): {
+    all: () => ChainSpec[];
+    byKey(key: string): ChainSpec;
+    /** Every asset that can be deposited on a chain. */
+    assetsOn: (chain: string) => ChainAsset[];
+    /** Every chain an asset can arrive on. USDT exists on several. */
+    chainsFor: (asset: string) => ChainSpec[];
+    asset(chain: string, asset: string): ChainAsset;
+    explorerTx: (chain: string, hash: string) => string;
+    explorerAddress: (chain: string, address: string) => string;
+    validate(chain: string, address: string): void;
+};
+export type ChainRegistry = ReturnType<typeof createChainRegistry>;
+/**
+ * Sensible starting values, for a fresh install to edit.
+ *
+ * A SEED, not a source of truth — the registry is a store and this is what
+ * populates it the first time. The distinction matters: a constant that the
+ * code reads directly is a deploy every time a token is listed.
+ */
+export declare const SEED_CHAINS: readonly ChainSpec[];
+export declare const SEED_CHAIN_ASSETS: readonly ChainAsset[];

package/dist/finance/chain.js

@@ -0,0 +1,316 @@
+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/chain.ts
+class ChainError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ChainError";
+  }
+}
+var ADDRESS_SCHEMES = ["evm", "bitcoin", "tron", "solana"];
+var SCHEME_PATTERNS = {
+  evm: /^0x[a-fA-F0-9]{40}$/,
+  bitcoin: /^(bc1[a-z0-9]{25,62}|[13][a-km-zA-HJ-NP-Z1-9]{25,34})$/,
+  tron: /^T[a-zA-Z0-9]{33}$/,
+  solana: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/
+};
+function validateAddress(address, chain) {
+  if (!SCHEME_PATTERNS[chain.scheme].test(address.trim())) {
+    throw new ChainError("BAD_ADDRESS", `"${address.slice(0, 12)}…" is not a valid ${chain.label} address. Check you have not pasted an address for a different chain — that is the mistake that cannot be undone.`);
+  }
+}
+function assertChain(chain) {
+  if (chain.confirmations.length === 0) {
+    throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} declares no confirmation depth.`);
+  }
+  if (chain.confirmations[0].aboveUsd !== 0) {
+    throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} must have a band starting at 0, or small transfers match no rule.`);
+  }
+  let previous = -1;
+  for (const band of chain.confirmations) {
+    if (band.aboveUsd <= previous) {
+      throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} bands must ascend; ${band.aboveUsd} follows ${previous}.`);
+    }
+    if (!Number.isInteger(band.confirmations) || band.confirmations < 1) {
+      throw new ChainError("BAD_CONFIRMATIONS", `${chain.key} band above $${band.aboveUsd} needs at least one confirmation.`);
+    }
+    previous = band.aboveUsd;
+  }
+}
+function confirmationsFor(chain, usdValue) {
+  let depth = chain.confirmations[0].confirmations;
+  for (const band of chain.confirmations) {
+    if (usdValue >= band.aboveUsd)
+      depth = band.confirmations;
+  }
+  return depth;
+}
+var estimatedSeconds = (chain, usdValue) => confirmationsFor(chain, usdValue) * chain.blockSeconds;
+function createChainRegistry(args) {
+  for (const chain of args.chains)
+    assertChain(chain);
+  const chains = new Map(args.chains.map((chain) => [chain.key, chain]));
+  return {
+    all: () => [...chains.values()].filter((chain) => chain.enabled),
+    byKey(key) {
+      const chain = chains.get(key);
+      if (!chain)
+        throw new ChainError("UNKNOWN_CHAIN", `No chain "${key}" is configured.`);
+      return chain;
+    },
+    assetsOn: (chain) => args.assets.filter((asset) => asset.chain === chain && asset.enabled),
+    chainsFor: (asset) => args.assets.filter((entry) => entry.asset === asset && entry.enabled).map((entry) => chains.get(entry.chain)).filter((chain) => chain?.enabled === true),
+    asset(chain, asset) {
+      const entry = args.assets.find((row) => row.chain === chain && row.asset === asset);
+      if (!entry) {
+        throw new ChainError("UNKNOWN_ASSET", `${asset} is not configured on ${chain}.`);
+      }
+      assetSpec(asset);
+      return entry;
+    },
+    explorerTx: (chain, hash) => {
+      const spec = chains.get(chain);
+      return spec ? `${spec.explorerTx}${hash}` : hash;
+    },
+    explorerAddress: (chain, address) => {
+      const spec = chains.get(chain);
+      return spec ? `${spec.explorerAddress}${address}` : address;
+    },
+    validate(chain, address) {
+      validateAddress(address, this.byKey(chain));
+    }
+  };
+}
+var SEED_CHAINS = [
+  {
+    key: "bsc",
+    label: "BNB Smart Chain",
+    scheme: "evm",
+    chainId: 56,
+    nativeAsset: "BNB",
+    blockSeconds: 3,
+    confirmations: [
+      { aboveUsd: 0, confirmations: 15 },
+      { aboveUsd: 1e4, confirmations: 30 },
+      { aboveUsd: 1e5, confirmations: 60 }
+    ],
+    explorerTx: "https://bscscan.com/tx/",
+    explorerAddress: "https://bscscan.com/address/",
+    enabled: true
+  },
+  {
+    key: "ethereum",
+    label: "Ethereum",
+    scheme: "evm",
+    chainId: 1,
+    nativeAsset: "ETH",
+    blockSeconds: 12,
+    confirmations: [
+      { aboveUsd: 0, confirmations: 12 },
+      { aboveUsd: 50000, confirmations: 32 }
+    ],
+    explorerTx: "https://etherscan.io/tx/",
+    explorerAddress: "https://etherscan.io/address/",
+    enabled: true
+  },
+  {
+    key: "tron",
+    label: "Tron",
+    scheme: "tron",
+    nativeAsset: "TRX",
+    blockSeconds: 3,
+    confirmations: [{ aboveUsd: 0, confirmations: 20 }],
+    explorerTx: "https://tronscan.org/#/transaction/",
+    explorerAddress: "https://tronscan.org/#/address/",
+    enabled: true
+  }
+];
+var SEED_CHAIN_ASSETS = [
+  { chain: "bsc", asset: "BNB", minDeposit: "0.001", enabled: true },
+  {
+    chain: "bsc",
+    asset: "USDT",
+    contract: "0x55d398326f99059ff775485246999027b3197955",
+    minDeposit: "1",
+    enabled: true
+  },
+  { chain: "ethereum", asset: "ETH", minDeposit: "0.005", enabled: true },
+  {
+    chain: "ethereum",
+    asset: "USDT",
+    contract: "0xdac17f958d2ee523a2206206994597c13d831ec7",
+    minDeposit: "20",
+    enabled: true
+  },
+  {
+    chain: "tron",
+    asset: "USDT",
+    contract: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+    minDeposit: "1",
+    enabled: true
+  }
+];
+export {
+  validateAddress,
+  estimatedSeconds,
+  createChainRegistry,
+  confirmationsFor,
+  assertChain,
+  SEED_CHAIN_ASSETS,
+  SEED_CHAINS,
+  ChainError,
+  ADDRESS_SCHEMES
+};

package/dist/finance/commission.d.ts

@@ -0,0 +1,155 @@
+import { allocate, type Money } from './money';
+import { type Transaction, type AccountRef } from './ledger';
+/**
+ * What the platform earns, and who it is shared with.
+ *
+ * Three rules from the owner, and each is one line of arithmetic sitting on top
+ * of primitives that already exist:
+ *
+ *   COMMISSION  a share of the tenant's PROFIT for the period, at the tier rate
+ *   REFERRAL    a share of THAT — of our income, not of their profit — to
+ *               whoever introduced them
+ *   PREPAY      higher tiers pay half the projected term commission up front
+ *
+ * ## Profit, not volume
+ *
+ * The distinction is the whole basis of the charge and it is easy to get wrong
+ * under pressure: a period where a tenant traded ten million and lost money
+ * owes nothing. Commission on a losing period would be a fee dressed as a
+ * share, and the first tenant to notice would be right to leave.
+ *
+ * ## Losses carry forward
+ *
+ * A tenant who loses 50 in one week and makes 60 the next is not up 60 — they
+ * are up 10, and charging on 60 charges them for recovering their own money.
+ * The high-water mark makes that structural rather than a policy somebody has
+ * to remember.
+ */
+export declare class CommissionError extends Error {
+    readonly code: 'BAD_RATE' | 'NO_TIER' | 'ASSET_MISMATCH' | 'NEGATIVE_PERIOD';
+    constructor(code: 'BAD_RATE' | 'NO_TIER' | 'ASSET_MISMATCH' | 'NEGATIVE_PERIOD', message: string);
+}
+export interface PeriodPerformance {
+    /** Equity at the start of the period, in the account's asset. */
+    openingEquity: Money;
+    closingEquity: Money;
+    /** Deposits during the period. Not profit — the tenant's own money. */
+    deposits: Money;
+    withdrawals: Money;
+    /**
+     * The highest equity ever charged on, net of flows.
+     *
+     * Losses carry forward against this, so a recovery is not charged twice.
+     */
+    highWaterMark: Money;
+}
+/**
+ * Profit for one period, adjusted for money moving in and out.
+ *
+ *     profit = closing − opening − deposits + withdrawals
+ *
+ * Without the flow adjustment a tenant depositing a million looks like a
+ * million of profit, and the invoice that follows would be indefensible. This
+ * is the single most important line in the file.
+ */
+export declare function periodProfit(performance: PeriodPerformance): Money;
+/**
+ * The part of the profit that is actually chargeable.
+ *
+ * Zero when the account is still below its high-water mark. A tenant who lost
+ * 50 and made 60 owes on 10, not on 60 — charging on the recovery charges them
+ * for getting their own money back.
+ */
+export declare function chargeableProfit(performance: PeriodPerformance): Money;
+/** The new mark after a period. Never falls — that is what "high water" means. */
+export declare const nextHighWaterMark: (performance: PeriodPerformance) => Money;
+export interface CommissionInput {
+    profit: Money;
+    /** Platform share of profit. `'0.30'` is thirty per cent. */
+    commissionRate: string;
+    /** Referrer share of OUR income — not of the profit. */
+    referralRate?: string;
+    referrer?: string;
+}
+export interface CommissionSplit {
+    /** What the tenant owes. */
+    total: Money;
+    /** What the platform keeps after the referral share. */
+    platform: Money;
+    referral: Money;
+    referrer?: string;
+}
+/**
+ * Split a period's profit into what is owed and how it is shared.
+ *
+ * `allocate` does the division, so the parts always sum back to the total. A
+ * split that loses a unit is a transaction that cannot be posted, because the
+ * ledger refuses anything that does not balance — which is the correct place
+ * for that to fail.
+ */
+export declare function splitCommission(input: CommissionInput): CommissionSplit;
+/**
+ * The split as ledger entries.
+ *
+ * One transaction with three legs, so it balances or it does not post. A
+ * referral paid by a second transaction could succeed while the first failed,
+ * which is how a referrer gets paid on income the platform never collected.
+ */
+export declare function commissionTransaction(args: {
+    reference: string;
+    owner: string;
+    split: CommissionSplit;
+    atMs: number;
+    revenueAccount?: AccountRef;
+}): Transaction | null;
+export interface PrepayInput {
+    /** What the tenant is subscribing with. */
+    subscriptionAmount: Money;
+    /** Expected return over the term, as a rate. `'0.20'` is twenty per cent. */
+    projectedReturnRate: string;
+    commissionRate: string;
+    /** Fraction of the projected commission payable now. The owner's rule is a half. */
+    prepayRate: string;
+}
+export interface Prepay {
+    /** What the term is projected to yield the tenant. */
+    projectedProfit: Money;
+    /** Commission on that, if the projection holds. */
+    projectedCommission: Money;
+    /** Payable up front. */
+    due: Money;
+}
+/**
+ * What a higher tier pays before the term starts.
+ *
+ * Every input is a rate the operator sets, including the projection — this is
+ * arithmetic on stated assumptions, not a forecast. Naming it `projected`
+ * everywhere is deliberate: a figure derived from an assumed return should
+ * never read on a screen as an amount somebody has earned.
+ *
+ * The prepay is a CREDIT against real commission, not an extra charge. That
+ * belongs to whoever settles the invoice, and the shape here makes it easy to
+ * do: `due` is in the same asset as the commission it offsets.
+ */
+export declare function projectPrepay(input: PrepayInput): Prepay;
+export interface ReferralShare {
+    referrer: string;
+    rate: string;
+}
+/**
+ * Split one income figure across several referrers.
+ *
+ * Multi-level is not currently used and the shape supports it anyway, because
+ * retrofitting a second level means changing how every historical commission
+ * was computed. `allocate` guarantees the parts sum to the whole, so the
+ * platform's remainder absorbs any rounding rather than a unit vanishing.
+ */
+export declare function splitReferrals(income: Money, shares: readonly ReferralShare[]): {
+    platform: Money;
+    paid: {
+        referrer: string;
+        amount: Money;
+    }[];
+};
+/** Even split of a remainder, losing nothing. Re-exported so callers need one import. */
+export { allocate };