@the-situation/collateral 0.5.0-alpha.0

package/dist/compute.js

@@ -0,0 +1,786 @@
+/**
+ * Off-chain collateral computation for trading between normal distributions.
+ *
+ * Computes the collateral requirement for transitioning from distribution f to g:
+ *   C = max(0, sup_x[f(x) - g(x)]) = max(0, -inf_x[g(x) - f(x)])
+ *
+ * Uses Newton-Raphson minimization to find x* where d(x) = g(x) - f(x) achieves
+ * its infimum. The smart contracts verify but don't compute - this computation
+ * must be done locally.
+ *
+ * @module
+ */
+import { HALF, ONE, SQ128x128, ZERO } from '@the-situation/core';
+// ============================================================================
+// AMM Scaling Constants
+// ============================================================================
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export const SQRT_PI = Math.sqrt(Math.PI);
+/**
+ * Computes the L2 norm of a normal distribution's PDF.
+ *
+ * For a normal PDF with standard deviation σ:
+ *   ||p||_2 = 1 / sqrt(2 * σ * sqrt(π))
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The L2 norm
+ */
+export function computeL2NormNumber(sigma) {
+    if (sigma <= 0) {
+        return 0;
+    }
+    // ||p||_2 = 1 / sqrt(2 * sigma * sqrt(pi))
+    const denomSq = 2 * sigma * SQRT_PI;
+    return 1 / Math.sqrt(denomSq);
+}
+/**
+ * Computes the lambda scaling factor for a distribution.
+ *
+ * lambda = k / ||p||_2 = k * sqrt(2 * σ * sqrt(π))
+ *
+ * @param sigma - The distribution's standard deviation (as number)
+ * @param k - The AMM invariant parameter (as number)
+ * @returns The lambda scaling factor
+ */
+export function computeLambdaNumber(sigma, k) {
+    const l2Norm = computeL2NormNumber(sigma);
+    if (l2Norm <= 0) {
+        return 0;
+    }
+    return k / l2Norm;
+}
+/**
+ * Computes the L2 norm of a normal distribution's PDF.
+ *
+ * For a normal PDF with standard deviation σ:
+ *   ||p||_2 = 1 / sqrt(2 * σ * sqrt(π))
+ *
+ * @param sigma - The standard deviation
+ * @returns The L2 norm, or null if computation fails
+ */
+export function computeL2Norm(sigma) {
+    if (sigma.isZero()) {
+        return null;
+    }
+    const sigmaNum = sigma.toNumber();
+    const l2NormNum = computeL2NormNumber(sigmaNum);
+    return SQ128x128.fromNumber(l2NormNum);
+}
+/**
+ * Computes the lambda scaling factor for a distribution.
+ *
+ * lambda = k / ||p||_2 = k * sqrt(2 * σ * sqrt(π))
+ *
+ * This is the multiplier applied to the base PDF to create a scaled position
+ * that satisfies the AMM invariant ||f||_2 = k.
+ *
+ * @param sigma - The distribution's standard deviation
+ * @param k - The AMM invariant parameter
+ * @returns The lambda scaling factor, or null if computation fails
+ */
+export function computeLambda(sigma, k) {
+    const l2Norm = computeL2Norm(sigma);
+    if (!l2Norm || l2Norm.isZero()) {
+        return null;
+    }
+    return k.div(l2Norm);
+}
+/**
+ * Returns the default minimization policy.
+ */
+export function defaultPolicy() {
+    const four = SQ128x128.fromNumber(4);
+    const maxMean = SQ128x128.fromNumber(1048576); // 2^20
+    return {
+        maxSigmaRatio: four,
+        maxMeanSepSigmas: four,
+        maxAbsoluteMean: maxMean,
+    };
+}
+/**
+ * Returns a relaxed minimization policy for close position scenarios.
+ *
+ * The default policy (4σ limits) may be too restrictive for closing positions
+ * when the market has moved significantly. This relaxed policy allows the
+ * offchain solver to attempt computation for larger separations.
+ *
+ * The actual validation is done by calling `check_close_position` on-chain,
+ * which validates the computed x* without the artificial solver limits.
+ */
+export function relaxedPolicy() {
+    const sixteen = SQ128x128.fromNumber(16);
+    const maxMean = SQ128x128.fromNumber(1048576); // 2^20
+    return {
+        maxSigmaRatio: sixteen,
+        maxMeanSepSigmas: sixteen,
+        maxAbsoluteMean: maxMean,
+    };
+}
+// ============================================================================
+// PDF Difference Functions
+// ============================================================================
+/**
+ * Computes the pointwise PDF difference d(x) = g(x) - f(x).
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x - The point at which to evaluate
+ * @returns The difference g(x) - f(x), or null if computation fails
+ */
+export function pdfDifference(f, g, x) {
+    const gPdf = g.pdf(x);
+    const fPdf = f.pdf(x);
+    if (!gPdf || !fPdf) {
+        return null;
+    }
+    return gPdf.sub(fPdf);
+}
+/**
+ * Computes d'(x) = g'(x) - f'(x), the derivative of the PDF difference.
+ *
+ * At a stationary point x*, d'(x*) = 0.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x - The point at which to evaluate
+ * @returns The derivative difference, or null if computation fails
+ */
+export function pdfDifferenceDerivative(f, g, x) {
+    const gDeriv = g.pdfDerivative(x);
+    const fDeriv = f.pdfDerivative(x);
+    if (!gDeriv || !fDeriv) {
+        return null;
+    }
+    return gDeriv.sub(fDeriv);
+}
+/**
+ * Computes d''(x) = g''(x) - f''(x), the second derivative of the PDF difference.
+ *
+ * At a minimum x*, d''(x*) > 0.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x - The point at which to evaluate
+ * @returns The second derivative difference, or null if computation fails
+ */
+export function pdfDifferenceSecondDerivative(f, g, x) {
+    const gSecond = g.pdfSecondDerivative(x);
+    const fSecond = f.pdfSecondDerivative(x);
+    if (!gSecond || !fSecond) {
+        return null;
+    }
+    return gSecond.sub(fSecond);
+}
+// ============================================================================
+// Initial Guess and Collateral Helpers
+// ============================================================================
+/**
+ * Suggests an initial guess for Newton-Raphson minimization.
+ *
+ * The minimum of d(x) = g(x) - f(x) depends on the relationship between f and g:
+ *
+ * 1. Different means: minimum is on the side of f opposite to g, close to f's mean
+ * 2. Same mean (or nearly equal), narrow to wide (σ_f < σ_g): minimum is at the mean
+ * 3. Same mean (or nearly equal), wide to narrow (σ_f > σ_g): minimum is in the tails
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @returns The suggested initial guess
+ */
+export function suggestInitialGuess(f, g) {
+    const muF = f.mean;
+    const muG = g.mean;
+    const sigmaF = f.sigma;
+    const sigmaG = g.sigma;
+    // Check for near-equal means (within 1% of narrower sigma)
+    // This tolerance-based check ensures variance-only trades work even when
+    // means differ by tiny floating-point amounts
+    const meanDiff = muF.gt(muG) ? muF.sub(muG) : muG.sub(muF);
+    const sigmaNarrow = sigmaF.lt(sigmaG) ? sigmaF : sigmaG;
+    const thresholdFactor = SQ128x128.fromNumber(0.01);
+    const threshold = thresholdFactor ? sigmaNarrow.mul(thresholdFactor) : null;
+    const nearlyEqualMeans = !meanDiff || (threshold && meanDiff.lt(threshold));
+    // For same mean or nearly equal means (only variance differs)
+    if (nearlyEqualMeans) {
+        if (sigmaF.lt(sigmaG)) {
+            // Narrow to wide: minimum is at the mean
+            return muF;
+        }
+        // Wide to narrow: minimum is in the tails
+        // Use 1.0 * σ_f as initial guess - this is closer to the actual minimum
+        // than 1.5σ and works better across different variance ratios
+        const offset = sigmaF;
+        // Return positive side (symmetric case, either side works)
+        return muF.add(offset) ?? muF;
+    }
+    // Mean separation (not near-equal)
+    if (!meanDiff) {
+        return muF;
+    }
+    // For combined mean shift + variance change, the minimum location depends on both.
+    // When going wide-to-narrow with mean shift, the minimum is in the tail of f
+    // on the opposite side of the mean shift, typically around 1σ_f from the mean.
+    // When going narrow-to-wide with mean shift, minimum is closer to f's mean.
+    const wideToNarrow = sigmaF.gt(sigmaG);
+    let offset;
+    if (wideToNarrow) {
+        // Wide to narrow: minimum is further out in f's tail
+        // Use σ_f as the offset - this gives a better starting point
+        offset = sigmaF;
+    }
+    else {
+        // Narrow to wide: minimum is closer to f's mean
+        // Use half the mean difference, capped at σ_f
+        const halfDiff = meanDiff.mul(HALF);
+        offset = halfDiff && halfDiff.lt(sigmaF) ? halfDiff : sigmaF;
+    }
+    if (muG.gt(muF)) {
+        // g is to the right, minimum is to the left of f
+        const result = muF.sub(offset);
+        return result ?? muF;
+    }
+    // g is to the left, minimum is to the right of f
+    const result = muF.add(offset);
+    return result ?? muF;
+}
+/**
+ * Computes collateral from the minimum value of d(x).
+ *
+ * C = max(0, -d_min) = max(0, f(x*) - g(x*))
+ *
+ * @param dMin - The minimum value of d(x) = g(x) - f(x)
+ * @returns The collateral requirement
+ */
+export function collateralFromMinimum(dMin) {
+    const negDMin = dMin.neg();
+    if (!negDMin) {
+        return ZERO;
+    }
+    return negDMin.gt(ZERO) ? negDMin : ZERO;
+}
+/**
+ * Checks if x is on the correct side of μ_f relative to μ_g.
+ *
+ * The minimum of d(x) = g(x) - f(x) occurs on the side of f opposite to g:
+ * - If μ_g > μ_f, then x should be < μ_f (left of f, away from g)
+ * - If μ_g < μ_f, then x should be > μ_f (right of f, away from g)
+ * - If μ_g = μ_f, any side is valid (symmetric case)
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x - The point to check
+ * @returns True if x is on the correct side
+ */
+export function isOnCorrectSide(f, g, x) {
+    const muF = f.mean;
+    const muG = g.mean;
+    if (muG.gt(muF)) {
+        return x.lt(muF);
+    }
+    if (muG.lt(muF)) {
+        return x.gt(muF);
+    }
+    // Same mean - any side is valid
+    return true;
+}
+// ============================================================================
+// Precheck: Validate Inputs Against Policy
+// ============================================================================
+/**
+ * Checks if inputs are within the safe operating envelope.
+ *
+ * @returns null if inputs pass, or a rejection reason if they should be rejected
+ */
+function precheck(f, g, policy) {
+    // Reject non-positive variance
+    if (f.variance.lte(ZERO) || g.variance.lte(ZERO)) {
+        return 'degenerate_distribution';
+    }
+    // Check sigma ratio
+    const varF = f.variance;
+    const varG = g.variance;
+    const [varLarge, varSmall] = varF.gt(varG) ? [varF, varG] : [varG, varF];
+    // Skip ratio check for equal variance
+    if (!varF.eq(varG)) {
+        const maxRatioSq = policy.maxSigmaRatio.pow2();
+        if (!maxRatioSq) {
+            return 'computation_failed';
+        }
+        const threshold = maxRatioSq.mul(varSmall);
+        if (threshold && varLarge.gt(threshold)) {
+            return 'sigma_ratio_too_high';
+        }
+    }
+    // Check absolute magnitude of means
+    const absMuF = f.mean.abs();
+    const absMuG = g.mean.abs();
+    if (absMuF.gt(policy.maxAbsoluteMean) || absMuG.gt(policy.maxAbsoluteMean)) {
+        return 'mean_magnitude_too_large';
+    }
+    // Check mean separation
+    const muSep = f.mean.gt(g.mean) ? f.mean.sub(g.mean) : g.mean.sub(f.mean);
+    if (!muSep) {
+        return 'computation_failed';
+    }
+    // Use the narrower distribution's sigma for the threshold
+    const sigmaNarrow = varF.lte(varG) ? f.sigma : g.sigma;
+    const maxSep = policy.maxMeanSepSigmas.mul(sigmaNarrow);
+    if (maxSep && muSep.gt(maxSep)) {
+        return 'mean_separation_too_large';
+    }
+    return null;
+}
+// ============================================================================
+// Newton-Raphson Minimization
+// ============================================================================
+/** Default convergence tolerance */
+export const DEFAULT_TOLERANCE = SQ128x128.fromNumber(1e-10);
+/** Default maximum iterations */
+export const DEFAULT_MAX_ITERATIONS = 50;
+/**
+ * Maximum step size as a multiple of sigma.
+ * Prevents Newton from overshooting when d''(x) is very small.
+ */
+const MAX_STEP_SIGMAS = SQ128x128.fromNumber(0.5);
+/**
+ * Performs one damped Newton-Raphson step for minimizing d(x) = g(x) - f(x).
+ *
+ * For minimization: x_next = x - d'(x) / d''(x)
+ *
+ * Step damping: Limits step size to MAX_STEP_SIGMAS * max(σ_f, σ_g)
+ * to prevent overshooting when the second derivative is very small.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x - Current guess
+ * @returns Next guess, or null if step fails
+ */
+function newtonStep(f, g, x) {
+    const dPrime = pdfDifferenceDerivative(f, g, x);
+    const dDoublePrime = pdfDifferenceSecondDerivative(f, g, x);
+    if (!dPrime || !dDoublePrime || dDoublePrime.isZero()) {
+        return null;
+    }
+    // Newton step: x - f'(x)/f''(x)
+    let step = dPrime.div(dDoublePrime);
+    if (!step) {
+        return null;
+    }
+    // Damp step size to prevent overshooting
+    // Max step = 0.5 * max(σ_f, σ_g)
+    const maxSigma = f.sigma.gt(g.sigma) ? f.sigma : g.sigma;
+    const maxStep = MAX_STEP_SIGMAS.mul(maxSigma);
+    if (maxStep) {
+        const absStep = step.abs();
+        if (absStep.gt(maxStep)) {
+            // Scale down the step while preserving direction
+            if (step.isNegative()) {
+                step = maxStep.neg();
+            }
+            else {
+                step = maxStep;
+            }
+        }
+    }
+    return x.sub(step);
+}
+/**
+ * Validates a candidate minimum against stationary, curvature, and side constraints.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param xMin - The candidate minimum point
+ * @param tolerance - Maximum allowed |d'(x*)|
+ * @returns null if valid, or a reason if invalid
+ */
+function validateCandidate(f, g, xMin, tolerance) {
+    // 1. Stationary check: |d'(x_min)| ≤ tolerance
+    const dPrime = pdfDifferenceDerivative(f, g, xMin);
+    if (!dPrime) {
+        return 'computation_failed';
+    }
+    const absDPrime = dPrime.abs();
+    if (absDPrime.gt(tolerance)) {
+        return 'not_stationary';
+    }
+    // 2. Curvature check: d''(x*) > 0
+    const dDoublePrime = pdfDifferenceSecondDerivative(f, g, xMin);
+    if (!dDoublePrime) {
+        return 'computation_failed';
+    }
+    if (dDoublePrime.lte(ZERO)) {
+        return 'curvature_not_positive';
+    }
+    // 3. Side check
+    if (!isOnCorrectSide(f, g, xMin)) {
+        return 'wrong_side';
+    }
+    return null;
+}
+/**
+ * Finds the minimum of d(x) = g(x) - f(x) using Newton-Raphson.
+ *
+ * This is the primary entry point for collateral computation.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @param x0 - Optional initial guess (will be computed if not provided)
+ * @param tolerance - Convergence threshold (default: 1e-10)
+ * @param maxIterations - Maximum Newton iterations (default: 50)
+ * @param policy - Safe envelope policy (default: defaultPolicy())
+ * @returns The minimization result
+ */
+export function findMinimum(f, g, x0, tolerance = DEFAULT_TOLERANCE, maxIterations = DEFAULT_MAX_ITERATIONS, policy = defaultPolicy()) {
+    // Precheck: reject inputs outside safe envelope
+    const precheckReason = precheck(f, g, policy);
+    if (precheckReason) {
+        return { type: 'rejected', reason: precheckReason };
+    }
+    // Special case: identical distributions
+    if (f.isIdentical(g)) {
+        return {
+            type: 'verified',
+            result: {
+                xMin: f.mean,
+                dMin: ZERO,
+                collateral: ZERO,
+                tolerance,
+                iterations: 0,
+                method: 'closed-form',
+            },
+        };
+    }
+    // Use provided or suggested initial guess
+    let x = x0 ?? suggestInitialGuess(f, g);
+    let iterations = 0;
+    let converged = false;
+    // Newton-Raphson iteration
+    for (let i = 0; i < maxIterations; i++) {
+        const xNext = newtonStep(f, g, x);
+        if (!xNext) {
+            break;
+        }
+        iterations = i + 1;
+        // Check convergence: |x_next - x| < tolerance
+        const diff = xNext.sub(x);
+        if (diff && diff.abs().lt(tolerance)) {
+            converged = true;
+            x = xNext;
+            break;
+        }
+        x = xNext;
+    }
+    // Compute d(x*) and collateral
+    const dMin = pdfDifference(f, g, x) ?? ZERO;
+    const collateral = collateralFromMinimum(dMin);
+    const candidate = {
+        x,
+        d: dMin,
+        collateral,
+        iterations,
+        method: 'newton',
+    };
+    // Check convergence
+    if (!converged) {
+        return {
+            type: 'not_verified',
+            reason: 'newton_did_not_converge',
+            candidate,
+        };
+    }
+    // Validate the candidate
+    const validationReason = validateCandidate(f, g, x, tolerance);
+    if (validationReason) {
+        return {
+            type: 'not_verified',
+            reason: validationReason,
+            candidate,
+        };
+    }
+    // All checks passed
+    return {
+        type: 'verified',
+        result: {
+            xMin: x,
+            dMin,
+            collateral,
+            tolerance,
+            iterations,
+            method: 'newton',
+        },
+    };
+}
+/**
+ * Convenience function to compute collateral directly.
+ *
+ * Returns the verified collateral amount, or null if verification fails.
+ *
+ * @param f - The "from" distribution
+ * @param g - The "to" distribution
+ * @returns The collateral requirement, or null if computation fails
+ */
+export function computeCollateral(f, g) {
+    const result = findMinimum(f, g);
+    if (result.type === 'verified') {
+        return result.result.collateral;
+    }
+    return null;
+}
+/**
+ * Extracts the verified minimum from a result, if available.
+ *
+ * @param result - The FindMinimumResult
+ * @returns The VerifiedMinimum if verified, null otherwise
+ */
+export function getVerifiedMinimum(result) {
+    if (result.type === 'verified') {
+        return result.result;
+    }
+    return null;
+}
+/**
+ * Checks if a FindMinimumResult is verified.
+ *
+ * @param result - The FindMinimumResult
+ * @returns True if the result is verified
+ */
+export function isVerified(result) {
+    return result.type === 'verified';
+}
+// ============================================================================
+// Scaled PDF Difference Functions
+// ============================================================================
+/**
+ * Computes the scaled PDF difference: d_s(x) = lambda_g * g(x) - lambda_f * f(x)
+ *
+ * When variances differ, finding the minimum of this scaled difference
+ * is necessary for correct collateral computation.
+ */
+export function scaledPdfDifference(f, g, lambdaF, lambdaG, x) {
+    const fPdf = f.pdf(x);
+    const gPdf = g.pdf(x);
+    if (!fPdf || !gPdf)
+        return null;
+    return lambdaG * gPdf.toNumber() - lambdaF * fPdf.toNumber();
+}
+/**
+ * Computes the derivative of scaled PDF difference:
+ * d_s'(x) = lambda_g * g'(x) - lambda_f * f'(x)
+ */
+export function scaledPdfDifferenceDerivative(f, g, lambdaF, lambdaG, x) {
+    const fDeriv = f.pdfDerivative(x);
+    const gDeriv = g.pdfDerivative(x);
+    if (!fDeriv || !gDeriv)
+        return null;
+    return lambdaG * gDeriv.toNumber() - lambdaF * fDeriv.toNumber();
+}
+/**
+ * Computes the second derivative of scaled PDF difference:
+ * d_s''(x) = lambda_g * g''(x) - lambda_f * f''(x)
+ */
+export function scaledPdfDifferenceSecondDerivative(f, g, lambdaF, lambdaG, x) {
+    const fSecond = f.pdfSecondDerivative(x);
+    const gSecond = g.pdfSecondDerivative(x);
+    if (!fSecond || !gSecond)
+        return null;
+    return lambdaG * gSecond.toNumber() - lambdaF * fSecond.toNumber();
+}
+/**
+ * Performs one damped Newton-Raphson step for the scaled PDF difference.
+ *
+ * For minimization: x_next = x - d_s'(x) / d_s''(x)
+ */
+function scaledNewtonStep(f, g, lambdaF, lambdaG, x, maxStepSize) {
+    const dPrime = scaledPdfDifferenceDerivative(f, g, lambdaF, lambdaG, x);
+    const dDoublePrime = scaledPdfDifferenceSecondDerivative(f, g, lambdaF, lambdaG, x);
+    if (dPrime === null || dDoublePrime === null || Math.abs(dDoublePrime) < 1e-20) {
+        return null;
+    }
+    // Newton step: x - f'(x)/f''(x)
+    let step = dPrime / dDoublePrime;
+    // Damp step size to prevent overshooting
+    if (Math.abs(step) > maxStepSize) {
+        step = step > 0 ? maxStepSize : -maxStepSize;
+    }
+    const xNum = x.toNumber();
+    const nextX = xNum - step;
+    return SQ128x128.fromNumber(nextX);
+}
+/**
+ * Finds the minimum of the scaled PDF difference using Newton-Raphson.
+ *
+ * This is the correct approach when lambda_f ≠ lambda_g (different variances).
+ * The minimum of d_s(x) = lambda_g * g(x) - lambda_f * f(x) may be at a
+ * different location than the minimum of d(x) = g(x) - f(x).
+ */
+function findScaledMinimum(f, g, lambdaF, lambdaG, tolerance = 1e-10, maxIterations = 50) {
+    // Initial guess - start on the side of f away from g
+    const muF = f.mean.toNumber();
+    const muG = g.mean.toNumber();
+    const sigmaF = f.sigma.toNumber();
+    const sigmaG = g.sigma.toNumber();
+    const maxSigma = Math.max(sigmaF, sigmaG);
+    let x;
+    // Check for near-equal means (within 1% of narrower sigma)
+    // This tolerance-based check ensures variance-only trades work even when
+    // means differ by tiny floating-point amounts
+    const meanDiff = Math.abs(muF - muG);
+    const sigmaNarrow = Math.min(sigmaF, sigmaG);
+    const nearlyEqualMeans = meanDiff < 0.01 * sigmaNarrow;
+    // For same mean or near-equal means (variance only change)
+    if (nearlyEqualMeans) {
+        if (sigmaF < sigmaG) {
+            // Narrow to wide: minimum is near the mean
+            x = f.mean;
+        }
+        else {
+            // Wide to narrow: minimum is in the tails
+            // Use 1.0 * σ_f as initial guess - closer to actual minimum
+            const xNum = muF + sigmaF;
+            x = SQ128x128.fromNumber(xNum);
+        }
+    }
+    else {
+        // Mean differs significantly: start on the opposite side of f from g
+        // For wide-to-narrow with mean shift, use σ_f as offset (minimum is further out)
+        // For narrow-to-wide, use smaller offset
+        const wideToNarrow = sigmaF > sigmaG;
+        const offset = wideToNarrow ? sigmaF : Math.min(sigmaF * 0.5, meanDiff * 0.5);
+        const xNum = muG > muF ? muF - offset : muF + offset;
+        x = SQ128x128.fromNumber(xNum);
+    }
+    const maxStepSize = 0.5 * maxSigma;
+    let iterations = 0;
+    let converged = false;
+    for (let i = 0; i < maxIterations; i++) {
+        const xNext = scaledNewtonStep(f, g, lambdaF, lambdaG, x, maxStepSize);
+        if (!xNext) {
+            break;
+        }
+        iterations = i + 1;
+        // Check convergence
+        const diff = Math.abs(xNext.toNumber() - x.toNumber());
+        if (diff < tolerance) {
+            converged = true;
+            x = xNext;
+            break;
+        }
+        x = xNext;
+    }
+    const xStar = x.toNumber();
+    const dMin = scaledPdfDifference(f, g, lambdaF, lambdaG, x);
+    if (dMin === null) {
+        return null;
+    }
+    return { xStar, dMin, iterations, converged };
+}
+/**
+ * Computes the scaled collateral for AMM trading.
+ *
+ * The AMM uses lambda-scaled PDFs where lambda = k / ||p||_2.
+ *
+ * For distributions with the same variance, lambda_f = lambda_g and we can
+ * use the unscaled minimum.
+ *
+ * For distributions with different variances, we find x* by minimizing
+ * the scaled difference: d_s(x) = lambda_g * g(x) - lambda_f * f(x)
+ *
+ * Collateral = max(0, lambda_f * f(x*) - lambda_g * g(x*)) = max(0, -d_s(x*))
+ *
+ * @param f - The "from" distribution (current market)
+ * @param g - The "to" distribution (candidate)
+ * @param k - The AMM invariant parameter (default: 1)
+ * @param policy - The minimization policy (default: defaultPolicy())
+ * @returns The scaled collateral result, or null if computation fails
+ *
+ * @example
+ * ```typescript
+ * const f = NormalDistribution.create(mean100, variance100);
+ * const g = NormalDistribution.create(mean105, variance100);
+ * const result = computeScaledCollateral(f, g, SQ128x128.fromNumber(1));
+ * if (result) {
+ *   console.log('Collateral:', result.scaledCollateral.toNumber());
+ *   console.log('x*:', result.xStar.toNumber());
+ * }
+ * ```
+ */
+export function computeScaledCollateral(f, g, k = ONE, policy = defaultPolicy()) {
+    const kNum = k.toNumber();
+    // Compute lambda for both distributions
+    const sigmaF = f.sigma.toNumber();
+    const sigmaG = g.sigma.toNumber();
+    const lambdaFNum = computeLambdaNumber(sigmaF, kNum);
+    const lambdaGNum = computeLambdaNumber(sigmaG, kNum);
+    // Check if lambdas are approximately equal (same variance case)
+    const lambdaRatio = lambdaFNum / lambdaGNum;
+    const sameVariance = Math.abs(lambdaRatio - 1.0) < 0.001;
+    let xStarNum;
+    let iterations;
+    let scaledCollateralNum;
+    let unscaledCollateralNum;
+    if (sameVariance) {
+        // Same variance: use unscaled minimization (faster, same result)
+        const result = findMinimum(f, g, undefined, DEFAULT_TOLERANCE, DEFAULT_MAX_ITERATIONS, policy);
+        if (result.type !== 'verified') {
+            return null;
+        }
+        xStarNum = result.result.xMin.toNumber();
+        iterations = result.result.iterations;
+        unscaledCollateralNum = result.result.collateral.toNumber();
+        // Scale the collateral: C_scaled = lambda * C_unscaled
+        scaledCollateralNum = lambdaFNum * unscaledCollateralNum;
+    }
+    else {
+        // Different variances: minimize the scaled difference directly
+        const scaledResult = findScaledMinimum(f, g, lambdaFNum, lambdaGNum);
+        if (!scaledResult || !scaledResult.converged) {
+            // Fallback to unscaled with a safety buffer
+            const result = findMinimum(f, g, undefined, DEFAULT_TOLERANCE, DEFAULT_MAX_ITERATIONS, policy);
+            if (result.type !== 'verified') {
+                return null;
+            }
+            xStarNum = result.result.xMin.toNumber();
+            iterations = result.result.iterations;
+            unscaledCollateralNum = result.result.collateral.toNumber();
+            // Compute actual scaled collateral at unscaled x*
+            const xStar = result.result.xMin;
+            const fPdf = f.pdf(xStar)?.toNumber() ?? 0;
+            const gPdf = g.pdf(xStar)?.toNumber() ?? 0;
+            scaledCollateralNum = Math.max(0, lambdaFNum * fPdf - lambdaGNum * gPdf);
+        }
+        else {
+            xStarNum = scaledResult.xStar;
+            iterations = scaledResult.iterations;
+            // Compute collateral from scaled minimum
+            // C_scaled = max(0, -d_s(x*)) = max(0, lambda_f * f(x*) - lambda_g * g(x*))
+            scaledCollateralNum = Math.max(0, -scaledResult.dMin);
+            // Also compute unscaled for reference
+            const xStar = SQ128x128.fromNumber(xStarNum);
+            const fPdf = f.pdf(xStar)?.toNumber() ?? 0;
+            const gPdf = g.pdf(xStar)?.toNumber() ?? 0;
+            unscaledCollateralNum = Math.max(0, fPdf - gPdf);
+        }
+    }
+    const xStar = SQ128x128.fromNumber(xStarNum);
+    const scaledCollateral = SQ128x128.fromNumber(scaledCollateralNum);
+    const unscaledCollateral = SQ128x128.fromNumber(unscaledCollateralNum ?? scaledCollateralNum / lambdaFNum);
+    const lambdaF = SQ128x128.fromNumber(lambdaFNum);
+    const lambdaG = SQ128x128.fromNumber(lambdaGNum);
+    if (!xStar || !scaledCollateral || !unscaledCollateral || !lambdaF || !lambdaG) {
+        return null;
+    }
+    return {
+        unscaledCollateral,
+        scaledCollateral,
+        lambda: lambdaF, // For backward compatibility
+        xStar,
+        iterations,
+        lambdaF,
+        lambdaG,
+    };
+}
+//# sourceMappingURL=compute.js.map