@lagoon-protocol/lagoon-mcp 0.1.0

package/dist/sdk/apr-service.d.ts

@@ -0,0 +1,101 @@
+/**
+ * APR Service Module
+ *
+ * Production-validated APR calculations using Lagoon SDK.
+ * Patterns from frontend-dapp-v2/src/lib/manage/apr-data-service.ts
+ *
+ * @module sdk/apr-service
+ */
+import type { VaultData } from '../graphql/fragments/index.js';
+import type { Vault } from '../types/generated.js';
+/**
+ * Period summary structure from GraphQL
+ */
+export interface PeriodSummary {
+    timestamp: string;
+    totalAssetsAtStart: string;
+    totalSupplyAtStart: string;
+}
+/**
+ * APR historical data point
+ */
+export interface APRDataPoint {
+    timestamp: number;
+    pricePerShare: bigint;
+}
+/**
+ * APR historical data structure
+ */
+export interface APRHistoricalData {
+    thirtyDay?: APRDataPoint;
+    inception?: APRDataPoint;
+}
+/**
+ * Transform period summaries to APR historical data
+ *
+ * Production pattern from frontend-dapp-v2/src/lib/manage/apr-data-service.ts
+ *
+ * Extracts 30-day and inception data points using SDK's getLastPeriodSummaryInDuration.
+ * Gracefully handles new vaults with no history (returns empty object).
+ *
+ * @param periodSummaries - Historical period summaries from GraphQL
+ * @param vault - Vault data for decimal calculations
+ * @returns APR historical data with optional 30-day and inception points
+ *
+ * @example
+ * ```typescript
+ * const aprData = transformPeriodSummariesToAPRData(periodSummaries, vault);
+ *
+ * if (aprData.thirtyDay) {
+ *   console.log('30-day price:', aprData.thirtyDay.pricePerShare);
+ *   console.log('Timestamp:', aprData.thirtyDay.timestamp);
+ * }
+ * ```
+ */
+export declare function transformPeriodSummariesToAPRData(periodSummaries: PeriodSummary[], vault: Vault | VaultData): APRHistoricalData;
+/**
+ * Calculate APR from price per share change
+ *
+ * Computes annualized percentage return based on price per share change over time.
+ * Uses precise BigInt math to avoid floating-point errors.
+ *
+ * @param oldPrice - Historical price per share
+ * @param newPrice - Current price per share
+ * @param daysElapsed - Number of days between prices
+ * @returns APR as percentage (e.g., 15.5 for 15.5%)
+ *
+ * @example
+ * ```typescript
+ * const apr = calculateAPRFromPriceChange(
+ *   1000000n,  // 1.0 USDC (6 decimals)
+ *   1025000n,  // 1.025 USDC
+ *   30         // 30 days
+ * );
+ * // => ~30.42% APR (2.5% in 30 days, annualized)
+ * ```
+ */
+export declare function calculateAPRFromPriceChange(oldPrice: bigint, newPrice: bigint, daysElapsed: number): number;
+/**
+ * Calculate current APR from historical data
+ *
+ * Convenience function that combines APR historical data with current price
+ * to compute 30-day and inception APR values.
+ *
+ * @param aprData - APR historical data with 30-day and/or inception points
+ * @param currentPricePerShare - Current price per share
+ * @returns Object with 30-day and inception APR values (undefined if no data)
+ *
+ * @example
+ * ```typescript
+ * const aprs = calculateCurrentAPR(aprData, currentPrice);
+ *
+ * if (aprs.thirtyDay !== undefined) {
+ *   console.log(`30-day APR: ${aprs.thirtyDay.toFixed(2)}%`);
+ * }
+ * ```
+ */
+export declare function calculateCurrentAPR(aprData: APRHistoricalData, currentPricePerShare: bigint): {
+    thirtyDay?: number;
+    inception?: number;
+};
+//# sourceMappingURL=apr-service.d.ts.map

package/dist/sdk/apr-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apr-service.d.ts","sourceRoot":"","sources":["../../src/sdk/apr-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAOnD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAWD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iCAAiC,CAC/C,eAAe,EAAE,aAAa,EAAE,EAChC,KAAK,EAAE,KAAK,GAAG,SAAS,GACvB,iBAAiB,CAqDnB;AAoCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,CAaR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,oBAAoB,EAAE,MAAM,GAC3B;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CA4B5C"}

package/dist/sdk/apr-service.js

@@ -0,0 +1,175 @@
+/**
+ * APR Service Module
+ *
+ * Production-validated APR calculations using Lagoon SDK.
+ * Patterns from frontend-dapp-v2/src/lib/manage/apr-data-service.ts
+ *
+ * @module sdk/apr-service
+ */
+import * as LagoonCore from '@lagoon-protocol/v0-core';
+import { getLastPeriodSummaryInDuration } from '@lagoon-protocol/v0-computation';
+/**
+ * Duration constants (seconds)
+ */
+const THIRTY_DAYS_SECONDS = 30 * 24 * 60 * 60;
+/**
+ * Transform period summaries to APR historical data
+ *
+ * Production pattern from frontend-dapp-v2/src/lib/manage/apr-data-service.ts
+ *
+ * Extracts 30-day and inception data points using SDK's getLastPeriodSummaryInDuration.
+ * Gracefully handles new vaults with no history (returns empty object).
+ *
+ * @param periodSummaries - Historical period summaries from GraphQL
+ * @param vault - Vault data for decimal calculations
+ * @returns APR historical data with optional 30-day and inception points
+ *
+ * @example
+ * ```typescript
+ * const aprData = transformPeriodSummariesToAPRData(periodSummaries, vault);
+ *
+ * if (aprData.thirtyDay) {
+ *   console.log('30-day price:', aprData.thirtyDay.pricePerShare);
+ *   console.log('Timestamp:', aprData.thirtyDay.timestamp);
+ * }
+ * ```
+ */
+export function transformPeriodSummariesToAPRData(periodSummaries, vault) {
+    // Graceful degradation for new vaults with no history
+    if (!periodSummaries?.length) {
+        return {};
+    }
+    try {
+        // Transform to SDK format (BigInt timestamps for getLastPeriodSummaryInDuration)
+        const sdkPeriodSummaries = periodSummaries.map((ps) => ({
+            ...ps,
+            timestamp: BigInt(parseInt(ps.timestamp)),
+        }));
+        const result = {};
+        // Find 30-day data point using SDK function
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call -- SDK function lacks proper type exports
+        const thirtyDayPeriod = getLastPeriodSummaryInDuration(sdkPeriodSummaries, THIRTY_DAYS_SECONDS);
+        if (thirtyDayPeriod && typeof thirtyDayPeriod.timestamp === 'bigint') {
+            // Find original period summary for conversion
+            const original = periodSummaries.find((ps) => ps.timestamp === thirtyDayPeriod.timestamp.toString());
+            if (original) {
+                result.thirtyDay = {
+                    timestamp: Number(thirtyDayPeriod.timestamp),
+                    pricePerShare: calculatePricePerShareFromPeriod(original, vault),
+                };
+            }
+        }
+        // Find inception (oldest) data point
+        const sorted = [...periodSummaries].sort((a, b) => parseInt(a.timestamp) - parseInt(b.timestamp));
+        if (sorted[0]) {
+            result.inception = {
+                timestamp: parseInt(sorted[0].timestamp),
+                pricePerShare: calculatePricePerShareFromPeriod(sorted[0], vault),
+            };
+        }
+        return result;
+    }
+    catch (error) {
+        console.error('Failed to transform period summaries:', error);
+        return {}; // Graceful degradation on error
+    }
+}
+/**
+ * Calculate price per share from period summary
+ *
+ * Internal helper using VaultUtils.convertToAssets for protocol-accurate calculation.
+ * Matches smart contract pricing logic.
+ *
+ * @param period - Period summary with historical vault state
+ * @param vault - Vault data for decimal configuration
+ * @returns Price per share in asset decimals
+ *
+ * @internal
+ */
+function calculatePricePerShareFromPeriod(period, vault) {
+    const vaultDecimals = vault.decimals ?? 18;
+    const assetDecimals = vault.asset.decimals;
+    const decimalsOffset = vaultDecimals - assetDecimals;
+    try {
+        return LagoonCore.VaultUtils.convertToAssets(BigInt(1e18), // 1 share in wei (18 decimals)
+        {
+            totalAssets: BigInt(period.totalAssetsAtStart),
+            totalSupply: BigInt(period.totalSupplyAtStart),
+            decimalsOffset: BigInt(decimalsOffset),
+        }, 'Down' // Round down for conservative pricing
+        );
+    }
+    catch (error) {
+        // Fallback to 1:1 ratio if calculation fails (e.g., zero supply)
+        console.warn('Price per share calculation failed, using 1:1 ratio:', error);
+        return BigInt(10 ** assetDecimals);
+    }
+}
+/**
+ * Calculate APR from price per share change
+ *
+ * Computes annualized percentage return based on price per share change over time.
+ * Uses precise BigInt math to avoid floating-point errors.
+ *
+ * @param oldPrice - Historical price per share
+ * @param newPrice - Current price per share
+ * @param daysElapsed - Number of days between prices
+ * @returns APR as percentage (e.g., 15.5 for 15.5%)
+ *
+ * @example
+ * ```typescript
+ * const apr = calculateAPRFromPriceChange(
+ *   1000000n,  // 1.0 USDC (6 decimals)
+ *   1025000n,  // 1.025 USDC
+ *   30         // 30 days
+ * );
+ * // => ~30.42% APR (2.5% in 30 days, annualized)
+ * ```
+ */
+export function calculateAPRFromPriceChange(oldPrice, newPrice, daysElapsed) {
+    if (oldPrice === 0n || daysElapsed <= 0) {
+        return 0;
+    }
+    // Calculate percentage change with 10000x scaling for precision
+    const priceChange = ((newPrice - oldPrice) * 10000n) / oldPrice;
+    // Annualize: multiply by (365 / daysElapsed)
+    const annualizedChange = (Number(priceChange) * 365) / daysElapsed;
+    // Convert from basis points to percentage (divide by 100)
+    return annualizedChange / 100;
+}
+/**
+ * Calculate current APR from historical data
+ *
+ * Convenience function that combines APR historical data with current price
+ * to compute 30-day and inception APR values.
+ *
+ * @param aprData - APR historical data with 30-day and/or inception points
+ * @param currentPricePerShare - Current price per share
+ * @returns Object with 30-day and inception APR values (undefined if no data)
+ *
+ * @example
+ * ```typescript
+ * const aprs = calculateCurrentAPR(aprData, currentPrice);
+ *
+ * if (aprs.thirtyDay !== undefined) {
+ *   console.log(`30-day APR: ${aprs.thirtyDay.toFixed(2)}%`);
+ * }
+ * ```
+ */
+export function calculateCurrentAPR(aprData, currentPricePerShare) {
+    const result = {};
+    if (aprData.thirtyDay) {
+        const daysElapsed = (Date.now() / 1000 - aprData.thirtyDay.timestamp) / (24 * 60 * 60);
+        if (daysElapsed > 0) {
+            result.thirtyDay = calculateAPRFromPriceChange(aprData.thirtyDay.pricePerShare, currentPricePerShare, daysElapsed);
+        }
+    }
+    if (aprData.inception) {
+        const daysElapsed = (Date.now() / 1000 - aprData.inception.timestamp) / (24 * 60 * 60);
+        if (daysElapsed > 0) {
+            result.inception = calculateAPRFromPriceChange(aprData.inception.pricePerShare, currentPricePerShare, daysElapsed);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=apr-service.js.map

package/dist/sdk/apr-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apr-service.js","sourceRoot":"","sources":["../../src/sdk/apr-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AAIjF;;GAEG;AACH,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAoC9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iCAAiC,CAC/C,eAAgC,EAChC,KAAwB;IAExB,sDAAsD;IACtD,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,iFAAiF;QACjF,MAAM,kBAAkB,GAAuB,eAAe,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC1E,GAAG,EAAE;YACL,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;SAC1C,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAsB,EAAE,CAAC;QAErC,4CAA4C;QAC5C,uGAAuG;QACvG,MAAM,eAAe,GAAG,8BAA8B,CACpD,kBAAkB,EAClB,mBAAmB,CACY,CAAC;QAElC,IAAI,eAAe,IAAI,OAAO,eAAe,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YACrE,8CAA8C;YAC9C,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CACnC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,KAAK,eAAe,CAAC,SAAS,CAAC,QAAQ,EAAE,CAC9D,CAAC;YAEF,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,SAAS,GAAG;oBACjB,SAAS,EAAE,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC;oBAC5C,aAAa,EAAE,gCAAgC,CAAC,QAAQ,EAAE,KAAkB,CAAC;iBAC9E,CAAC;YACJ,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,MAAM,MAAM,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,CACtC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CACxD,CAAC;QAEF,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACd,MAAM,CAAC,SAAS,GAAG;gBACjB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACxC,aAAa,EAAE,gCAAgC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAkB,CAAC;aAC/E,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,CAAC,gCAAgC;IAC7C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gCAAgC,CAAC,MAAqB,EAAE,KAAgB;IAC/E,MAAM,aAAa,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC3C,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC3C,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,CAAC;IAErD,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,UAAU,CAAC,eAAe,CAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,+BAA+B;QAC7C;YACE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC;YAC9C,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC;YAC9C,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC;SACvC,EACD,MAAM,CAAC,sCAAsC;SAC9C,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iEAAiE;QACjE,OAAO,CAAC,IAAI,CAAC,sDAAsD,EAAE,KAAK,CAAC,CAAC;QAC5E,OAAO,MAAM,CAAC,EAAE,IAAI,aAAa,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAgB,EAChB,QAAgB,EAChB,WAAmB;IAEnB,IAAI,QAAQ,KAAK,EAAE,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,gEAAgE;IAChE,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,GAAG,QAAQ,CAAC;IAEhE,6CAA6C;IAC7C,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC,GAAG,WAAW,CAAC;IAEnE,0DAA0D;IAC1D,OAAO,gBAAgB,GAAG,GAAG,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA0B,EAC1B,oBAA4B;IAE5B,MAAM,MAAM,GAA+C,EAAE,CAAC;IAE9D,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QAEvF,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,SAAS,GAAG,2BAA2B,CAC5C,OAAO,CAAC,SAAS,CAAC,aAAa,EAC/B,oBAAoB,EACpB,WAAW,CACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QAEvF,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,SAAS,GAAG,2BAA2B,CAC5C,OAAO,CAAC,SAAS,CAAC,aAAa,EAC/B,oBAAoB,EACpB,WAAW,CACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/sdk/math-utils.d.ts

@@ -0,0 +1,138 @@
+/**
+ * BigInt Mathematical Utilities
+ *
+ * Production-validated utilities for safe BigInt operations and serialization.
+ * Patterns from frontend-dapp-v2 ensuring no precision loss.
+ *
+ * @module sdk/math-utils
+ */
+/**
+ * Safely serialize BigInt values to JSON
+ *
+ * Production pattern from frontend-dapp-v2 for JSON serialization of BigInt values.
+ * Prevents TypeError: Do not know how to serialize a BigInt.
+ *
+ * @param _key - JSON key (unused but required by replacer signature)
+ * @param value - Value to serialize
+ * @returns Serializable value (BigInt → string, others unchanged)
+ *
+ * @example
+ * ```typescript
+ * const data = { amount: 1000000000000000000n };
+ * JSON.stringify(data, bigIntReplacer);
+ * // => '{"amount":"1000000000000000000"}'
+ * ```
+ */
+export declare function bigIntReplacer(_key: string, value: unknown): unknown;
+/**
+ * Stringify object with BigInt support
+ *
+ * Convenience wrapper for JSON.stringify with automatic BigInt handling.
+ * Uses 2-space indentation for readability.
+ *
+ * @param obj - Object to stringify (may contain BigInt values)
+ * @returns JSON string with BigInt values as strings
+ *
+ * @example
+ * ```typescript
+ * safeBigIntStringify({ balance: 1000000000000000000n });
+ * // => '{\n  "balance": "1000000000000000000"\n}'
+ * ```
+ */
+export declare function safeBigIntStringify(obj: unknown): string;
+/**
+ * Format BigInt to human-readable decimal string
+ *
+ * Converts BigInt wei amounts to decimal representation with proper decimal placement.
+ * No floating-point operations - pure integer math for precision.
+ *
+ * @param value - BigInt value in smallest unit (e.g., wei)
+ * @param decimals - Number of decimal places (e.g., 18 for ether)
+ * @returns Formatted decimal string (e.g., "1.500000000000000000")
+ *
+ * @example
+ * ```typescript
+ * formatBigInt(1500000000000000000n, 18);
+ * // => "1.500000000000000000"
+ *
+ * formatBigInt(1000000n, 6);
+ * // => "1.000000"
+ * ```
+ */
+export declare function formatBigInt(value: bigint, decimals: number): string;
+/**
+ * Parse decimal string to BigInt
+ *
+ * Converts human-readable decimal to BigInt in smallest unit.
+ * Validates input format and handles edge cases safely.
+ *
+ * @param value - Decimal string (e.g., "1.5" or "1500")
+ * @param decimals - Target decimal places
+ * @returns BigInt value in smallest unit
+ * @throws {Error} If value format is invalid
+ *
+ * @example
+ * ```typescript
+ * parseBigInt("1.5", 18);
+ * // => 1500000000000000000n
+ *
+ * parseBigInt("1000000", 6);
+ * // => 1000000000000n
+ * ```
+ */
+export declare function parseBigInt(value: string, decimals: number): bigint;
+/**
+ * Validate BigInt string format
+ *
+ * Checks if a string represents a valid BigInt (unsigned integer).
+ * Returns false for negative numbers, decimals, or invalid formats.
+ *
+ * @param value - String to validate
+ * @returns true if valid BigInt string, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidBigIntString("1000000000000000000"); // => true
+ * isValidBigIntString("1.5");                  // => false
+ * isValidBigIntString("-100");                 // => false
+ * isValidBigIntString("abc");                  // => false
+ * ```
+ */
+export declare function isValidBigIntString(value: string): boolean;
+/**
+ * Calculate percentage change between two BigInt values
+ *
+ * Computes percentage change with high precision using integer math.
+ * Returns result scaled to basis points (10000 = 100.00%).
+ *
+ * @param oldValue - Original value
+ * @param newValue - New value
+ * @returns Percentage change in basis points (e.g., 250 = 2.50%)
+ *
+ * @example
+ * ```typescript
+ * percentageChange(1000000n, 1025000n);
+ * // => 250 (2.50% increase)
+ *
+ * percentageChange(1000000n, 975000n);
+ * // => -250 (2.50% decrease)
+ * ```
+ */
+export declare function percentageChange(oldValue: bigint, newValue: bigint): number;
+/**
+ * Format percentage change for display
+ *
+ * Converts basis points to human-readable percentage string.
+ *
+ * @param basisPoints - Percentage change in basis points
+ * @returns Formatted percentage string with sign and symbol
+ *
+ * @example
+ * ```typescript
+ * formatPercentageChange(250);   // => "+2.50%"
+ * formatPercentageChange(-250);  // => "-2.50%"
+ * formatPercentageChange(0);     // => "0.00%"
+ * ```
+ */
+export declare function formatPercentageChange(basisPoints: number): string;
+//# sourceMappingURL=math-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"math-utils.d.ts","sourceRoot":"","sources":["../../src/sdk/math-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiBpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwCnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAkB1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAalE"}

package/dist/sdk/math-utils.js

@@ -0,0 +1,218 @@
+/**
+ * BigInt Mathematical Utilities
+ *
+ * Production-validated utilities for safe BigInt operations and serialization.
+ * Patterns from frontend-dapp-v2 ensuring no precision loss.
+ *
+ * @module sdk/math-utils
+ */
+/**
+ * Safely serialize BigInt values to JSON
+ *
+ * Production pattern from frontend-dapp-v2 for JSON serialization of BigInt values.
+ * Prevents TypeError: Do not know how to serialize a BigInt.
+ *
+ * @param _key - JSON key (unused but required by replacer signature)
+ * @param value - Value to serialize
+ * @returns Serializable value (BigInt → string, others unchanged)
+ *
+ * @example
+ * ```typescript
+ * const data = { amount: 1000000000000000000n };
+ * JSON.stringify(data, bigIntReplacer);
+ * // => '{"amount":"1000000000000000000"}'
+ * ```
+ */
+export function bigIntReplacer(_key, value) {
+    return typeof value === 'bigint' ? value.toString() : value;
+}
+/**
+ * Stringify object with BigInt support
+ *
+ * Convenience wrapper for JSON.stringify with automatic BigInt handling.
+ * Uses 2-space indentation for readability.
+ *
+ * @param obj - Object to stringify (may contain BigInt values)
+ * @returns JSON string with BigInt values as strings
+ *
+ * @example
+ * ```typescript
+ * safeBigIntStringify({ balance: 1000000000000000000n });
+ * // => '{\n  "balance": "1000000000000000000"\n}'
+ * ```
+ */
+export function safeBigIntStringify(obj) {
+    return JSON.stringify(obj, bigIntReplacer, 2);
+}
+/**
+ * Format BigInt to human-readable decimal string
+ *
+ * Converts BigInt wei amounts to decimal representation with proper decimal placement.
+ * No floating-point operations - pure integer math for precision.
+ *
+ * @param value - BigInt value in smallest unit (e.g., wei)
+ * @param decimals - Number of decimal places (e.g., 18 for ether)
+ * @returns Formatted decimal string (e.g., "1.500000000000000000")
+ *
+ * @example
+ * ```typescript
+ * formatBigInt(1500000000000000000n, 18);
+ * // => "1.500000000000000000"
+ *
+ * formatBigInt(1000000n, 6);
+ * // => "1.000000"
+ * ```
+ */
+export function formatBigInt(value, decimals) {
+    if (decimals < 0) {
+        throw new Error('Decimals must be non-negative');
+    }
+    if (decimals === 0) {
+        return value.toString();
+    }
+    const divisor = BigInt(10 ** decimals);
+    const integerPart = value / divisor;
+    const remainder = value % divisor;
+    // Pad fractional part with leading zeros
+    const fractionalPart = remainder.toString().padStart(decimals, '0');
+    return `${integerPart}.${fractionalPart}`;
+}
+/**
+ * Parse decimal string to BigInt
+ *
+ * Converts human-readable decimal to BigInt in smallest unit.
+ * Validates input format and handles edge cases safely.
+ *
+ * @param value - Decimal string (e.g., "1.5" or "1500")
+ * @param decimals - Target decimal places
+ * @returns BigInt value in smallest unit
+ * @throws {Error} If value format is invalid
+ *
+ * @example
+ * ```typescript
+ * parseBigInt("1.5", 18);
+ * // => 1500000000000000000n
+ *
+ * parseBigInt("1000000", 6);
+ * // => 1000000000000n
+ * ```
+ */
+export function parseBigInt(value, decimals) {
+    if (!value || value.trim() === '') {
+        throw new Error('Value cannot be empty');
+    }
+    if (decimals < 0) {
+        throw new Error('Decimals must be non-negative');
+    }
+    const trimmed = value.trim();
+    // Handle integer-only values
+    if (!trimmed.includes('.')) {
+        if (!/^\d+$/.test(trimmed)) {
+            throw new Error(`Invalid integer format: ${value}`);
+        }
+        return BigInt(trimmed) * BigInt(10 ** decimals);
+    }
+    // Handle decimal values
+    const parts = trimmed.split('.');
+    if (parts.length > 2) {
+        throw new Error(`Invalid decimal format: ${value}`);
+    }
+    const [integerPart, fractionalPart] = parts;
+    if (!/^\d+$/.test(integerPart) || !/^\d+$/.test(fractionalPart)) {
+        throw new Error(`Invalid decimal format: ${value}`);
+    }
+    if (fractionalPart.length > decimals) {
+        throw new Error(`Too many decimal places: ${value} (max: ${decimals})`);
+    }
+    // Pad fractional part to match decimals
+    const paddedFractional = fractionalPart.padEnd(decimals, '0');
+    return BigInt(integerPart) * BigInt(10 ** decimals) + BigInt(paddedFractional);
+}
+/**
+ * Validate BigInt string format
+ *
+ * Checks if a string represents a valid BigInt (unsigned integer).
+ * Returns false for negative numbers, decimals, or invalid formats.
+ *
+ * @param value - String to validate
+ * @returns true if valid BigInt string, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidBigIntString("1000000000000000000"); // => true
+ * isValidBigIntString("1.5");                  // => false
+ * isValidBigIntString("-100");                 // => false
+ * isValidBigIntString("abc");                  // => false
+ * ```
+ */
+export function isValidBigIntString(value) {
+    if (!value || value.trim() === '') {
+        return false;
+    }
+    const trimmed = value.trim();
+    // Must be digits only (no negative, no decimal)
+    if (!/^\d+$/.test(trimmed)) {
+        return false;
+    }
+    try {
+        BigInt(trimmed);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Calculate percentage change between two BigInt values
+ *
+ * Computes percentage change with high precision using integer math.
+ * Returns result scaled to basis points (10000 = 100.00%).
+ *
+ * @param oldValue - Original value
+ * @param newValue - New value
+ * @returns Percentage change in basis points (e.g., 250 = 2.50%)
+ *
+ * @example
+ * ```typescript
+ * percentageChange(1000000n, 1025000n);
+ * // => 250 (2.50% increase)
+ *
+ * percentageChange(1000000n, 975000n);
+ * // => -250 (2.50% decrease)
+ * ```
+ */
+export function percentageChange(oldValue, newValue) {
+    if (oldValue === 0n) {
+        return newValue === 0n ? 0 : Infinity;
+    }
+    // Calculate change with 10000x scaling for basis points
+    const change = ((newValue - oldValue) * 10000n) / oldValue;
+    return Number(change);
+}
+/**
+ * Format percentage change for display
+ *
+ * Converts basis points to human-readable percentage string.
+ *
+ * @param basisPoints - Percentage change in basis points
+ * @returns Formatted percentage string with sign and symbol
+ *
+ * @example
+ * ```typescript
+ * formatPercentageChange(250);   // => "+2.50%"
+ * formatPercentageChange(-250);  // => "-2.50%"
+ * formatPercentageChange(0);     // => "0.00%"
+ * ```
+ */
+export function formatPercentageChange(basisPoints) {
+    if (basisPoints === Infinity) {
+        return '+∞%';
+    }
+    if (basisPoints === -Infinity) {
+        return '-∞%';
+    }
+    const percentage = basisPoints / 100;
+    const sign = percentage > 0 ? '+' : '';
+    return `${sign}${percentage.toFixed(2)}%`;
+}
+//# sourceMappingURL=math-utils.js.map

package/dist/sdk/math-utils.js.map

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