@the-situation/sdk 0.1.0-alpha.0

package/dist/utils/decimal-scale.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Decimal scaling utilities for token amount conversions.
+ *
+ * Converts between token amounts (with varying decimal places) and
+ * SQ128x128 fixed-point values used internally by the protocol.
+ *
+ * ## Rounding Convention
+ *
+ * - **Deposits**: Use `toTokenAmountUp()` - rounds up, conservative for protocol
+ * - **Withdrawals**: Use `toTokenAmountDown()` - rounds down, conservative for protocol
+ *
+ * This ensures the protocol never gives away more than it should.
+ *
+ * @module
+ */
+import { SQ128x128 } from '../types/sq128';
+/** 10^18 - standard ERC20 decimal places */
+export declare const DECIMALS_18: bigint;
+/** 10^6 - USDC/USDT decimal places */
+export declare const DECIMALS_6: bigint;
+/**
+ * Converts a token amount to SQ128x128.
+ *
+ * @param amount - Raw token amount (e.g., 1e18 for 1 token with 18 decimals)
+ * @param decimals - Token decimal places (e.g., 18 for ETH, 6 for USDC)
+ * @returns SQ128x128 value, or null on overflow
+ *
+ * @example
+ * ```ts
+ * // 1.5 USDC (6 decimals) = 1_500_000 raw
+ * const sq = fromTokenAmount(1_500_000n, 6);
+ * // sq.toNumber() ≈ 1.5
+ * ```
+ */
+export declare function fromTokenAmount(amount: bigint, decimals: number): SQ128x128 | null;
+/**
+ * Converts SQ128x128 to token amount, rounding down.
+ *
+ * Use for withdrawals - conservative for protocol (pays less).
+ *
+ * @param value - The SQ128x128 value
+ * @param decimals - Target token decimal places
+ * @returns Raw token amount (rounded down)
+ *
+ * @example
+ * ```ts
+ * const sq = SQ128x128.fromNumber(1.5);
+ * const amount = toTokenAmountDown(sq, 6);
+ * // amount = 1_500_000n (1.5 USDC)
+ * ```
+ */
+export declare function toTokenAmountDown(value: SQ128x128, decimals: number): bigint;
+/**
+ * Converts SQ128x128 to token amount, rounding up.
+ *
+ * Use for deposits - conservative for protocol (requires more).
+ *
+ * @param value - The SQ128x128 value
+ * @param decimals - Target token decimal places
+ * @returns Raw token amount (rounded up)
+ */
+export declare function toTokenAmountUp(value: SQ128x128, decimals: number): bigint;
+//# sourceMappingURL=decimal-scale.d.ts.map

package/dist/utils/decimal-scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal-scale.d.ts","sourceRoot":"","sources":["../../src/utils/decimal-scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,4CAA4C;AAC5C,eAAO,MAAM,WAAW,EAAE,MAAmB,CAAC;AAE9C,sCAAsC;AACtC,eAAO,MAAM,UAAU,EAAE,MAAkB,CAAC;AAY5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAqBlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU1E"}

package/dist/utils/decimal-scale.js

@@ -0,0 +1,108 @@
+/**
+ * Decimal scaling utilities for token amount conversions.
+ *
+ * Converts between token amounts (with varying decimal places) and
+ * SQ128x128 fixed-point values used internally by the protocol.
+ *
+ * ## Rounding Convention
+ *
+ * - **Deposits**: Use `toTokenAmountUp()` - rounds up, conservative for protocol
+ * - **Withdrawals**: Use `toTokenAmountDown()` - rounds down, conservative for protocol
+ *
+ * This ensures the protocol never gives away more than it should.
+ *
+ * @module
+ */
+import { SQ128x128 } from '../types/sq128';
+/** 10^18 - standard ERC20 decimal places */
+export const DECIMALS_18 = 10n ** 18n;
+/** 10^6 - USDC/USDT decimal places */
+export const DECIMALS_6 = 10n ** 6n;
+/** 2^128 - the SQ128x128 scaling factor */
+const SQ_SCALE = 1n << 128n;
+/**
+ * Computes 10^decimals as a bigint.
+ */
+function decimalScale(decimals) {
+    return 10n ** BigInt(decimals);
+}
+/**
+ * Converts a token amount to SQ128x128.
+ *
+ * @param amount - Raw token amount (e.g., 1e18 for 1 token with 18 decimals)
+ * @param decimals - Token decimal places (e.g., 18 for ETH, 6 for USDC)
+ * @returns SQ128x128 value, or null on overflow
+ *
+ * @example
+ * ```ts
+ * // 1.5 USDC (6 decimals) = 1_500_000 raw
+ * const sq = fromTokenAmount(1_500_000n, 6);
+ * // sq.toNumber() ≈ 1.5
+ * ```
+ */
+export function fromTokenAmount(amount, decimals) {
+    const scale = decimalScale(decimals);
+    // Convert: amount / 10^decimals -> SQ128x128
+    // SQ128x128 internal: value * 2^128
+    // So: (amount * 2^128) / 10^decimals
+    const scaledValue = (amount * SQ_SCALE) / scale;
+    // Check if within SQ128x128 range (256 bits)
+    const maxMag = (1n << 256n) - 1n;
+    if (scaledValue > maxMag) {
+        return null;
+    }
+    // Construct the SQ128x128 from the scaled value
+    return SQ128x128.fromRaw({
+        limb0: scaledValue & ((1n << 64n) - 1n),
+        limb1: (scaledValue >> 64n) & ((1n << 64n) - 1n),
+        limb2: (scaledValue >> 128n) & ((1n << 64n) - 1n),
+        limb3: scaledValue >> 192n,
+        neg: false,
+    });
+}
+/**
+ * Converts SQ128x128 to token amount, rounding down.
+ *
+ * Use for withdrawals - conservative for protocol (pays less).
+ *
+ * @param value - The SQ128x128 value
+ * @param decimals - Target token decimal places
+ * @returns Raw token amount (rounded down)
+ *
+ * @example
+ * ```ts
+ * const sq = SQ128x128.fromNumber(1.5);
+ * const amount = toTokenAmountDown(sq, 6);
+ * // amount = 1_500_000n (1.5 USDC)
+ * ```
+ */
+export function toTokenAmountDown(value, decimals) {
+    const raw = value.toRaw();
+    const magnitude = raw.limb0 + (raw.limb1 << 64n) + (raw.limb2 << 128n) + (raw.limb3 << 192n);
+    const scale = decimalScale(decimals);
+    // Convert: SQ128x128 -> amount * 10^decimals
+    // value = magnitude / 2^128
+    // amount = value * 10^decimals = (magnitude * 10^decimals) / 2^128
+    // Round down: integer division naturally rounds down for positive numbers
+    const result = (magnitude * scale) / SQ_SCALE;
+    return raw.neg ? -result : result;
+}
+/**
+ * Converts SQ128x128 to token amount, rounding up.
+ *
+ * Use for deposits - conservative for protocol (requires more).
+ *
+ * @param value - The SQ128x128 value
+ * @param decimals - Target token decimal places
+ * @returns Raw token amount (rounded up)
+ */
+export function toTokenAmountUp(value, decimals) {
+    const raw = value.toRaw();
+    const magnitude = raw.limb0 + (raw.limb1 << 64n) + (raw.limb2 << 128n) + (raw.limb3 << 192n);
+    const scale = decimalScale(decimals);
+    // Round up: (a + b - 1) / b
+    const numerator = magnitude * scale;
+    const result = numerator === 0n ? 0n : (numerator + SQ_SCALE - 1n) / SQ_SCALE;
+    return raw.neg ? -result : result;
+}
+//# sourceMappingURL=decimal-scale.js.map

package/dist/utils/decimal-scale.js.map

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

package/dist/utils/hints.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Hint computation for NormalSqrtHints.
+ *
+ * Contract validates: l2_norm_denom² == 2 * sigma * sqrt(pi)
+ * For variance-change trades, must use Newton-Raphson sqrt for exact match.
+ *
+ * @module
+ */
+import { SQ128x128 } from '../types/sq128';
+import type { NormalSqrtHintsRaw } from '../types/normal-sqrt-hints-raw';
+/**
+ * Computes the l2_norm_denom hint as a float.
+ *
+ * Formula: sqrt(2 * sigma * sqrt(pi))
+ *
+ * Use this for mean-only trades where float precision is sufficient.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The l2_norm_denom hint
+ */
+export declare function computeL2NormDenomHintNumber(sigma: number): number;
+/**
+ * Computes the backing_denom hint as a float.
+ *
+ * Formula: sqrt(sigma * sqrt(pi))
+ *
+ * Use this for mean-only trades where float precision is sufficient.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The backing_denom hint
+ */
+export declare function computeBackingDenomHintNumber(sigma: number): number;
+/**
+ * Computes the l2_norm_denom hint with full SQ128x128 precision.
+ *
+ * Formula: sqrt(2 * sigma * sqrt(pi))
+ *
+ * Required for variance-change trades where the contract validates
+ * l2_norm_denom² == 2 * sigma * sqrt(pi) in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The l2_norm_denom hint, or null if computation fails
+ */
+export declare function computeL2NormDenomHint(sigma: SQ128x128): SQ128x128 | null;
+/**
+ * Computes the backing_denom hint with full SQ128x128 precision.
+ *
+ * Formula: sqrt(sigma * sqrt(pi))
+ *
+ * Required for variance-change trades where the contract validates
+ * backing_denom² == sigma * sqrt(pi) in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The backing_denom hint, or null if computation fails
+ */
+export declare function computeBackingDenomHint(sigma: SQ128x128): SQ128x128 | null;
+/**
+ * Computes hints with full SQ128x128 precision.
+ *
+ * Required for variance-change trades where the contract validates
+ * hint values in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The hints, or null if computation fails
+ */
+export declare function computeHints(sigma: SQ128x128): NormalSqrtHintsRaw | null;
+/**
+ * Computes hints from a numeric sigma value.
+ *
+ * Convenience wrapper that converts sigma to SQ128x128 and computes
+ * hints with full precision.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The hints
+ * @throws Error if sigma cannot be converted or hints cannot be computed
+ */
+export declare function computeHintsFromNumber(sigma: number): NormalSqrtHintsRaw;
+//# sourceMappingURL=hints.d.ts.map

package/dist/utils/hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.d.ts","sourceRoot":"","sources":["../../src/utils/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAO,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGzE;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAYzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAO1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,kBAAkB,GAAG,IAAI,CAYxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAYxE"}

package/dist/utils/hints.js

@@ -0,0 +1,118 @@
+/**
+ * Hint computation for NormalSqrtHints.
+ *
+ * Contract validates: l2_norm_denom² == 2 * sigma * sqrt(pi)
+ * For variance-change trades, must use Newton-Raphson sqrt for exact match.
+ *
+ * @module
+ */
+import { SQ128x128, TWO } from '../types/sq128';
+import { SQRT_PI, SQRT_PI_SQ, sqrtSQ128x128 } from './math';
+/**
+ * Computes the l2_norm_denom hint as a float.
+ *
+ * Formula: sqrt(2 * sigma * sqrt(pi))
+ *
+ * Use this for mean-only trades where float precision is sufficient.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The l2_norm_denom hint
+ */
+export function computeL2NormDenomHintNumber(sigma) {
+    return Math.sqrt(2 * sigma * SQRT_PI);
+}
+/**
+ * Computes the backing_denom hint as a float.
+ *
+ * Formula: sqrt(sigma * sqrt(pi))
+ *
+ * Use this for mean-only trades where float precision is sufficient.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The backing_denom hint
+ */
+export function computeBackingDenomHintNumber(sigma) {
+    return Math.sqrt(sigma * SQRT_PI);
+}
+/**
+ * Computes the l2_norm_denom hint with full SQ128x128 precision.
+ *
+ * Formula: sqrt(2 * sigma * sqrt(pi))
+ *
+ * Required for variance-change trades where the contract validates
+ * l2_norm_denom² == 2 * sigma * sqrt(pi) in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The l2_norm_denom hint, or null if computation fails
+ */
+export function computeL2NormDenomHint(sigma) {
+    const twoSigma = sigma.mul(TWO);
+    if (!twoSigma) {
+        return null;
+    }
+    const twoSigmaSqrtPi = twoSigma.mul(SQRT_PI_SQ);
+    if (!twoSigmaSqrtPi) {
+        return null;
+    }
+    return sqrtSQ128x128(twoSigmaSqrtPi);
+}
+/**
+ * Computes the backing_denom hint with full SQ128x128 precision.
+ *
+ * Formula: sqrt(sigma * sqrt(pi))
+ *
+ * Required for variance-change trades where the contract validates
+ * backing_denom² == sigma * sqrt(pi) in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The backing_denom hint, or null if computation fails
+ */
+export function computeBackingDenomHint(sigma) {
+    const sigmaSqrtPi = sigma.mul(SQRT_PI_SQ);
+    if (!sigmaSqrtPi) {
+        return null;
+    }
+    return sqrtSQ128x128(sigmaSqrtPi);
+}
+/**
+ * Computes hints with full SQ128x128 precision.
+ *
+ * Required for variance-change trades where the contract validates
+ * hint values in exact SQ128x128 arithmetic.
+ *
+ * @param sigma - The standard deviation as SQ128x128
+ * @returns The hints, or null if computation fails
+ */
+export function computeHints(sigma) {
+    const l2NormDenom = computeL2NormDenomHint(sigma);
+    const backingDenom = computeBackingDenomHint(sigma);
+    if (!l2NormDenom || !backingDenom) {
+        return null;
+    }
+    return {
+        l2_norm_denom: l2NormDenom.toRaw(),
+        backing_denom: backingDenom.toRaw(),
+    };
+}
+/**
+ * Computes hints from a numeric sigma value.
+ *
+ * Convenience wrapper that converts sigma to SQ128x128 and computes
+ * hints with full precision.
+ *
+ * @param sigma - The standard deviation (as number)
+ * @returns The hints
+ * @throws Error if sigma cannot be converted or hints cannot be computed
+ */
+export function computeHintsFromNumber(sigma) {
+    const sigmaSq = SQ128x128.fromNumber(sigma);
+    if (!sigmaSq) {
+        throw new Error(`Failed to convert sigma=${sigma} to SQ128x128`);
+    }
+    const hints = computeHints(sigmaSq);
+    if (!hints) {
+        throw new Error(`Failed to compute hints for sigma=${sigma}`);
+    }
+    return hints;
+}
+//# sourceMappingURL=hints.js.map

package/dist/utils/hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../../src/utils/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAa;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAgB;IACrD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,cAAc,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,aAAa,CAAC,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAgB;IACtD,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,aAAa,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,MAAM,WAAW,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAEpD,IAAI,CAAC,WAAW,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,aAAa,EAAE,WAAW,CAAC,KAAK,EAAE;QAClC,aAAa,EAAE,YAAY,CAAC,KAAK,EAAE;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,eAAe,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for The Situation SDK.
+ *
+ * @module utils
+ */
+export { DECIMALS_6, DECIMALS_18, fromTokenAmount, toTokenAmountDown, toTokenAmountUp, } from './decimal-scale';
+export { normalizeResponse, snakeToCamel } from './normalize';
+export { SQRT_PI, SQRT_PI_SQ, sqrtSQ128x128 } from './math';
+export { computeBackingDenomHint, computeBackingDenomHintNumber, computeHints, computeHintsFromNumber, computeL2NormDenomHint, computeL2NormDenomHintNumber, } from './hints';
+export { type AbiNormalDistribution, type AbiNormalSqrtHints, type AbiSQ128x128, createTradeEncoder, decodeAbiType, decodeNormalDistributionRawType, decodeNormalSqrtHintsRawType, decodeSQ128x128RawType, encodeAbiType, encodeNormalDistributionRawType, encodeNormalSqrtHintsRawType, encodeSQ128x128RawType, toAbiDistribution, toAbiHints, toAbiSQ128x128, TradeCalldataEncoder, } from './abi-encode';
+export { computeTwap, cumulative256ToNumber, cumulative256ToScaledBigInt, cumulativeDiff, formatCumulative256, } from './cumulative';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5D,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,kBAAkB,EAClB,aAAa,EACb,+BAA+B,EAC/B,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,+BAA+B,EAC/B,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for The Situation SDK.
+ *
+ * @module utils
+ */
+export { DECIMALS_6, DECIMALS_18, fromTokenAmount, toTokenAmountDown, toTokenAmountUp, } from './decimal-scale';
+export { normalizeResponse, snakeToCamel } from './normalize';
+export { SQRT_PI, SQRT_PI_SQ, sqrtSQ128x128 } from './math';
+export { computeBackingDenomHint, computeBackingDenomHintNumber, computeHints, computeHintsFromNumber, computeL2NormDenomHint, computeL2NormDenomHintNumber, } from './hints';
+export { createTradeEncoder, decodeAbiType, decodeNormalDistributionRawType, decodeNormalSqrtHintsRawType, decodeSQ128x128RawType, encodeAbiType, encodeNormalDistributionRawType, encodeNormalSqrtHintsRawType, encodeSQ128x128RawType, toAbiDistribution, toAbiHints, toAbiSQ128x128, TradeCalldataEncoder, } from './abi-encode';
+export { computeTwap, cumulative256ToNumber, cumulative256ToScaledBigInt, cumulativeDiff, formatCumulative256, } from './cumulative';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5D,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,SAAS,CAAC;AAEjB,OAAO,EAIL,kBAAkB,EAClB,aAAa,EACb,+BAA+B,EAC/B,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,+BAA+B,EAC/B,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/utils/math.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Mathematical utilities for SQ128x128 fixed-point arithmetic.
+ *
+ * @module
+ */
+import { SQ128x128 } from '../types/sq128';
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export declare const SQRT_PI: number;
+/**
+ * sqrt(π) as SQ128x128 constant.
+ *
+ * Computed with high precision: 1.7724538509055159...
+ */
+export declare const SQRT_PI_SQ: SQ128x128;
+/**
+ * Computes the square root of an SQ128x128 value using Newton-Raphson iteration.
+ *
+ * The Newton-Raphson formula for sqrt(n) is:
+ *   x_{k+1} = (x_k + n/x_k) / 2
+ *
+ * This converges quadratically, so ~10 iterations gives full 256-bit precision.
+ *
+ * @param n - The value to take the square root of (must be non-negative)
+ * @param maxIter - Maximum iterations (default: 20 for full precision)
+ * @returns The square root, or null if input is negative or computation fails
+ *
+ * @example
+ * ```typescript
+ * // Compute sqrt(2)
+ * const two = SQ128x128.fromNumber(2)!;
+ * const sqrtTwo = sqrtSQ128x128(two);
+ * console.log(sqrtTwo?.toNumber()); // ~1.4142135623730951
+ *
+ * // Compute hints for variance trades
+ * const twoSigmaSqrtPi = sigma.mul(TWO)!.mul(SQRT_PI_SQ)!;
+ * const l2NormDenom = sqrtSQ128x128(twoSigmaSqrtPi);
+ * ```
+ */
+export declare function sqrtSQ128x128(n: SQ128x128, maxIter?: number): SQ128x128 | null;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAa,MAAM,gBAAgB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,OAAO,QAAqB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,UAAU,WAAiC,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,SAAK,GAAG,SAAS,GAAG,IAAI,CAkD1E"}

package/dist/utils/math.js

@@ -0,0 +1,85 @@
+/**
+ * Mathematical utilities for SQ128x128 fixed-point arithmetic.
+ *
+ * @module
+ */
+import { SQ128x128, TWO, ZERO } from '../types/sq128';
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export const SQRT_PI = Math.sqrt(Math.PI);
+/**
+ * sqrt(π) as SQ128x128 constant.
+ *
+ * Computed with high precision: 1.7724538509055159...
+ */
+export const SQRT_PI_SQ = SQ128x128.fromNumber(SQRT_PI);
+/**
+ * Computes the square root of an SQ128x128 value using Newton-Raphson iteration.
+ *
+ * The Newton-Raphson formula for sqrt(n) is:
+ *   x_{k+1} = (x_k + n/x_k) / 2
+ *
+ * This converges quadratically, so ~10 iterations gives full 256-bit precision.
+ *
+ * @param n - The value to take the square root of (must be non-negative)
+ * @param maxIter - Maximum iterations (default: 20 for full precision)
+ * @returns The square root, or null if input is negative or computation fails
+ *
+ * @example
+ * ```typescript
+ * // Compute sqrt(2)
+ * const two = SQ128x128.fromNumber(2)!;
+ * const sqrtTwo = sqrtSQ128x128(two);
+ * console.log(sqrtTwo?.toNumber()); // ~1.4142135623730951
+ *
+ * // Compute hints for variance trades
+ * const twoSigmaSqrtPi = sigma.mul(TWO)!.mul(SQRT_PI_SQ)!;
+ * const l2NormDenom = sqrtSQ128x128(twoSigmaSqrtPi);
+ * ```
+ */
+export function sqrtSQ128x128(n, maxIter = 20) {
+    const raw = n.toRaw();
+    // sqrt(0) = 0
+    if (raw.limb0 === 0n && raw.limb1 === 0n && raw.limb2 === 0n && raw.limb3 === 0n) {
+        return ZERO;
+    }
+    // Negative numbers don't have real square roots
+    if (raw.neg) {
+        return null;
+    }
+    // Initial guess: use JavaScript sqrt for a good starting point
+    const floatGuess = Math.sqrt(n.toNumber());
+    let x = SQ128x128.fromNumber(floatGuess);
+    if (!x) {
+        return null;
+    }
+    // Newton-Raphson iteration: x = (x + n/x) / 2
+    for (let i = 0; i < maxIter; i++) {
+        const nDivX = n.div(x);
+        if (!nDivX) {
+            return null;
+        }
+        const sum = x.add(nDivX);
+        if (!sum) {
+            return null;
+        }
+        const next = sum.div(TWO);
+        if (!next) {
+            return null;
+        }
+        // Check for convergence (when x stops changing significantly)
+        const diff = next.sub(x);
+        if (diff) {
+            const diffRaw = diff.toRaw();
+            if (diffRaw.limb0 === 0n && diffRaw.limb1 === 0n) {
+                return next;
+            }
+        }
+        x = next;
+    }
+    return x;
+}
+//# sourceMappingURL=math.js.map

package/dist/utils/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,OAAO,CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,CAAY,EAAE,OAAO,GAAG,EAAE;IACtD,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;IAEtB,cAAc;IACd,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,IAAI,GAAG,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gDAAgD;IAChD,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+DAA+D;IAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8CAA8C;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,IAAI,CAAC;QACd,CAAC;QAED,8DAA8D;QAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,OAAO,CAAC,KAAK,KAAK,EAAE,IAAI,OAAO,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;gBACjD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,CAAC,GAAG,IAAI,CAAC;IACX,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/utils/normalize.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Response normalization utilities for The Situation SDK.
+ *
+ * Handles conversion of snake_case keys from Starknet contract responses
+ * to camelCase for TypeScript consumption.
+ *
+ * @module utils/normalize
+ */
+/**
+ * Converts a snake_case string to camelCase.
+ *
+ * @param str - The snake_case string to convert
+ * @returns The camelCase string
+ *
+ * @example
+ * ```typescript
+ * snakeToCamel('is_initialized'); // 'isInitialized'
+ * snakeToCamel('total_collateral_locked'); // 'totalCollateralLocked'
+ * ```
+ */
+export declare function snakeToCamel(str: string): string;
+/**
+ * Recursively normalizes a contract response by converting all snake_case
+ * keys to camelCase.
+ *
+ * This function handles:
+ * - Objects with nested properties
+ * - Arrays of objects
+ * - Primitive values (passed through unchanged)
+ * - null/undefined (passed through unchanged)
+ * - BigInt values (passed through unchanged)
+ *
+ * @param raw - The raw response from a Starknet contract call
+ * @returns The normalized response with camelCase keys
+ *
+ * @example
+ * ```typescript
+ * const raw = {
+ *   is_initialized: true,
+ *   settlement_value: { limb0: 0n, limb1: 0n }
+ * };
+ * const normalized = normalizeResponse(raw);
+ * // { isInitialized: true, settlementValue: { limb0: 0n, limb1: 0n } }
+ * ```
+ */
+export declare function normalizeResponse<T>(raw: unknown): T;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,CAuBpD"}