@the-situation/utils 0.5.0-alpha.0

package/dist/call-format.js

@@ -0,0 +1,77 @@
+/**
+ * Call format conversion utilities for wallet connector compatibility.
+ *
+ * starknet.js uses camelCase (`contractAddress`, `entrypoint`) but the
+ * Starknet JSON-RPC spec uses snake_case (`contract_address`, `entry_point`).
+ * Some wallet connectors (e.g., starknetkit) validate against the RPC format.
+ *
+ * @module
+ */
+import { num } from 'starknet';
+import { toHexAddress } from './address';
+/**
+ * Converts calldata values to hex strings.
+ */
+function normalizeCalldata(calldata) {
+    if (!calldata)
+        return [];
+    if (!Array.isArray(calldata))
+        return [];
+    return calldata.map((v) => {
+        if (typeof v === 'string') {
+            return v.startsWith('0x') ? v : num.toHex(v);
+        }
+        if (typeof v === 'bigint' || typeof v === 'number') {
+            return num.toHex(v);
+        }
+        return String(v);
+    });
+}
+/**
+ * Converts a starknet.js Call to snake_case RPC format.
+ *
+ * Also normalizes all addresses and calldata values to hex format
+ * for maximum wallet connector compatibility.
+ *
+ * Use this when your wallet connector (e.g., starknetkit) expects
+ * snake_case field names instead of starknet.js camelCase format.
+ *
+ * @param call - starknet.js Call object (camelCase)
+ * @returns Call in RPC format (snake_case) with hex-formatted values
+ *
+ * @example
+ * ```typescript
+ * import { toRpcCall } from '@the-situation/sdk';
+ *
+ * const trade = await market.prepareTrade({ targetMean: 105 });
+ * const rpcCalls = trade.calls.map(toRpcCall);
+ * await account.execute(rpcCalls);
+ * ```
+ */
+export function toRpcCall(call) {
+    return {
+        contract_address: toHexAddress(call.contractAddress),
+        entry_point: call.entrypoint,
+        calldata: normalizeCalldata(call.calldata),
+    };
+}
+/**
+ * Converts an array of starknet.js Calls to snake_case RPC format.
+ *
+ * Convenience wrapper for `calls.map(toRpcCall)`.
+ *
+ * @param calls - Array of starknet.js Call objects (camelCase)
+ * @returns Array of Calls in RPC format (snake_case)
+ *
+ * @example
+ * ```typescript
+ * import { toRpcCalls } from '@the-situation/sdk';
+ *
+ * const trade = await market.prepareTrade({ targetMean: 105 });
+ * await account.execute(toRpcCalls(trade.calls));
+ * ```
+ */
+export function toRpcCalls(calls) {
+    return calls.map(toRpcCall);
+}
+//# sourceMappingURL=call-format.js.map

package/dist/call-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-format.js","sourceRoot":"","sources":["../src/call-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAa,GAAG,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAczC;;GAEG;AACH,SAAS,iBAAiB,CAAC,QAAiB;IAC1C,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAU;IAClC,OAAO;QACL,gBAAgB,EAAE,YAAY,CAAC,IAAI,CAAC,eAAe,CAAC;QACpD,WAAW,EAAE,IAAI,CAAC,UAAU;QAC5B,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC"}

package/dist/cumulative.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Cumulative256 utilities for Oracle TWAP calculations.
+ *
+ * The Oracle stores cumulative mean and variance values as Cumulative256,
+ * which has the same structure as SQ128x128Raw but represents accumulated
+ * time-weighted values.
+ *
+ * TWAP calculation:
+ *   average = (cumulative_end - cumulative_start) / (time_end - time_start)
+ *
+ * @module
+ */
+import type { Cumulative256Raw } from '@the-situation/abi';
+/**
+ * Converts a Cumulative256Raw to its scaled bigint representation.
+ *
+ * The returned value is scaled by 2^128 (same as SQ128x128).
+ *
+ * @param raw - The raw cumulative value from the Oracle contract
+ * @returns The signed scaled bigint
+ */
+export declare function cumulative256ToScaledBigInt(raw: Cumulative256Raw): bigint;
+/**
+ * Converts a Cumulative256Raw to a JavaScript number.
+ *
+ * Note: May lose precision for very large cumulative values.
+ * Use `cumulative256ToScaledBigInt` for precise calculations.
+ *
+ * @param raw - The raw cumulative value from the Oracle contract
+ * @returns The numeric value (unscaled)
+ */
+export declare function cumulative256ToNumber(raw: Cumulative256Raw): number;
+/**
+ * Computes the difference between two cumulative values.
+ *
+ * @param end - The ending cumulative value
+ * @param start - The starting cumulative value
+ * @returns The difference as a scaled bigint
+ */
+export declare function cumulativeDiff(end: Cumulative256Raw, start: Cumulative256Raw): bigint;
+/**
+ * Computes the TWAP (Time-Weighted Average Price) from cumulative values.
+ *
+ * TWAP = (cumulative_end - cumulative_start) / (time_end - time_start)
+ *
+ * @param startSnapshot - Snapshot at period start (timestamp and cumulative)
+ * @param endSnapshot - Snapshot at period end (timestamp and cumulative)
+ * @param field - Which cumulative field to use ('mean' or 'variance')
+ * @returns The computed TWAP as a number, or null if time difference is zero
+ *
+ * @example
+ * ```typescript
+ * const twapMean = computeTwap(
+ *   { blockTimestamp: 100n, meanCumulative: start },
+ *   { blockTimestamp: 200n, meanCumulative: end },
+ *   'mean'
+ * );
+ * ```
+ */
+export declare function computeTwap(startSnapshot: {
+    blockTimestamp: bigint;
+    meanCumulative: Cumulative256Raw;
+    varianceCumulative: Cumulative256Raw;
+}, endSnapshot: {
+    blockTimestamp: bigint;
+    meanCumulative: Cumulative256Raw;
+    varianceCumulative: Cumulative256Raw;
+}, field: 'mean' | 'variance'): number | null;
+/**
+ * Formats a Cumulative256Raw for logging/debugging.
+ *
+ * @param raw - The raw cumulative value
+ * @param label - Optional label for the output
+ * @returns Formatted string showing limbs and numeric value
+ */
+export declare function formatCumulative256(raw: Cumulative256Raw, label?: string): string;
+//# sourceMappingURL=cumulative.d.ts.map

package/dist/cumulative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cumulative.d.ts","sourceRoot":"","sources":["../src/cumulative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAY3D;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAGzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAErF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,gBAAgB,CAAC;IAAC,kBAAkB,EAAE,gBAAgB,CAAA;CAAE,EACjH,WAAW,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,gBAAgB,CAAC;IAAC,kBAAkB,EAAE,gBAAgB,CAAA;CAAE,EAC/G,KAAK,EAAE,MAAM,GAAG,UAAU,GACzB,MAAM,GAAG,IAAI,CAgBf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjF"}

package/dist/cumulative.js

@@ -0,0 +1,102 @@
+/**
+ * Cumulative256 utilities for Oracle TWAP calculations.
+ *
+ * The Oracle stores cumulative mean and variance values as Cumulative256,
+ * which has the same structure as SQ128x128Raw but represents accumulated
+ * time-weighted values.
+ *
+ * TWAP calculation:
+ *   average = (cumulative_end - cumulative_start) / (time_end - time_start)
+ *
+ * @module
+ */
+/** 2^128 - the scaling factor for SQ128x128 fractional part */
+const SCALE = 1n << 128n;
+/**
+ * Reconstructs a 256-bit magnitude from four 64-bit limbs.
+ */
+function fromLimbs(limb0, limb1, limb2, limb3) {
+    return limb0 + (limb1 << 64n) + (limb2 << 128n) + (limb3 << 192n);
+}
+/**
+ * Converts a Cumulative256Raw to its scaled bigint representation.
+ *
+ * The returned value is scaled by 2^128 (same as SQ128x128).
+ *
+ * @param raw - The raw cumulative value from the Oracle contract
+ * @returns The signed scaled bigint
+ */
+export function cumulative256ToScaledBigInt(raw) {
+    const magnitude = fromLimbs(raw.limb0, raw.limb1, raw.limb2, raw.limb3);
+    return raw.neg ? -magnitude : magnitude;
+}
+/**
+ * Converts a Cumulative256Raw to a JavaScript number.
+ *
+ * Note: May lose precision for very large cumulative values.
+ * Use `cumulative256ToScaledBigInt` for precise calculations.
+ *
+ * @param raw - The raw cumulative value from the Oracle contract
+ * @returns The numeric value (unscaled)
+ */
+export function cumulative256ToNumber(raw) {
+    const magnitude = fromLimbs(raw.limb0, raw.limb1, raw.limb2, raw.limb3);
+    const value = Number(magnitude) / Number(SCALE);
+    return raw.neg ? -value : value;
+}
+/**
+ * Computes the difference between two cumulative values.
+ *
+ * @param end - The ending cumulative value
+ * @param start - The starting cumulative value
+ * @returns The difference as a scaled bigint
+ */
+export function cumulativeDiff(end, start) {
+    return cumulative256ToScaledBigInt(end) - cumulative256ToScaledBigInt(start);
+}
+/**
+ * Computes the TWAP (Time-Weighted Average Price) from cumulative values.
+ *
+ * TWAP = (cumulative_end - cumulative_start) / (time_end - time_start)
+ *
+ * @param startSnapshot - Snapshot at period start (timestamp and cumulative)
+ * @param endSnapshot - Snapshot at period end (timestamp and cumulative)
+ * @param field - Which cumulative field to use ('mean' or 'variance')
+ * @returns The computed TWAP as a number, or null if time difference is zero
+ *
+ * @example
+ * ```typescript
+ * const twapMean = computeTwap(
+ *   { blockTimestamp: 100n, meanCumulative: start },
+ *   { blockTimestamp: 200n, meanCumulative: end },
+ *   'mean'
+ * );
+ * ```
+ */
+export function computeTwap(startSnapshot, endSnapshot, field) {
+    const timeDiff = endSnapshot.blockTimestamp - startSnapshot.blockTimestamp;
+    if (timeDiff === 0n) {
+        return null;
+    }
+    const startCumulative = field === 'mean' ? startSnapshot.meanCumulative : startSnapshot.varianceCumulative;
+    const endCumulative = field === 'mean' ? endSnapshot.meanCumulative : endSnapshot.varianceCumulative;
+    const diff = cumulativeDiff(endCumulative, startCumulative);
+    // TWAP = diff / timeDiff
+    // Since diff is scaled by 2^128, we need to unscale: (diff / 2^128) / timeDiff
+    // = diff / (2^128 * timeDiff)
+    const scaledTimeDiff = SCALE * timeDiff;
+    return Number(diff) / Number(scaledTimeDiff);
+}
+/**
+ * Formats a Cumulative256Raw for logging/debugging.
+ *
+ * @param raw - The raw cumulative value
+ * @param label - Optional label for the output
+ * @returns Formatted string showing limbs and numeric value
+ */
+export function formatCumulative256(raw, label) {
+    const numValue = cumulative256ToNumber(raw);
+    const prefix = label ? `${label}: ` : '';
+    return `${prefix}{ limb0: ${raw.limb0}, limb1: ${raw.limb1}, limb2: ${raw.limb2}, limb3: ${raw.limb3}, neg: ${raw.neg} } ≈ ${numValue.toFixed(6)}`;
+}
+//# sourceMappingURL=cumulative.js.map

package/dist/cumulative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cumulative.js","sourceRoot":"","sources":["../src/cumulative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,+DAA+D;AAC/D,MAAM,KAAK,GAAG,EAAE,IAAI,IAAI,CAAC;AAEzB;;GAEG;AACH,SAAS,SAAS,CAAC,KAAa,EAAE,KAAa,EAAE,KAAa,EAAE,KAAa;IAC3E,OAAO,KAAK,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAqB;IAC/D,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACxE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAqB,EAAE,KAAuB;IAC3E,OAAO,2BAA2B,CAAC,GAAG,CAAC,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,WAAW,CACzB,aAAiH,EACjH,WAA+G,EAC/G,KAA0B;IAE1B,MAAM,QAAQ,GAAG,WAAW,CAAC,cAAc,GAAG,aAAa,CAAC,cAAc,CAAC;IAC3E,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,kBAAkB,CAAC;IAC3G,MAAM,aAAa,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,kBAAkB,CAAC;IAErG,MAAM,IAAI,GAAG,cAAc,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAE5D,yBAAyB;IACzB,+EAA+E;IAC/E,8BAA8B;IAC9B,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,CAAC;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAqB,EAAE,KAAc;IACvE,MAAM,QAAQ,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACzC,OAAO,GAAG,MAAM,YAAY,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,KAAK,UAAU,GAAG,CAAC,GAAG,QAAQ,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACrJ,CAAC"}

package/dist/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 '@the-situation/core';
+/** 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/decimal-scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal-scale.d.ts","sourceRoot":"","sources":["../src/decimal-scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,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/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 '@the-situation/core';
+/** 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/decimal-scale.js.map

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

package/dist/erc20.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ERC20 utilities for building token approval calls.
+ *
+ * @module
+ */
+import { type Call } from 'starknet';
+/**
+ * Builds an ERC20 approve call for the given token, spender, and amount.
+ *
+ * Includes a 5% buffer on the approve amount to handle rounding differences
+ * between SDK calculations and contract execution.
+ *
+ * @param tokenAddress - The ERC20 token contract address
+ * @param spender - The address to approve spending (e.g., the market contract)
+ * @param amount - The amount to approve (raw token amount with decimals)
+ * @param bufferPercent - Buffer percentage to add to amount (default: 5%)
+ * @returns Call object for batching with account.execute()
+ *
+ * @example
+ * ```typescript
+ * const approveCall = buildApproveCall(usdcAddress, marketAddress, 1_000_000n);
+ * await account.execute([approveCall, tradeCall]);
+ * ```
+ */
+export declare function buildApproveCall(tokenAddress: string, spender: string, amount: bigint, bufferPercent?: number): Call;
+//# sourceMappingURL=erc20.d.ts.map

package/dist/erc20.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc20.d.ts","sourceRoot":"","sources":["../src/erc20.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAc,MAAM,UAAU,CAAC;AAMjD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,aAAa,GAAE,MAAuC,GACrD,IAAI,CAcN"}

package/dist/erc20.js

@@ -0,0 +1,41 @@
+/**
+ * ERC20 utilities for building token approval calls.
+ *
+ * @module
+ */
+import { cairo, num } from 'starknet';
+import { toHexAddress } from './address';
+/** Default buffer percentage for approve amounts (5%) */
+const DEFAULT_APPROVE_BUFFER_PERCENT = 5;
+/**
+ * Builds an ERC20 approve call for the given token, spender, and amount.
+ *
+ * Includes a 5% buffer on the approve amount to handle rounding differences
+ * between SDK calculations and contract execution.
+ *
+ * @param tokenAddress - The ERC20 token contract address
+ * @param spender - The address to approve spending (e.g., the market contract)
+ * @param amount - The amount to approve (raw token amount with decimals)
+ * @param bufferPercent - Buffer percentage to add to amount (default: 5%)
+ * @returns Call object for batching with account.execute()
+ *
+ * @example
+ * ```typescript
+ * const approveCall = buildApproveCall(usdcAddress, marketAddress, 1_000_000n);
+ * await account.execute([approveCall, tradeCall]);
+ * ```
+ */
+export function buildApproveCall(tokenAddress, spender, amount, bufferPercent = DEFAULT_APPROVE_BUFFER_PERCENT) {
+    // Apply buffer to approve amount
+    const bufferedAmount = amount + (amount * BigInt(bufferPercent)) / 100n;
+    const uint256 = cairo.uint256(bufferedAmount);
+    // Normalize addresses to hex format
+    const hexToken = toHexAddress(tokenAddress);
+    const hexSpender = toHexAddress(spender);
+    return {
+        contractAddress: hexToken,
+        entrypoint: 'approve',
+        calldata: [hexSpender, num.toHex(uint256.low), num.toHex(uint256.high)],
+    };
+}
+//# sourceMappingURL=erc20.js.map

package/dist/erc20.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc20.js","sourceRoot":"","sources":["../src/erc20.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAa,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,yDAAyD;AACzD,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAAoB,EACpB,OAAe,EACf,MAAc,EACd,gBAAwB,8BAA8B;IAEtD,iCAAiC;IACjC,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC;IACxE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAE9C,oCAAoC;IACpC,MAAM,QAAQ,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAEzC,OAAO;QACL,eAAe,EAAE,QAAQ;QACzB,UAAU,EAAE,SAAS;QACrB,QAAQ,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/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 '@the-situation/core';
+import type { NormalSqrtHintsRaw } from '@the-situation/core';
+/**
+ * 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/hints.d.ts.map

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