@forgezero/runtime 0.1.0

package/dist/finance/chain-deposits.js

@@ -0,0 +1,596 @@
+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/ledger.ts
+class LedgerError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "LedgerError";
+  }
+}
+var BUCKETS = ["available", "held"];
+var ACCOUNT_KINDS = ["user", "platform", "external"];
+var accountId = (account) => `${account.kind}:${account.owner}:${account.bucket ?? "available"}`;
+function parseAccount(id) {
+  const [kind, owner, bucket] = id.split(":");
+  return { kind, owner, bucket };
+}
+var queueKeyFor = (account) => `${account.kind}:${account.owner}`;
+function assertBalanced(transaction) {
+  if (transaction.entries.length === 0) {
+    throw new LedgerError("EMPTY_TRANSACTION", "A transaction needs at least two entries.");
+  }
+  const totals = new Map;
+  for (const entry of transaction.entries) {
+    if (entry.amount.units === 0n) {
+      throw new LedgerError("ZERO_ENTRY", `An entry on ${accountId(entry.account)} moves nothing. Remove it or give it an amount.`);
+    }
+    totals.set(entry.amount.asset, (totals.get(entry.amount.asset) ?? 0n) + entry.amount.units);
+  }
+  for (const [asset, total] of totals) {
+    if (total !== 0n) {
+      throw new LedgerError("UNBALANCED", `${asset} does not sum to zero — it is off by ${total} minor units. Every movement needs a counterparty.`);
+    }
+  }
+}
+function transfer(args) {
+  const transaction = {
+    reference: args.reference,
+    kind: args.kind,
+    atMs: args.atMs,
+    memo: args.memo,
+    entries: [
+      { account: args.from, amount: { units: -args.amount.units, asset: args.amount.asset } },
+      { account: args.to, amount: args.amount }
+    ]
+  };
+  assertBalanced(transaction);
+  return transaction;
+}
+var placeHold = (args) => transfer({
+  reference: args.reference,
+  kind: "hold.place",
+  from: { kind: args.kind ?? "user", owner: args.owner, bucket: "available" },
+  to: { kind: args.kind ?? "user", owner: args.owner, bucket: "held" },
+  amount: args.amount,
+  atMs: args.atMs,
+  memo: args.memo
+});
+var releaseHold = (args) => transfer({
+  reference: args.reference,
+  kind: "hold.release",
+  from: { kind: args.kind ?? "user", owner: args.owner, bucket: "held" },
+  to: { kind: args.kind ?? "user", owner: args.owner, bucket: "available" },
+  amount: args.amount,
+  atMs: args.atMs
+});
+var captureHold = (args) => transfer({
+  reference: args.reference,
+  kind: "hold.capture",
+  from: { kind: args.kind ?? "user", owner: args.owner, bucket: "held" },
+  to: args.to,
+  amount: args.amount,
+  atMs: args.atMs,
+  memo: args.memo
+});
+function balancesFrom(transactions) {
+  const balances = new Map;
+  for (const transaction of transactions) {
+    for (const entry of transaction.entries) {
+      const id = accountId(entry.account);
+      const perAsset = balances.get(id) ?? new Map;
+      const current = perAsset.get(entry.amount.asset) ?? zero(entry.amount.asset);
+      perAsset.set(entry.amount.asset, add(current, entry.amount));
+      balances.set(id, perAsset);
+    }
+  }
+  return balances;
+}
+function balanceOf(balances, account, asset) {
+  return balances.get(accountId(account))?.get(asset) ?? zero(asset);
+}
+var availableOf = (balances, owner, asset, kind = "user") => balanceOf(balances, { kind, owner, bucket: "available" }, asset);
+var heldOf = (balances, owner, asset, kind = "user") => balanceOf(balances, { kind, owner, bucket: "held" }, asset);
+var totalOf = (balances, owner, asset, kind = "user") => add(availableOf(balances, owner, asset, kind), heldOf(balances, owner, asset, kind));
+function trialBalance(transactions) {
+  const totals = new Map;
+  const accounts = new Map;
+  for (const transaction of transactions) {
+    for (const entry of transaction.entries) {
+      totals.set(entry.amount.asset, (totals.get(entry.amount.asset) ?? 0n) + entry.amount.units);
+      const seen = accounts.get(entry.amount.asset) ?? new Set;
+      seen.add(accountId(entry.account));
+      accounts.set(entry.amount.asset, seen);
+    }
+  }
+  const perAsset = [...totals.entries()].map(([asset, total]) => ({
+    asset,
+    total,
+    accounts: accounts.get(asset)?.size ?? 0
+  }));
+  const discrepancies = perAsset.filter((row) => row.total !== 0n).map((row) => ({ asset: row.asset, off: row.total }));
+  return { ok: discrepancies.length === 0, perAsset, discrepancies };
+}
+function statement(transactions, account, asset) {
+  const id = accountId(account);
+  let running = zero(asset);
+  return [...transactions].sort((a, b) => a.atMs - b.atMs).flatMap((transaction) => transaction.entries.filter((entry) => accountId(entry.account) === id && entry.amount.asset === asset).map((entry) => {
+    running = add(running, entry.amount);
+    return {
+      atMs: transaction.atMs,
+      reference: transaction.reference,
+      kind: transaction.kind,
+      amount: formatAmount(entry.amount, { trim: true }),
+      balance: formatAmount(running, { trim: true })
+    };
+  }));
+}
+function assertAvailable(balances, args) {
+  const available = availableOf(balances, args.owner, args.amount.asset, args.kind ?? "user");
+  if (subtract(available, args.amount).units < 0n) {
+    throw new LedgerError("INSUFFICIENT_AVAILABLE", `${args.owner} has ${formatAmount(available, { trim: true })} ${args.amount.asset} available; this needs ${formatAmount(args.amount, { trim: true })}.`);
+  }
+}
+var VERSION2 = "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
+  }
+];
+
+// src/finance/chain-deposits.ts
+class DepositError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DepositError";
+  }
+}
+var depositReference = (args) => `deposit:${args.chain}:${args.txHash.toLowerCase()}:${args.logIndex}`;
+function isConfirmed(args) {
+  const depth = args.head - args.transfer.blockNumber + 1;
+  return depth >= confirmationsFor(args.chain, args.usdValue);
+}
+function creditDeposit(args) {
+  const external = { kind: "external", owner: args.chain, bucket: "available" };
+  const user = { kind: "user", owner: args.owner, bucket: "available" };
+  return transfer({
+    reference: depositReference({
+      chain: args.chain,
+      txHash: args.transfer.txHash,
+      logIndex: args.transfer.logIndex
+    }),
+    kind: "deposit",
+    from: external,
+    to: user,
+    amount: args.amount,
+    atMs: args.atMs,
+    memo: `${args.chain} ${args.transfer.txHash}`
+  });
+}
+var DEFAULT_BATCH = 2000;
+async function scanOnce(cursor, context) {
+  if (cursor.chain !== context.chain.key) {
+    throw new DepositError("BAD_CURSOR", `That cursor is for ${cursor.chain}, not ${context.chain.key}.`);
+  }
+  const head = await context.reader.head();
+  const fromBlock = cursor.scannedTo + 1;
+  const batch = Math.max(1, context.batchSize ?? DEFAULT_BATCH);
+  const toBlock = Math.min(head, cursor.scannedTo + batch);
+  if (toBlock < fromBlock) {
+    return {
+      chain: context.chain.key,
+      fromBlock,
+      toBlock: cursor.scannedTo,
+      head,
+      matched: 0,
+      credited: 0,
+      pending: 0,
+      duplicates: 0,
+      dust: 0,
+      transactions: [],
+      cursor
+    };
+  }
+  const found = await context.reader.transfersIn({ fromBlock, toBlock });
+  const outcome = await classify(found, context, head);
+  const shallowest = outcome.pendingBlocks.length > 0 ? Math.min(...outcome.pendingBlocks) : null;
+  const scannedTo = shallowest === null ? toBlock : shallowest - 1;
+  return {
+    chain: context.chain.key,
+    fromBlock,
+    toBlock,
+    head,
+    matched: outcome.matched,
+    credited: outcome.transactions.length,
+    pending: outcome.pendingBlocks.length,
+    duplicates: outcome.duplicates,
+    dust: outcome.dust,
+    transactions: outcome.transactions,
+    cursor: { chain: cursor.chain, scannedTo: Math.max(cursor.scannedTo, scannedTo) }
+  };
+}
+async function rescanRange(range, context) {
+  if (range.toBlock < range.fromBlock) {
+    throw new DepositError("BAD_RANGE", "A rescan range ends before it starts.");
+  }
+  const head = await context.reader.head();
+  const found = await context.reader.transfersIn(range);
+  const outcome = await classify(found, context, head);
+  return {
+    chain: context.chain.key,
+    fromBlock: range.fromBlock,
+    toBlock: range.toBlock,
+    head,
+    matched: outcome.matched,
+    credited: outcome.transactions.length,
+    pending: outcome.pendingBlocks.length,
+    duplicates: outcome.duplicates,
+    dust: outcome.dust,
+    transactions: outcome.transactions,
+    cursor: { chain: context.chain.key, scannedTo: range.toBlock }
+  };
+}
+async function classify(found, context, head) {
+  const transactions = [];
+  const pendingBlocks = [];
+  let matched = 0;
+  let duplicates = 0;
+  let dust = 0;
+  for (const item of found) {
+    const owner = context.addresses.get(item.to.trim().toLowerCase());
+    if (!owner)
+      continue;
+    matched += 1;
+    let amount;
+    try {
+      amount = money(BigInt(item.units), item.asset);
+    } catch {
+      throw new DepositError("UNKNOWN_ASSET", `${item.asset} arrived at a watched address on ${context.chain.key} and is not a known asset. ` + "Crediting it would invent a balance; ignoring it silently would lose a real deposit.");
+    }
+    const usdValue = context.usdValueOf(amount);
+    if (context.minDepositUsd !== undefined && usdValue < context.minDepositUsd) {
+      dust += 1;
+      continue;
+    }
+    if (!isConfirmed({ chain: context.chain, transfer: item, head, usdValue })) {
+      pendingBlocks.push(item.blockNumber);
+      continue;
+    }
+    const reference = depositReference({
+      chain: context.chain.key,
+      txHash: item.txHash,
+      logIndex: item.logIndex
+    });
+    if (await context.seen(reference)) {
+      duplicates += 1;
+      continue;
+    }
+    transactions.push(creditDeposit({
+      chain: context.chain.key,
+      transfer: item,
+      owner,
+      amount,
+      atMs: context.atMs
+    }));
+  }
+  return { transactions, pendingBlocks, matched, duplicates, dust };
+}
+var cursorFrom = (chain, block) => {
+  if (!Number.isInteger(block) || block < 0) {
+    throw new DepositError("BAD_CURSOR", "A cursor starts at a whole, non-negative block.");
+  }
+  return { chain, scannedTo: block };
+};
+var describeScan = (report) => `${report.chain} ${report.fromBlock}–${report.toBlock} of ${report.head}: ` + `${report.credited} credited, ${report.pending} pending, ${report.duplicates} already seen, ${report.dust} dust`;
+export {
+  scanOnce,
+  rescanRange,
+  isConfirmed,
+  describeScan,
+  depositReference,
+  cursorFrom,
+  creditDeposit,
+  DepositError
+};

package/dist/finance/chain-reconcile.d.ts

@@ -0,0 +1,112 @@
+import { type Money } from './money';
+/**
+ * Comparing what the chain holds against what the ledger says it owes.
+ *
+ * Every other guard in this package is preventive: the confirmation depth, the
+ * idempotency key, the hold placed with acceptance. This is the one that tells
+ * you a preventive guard FAILED — and it is the difference between finding a
+ * shortfall in a scheduled report and finding it in a withdrawal queue, where
+ * the person who finds it is a customer.
+ *
+ * ## Why a surplus is a finding too
+ *
+ * The instinct is to alert on "less on chain than we owe" and treat the other
+ * direction as a happy accident. It is not. A surplus means money arrived that
+ * nothing credited — a deposit the scanner missed, an asset nobody configured,
+ * a transfer to an address the book no longer derives. Somebody is owed that
+ * money and does not know it, and the longer it sits the harder it is to
+ * attribute. Both directions are reported, with the reason each matters.
+ *
+ * ## Why this holds no I/O
+ *
+ * `@forgezero/runtime` has no credentials and no network. Both sides are passed
+ * in, so the same comparison runs against a live node, a snapshot taken during
+ * an incident, or a fixture — and the tests exercise real discrepancies rather
+ * than a mock of a reconciler.
+ */
+export declare class ReconcileError extends Error {
+    readonly code: 'ASSET_MISMATCH' | 'MALFORMED';
+    constructor(code: 'ASSET_MISMATCH' | 'MALFORMED', message: string);
+}
+/** What the chain actually holds, per asset, across every address in custody. */
+export interface OnChainHolding {
+    chain: string;
+    asset: string;
+    /** Deposit addresses plus the hot wallet plus cold storage — everything. */
+    units: bigint;
+}
+/** What the ledger says is owed, per asset. */
+export interface LedgerLiability {
+    chain: string;
+    asset: string;
+    /**
+     * Every user balance in this asset, available and held together.
+     *
+     * Held is INCLUDED. A withdrawal awaiting approval is money the platform
+     * still owes somebody; excluding it would make the platform look solvent
+     * exactly while a payout queue is building up against it.
+     */
+    units: bigint;
+    /** Dispatched and not yet confirmed — in flight, and no longer on chain. */
+    inFlightUnits?: bigint;
+}
+export declare const DISCREPANCY_KINDS: readonly ["shortfall", "surplus"];
+export type DiscrepancyKind = (typeof DISCREPANCY_KINDS)[number];
+export interface Discrepancy {
+    chain: string;
+    asset: string;
+    kind: DiscrepancyKind;
+    /** Always positive — `kind` carries the direction. */
+    difference: Money;
+    onChain: Money;
+    owed: Money;
+    /** What this means, in the terms an operator has to act on. */
+    meaning: string;
+}
+export interface ReconcileReport {
+    atMs: number;
+    /** Every (chain, asset) pair compared, whether or not it differed. */
+    checked: number;
+    discrepancies: readonly Discrepancy[];
+    /** True when nothing differed. The only result that needs no action. */
+    balanced: boolean;
+}
+/**
+ * Compare one snapshot of both sides.
+ *
+ * A pair present on one side and absent from the other is treated as zero on
+ * the missing side rather than skipped. Skipping is how the most serious case
+ * hides: an asset that exists on chain and is entirely unknown to the ledger
+ * has no ledger row to iterate over, so a loop driven by ledger rows never
+ * looks at it.
+ */
+export declare function reconcileOnce(args: {
+    onChain: readonly OnChainHolding[];
+    owed: readonly LedgerLiability[];
+    /**
+     * How much difference is not worth reporting, per asset in smallest units.
+     *
+     * Not a way to hide a shortfall — a tolerance covers rounding on chains that
+     * charge fees in the transferred asset, and nothing larger. It is per asset
+     * because "a thousand units" is dust in one and a fortune in another.
+     */
+    tolerance?: Record<string, bigint>;
+    atMs: number;
+}): ReconcileReport;
+/**
+ * The report, as an operator reads it.
+ *
+ * Shortfalls first and named individually. A summary that leads with "3
+ * discrepancies" buries the one that matters underneath two that do not, and
+ * this text exists to be the first line of an alert.
+ */
+export declare function reconcileReport(report: ReconcileReport): string;
+/**
+ * The one number an operator watches.
+ *
+ * Total shortfall across every pair, in USD, using a rate function the caller
+ * supplies. Per-asset figures are what you act on; this is what tells you
+ * whether to act now — and summing units across assets without converting
+ * would add satoshis to cents and produce a number that means nothing.
+ */
+export declare function shortfallUsd(report: ReconcileReport, usdValueOf: (amount: Money) => number): number;