@the-situation/collateral 0.5.0-alpha.0

package/dist/compute.d.ts

@@ -0,0 +1,326 @@
+/**
+ * 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 { NormalDistribution, SQ128x128 } from '@the-situation/core';
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export declare const SQRT_PI: number;
+/**
+ * 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 declare function computeL2NormNumber(sigma: number): number;
+/**
+ * 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 declare function computeLambdaNumber(sigma: number, k: number): number;
+/**
+ * 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 declare function computeL2Norm(sigma: SQ128x128): SQ128x128 | null;
+/**
+ * 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 declare function computeLambda(sigma: SQ128x128, k: SQ128x128): SQ128x128 | null;
+/**
+ * Policy parameters for the minimization algorithm.
+ *
+ * These define the "safe operating envelope" where Newton-Raphson
+ * is expected to produce correct results.
+ */
+export interface MinimizationPolicy {
+    /** Maximum allowed sigma ratio (σ_large / σ_small). Default: 4.0 */
+    maxSigmaRatio: SQ128x128;
+    /** Maximum mean separation in units of the narrower σ. Default: 4.0 */
+    maxMeanSepSigmas: SQ128x128;
+    /** Maximum absolute value of mean. Default: 2^20 */
+    maxAbsoluteMean: SQ128x128;
+}
+/**
+ * Returns the default minimization policy.
+ */
+export declare function defaultPolicy(): MinimizationPolicy;
+/**
+ * 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 declare function relaxedPolicy(): MinimizationPolicy;
+/** Method used to find the minimum. */
+export type MinimizationMethod = 'closed-form' | 'newton';
+/**
+ * A verified minimum that passed all validation checks.
+ *
+ * This is a self-contained certificate that includes all context needed
+ * for verification.
+ */
+export interface VerifiedMinimum {
+    /** The x-coordinate where the minimum occurs */
+    xMin: SQ128x128;
+    /** The minimum value d(xMin) = g(xMin) - f(xMin) */
+    dMin: SQ128x128;
+    /** The computed collateral: max(0, -dMin) */
+    collateral: SQ128x128;
+    /** The tolerance used for stationary validation */
+    tolerance: SQ128x128;
+    /** Number of iterations (0 for closed-form) */
+    iterations: number;
+    /** Method used to find the minimum */
+    method: MinimizationMethod;
+}
+/**
+ * A candidate minimum that has not been verified.
+ */
+export interface CandidateMinimum {
+    /** The x-coordinate of the candidate */
+    x: SQ128x128;
+    /** The function value at x */
+    d: SQ128x128;
+    /** Tentative collateral (may be incorrect) */
+    collateral: SQ128x128;
+    /** Number of iterations */
+    iterations: number;
+    /** Method used */
+    method: MinimizationMethod;
+}
+/** Reason why the minimum could not be verified or was rejected. */
+export type NotVerifiedReason = 'degenerate_distribution' | 'sigma_ratio_too_high' | 'mean_separation_too_large' | 'mean_magnitude_too_large' | 'newton_did_not_converge' | 'not_stationary' | 'curvature_not_positive' | 'wrong_side' | 'computation_failed';
+/** Result of attempting to find the minimum. */
+export type FindMinimumResult = {
+    type: 'verified';
+    result: VerifiedMinimum;
+} | {
+    type: 'not_verified';
+    reason: NotVerifiedReason;
+    candidate?: CandidateMinimum;
+} | {
+    type: 'rejected';
+    reason: NotVerifiedReason;
+};
+/**
+ * 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 declare function pdfDifference(f: NormalDistribution, g: NormalDistribution, x: SQ128x128): SQ128x128 | null;
+/**
+ * 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 declare function pdfDifferenceDerivative(f: NormalDistribution, g: NormalDistribution, x: SQ128x128): SQ128x128 | null;
+/**
+ * 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 declare function pdfDifferenceSecondDerivative(f: NormalDistribution, g: NormalDistribution, x: SQ128x128): SQ128x128 | null;
+/**
+ * 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 declare function suggestInitialGuess(f: NormalDistribution, g: NormalDistribution): SQ128x128;
+/**
+ * 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 declare function collateralFromMinimum(dMin: SQ128x128): SQ128x128;
+/**
+ * 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 declare function isOnCorrectSide(f: NormalDistribution, g: NormalDistribution, x: SQ128x128): boolean;
+/** Default convergence tolerance */
+export declare const DEFAULT_TOLERANCE: SQ128x128;
+/** Default maximum iterations */
+export declare const DEFAULT_MAX_ITERATIONS = 50;
+/**
+ * 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 declare function findMinimum(f: NormalDistribution, g: NormalDistribution, x0?: SQ128x128, tolerance?: SQ128x128, maxIterations?: number, policy?: MinimizationPolicy): FindMinimumResult;
+/**
+ * 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 declare function computeCollateral(f: NormalDistribution, g: NormalDistribution): SQ128x128 | null;
+/**
+ * Extracts the verified minimum from a result, if available.
+ *
+ * @param result - The FindMinimumResult
+ * @returns The VerifiedMinimum if verified, null otherwise
+ */
+export declare function getVerifiedMinimum(result: FindMinimumResult): VerifiedMinimum | null;
+/**
+ * Checks if a FindMinimumResult is verified.
+ *
+ * @param result - The FindMinimumResult
+ * @returns True if the result is verified
+ */
+export declare function isVerified(result: FindMinimumResult): boolean;
+/**
+ * Result of scaled collateral computation.
+ */
+export interface ScaledCollateralResult {
+    /** The unscaled collateral (before lambda multiplication) */
+    readonly unscaledCollateral: SQ128x128;
+    /** The scaled collateral (lambda * unscaledCollateral) */
+    readonly scaledCollateral: SQ128x128;
+    /** The lambda scaling factor */
+    readonly lambda: SQ128x128;
+    /** The minimum point x* */
+    readonly xStar: SQ128x128;
+    /** Number of iterations used */
+    readonly iterations: number;
+    /** Lambda for the "from" distribution */
+    readonly lambdaF: SQ128x128;
+    /** Lambda for the "to" distribution */
+    readonly lambdaG: SQ128x128;
+}
+/**
+ * Extended result for scaled collateral with both lambdas.
+ * @deprecated Use ScaledCollateralResult which now includes both lambdas
+ */
+export interface ScaledCollateralResultExtended extends ScaledCollateralResult {
+}
+/**
+ * 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 declare function scaledPdfDifference(f: NormalDistribution, g: NormalDistribution, lambdaF: number, lambdaG: number, x: SQ128x128): number | null;
+/**
+ * Computes the derivative of scaled PDF difference:
+ * d_s'(x) = lambda_g * g'(x) - lambda_f * f'(x)
+ */
+export declare function scaledPdfDifferenceDerivative(f: NormalDistribution, g: NormalDistribution, lambdaF: number, lambdaG: number, x: SQ128x128): number | null;
+/**
+ * Computes the second derivative of scaled PDF difference:
+ * d_s''(x) = lambda_g * g''(x) - lambda_f * f''(x)
+ */
+export declare function scaledPdfDifferenceSecondDerivative(f: NormalDistribution, g: NormalDistribution, lambdaF: number, lambdaG: number, x: SQ128x128): number | null;
+/**
+ * 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 declare function computeScaledCollateral(f: NormalDistribution, g: NormalDistribution, k?: SQ128x128, policy?: MinimizationPolicy): ScaledCollateralResult | null;
+//# sourceMappingURL=compute.d.ts.map

package/dist/compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../src/compute.ts"],"names":[],"mappings":"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"}