@the-situation/utils 0.5.0-alpha.0

package/dist/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 '@the-situation/core';
+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/hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../src/hints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAErD,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/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility functions for The Situation SDK.
+ *
+ * @module utils
+ */
+export { DECIMALS_6, DECIMALS_18, fromTokenAmount, toTokenAmountDown, toTokenAmountUp, } from './decimal-scale';
+export { buildApproveCall } from './erc20';
+export { toHexAddress } from './address';
+export { type CallRpc, toRpcCall, toRpcCalls } from './call-format';
+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/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/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,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,KAAK,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEpE,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/index.js

@@ -0,0 +1,15 @@
+/**
+ * Utility functions for The Situation SDK.
+ *
+ * @module utils
+ */
+export { DECIMALS_6, DECIMALS_18, fromTokenAmount, toTokenAmountDown, toTokenAmountUp, } from './decimal-scale';
+export { buildApproveCall } from './erc20';
+export { toHexAddress } from './address';
+export { toRpcCall, toRpcCalls } from './call-format';
+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/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/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,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAgB,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEpE,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/math.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Mathematical utilities for SQ128x128 fixed-point arithmetic.
+ *
+ * @module
+ */
+import { SQ128x128 } from '@the-situation/core';
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export declare const SQRT_PI: number;
+/**
+ * sqrt(π) as SQ128x128 constant.
+ *
+ * Uses the exact raw constant from Cairo contracts.
+ */
+export declare const SQRT_PI_SQ: SQ128x128;
+/**
+ * Computes floor(sqrt(n)) in SQ128x128 space with contract-equivalent semantics.
+ *
+ * @param n - The value to take the square root of (must be non-negative)
+ * @param maxIter - Deprecated legacy parameter (ignored)
+ * @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/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAQ,MAAM,qBAAqB,CAAC;AA2DtD;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,MAA2B,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,SAMrB,CAAC;AAEL;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,GAAE,MAAW,GAAG,SAAS,GAAG,IAAI,CAgBlF"}

package/dist/math.js

@@ -0,0 +1,105 @@
+/**
+ * Mathematical utilities for SQ128x128 fixed-point arithmetic.
+ *
+ * @module
+ */
+import { SQ128x128, ZERO } from '@the-situation/core';
+const LIMB_BITS = 64n;
+const LIMB_MASK = (1n << LIMB_BITS) - 1n;
+const SQRT_SCALE_SHIFT = 128n;
+// Matches contracts/src/market/normal/constants.cairo::SQRT_PI_RAW.
+const CONTRACT_SQRT_PI_RAW = {
+    limb0: 0xc3b0520d5db9383fn,
+    limb1: 0xc5bf891b4ef6aa79n,
+    limb2: 0x1n,
+    limb3: 0x0n,
+    neg: false,
+};
+function rawToMagnitude(raw) {
+    return (raw.limb0 +
+        (raw.limb1 << LIMB_BITS) +
+        (raw.limb2 << (LIMB_BITS * 2n)) +
+        (raw.limb3 << (LIMB_BITS * 3n)));
+}
+function magnitudeToRaw(magnitude) {
+    return {
+        limb0: magnitude & LIMB_MASK,
+        limb1: (magnitude >> LIMB_BITS) & LIMB_MASK,
+        limb2: (magnitude >> (LIMB_BITS * 2n)) & LIMB_MASK,
+        limb3: (magnitude >> (LIMB_BITS * 3n)) & LIMB_MASK,
+        neg: false,
+    };
+}
+/**
+ * Integer square root (floor): returns max r such that r^2 <= value.
+ */
+function integerSqrtFloor(value) {
+    if (value < 0n) {
+        throw new Error('integerSqrtFloor requires non-negative input');
+    }
+    if (value < 2n) {
+        return value;
+    }
+    const bitLength = BigInt(value.toString(2).length);
+    let x = 1n << ((bitLength + 1n) >> 1n);
+    while (true) {
+        const next = (x + (value / x)) >> 1n;
+        if (next >= x) {
+            return x;
+        }
+        x = next;
+    }
+}
+/**
+ * sqrt(π) ≈ 1.7724538509055159
+ *
+ * Used for L2 norm and lambda computation.
+ */
+export const SQRT_PI = Math.sqrt(Math.PI);
+/**
+ * sqrt(π) as SQ128x128 constant.
+ *
+ * Uses the exact raw constant from Cairo contracts.
+ */
+export const SQRT_PI_SQ = (() => {
+    const value = SQ128x128.fromRaw(CONTRACT_SQRT_PI_RAW);
+    if (!value) {
+        throw new Error('Invalid contract SQRT_PI raw constant');
+    }
+    return value;
+})();
+/**
+ * Computes floor(sqrt(n)) in SQ128x128 space with contract-equivalent semantics.
+ *
+ * @param n - The value to take the square root of (must be non-negative)
+ * @param maxIter - Deprecated legacy parameter (ignored)
+ * @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) {
+    void maxIter;
+    const raw = n.toRaw();
+    if (raw.neg) {
+        return null;
+    }
+    const magnitude = rawToMagnitude(raw);
+    if (magnitude === 0n) {
+        return ZERO;
+    }
+    // Contract uses integer sqrt over (raw << 128) and floor rounding.
+    const shifted = magnitude << SQRT_SCALE_SHIFT;
+    const rootMagnitude = integerSqrtFloor(shifted);
+    return SQ128x128.fromRaw(magnitudeToRaw(rootMagnitude));
+}
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

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

package/dist/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/normalize.d.ts.map

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

package/dist/normalize.js

@@ -0,0 +1,115 @@
+/**
+ * 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
+ */
+/**
+ * Checks if a value is a Cairo boolean enum and converts it to a JS boolean.
+ *
+ * Cairo's `core::bool` is an enum with variants `True` and `False`.
+ * starknet.js may return these as objects like `{ variant: 'True' }`,
+ * `{ 'True': {} }`, or `{ activeVariant: 'True' }`.
+ *
+ * @param value - The value to check
+ * @returns A JavaScript boolean if the value is a Cairo bool, undefined otherwise
+ */
+function tryParseCairoBool(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const obj = value;
+    // Pattern 1: { variant: 'True' } or { variant: 'False' }
+    if ('variant' in obj) {
+        const variant = obj['variant'];
+        if (variant === 'True' || variant === true)
+            return true;
+        if (variant === 'False' || variant === false)
+            return false;
+    }
+    // Pattern 2: { activeVariant: 'True' }
+    if ('activeVariant' in obj) {
+        const variant = obj['activeVariant'];
+        if (variant === 'True' || variant === true)
+            return true;
+        if (variant === 'False' || variant === false)
+            return false;
+    }
+    // Pattern 3: { True: {} } or { False: {} }
+    const keys = Object.keys(obj);
+    if (keys.length === 1) {
+        if (keys[0] === 'True')
+            return true;
+        if (keys[0] === 'False')
+            return false;
+    }
+    return undefined;
+}
+/**
+ * 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 function snakeToCamel(str) {
+    return str.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+}
+/**
+ * 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 function normalizeResponse(raw) {
+    // Pass through null/undefined
+    if (raw === null || raw === undefined) {
+        return raw;
+    }
+    // Pass through primitives (string, number, boolean, bigint, symbol)
+    if (typeof raw !== 'object') {
+        return raw;
+    }
+    // Handle arrays
+    if (Array.isArray(raw)) {
+        return raw.map((item) => normalizeResponse(item));
+    }
+    // Check if this object is a Cairo boolean enum
+    const boolValue = tryParseCairoBool(raw);
+    if (boolValue !== undefined) {
+        return boolValue;
+    }
+    // Handle objects
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const camelKey = snakeToCamel(key);
+        result[camelKey] = normalizeResponse(value);
+    }
+    return result;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,yDAAyD;IACzD,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACxD,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;IAC7D,CAAC;IAED,uCAAuC;IACvC,IAAI,eAAe,IAAI,GAAG,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;QACrC,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACxD,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;IAC7D,CAAC;IAED,2CAA2C;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACpC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAAI,GAAY;IAC/C,8BAA8B;IAC9B,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,GAAQ,CAAC;IAClB,CAAC;IAED,oEAAoE;IACpE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAQ,CAAC;IAClB,CAAC;IAED,gBAAgB;IAChB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAM,CAAC;IACzD,CAAC;IAED,+CAA+C;IAC/C,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,SAAc,CAAC;IACxB,CAAC;IAED,iBAAiB;IACjB,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,QAAQ,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAW,CAAC;AACrB,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@the-situation/utils",
+  "version": "0.5.0-alpha.0",
+  "description": "Utility functions for The Situation SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "test": "bun test src/ 2>/dev/null || true",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "dependencies": {
+    "@the-situation/core": "0.5.0-alpha.0",
+    "@the-situation/abi": "0.5.0-alpha.0",
+    "starknet": "^9.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/bun": "^1.1.0"
+  },
+  "license": "MIT"
+}