@primuslabs/fhetransform-sdk 0.4.0

package/dist/core/pretty-print.js

@@ -0,0 +1,84 @@
+import { bytesToHex } from "./bytes.js";
+/**
+ * Recursively formats values for human-readable display.
+ * - Truncates long strings (>132 chars) to show head and tail with length.
+ * - Converts BigInts to strings.
+ * - Recursively processes objects.
+ *
+ * @param value - The value to format
+ * @returns The formatted value
+ */
+export function formatValue(value) {
+    // Truncate long strings (> 132 characters)
+    if (typeof value === "string" && value.length > 132) {
+        return `${value.slice(0, 20)}...${value.slice(-20)} (${value.length})`;
+    }
+    // Convert BigInts to strings for readable output
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    // Convert Uint8Array to hex-strings for readable output
+    if (value instanceof Uint8Array) {
+        if (value.length > 32) {
+            return bytesToHex(value.subarray(0, 32)) + `... (${value.length})`;
+        }
+        return formatValue(bytesToHex(value));
+    }
+    // Recursively format object properties
+    if (value !== null && typeof value === "object") {
+        try {
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                result[key] = formatValue(val);
+            }
+            return result;
+        }
+        catch {
+            // If recursion fails, return the original value
+            return value;
+        }
+    }
+    // Return all other values unchanged
+    return value;
+}
+/**
+ * Truncates a long hex string for display purposes.
+ * @param value - The value to process (strings, bigints, or other types)
+ * @returns A shortened representation if the value is a long hex string, otherwise the original value
+ */
+function shortHex(value) {
+    // Truncate long hex strings (> 132 characters)
+    if (typeof value === "string" && value.length > 132) {
+        return `${value.slice(0, 20)}...${value.slice(-20)} (${value.length})`;
+    }
+    // Convert bigints to strings for serialization
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    return value;
+}
+/**
+ * Pretty-prints data to the console with hex string truncation.
+ * - In browser environments: uses console.log with JSON formatting
+ * - In Node.js environments: uses console.dir with detailed options
+ *
+ * @param data - The data to pretty-print
+ */
+export function prettyPrint(data) {
+    const replacer = (_, v) => shortHex(v);
+    if (typeof window !== "undefined") {
+        // Browser environment: log as formatted JSON
+        console.log(JSON.stringify(data, replacer, 2));
+    }
+    else {
+        // Node.js environment: use console.dir for better formatting
+        const serialized = JSON.parse(JSON.stringify(data, replacer));
+        console.dir(serialized, {
+            depth: null,
+            colors: true,
+            compact: false,
+            breakLength: Infinity,
+        });
+    }
+}
+//# sourceMappingURL=pretty-print.js.map

package/dist/core/pretty-print.js.map

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

package/dist/core/primitives.d.ts

@@ -0,0 +1,22 @@
+declare const __hex0x: unique symbol;
+declare const __hexNo0x: unique symbol;
+declare const __evenLen: unique symbol;
+export type Hex0xString = {
+    readonly [__hex0x]: never;
+};
+export type HexNo0xString = {
+    readonly [__hexNo0x]: never;
+};
+export type EvenLen = {
+    readonly [__evenLen]: never;
+};
+export type Hex0x = `0x${string}` & Hex0xString;
+export type HexNo0x = string & HexNo0xString;
+export type BytesHex = Hex0x & EvenLen;
+export type BytesHexNo0x = HexNo0x & EvenLen;
+export type Address = BytesHex;
+export type Bytes32Hex = BytesHex;
+export type Bytes65Hex = BytesHex;
+export type Bytes65HexNo0x = HexNo0x;
+export type Bytes = Uint8Array;
+export {};

package/dist/core/primitives.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=primitives.js.map

package/dist/core/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/core/primitives.ts"],"names":[],"mappings":""}

package/dist/core/retryable-handler.d.ts

@@ -0,0 +1,74 @@
+export interface RetryableOptions {
+    retryableStatusCodes?: number[];
+    retryableErrors?: string[];
+    /**
+     * If true, user values override defaults (replace behavior)
+     * If false, user values are appended to defaults (default behavior)
+     */
+    overrideDefaults?: boolean;
+}
+export declare abstract class RetryableHandler {
+    protected retryableStatusCodes: number[];
+    protected retryableErrors: string[];
+    constructor(options?: RetryableOptions);
+    /**
+     * Determine if an error should trigger a retry
+     * @param err - The error object
+     * @returns True if retry should be attempted
+     */
+    protected shouldRetry(err: any): boolean;
+    /**
+     * Enhance error with additional context information
+     * @param err - Original error
+     * @param operationName - Name of the operation
+     * @param context - Optional context data
+     * @returns Enhanced error object
+     */
+    protected enhanceError(err: any, operationName: string, context?: any): Error;
+}
+export interface CountRetryOptions extends RetryableOptions {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    backoffFactor?: number;
+    maxDelayMs?: number;
+}
+export declare class CountRetryHandler extends RetryableHandler {
+    private maxRetries;
+    private initialDelayMs;
+    private backoffFactor;
+    private maxDelayMs;
+    constructor(options?: CountRetryOptions);
+    /**
+     * Execute operation with count-based retry logic using exponential backoff
+     * @param operation - Async operation to execute
+     * @param operationName - Name of the operation for logging
+     * @param context - Optional context data for error enhancement
+     * @returns Promise resolving to the operation result
+     */
+    withRetry<T>(operation: () => Promise<T>, operationName: string, context?: any): Promise<T>;
+}
+export interface TimeoutRetryOptions extends RetryableOptions {
+    maxRetryTimeMs?: number;
+    initialIntervalMs?: number;
+    adaptiveInterval?: boolean;
+    maxIntervalMs?: number;
+}
+export declare class TimeoutRetryHandler extends RetryableHandler {
+    private maxRetryTimeMs;
+    private initialIntervalMs;
+    private adaptiveInterval;
+    private maxIntervalMs;
+    constructor(options?: TimeoutRetryOptions);
+    /**
+     * Execute operation with timeout-based retry logic
+     * Timeout check is performed after each failure, before scheduling the next retry.
+     * This ensures the current attempt is never interrupted.
+     *
+     * @param operation - Async operation to execute
+     * @param operationName - Name of the operation for logging
+     * @param context - Optional context data for error enhancement
+     * @param errCallback - Optional callback to execute after failure
+     * @returns Promise resolving to the operation result
+     */
+    withRetry<T>(operation: () => Promise<T>, operationName: string, context?: any, errCallback?: () => Promise<void>): Promise<T>;
+}

package/dist/core/retryable-handler.js

@@ -0,0 +1,227 @@
+import { logger } from "./logger.js";
+import { sleepMs } from "./utils.js";
+import { getErrorRetryPolicy, isFheError } from "./errors/error-utils.js";
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+const MIN_RETRY_INTERVAL_MS = 500;
+export class RetryableHandler {
+    retryableStatusCodes;
+    retryableErrors;
+    constructor(options) {
+        const defaultStatusCodes = [404];
+        const defaultErrors = [
+            'UNAVAILABLE',
+            'DEADLINE_EXCEEDED',
+            'timeout',
+            'Failed to fetch',
+            'fetch failed',
+            'NetworkError',
+        ];
+        if (options?.overrideDefaults) {
+            // Override mode: user values replace defaults
+            this.retryableStatusCodes = options.retryableStatusCodes ?? defaultStatusCodes;
+            this.retryableErrors = options.retryableErrors ?? defaultErrors;
+        }
+        else {
+            // Append mode (default): user values are added to defaults (deduplicated)
+            this.retryableStatusCodes = [
+                ...defaultStatusCodes,
+                ...(options?.retryableStatusCodes?.filter(code => !defaultStatusCodes.includes(code)) ?? []),
+            ];
+            this.retryableErrors = [
+                ...defaultErrors,
+                ...(options?.retryableErrors?.filter(err => !defaultErrors.includes(err)) ?? []),
+            ];
+        }
+    }
+    /**
+     * Determine if an error should trigger a retry
+     * @param err - The error object
+     * @returns True if retry should be attempted
+     */
+    shouldRetry(err) {
+        const message = typeof err?.message === "string" ? err.message.toLowerCase() : "";
+        // Check retryable gRPC status codes
+        if (err.code && this.retryableStatusCodes.includes(err.code)) {
+            return true;
+        }
+        // Check retryable error message patterns
+        if (message) {
+            for (const retryableError of this.retryableErrors) {
+                if (message.includes(retryableError.toLowerCase())) {
+                    return true;
+                }
+            }
+        }
+        // Check for 404 error or gRPC code 5 (NOT_FOUND)
+        if (message.includes('404') || err.code === 5) {
+            return true;
+        }
+        // FheErrors carry their retry policy directly.
+        if (isFheError(err)) {
+            return getErrorRetryPolicy(err).retryable;
+        }
+        return false;
+    }
+    /**
+     * Enhance error with additional context information
+     * @param err - Original error
+     * @param operationName - Name of the operation
+     * @param context - Optional context data
+     * @returns Enhanced error object
+     */
+    enhanceError(err, operationName, context) {
+        const enhancedError = new FheError({
+            code: FheErrorCode.Internal,
+            message: `[${operationName}] ${err.message}\n` +
+                `Context: ${JSON.stringify(context, null, 2)}`,
+            cause: err,
+        });
+        enhancedError.originalError = err;
+        enhancedError.operationName = operationName;
+        return enhancedError;
+    }
+}
+export class CountRetryHandler extends RetryableHandler {
+    maxRetries;
+    initialDelayMs;
+    backoffFactor;
+    maxDelayMs;
+    constructor(options) {
+        super(options);
+        this.maxRetries = options?.maxRetries ?? 3;
+        this.initialDelayMs = options?.initialDelayMs ?? 1000;
+        this.backoffFactor = options?.backoffFactor ?? 2;
+        this.maxDelayMs = options?.maxDelayMs ?? 30000;
+    }
+    /**
+     * Execute operation with count-based retry logic using exponential backoff
+     * @param operation - Async operation to execute
+     * @param operationName - Name of the operation for logging
+     * @param context - Optional context data for error enhancement
+     * @returns Promise resolving to the operation result
+     */
+    async withRetry(operation, operationName, context) {
+        let lastError = null;
+        let delay = this.initialDelayMs;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                if (attempt > 0) {
+                    logger.debug(`[${operationName}] Retry attempt ${attempt + 1}/${this.maxRetries + 1}`);
+                }
+                const result = await operation();
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                const canRetry = this.shouldRetry(err);
+                const isLastAttempt = attempt >= this.maxRetries;
+                if (!canRetry || isLastAttempt) {
+                    const reason = !canRetry ? 'non-retryable error' : 'max retries reached';
+                    logger.error(`[${operationName}] Failed - ${reason}: ${err.message}`);
+                    throw this.enhanceError(err, operationName, context);
+                }
+                logger.warn(`[${operationName}] Retry failed (${attempt + 1}/${this.maxRetries + 1}): ${err.message}. Waiting ${delay}ms...`);
+                await sleepMs(delay);
+                delay = Math.min(delay * this.backoffFactor, this.maxDelayMs);
+            }
+        }
+        throw this.enhanceError(lastError, operationName, context);
+    }
+}
+export class TimeoutRetryHandler extends RetryableHandler {
+    maxRetryTimeMs;
+    initialIntervalMs;
+    adaptiveInterval;
+    maxIntervalMs;
+    constructor(options) {
+        super(options);
+        this.maxRetryTimeMs = options?.maxRetryTimeMs ?? 30000;
+        this.initialIntervalMs = options?.initialIntervalMs ?? 1000;
+        this.adaptiveInterval = options?.adaptiveInterval ?? false;
+        this.maxIntervalMs = options?.maxIntervalMs ?? 5000;
+    }
+    /**
+     * Execute operation with timeout-based retry logic
+     * Timeout check is performed after each failure, before scheduling the next retry.
+     * This ensures the current attempt is never interrupted.
+     *
+     * @param operation - Async operation to execute
+     * @param operationName - Name of the operation for logging
+     * @param context - Optional context data for error enhancement
+     * @param errCallback - Optional callback to execute after failure
+     * @returns Promise resolving to the operation result
+     */
+    async withRetry(operation, operationName, context, errCallback) {
+        let lastError = null;
+        const startTime = Date.now();
+        let attempt = 0;
+        let currentInterval = this.initialIntervalMs;
+        while (true) {
+            try {
+                // Execute the operation
+                if (attempt > 0) {
+                    const elapsedTime = Date.now() - startTime;
+                    logger.debug(`[${operationName}] Retry attempt ${attempt}, elapsed ${elapsedTime}ms`);
+                }
+                const result = await operation();
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                // Check if the error is retryable
+                const canRetry = context?.shouldRetry ? context.shouldRetry(err) : this.shouldRetry(err);
+                if (!canRetry) {
+                    logger.error(`[${operationName}] Failed - non-retryable error: ${err.message}`);
+                    throw this.enhanceError(err, operationName, context);
+                }
+                // Check timeout after failure, before scheduling next retry
+                const elapsedTime = Date.now() - startTime;
+                const remainingTime = this.maxRetryTimeMs - elapsedTime;
+                if (remainingTime <= 0) {
+                    logger.error(`[${operationName}] Failed - timeout exceeded ${this.maxRetryTimeMs}ms after ${attempt} attempts`);
+                    throw this.enhanceError(err, operationName, context);
+                }
+                // Calculate next interval
+                const retryAfterMs = err?.retryAfterMs;
+                const isValidRetryAfterMs = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs > 0;
+                let nextInterval;
+                if (isValidRetryAfterMs) {
+                    nextInterval = retryAfterMs;
+                }
+                else if (this.adaptiveInterval) {
+                    nextInterval = Math.min(currentInterval * 1.5, this.maxIntervalMs);
+                }
+                else {
+                    nextInterval = currentInterval;
+                }
+                // Verify sufficient time remains for another retry
+                if (nextInterval > remainingTime) {
+                    logger.warn(`[${operationName}] Insufficient time for retry (need ${nextInterval}ms, have ${remainingTime}ms)`);
+                    nextInterval = remainingTime;
+                }
+                nextInterval = Math.max(MIN_RETRY_INTERVAL_MS, nextInterval);
+                logger.warn(`[${operationName}] Retry failed (attempt ${attempt + 1}, elapsed ${elapsedTime}ms, nextInterval ${nextInterval}): ${err.message}`);
+                logger.debug(`[${operationName}] Waiting ${nextInterval}ms before next attempt...`);
+                // Start callback execution in parallel with sleep. A throwing callback
+                // must never mask the original operation error or break the retry flow.
+                let callbackPromise;
+                try {
+                    callbackPromise = Promise.resolve(errCallback?.());
+                }
+                catch (callbackError) {
+                    logger.warn(`[${operationName}] Retry callback failed`, { error: callbackError });
+                }
+                await Promise.all([
+                    sleepMs(nextInterval),
+                    callbackPromise?.catch((callbackError) => {
+                        logger.warn(`[${operationName}] Retry callback failed`, { error: callbackError });
+                    }),
+                ]);
+                currentInterval = nextInterval;
+                attempt++;
+            }
+        }
+    }
+}
+//# sourceMappingURL=retryable-handler.js.map

package/dist/core/retryable-handler.js.map

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

package/dist/core/signer-address-info.d.ts

@@ -0,0 +1,15 @@
+import { Address } from "../core/primitives.js";
+/**
+ * Represents the signer address information for KMS decryption operations.
+ * Currently only contains the TEE (Trusted Execution Environment) signer address.
+ */
+export type SignerAddressInfo = {
+    readonly kmsDecryptionSignerAddress: Address;
+};
+/**
+ * Retrieves the signer address information for a given blockchain chain ID.
+ *
+ * @param chainId - The chain ID (as bigint) of the target blockchain network.
+ * @returns The signer address information for the specified chain.
+ */
+export declare function getSignerAddressInfo(chainId: bigint): SignerAddressInfo;

package/dist/core/signer-address-info.js

@@ -0,0 +1,33 @@
+/**
+ * Retrieves the signer address information for a given blockchain chain ID.
+ *
+ * @param chainId - The chain ID (as bigint) of the target blockchain network.
+ * @returns The signer address information for the specified chain.
+ */
+export function getSignerAddressInfo(chainId) {
+    let info;
+    switch (chainId) {
+        case 31337n: // Anvil / Hardhat local development network (default test accounts)
+            info = {
+                kmsDecryptionSignerAddress: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
+            };
+            break;
+        case 56n: // BNB Smart Chain Mainnet
+            info = {
+                kmsDecryptionSignerAddress: "0x7d8769999bEcBfB91a8c127515044e3888ac3184",
+            };
+            break;
+        case 97n: // BNB Smart Chain Testnet
+            info = {
+                kmsDecryptionSignerAddress: "0x0c900B88D258fA4c6c2ef7725Db0f7cA1522ABd0",
+            };
+            break;
+        default:
+            info = {
+                kmsDecryptionSignerAddress: "0x7d8769999bEcBfB91a8c127515044e3888ac3184",
+            };
+            break;
+    }
+    return info;
+}
+//# sourceMappingURL=signer-address-info.js.map

package/dist/core/signer-address-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer-address-info.js","sourceRoot":"","sources":["../../src/core/signer-address-info.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,IAAuB,CAAC;IAE5B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM,EAAE,oEAAoE;YAC/E,IAAI,GAAG;gBACL,0BAA0B,EAAE,4CAAuD;aACpF,CAAC;YACF,MAAM;QAER,KAAK,GAAG,EAAE,0BAA0B;YAClC,IAAI,GAAG;gBACL,0BAA0B,EAAE,4CAAuD;aACpF,CAAC;YACF,MAAM;QAER,KAAK,GAAG,EAAE,0BAA0B;YAClC,IAAI,GAAG;gBACL,0BAA0B,EAAE,4CAAuD;aACpF,CAAC;YACF,MAAM;QAER;YACE,IAAI,GAAG;gBACL,0BAA0B,EAAE,4CAAuD;aACpF,CAAC;YACF,MAAM;IACV,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/string.d.ts

@@ -0,0 +1,28 @@
+import { BytesHex, BytesHexNo0x } from "./primitives.js";
+/**
+ * Ensures a hex string has the "0x" prefix.
+ * @param s - The hex string (with or without prefix)
+ * @returns The hex string with "0x" prefix
+ */
+export declare function ensure0x<T extends BytesHexNo0x>(s: T): BytesHex & Omit<T, keyof BytesHexNo0x>;
+export declare function ensure0x(s: string): `0x${string}`;
+/**
+ * Removes the "0x" prefix from a hex string.
+ * @param s - The hex string (with or without prefix)
+ * @returns The hex string without the "0x" prefix
+ */
+export declare function remove0x<T extends BytesHex>(s: T): BytesHexNo0x & Omit<T, keyof BytesHex>;
+export declare function remove0x(s: string): string;
+/**
+ * Removes a specified suffix from a string if present.
+ * @param s - The input string (or undefined)
+ * @param suffix - The suffix to remove
+ * @returns The string without the suffix, or empty string if input is undefined
+ */
+export declare function removeSuffix(s: string | undefined, suffix: string): string;
+/**
+ * Type guard that checks if a value is a non-empty string.
+ * @param s - The value to check
+ * @returns True if the value is a string with length > 0
+ */
+export declare function isNonEmptyString(s: unknown): s is string;

package/dist/core/string.js

@@ -0,0 +1,33 @@
+export function ensure0x(s) {
+    return !s.startsWith("0x") ? `0x${s}` : s;
+}
+export function remove0x(s) {
+    return s.startsWith("0x") ? s.substring(2) : s;
+}
+/**
+ * Removes a specified suffix from a string if present.
+ * @param s - The input string (or undefined)
+ * @param suffix - The suffix to remove
+ * @returns The string without the suffix, or empty string if input is undefined
+ */
+export function removeSuffix(s, suffix) {
+    if (s === undefined) {
+        return "";
+    }
+    if (suffix.length === 0) {
+        return s;
+    }
+    return s.endsWith(suffix) ? s.slice(0, -suffix.length) : s;
+}
+/**
+ * Type guard that checks if a value is a non-empty string.
+ * @param s - The value to check
+ * @returns True if the value is a string with length > 0
+ */
+export function isNonEmptyString(s) {
+    if (s === undefined || s === null || typeof s !== "string") {
+        return false;
+    }
+    return s.length > 0;
+}
+//# sourceMappingURL=string.js.map

package/dist/core/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../src/core/string.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAE,CAAmB,CAAC;AAC/D,CAAC;AASD,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAqB,EAAE,MAAc;IAChE,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAU;IACzC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACtB,CAAC"}

package/dist/core/swallow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runs a function and swallows any errors that occur during execution.
+ *
+ * This utility is useful for non-critical operations that should not
+ * interrupt the main application flow even if they fail. Errors are
+ * logged as warnings for debugging purposes.
+ *
+ * @param label - A descriptive label for the operation (used in log messages)
+ * @param fn - The async or sync function to execute
+ * @returns A promise that resolves when the function completes (or fails)
+ *
+ * @example
+ * // Swallow errors from a non-critical operation
+ * await swallow('Cache cleanup', async () => {
+ *   await cacheManager.clearExpired();
+ * });
+ *
+ * // Works with sync functions too
+ * await swallow('Log rotation', () => {
+ *   rotateLogFiles();
+ * });
+ */
+export declare function swallow(label: string, fn: () => Promise<void> | void): Promise<void>;

package/dist/core/swallow.js

@@ -0,0 +1,37 @@
+import { logger } from "./logger.js";
+/**
+ * Runs a function and swallows any errors that occur during execution.
+ *
+ * This utility is useful for non-critical operations that should not
+ * interrupt the main application flow even if they fail. Errors are
+ * logged as warnings for debugging purposes.
+ *
+ * @param label - A descriptive label for the operation (used in log messages)
+ * @param fn - The async or sync function to execute
+ * @returns A promise that resolves when the function completes (or fails)
+ *
+ * @example
+ * // Swallow errors from a non-critical operation
+ * await swallow('Cache cleanup', async () => {
+ *   await cacheManager.clearExpired();
+ * });
+ *
+ * // Works with sync functions too
+ * await swallow('Log rotation', () => {
+ *   rotateLogFiles();
+ * });
+ */
+export async function swallow(label, fn) {
+    try {
+        logger.debug(`[swallow] ${label} call`);
+        await fn();
+    }
+    catch (error) {
+        // Log the error as a warning and swallow it
+        logger.warn(`[swallow] ${label} failed`, {
+            label,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+//# sourceMappingURL=swallow.js.map

package/dist/core/swallow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swallow.js","sourceRoot":"","sources":["../../src/core/swallow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAa,EACb,EAA8B;IAG9B,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC,CAAC;QACxC,MAAM,EAAE,EAAE,CAAC;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4CAA4C;QAC5C,MAAM,CAAC,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE;YACvC,KAAK;YACL,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/core/system-contract-info.d.ts

@@ -0,0 +1,17 @@
+import { Address } from "../core/primitives.js";
+/**
+ * System contract addresses for FHE operations on supported chains.
+ */
+export type SystemContractInfo = {
+    readonly aclContractAddress: Address;
+    readonly spaceBridgeConfigAddress: Address;
+    readonly decryptionContractAddress: Address;
+    readonly ciphertextVerificationAddress: Address;
+};
+/**
+ * Returns the system contract addresses for a given blockchain chain ID.
+ * @param chainId - The blockchain chain ID
+ * @returns SystemContractInfo containing all required contract addresses
+ * @throws Error if the chain ID is not supported
+ */
+export declare function getSystemContractInfo(chainId: bigint): SystemContractInfo;