@forgezero/runtime 0.1.14 → 0.1.15

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

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

package/dist/finance/chain-reconcile.js

@@ -1,76 +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/chain-reconcile.ts
-class ReconcileError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "ReconcileError";
-  }
-}
-var DISCREPANCY_KINDS = ["shortfall", "surplus"];
-var key = (item) => `${item.chain}:${item.asset}`;
-function reconcileOnce(args) {
-  const chainSide = new Map(args.onChain.map((item) => [key(item), item]));
-  const ledgerSide = new Map(args.owed.map((item) => [key(item), item]));
-  const pairs = [...new Set([...chainSide.keys(), ...ledgerSide.keys()])].sort();
-  const discrepancies = [];
-  for (const pair of pairs) {
-    const held = chainSide.get(pair);
-    const liability = ledgerSide.get(pair);
-    const [chain, asset] = pair.split(":");
-    const onChainUnits = held?.units ?? 0n;
-    const owedUnits = (liability?.units ?? 0n) + (liability?.inFlightUnits ?? 0n);
-    const difference = onChainUnits - owedUnits;
-    const allowed = args.tolerance?.[asset] ?? 0n;
-    if (difference >= -allowed && difference <= allowed)
-      continue;
-    const kind = difference < 0n ? "shortfall" : "surplus";
-    discrepancies.push({
-      chain,
-      asset,
-      kind,
-      difference: { units: difference < 0n ? -difference : difference, asset },
-      onChain: { units: onChainUnits, asset },
-      owed: { units: owedUnits, asset },
-      meaning: kind === "shortfall" ? "The chain holds less than is owed. Withdrawals will fail once the balance is drawn down — " + "this is the state that becomes a customer-facing incident." : "Money arrived that nothing credited. Somebody is owed it and does not know, and attribution " + "gets harder the longer it sits."
-    });
-  }
-  return {
-    atMs: args.atMs,
-    checked: pairs.length,
-    discrepancies,
-    balanced: discrepancies.length === 0
-  };
-}
-function reconcileReport(report) {
-  if (report.balanced) {
-    return `Reconciled: ${report.checked} chain/asset pair(s) agree.`;
-  }
-  const shortfalls = report.discrepancies.filter((item) => item.kind === "shortfall");
-  const surpluses = report.discrepancies.filter((item) => item.kind === "surplus");
-  const line = (item) => `  ${item.kind === "shortfall" ? "SHORT" : "over "} ${item.chain}/${item.asset}: ` + `${item.difference.units} units (chain ${item.onChain.units}, owed ${item.owed.units})`;
-  return [
-    shortfalls.length > 0 ? `SHORTFALL on ${shortfalls.length} pair(s) — withdrawals will fail once drawn down.` : `No shortfall. ${surpluses.length} pair(s) hold more than is owed.`,
-    ...shortfalls.map(line),
-    ...surpluses.map(line)
-  ].join(`
-`);
-}
-function shortfallUsd(report, usdValueOf) {
-  return report.discrepancies.filter((item) => item.kind === "shortfall").reduce((total, item) => total + usdValueOf(item.difference), 0);
-}
-export {
-  shortfallUsd,
-  reconcileReport,
-  reconcileOnce,
-  ReconcileError,
-  DISCREPANCY_KINDS
-};

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

@@ -1,223 +0,0 @@
-import { type Transaction } from './ledger';
-import { type Money } from './money';
-import { type ChainSpec } from './chain';
-/**
- * Getting money out, which is the most dangerous path in the product.
- *
- * Everything else here can be wrong and cost a correction. This one can be
- * wrong and cost the money. Four things go wrong in practice and all four are
- * arranged against explicitly:
- *
- *   THE HOLD      placed as part of accepting the request, never after. A gap
- *                 between "accepted" and "held" is a window in which the same
- *                 balance funds two withdrawals.
- *   THE BROADCAST keyed, so a retry after a timeout cannot send twice. A
- *                 dispatcher that cannot tell "did not send" from "sent, reply
- *                 lost" will eventually send twice.
- *   THE REFUND    a transaction that fails AFTER the balance was debited leaves
- *                 the user short. The prior art reconciled failed and rejected
- *                 refunds in two separate passes, because both were found
- *                 missing in production — separately.
- *   THE SWEEP     on demand to fund a payout, never on a timer. A timer burns
- *                 gas continuously moving dust nobody asked to move.
- *
- * ## A hold is not a lock
- *
- * It is a posting between the owner's `available` and `held` sub-accounts. So
- * `availableOf()` is an ordinary balance query, there is no reservation table,
- * no expiry sweeper, and a process that dies mid-withdrawal strands nothing —
- * the posting either happened or it did not.
- */
-export declare class WithdrawalError extends Error {
-    readonly code: 'BAD_STATE' | 'BAD_ADDRESS' | 'BAD_AMOUNT' | 'INSUFFICIENT' | 'CHAIN_DISABLED' | 'MALFORMED';
-    constructor(code: 'BAD_STATE' | 'BAD_ADDRESS' | 'BAD_AMOUNT' | 'INSUFFICIENT' | 'CHAIN_DISABLED' | 'MALFORMED', message: string);
-}
-/**
- * Every state a withdrawal can be in, and there are no others.
- *
- * Written down as a list because the transitions are checked against it. An
- * undeclared state reachable by assignment is how a withdrawal ends up
- * `approved` twice, or dispatched from a state that never held the funds.
- */
-export declare const WITHDRAWAL_STATES: readonly ["requested", "approved", "dispatched", "confirmed", "rejected", "failed", "refunded"];
-export type WithdrawalState = (typeof WITHDRAWAL_STATES)[number];
-export interface Withdrawal {
-    key: string;
-    owner: string;
-    chain: string;
-    /** Where the money is going. Validated against the chain's scheme. */
-    destination: string;
-    amount: Money;
-    state: WithdrawalState;
-    requestedAtMs: number;
-    /** The broadcast idempotency key. Present from `approved` onward. */
-    broadcastKey?: string;
-    txHash?: string;
-    decidedByUserKey?: string;
-    reason?: string;
-}
-/** May this withdrawal move there? */
-export declare const canTransition: (from: WithdrawalState, to: WithdrawalState) => boolean;
-/** The reference for the hold, and therefore the queue's dedupe key. */
-export declare const holdReference: (key: string) => string;
-/**
- * The key a broadcast is made under.
- *
- * Derived from the withdrawal, so the same withdrawal produces the same key on
- * every attempt. A dispatcher that timed out and retries presents this again;
- * anything downstream that has seen it already knows this is the same send
- * rather than a second one. Deriving it rather than generating it is the whole
- * point — a generated key is a new key on every retry, which is exactly the
- * failure it was meant to prevent.
- */
-export declare const broadcastKeyFor: (withdrawal: Pick<Withdrawal, "key" | "chain">) => string;
-/**
- * Accept a request, and hold the funds in the same breath.
- *
- * Returns the withdrawal AND the posting together, so a caller cannot persist
- * one without the other. Two functions — "create the request" then "place the
- * hold" — would leave a window in which the balance is still available and a
- * second request can spend it. They are one operation because they must not be
- * separable.
- */
-export declare function requestWithdrawal(args: {
-    key: string;
-    owner: string;
-    chain: ChainSpec;
-    destination: string;
-    amount: Money;
-    /** From `availableOf()` — what the owner can actually spend right now. */
-    available: Money;
-    atMs: number;
-}): {
-    withdrawal: Withdrawal;
-    hold: Transaction;
-};
-/**
- * A human says yes.
- *
- * No posting: the funds were held at request time and stay held. Approval mints
- * the broadcast key, which is the moment the send acquires an identity — before
- * this there is nothing to be idempotent about.
- */
-export declare function approveWithdrawal(withdrawal: Withdrawal, args: {
-    actorUserKey: string;
-    atMs: number;
-}): Withdrawal;
-/**
- * A human says no, and the hold comes back.
- *
- * Reachable from `approved` as well as `requested`: a withdrawal approved and
- * not yet broadcast can still be stopped, and that is exactly when somebody
- * notices something is wrong.
- */
-export declare function rejectWithdrawal(withdrawal: Withdrawal, args: {
-    actorUserKey: string;
-    reason: string;
-    atMs: number;
-}): {
-    withdrawal: Withdrawal;
-    release: Transaction;
-};
-/** What a broadcaster must provide. Injected — runtime holds no credentials. */
-export interface Broadcaster {
-    /**
-     * Send, or report that this key was already sent.
-     *
-     * The KEY is the argument that matters. An implementation that ignores it
-     * and sends anyway defeats the only protection against a double payout, so
-     * it is passed first and named for what it does.
-     */
-    send(args: {
-        broadcastKey: string;
-        chain: string;
-        destination: string;
-        amount: Money;
-    }): Promise<{
-        txHash: string;
-        alreadySent: boolean;
-    }>;
-}
-/**
- * Broadcast one approved withdrawal.
- *
- * `alreadySent` is treated as success, not as an error. A dispatcher that timed
- * out and retried is the ordinary case, and treating the second attempt as a
- * failure would move a withdrawal that IS on-chain into `failed` and then
- * refund it — paying the same money twice, which is the exact outcome the key
- * exists to prevent.
- */
-export declare function processOnce(withdrawal: Withdrawal, args: {
-    broadcaster: Broadcaster;
-    atMs: number;
-}): Promise<Withdrawal>;
-/**
- * Seen on-chain, deep enough. The hold becomes a real debit.
- *
- * `captureHold` is what actually removes the money: until now it was held, not
- * spent, and a withdrawal abandoned before this point costs the owner nothing.
- */
-export declare function confirmWithdrawal(withdrawal: Withdrawal, args: {
-    txHash: string;
-    atMs: number;
-}): {
-    withdrawal: Withdrawal;
-    capture: Transaction;
-};
-/** Broadcast and failed on-chain. Marked, not yet made good. */
-export declare function markFailed(withdrawal: Withdrawal, args: {
-    reason: string;
-    atMs: number;
-}): Withdrawal;
-/**
- * Make a failed withdrawal good.
- *
- * A separate pass from rejection on purpose. They look like one problem — money
- * to return — and they are two: a rejection never left the platform, whereas a
- * failure was broadcast and did not land. The prior art ran them as one and
- * found BOTH refund paths missing in production, separately, which is the
- * strongest argument available for keeping them apart.
- */
-export declare function refundFailed(withdrawal: Withdrawal, args: {
-    atMs: number;
-}): {
-    withdrawal: Withdrawal;
-    release: Transaction;
-};
-/** A deposit address holding funds that have not been moved to the hot wallet. */
-export interface SweepCandidate {
-    address: string;
-    owner: string;
-    amount: Money;
-    /** What it costs to move it, in the same asset terms as `amount`. */
-    estimatedGas: Money;
-}
-export interface SweepPlan {
-    /** Addresses worth sweeping, largest first. */
-    sweep: readonly SweepCandidate[];
-    /** Skipped because moving them costs more than they hold. */
-    uneconomic: readonly SweepCandidate[];
-    /** What the plan raises, net of gas. */
-    raised: Money;
-    /** True when the plan cannot fund the payout even after sweeping everything. */
-    short: boolean;
-}
-/**
- * Which deposit addresses to sweep to fund one payout.
- *
- * ON DEMAND, never on a timer. A timer sweeps continuously and burns gas moving
- * dust nobody asked to move; funding a specific payout sweeps the least it can
- * and stops. That is why this takes a target rather than a schedule.
- *
- * Largest first, so the fewest transactions raise the amount — each sweep is
- * its own gas cost, and twenty small ones cost more than two large ones raising
- * the same total.
- */
-export declare function sweepForPayout(args: {
-    need: Money;
-    /** Already in the hot wallet and spendable without sweeping anything. */
-    hot: Money;
-    candidates: readonly SweepCandidate[];
-}): SweepPlan;
-/** Human-readable, for an operator screen. */
-export declare const describeSweep: (plan: SweepPlan) => string;