@forgezero/runtime 0.1.0

package/dist/finance/chain-reconcile.js

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

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