@gibs/bridge-sdk 1.12.0 → 1.13.0

package/dist/routing/search/compose.js

@@ -0,0 +1,98 @@
+import { assetNodeKey, combineComposedPathBasis } from './graph.js';
+/** The {@link ComposedPathBasis} one hop's figure contributes: `'quoted'` for a bound quote, its own basis for a `'probeRate'`. */
+export const composableHopBasis = (figure) => figure.kind === 'quote' ? 'quoted' : figure.basis;
+/**
+ * Applies one {@link ExchangeRate} to an actual input amount, as an exact
+ * bigint multiply-then-divide (floor division — the same rounding direction
+ * a real on-chain quote would apply against the reader). Never routes the
+ * amount through a float.
+ *
+ * @param inputAmount - the actual base-unit amount arriving at the hop
+ * @param rate - the hop's observed {@link ExchangeRate}
+ * @returns the estimated base-unit output
+ */
+const applyExchangeRate = (inputAmount, rate) => (inputAmount * rate.numerator) / rate.denominator;
+/**
+ * Composes a path's per-hop figures into one end-to-end estimated delivered
+ * amount, applying design section 3's rule: a later hop's output is its
+ * probe rate applied to the ACTUAL amount arriving at that hop — never the
+ * reference amount the probe itself was taken at.
+ *
+ * REFUSES RATHER THAN GUESSES in three cases, checked hop by hop so the
+ * refusal names the exact hop responsible: the path is empty
+ * ({@link ComposeRefusalReason} `'empty-path'`); a hop does not connect to the
+ * one before it (`'discontinuous-path'`); two hops disagree about a shared
+ * asset's decimals (`'decimals-mismatch'`); or a `'probeRate'` figure names
+ * no real ratio (`'missing-rate'`). See {@link ComposeRefusalReason} for why
+ * each of these is a refusal and not a best-effort answer.
+ *
+ * @param inputAmount - the base-unit amount entering the path's first hop
+ * @param hops - the path's hops, first to last
+ * @returns the composed estimate, or the refusal that stopped composition
+ */
+export const composeRouteDelivery = (inputAmount, hops) => {
+    if (hops.length === 0) {
+        return { kind: 'refused', reason: 'empty-path', hopIndex: 0 };
+    }
+    let actualInput = inputAmount;
+    let basis = 'quoted';
+    for (let hopIndex = 0; hopIndex < hops.length; hopIndex += 1) {
+        const hop = hops[hopIndex];
+        const continuityFailure = checkContinuity(hops, hopIndex);
+        if (continuityFailure !== null) {
+            return { kind: 'refused', reason: continuityFailure, hopIndex };
+        }
+        const outputAmount = hopOutputAmount(hop, actualInput);
+        if (outputAmount === null) {
+            return { kind: 'refused', reason: 'missing-rate', hopIndex };
+        }
+        basis = combineComposedPathBasis(basis, composableHopBasis(hop.figure));
+        actualInput = outputAmount;
+    }
+    return { kind: 'estimate', deliveredAmount: actualInput, basis };
+};
+/**
+ * Checks that hop `hopIndex` connects to the hop before it: the same asset,
+ * by {@link assetNodeKey}, with the same declared decimals. The first hop has
+ * nothing before it and always passes.
+ *
+ * @param hops - the full path being composed
+ * @param hopIndex - the hop to check against its predecessor
+ * @returns the refusal reason, or null when the hop connects cleanly
+ */
+const checkContinuity = (hops, hopIndex) => {
+    if (hopIndex === 0)
+        return null;
+    const previousTo = hops[hopIndex - 1].edge.to;
+    const currentFrom = hops[hopIndex].edge.from;
+    if (assetNodeKey(previousTo) !== assetNodeKey(currentFrom))
+        return 'discontinuous-path';
+    if (previousTo.decimals !== currentFrom.decimals)
+        return 'decimals-mismatch';
+    return null;
+};
+/**
+ * One hop's output amount for the actual amount arriving at it: the quote's
+ * own `outputAmount` when the figure is a real quote, or the probe rate
+ * applied to `actualInput` when it is a `'probeRate'`. Returns null — never a
+ * guessed number — when a `'probeRate'` figure's rate names no positive
+ * denominator.
+ *
+ * EXPORTED SO `waves.ts` REUSES THIS MATH RATHER THAN RESTATING IT.
+ * `recomposePath` (`waves.ts`) needs each hop's OWN output amount, not just
+ * the path's final total {@link composeRouteDelivery} returns, to refresh
+ * every hop's individual `outcome` — this is the one place that division
+ * happens, so both call sites agree by construction instead of by two
+ * separately-maintained copies of `numerator * input / denominator`.
+ *
+ * @param hop - the hop to price
+ * @param actualInput - the actual base-unit amount arriving at this hop
+ * @returns the hop's output amount, or null when its rate is missing
+ */
+export const hopOutputAmount = (hop, actualInput) => {
+    if (hop.figure.kind === 'quote')
+        return hop.figure.outputAmount;
+    if (hop.figure.rate.denominator <= 0n)
+        return null;
+    return applyExchangeRate(actualInput, hop.figure.rate);
+};