@primuslabs/fhetransform-sdk 0.4.0

package/dist/core/chain.js

@@ -0,0 +1,59 @@
+import { logger } from "./logger.js";
+import { FheErrorCode } from "./errors/error-codes.js";
+import { FheError } from "./errors/fhe-error.js";
+/**
+ * List of supported blockchain networks with their chain ID to chain key mappings.
+ * Chain key is a compact identifier used in handle generation.
+ */
+export const CHAINS = [
+    { chainId: 1n, chainKey: 1, name: "Ethereum Mainnet" },
+    { chainId: 11155111n, chainKey: 2, name: "Ethereum Sepolia" },
+    { chainId: 84532n, chainKey: 3, name: "Base Sepolia Testnet" },
+    { chainId: 133n, chainKey: 4, name: "Hashkey Chain Testnet" },
+    { chainId: 56n, chainKey: 5, name: "BNB Smart Chain Mainnet" },
+    { chainId: 8453n, chainKey: 6, name: "Base" },
+    { chainId: 177n, chainKey: 7, name: "HashKey Chain" },
+    { chainId: 97n, chainKey: 8, name: "BNB Smart Chain Testnet" },
+    /* Add more chain mappings here as needed */
+    { chainId: 31337n, chainKey: 255, name: "Hardhat or Anvil Local" },
+];
+/**
+ * Map chain key to chain ID for quick lookup
+ * Created as a Map for O(1) lookup performance
+ */
+export const chainKeyToChainIdMap = new Map(CHAINS.map((chain) => [chain.chainKey, chain.chainId]));
+/**
+ * Map chain ID to chain key for reverse lookup
+ * Useful for validation and debugging
+ */
+export const chainIdToChainKeyMap = new Map(CHAINS.map((chain) => [chain.chainId, chain.chainKey]));
+/**
+ * Converts a blockchain chain ID to its corresponding chain key.
+ * @param chainId - Blockchain chain ID (e.g., 1n for Ethereum Mainnet)
+ * @returns The mapped chain key (uint8) used in handle generation
+ * @throws Error if the chain ID is not supported
+ */
+export function getChainKey(chainId) {
+    logger.debug(`Getting chain key for chainId: ${chainId.toString()}`);
+    const chainKey = chainIdToChainKeyMap.get(chainId);
+    if (chainKey === undefined) {
+        logger.error(`Unsupported chainId: ${chainId.toString()}`);
+        throw new FheError({ code: FheErrorCode.UnsupportedChain, message: `Unsupported chainId: ${chainId.toString()}` });
+    }
+    logger.trace(`Chain key for ${chainId}: ${chainKey}`);
+    return chainKey;
+}
+/**
+ * Builds arguments for setting chain mappings in a smart contract.
+ * @returns An object containing arrays of chain IDs and their corresponding chain keys
+ */
+export function buildSetChainKeysArgs() {
+    const chainIds = CHAINS.map((c) => c.chainId);
+    const chainKeys = CHAINS.map((c) => c.chainKey);
+    logger.debug(`Building chain keys args: ${chainIds.length} chains`);
+    return {
+        chainIds,
+        chainKeys,
+    };
+}
+//# sourceMappingURL=chain.js.map

package/dist/core/chain.js.map

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

package/dist/core/constants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Number of seconds in a single day.
+ * Used as a base unit for TTL calculations across the application.
+ */
+export declare const SECONDS_PER_DAY: number;
+/**
+ * Default TTL (Time-To-Live) for transport key pairs in seconds.
+ */
+export declare const DEFAULT_TRANSPORT_KEY_PAIR_TTL_SECONDS: number;
+/**
+ * Default TTL for permits in days.
+ */
+export declare const DEFAULT_PERMIT_TTL_DAYS = 30;
+/**
+ * Default TTL for public keys in seconds.
+ */
+export declare const DEFAULT_PUBLIC_KEY_TTL_SECONDS: number;
+/**
+ * Default Jazz service base URL.
+ * @description Empty string indicates that the caller must provide a valid URL at runtime.
+ * This allows flexible configuration via environment variables or runtime injection.
+ */
+export declare const DEFAULT_JAZZ_URL: string;
+export declare const DB_BASE_NAME: "fhe-transform";

package/dist/core/constants.js

@@ -0,0 +1,25 @@
+/**
+ * Number of seconds in a single day.
+ * Used as a base unit for TTL calculations across the application.
+ */
+export const SECONDS_PER_DAY = 1 * 24 * 60 * 60;
+/**
+ * Default TTL (Time-To-Live) for transport key pairs in seconds.
+ */
+export const DEFAULT_TRANSPORT_KEY_PAIR_TTL_SECONDS = 30 * SECONDS_PER_DAY; // 30 Day
+/**
+ * Default TTL for permits in days.
+ */
+export const DEFAULT_PERMIT_TTL_DAYS = 30; // 30 Day
+/**
+ * Default TTL for public keys in seconds.
+ */
+export const DEFAULT_PUBLIC_KEY_TTL_SECONDS = 30 * SECONDS_PER_DAY; // 30 Day
+/**
+ * Default Jazz service base URL.
+ * @description Empty string indicates that the caller must provide a valid URL at runtime.
+ * This allows flexible configuration via environment variables or runtime injection.
+ */
+export const DEFAULT_JAZZ_URL = "https://jazz.primuslabs.xyz";
+export const DB_BASE_NAME = "fhe-transform";
+//# sourceMappingURL=constants.js.map

package/dist/core/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,EAAE,GAAG,eAAe,CAAC,CAAC,SAAS;AAErF;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC,CAAC,SAAS;AAEpD;;GAEG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,eAAe,CAAC,CAAC,SAAS;AAE7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAW,6BAA6B,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAG,eAAwB,CAAC"}

package/dist/core/error.d.ts

@@ -0,0 +1,2 @@
+export declare function toError(error: unknown): Error;
+export { isFheError, toFheError } from "./errors/error-utils.js";

package/dist/core/error.js

@@ -0,0 +1,14 @@
+export function toError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === "object" && error !== null && "message" in error) {
+        return new Error(String(error.message));
+    }
+    return new Error(String(error));
+}
+// Migration helpers: import toFheError / isFheError from here while existing
+// call sites switch from toError incrementally. toError stays identity-
+// preserving for backward compatibility.
+export { isFheError, toFheError } from "./errors/error-utils.js";
+//# sourceMappingURL=error.js.map

package/dist/core/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QACtE,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,6EAA6E;AAC7E,wEAAwE;AACxE,yCAAyC;AACzC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/core/errors/error-catalog.d.ts

@@ -0,0 +1,29 @@
+import { FheErrorCode } from "./error-codes.js";
+/** Serializable context attached to an error. Values must be JSON-safe. */
+export type FheErrorContext = Record<string, unknown>;
+export interface FheErrorCatalogEntry {
+    code: FheErrorCode;
+    severity: "error" | "warn";
+    retryable: boolean;
+    httpStatus: number;
+    messageKey: string;
+    messageTemplate: string;
+    docsUrl: string;
+    description: string;
+}
+/**
+ * Single source of truth for every error code.
+ * Defaults for retryability, HTTP status, message key, docs URL, and the
+ * human-readable message template all live here.
+ */
+export declare const FHE_ERROR_CATALOG: Record<FheErrorCode, FheErrorCatalogEntry>;
+/**
+ * Returns the catalog entry for a code. Unknown codes fall back to INTERNAL so
+ * serialization never fails on a missing entry.
+ */
+export declare function getErrorCatalogEntry(code: FheErrorCode | string): FheErrorCatalogEntry;
+/**
+ * Interpolates "{key}" placeholders from context. Missing values are left
+ * as-is so callers can spot template mismatches.
+ */
+export declare function formatMessage(template: string, context?: FheErrorContext): string;

package/dist/core/errors/error-catalog.js

@@ -0,0 +1,84 @@
+import { FheErrorCode } from "./error-codes.js";
+const DOCS_BASE = "https://docs.fhetransform.io/errors";
+function entry(code, severity, retryable, httpStatus, messageKey, messageTemplate, description) {
+    return {
+        code,
+        severity,
+        retryable,
+        httpStatus,
+        messageKey,
+        messageTemplate,
+        docsUrl: `${DOCS_BASE}#${code}`,
+        description,
+    };
+}
+/**
+ * Single source of truth for every error code.
+ * Defaults for retryability, HTTP status, message key, docs URL, and the
+ * human-readable message template all live here.
+ */
+export const FHE_ERROR_CATALOG = {
+    [FheErrorCode.InvalidConfig]: entry(FheErrorCode.InvalidConfig, "error", false, 500, "errors.invalid_config", "Invalid SDK configuration", "The SDK was constructed with an invalid configuration."),
+    [FheErrorCode.MissingProvider]: entry(FheErrorCode.MissingProvider, "error", false, 500, "errors.missing_provider", "Provider is required but not configured", "A blockchain provider is required for this operation."),
+    [FheErrorCode.MissingSigner]: entry(FheErrorCode.MissingSigner, "error", false, 500, "errors.missing_signer", "Signer is required but not available", "A signer is required for this operation."),
+    [FheErrorCode.MissingJazzUrl]: entry(FheErrorCode.MissingJazzUrl, "error", false, 500, "errors.missing_jazz_url", "Jazz URL is required but not configured", "A Jazz service URL is required for this operation."),
+    [FheErrorCode.UnsupportedChain]: entry(FheErrorCode.UnsupportedChain, "error", false, 400, "errors.unsupported_chain", "Unsupported chain ID: {chainId}", "The chain ID is not supported by the SDK."),
+    [FheErrorCode.InvalidArgument]: entry(FheErrorCode.InvalidArgument, "error", false, 400, "errors.invalid_argument", "Invalid argument", "A function argument was invalid."),
+    [FheErrorCode.InvalidAddress]: entry(FheErrorCode.InvalidAddress, "error", false, 400, "errors.invalid_address", "Invalid address: {address}", "The address is not a valid Ethereum address."),
+    [FheErrorCode.InvalidHandle]: entry(FheErrorCode.InvalidHandle, "error", false, 400, "errors.invalid_handle", "Invalid handle: {handle}", "The ciphertext handle is not a valid 32-byte handle."),
+    [FheErrorCode.InvalidHex]: entry(FheErrorCode.InvalidHex, "error", false, 400, "errors.invalid_hex", "Invalid hex string: {value}", "The hex string is malformed."),
+    [FheErrorCode.EmptyInput]: entry(FheErrorCode.EmptyInput, "error", false, 400, "errors.empty_input", "Input cannot be empty", "The operation requires non-empty input."),
+    [FheErrorCode.Network]: entry(FheErrorCode.Network, "error", true, 502, "errors.network", "Network error", "A network-level failure occurred."),
+    [FheErrorCode.Timeout]: entry(FheErrorCode.Timeout, "error", true, 504, "errors.timeout", "Request timed out", "The request exceeded the timeout budget."),
+    [FheErrorCode.HttpError]: entry(FheErrorCode.HttpError, "error", true, 502, "errors.http", "HTTP error {status}", "The HTTP request returned an unexpected status."),
+    [FheErrorCode.RateLimited]: entry(FheErrorCode.RateLimited, "warn", true, 429, "errors.rate_limited", "Rate limited", "The upstream service rate-limited the request."),
+    [FheErrorCode.Aborted]: entry(FheErrorCode.Aborted, "warn", false, 400, "errors.aborted", "Request aborted", "The request was aborted before completion."),
+    [FheErrorCode.AuthMissing]: entry(FheErrorCode.AuthMissing, "error", false, 401, "errors.auth_missing", "Authentication is required", "Authentication credentials were not provided."),
+    [FheErrorCode.AuthInvalid]: entry(FheErrorCode.AuthInvalid, "error", false, 401, "errors.auth_invalid", "Authentication failed", "The provided authentication credentials are invalid."),
+    [FheErrorCode.PermissionDenied]: entry(FheErrorCode.PermissionDenied, "error", false, 403, "errors.permission_denied", "Permission denied", "The operation is not permitted for the caller."),
+    [FheErrorCode.JazzRequestRejected]: entry(FheErrorCode.JazzRequestRejected, "error", false, 400, "errors.jazz_request_rejected", "Jazz request rejected", "The Jazz service rejected the request."),
+    [FheErrorCode.JazzJobFailed]: entry(FheErrorCode.JazzJobFailed, "error", true, 502, "errors.jazz_job_failed", "Jazz job failed", "The asynchronous Jazz job failed."),
+    [FheErrorCode.JazzUnexpectedResponse]: entry(FheErrorCode.JazzUnexpectedResponse, "error", false, 502, "errors.jazz_unexpected_response", "Unexpected Jazz response", "The Jazz service returned an unexpected response."),
+    [FheErrorCode.EncryptionFailed]: entry(FheErrorCode.EncryptionFailed, "error", false, 500, "errors.encryption_failed", "Encryption failed", "The encryption operation failed."),
+    [FheErrorCode.DecryptionFailed]: entry(FheErrorCode.DecryptionFailed, "error", false, 500, "errors.decryption_failed", "Decryption failed", "The decryption operation failed."),
+    [FheErrorCode.KmsNotInitialized]: entry(FheErrorCode.KmsNotInitialized, "error", true, 500, "errors.kms_not_initialized", "KMS module is not initialized", "The KMS WASM module has not been initialized."),
+    [FheErrorCode.WasmNotInitialized]: entry(FheErrorCode.WasmNotInitialized, "error", true, 500, "errors.wasm_not_initialized", "WASM module is not initialized", "The FHE WASM module has not been initialized."),
+    [FheErrorCode.WasmTimeout]: entry(FheErrorCode.WasmTimeout, "error", true, 500, "errors.wasm_timeout", "WASM initialization timed out", "The FHE WASM module failed to initialize in time."),
+    [FheErrorCode.ProofVerificationFailed]: entry(FheErrorCode.ProofVerificationFailed, "error", false, 500, "errors.proof_verification_failed", "Proof verification failed", "Signature or proof verification failed."),
+    [FheErrorCode.ThresholdNotMet]: entry(FheErrorCode.ThresholdNotMet, "error", false, 500, "errors.threshold_not_met", "Recovered signatures do not meet the threshold", "Not enough valid signatures were provided."),
+    [FheErrorCode.UnknownSigner]: entry(FheErrorCode.UnknownSigner, "error", false, 500, "errors.unknown_signer", "Unknown signer detected", "A recovered signer is not in the allowed signer set."),
+    [FheErrorCode.PermitNotFound]: entry(FheErrorCode.PermitNotFound, "warn", false, 404, "errors.permit_not_found", "Permit not found in cache", "No cached permit exists for the requested scope."),
+    [FheErrorCode.PermitInvalid]: entry(FheErrorCode.PermitInvalid, "error", false, 500, "errors.permit_invalid", "Permit is invalid", "The cached permit failed validation."),
+    [FheErrorCode.KeyPairNotFound]: entry(FheErrorCode.KeyPairNotFound, "warn", false, 404, "errors.keypair_not_found", "Transport key pair not found", "No cached transport key pair exists."),
+    [FheErrorCode.CacheFailure]: entry(FheErrorCode.CacheFailure, "error", false, 500, "errors.cache_failure", "Cache operation failed", "A cache read or write failed."),
+    [FheErrorCode.CacheMiss]: entry(FheErrorCode.CacheMiss, "warn", false, 404, "errors.cache_miss", "Cache entry not found", "The requested cache entry does not exist."),
+    [FheErrorCode.TransactionReverted]: entry(FheErrorCode.TransactionReverted, "error", true, 500, "errors.tx_reverted", "Transaction reverted: {txHash}", "The submitted transaction reverted on-chain."),
+    [FheErrorCode.TransactionFailed]: entry(FheErrorCode.TransactionFailed, "error", true, 500, "errors.tx_failed", "Transaction failed", "The transaction could not be completed."),
+    [FheErrorCode.FeeEstimationFailed]: entry(FheErrorCode.FeeEstimationFailed, "error", false, 500, "errors.fee_estimation_failed", "Fee estimation failed", "The FHE fee could not be estimated."),
+    [FheErrorCode.ContractCallFailed]: entry(FheErrorCode.ContractCallFailed, "error", false, 500, "errors.contract_call_failed", "Contract call failed", "A contract call failed."),
+    [FheErrorCode.NotImplemented]: entry(FheErrorCode.NotImplemented, "error", false, 501, "errors.not_implemented", "Not implemented", "The requested functionality is not implemented."),
+    [FheErrorCode.Unsupported]: entry(FheErrorCode.Unsupported, "error", false, 400, "errors.unsupported", "Unsupported operation", "The requested operation is not supported."),
+    [FheErrorCode.Internal]: entry(FheErrorCode.Internal, "error", false, 500, "errors.internal", "Internal SDK error", "An unexpected internal error occurred."),
+    [FheErrorCode.Unknown]: entry(FheErrorCode.Unknown, "error", false, 500, "errors.unknown", "Unknown error", "An error of unknown origin occurred."),
+};
+/**
+ * Returns the catalog entry for a code. Unknown codes fall back to INTERNAL so
+ * serialization never fails on a missing entry.
+ */
+export function getErrorCatalogEntry(code) {
+    return FHE_ERROR_CATALOG[code] ?? FHE_ERROR_CATALOG[FheErrorCode.Internal];
+}
+/**
+ * Interpolates "{key}" placeholders from context. Missing values are left
+ * as-is so callers can spot template mismatches.
+ */
+export function formatMessage(template, context) {
+    if (!context) {
+        return template;
+    }
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+        const value = context[key];
+        return value === undefined || value === null ? match : String(value);
+    });
+}
+//# sourceMappingURL=error-catalog.js.map

package/dist/core/errors/error-catalog.js.map

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

package/dist/core/errors/error-codes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stable, machine-readable error identifiers.
+ *
+ * Codes are UPPER_SNAKE strings grouped by domain. They are part of the
+ * public contract: clients switch on these values, so a code must never be
+ * renamed or reused for a different meaning after release.
+ */
+export declare const FheErrorCode: {
+    readonly InvalidConfig: "CONFIG_INVALID";
+    readonly MissingProvider: "CONFIG_MISSING_PROVIDER";
+    readonly MissingSigner: "CONFIG_MISSING_SIGNER";
+    readonly MissingJazzUrl: "CONFIG_MISSING_JAZZ_URL";
+    readonly UnsupportedChain: "CHAIN_UNSUPPORTED";
+    readonly InvalidArgument: "VALIDATION_INVALID_ARGUMENT";
+    readonly InvalidAddress: "VALIDATION_INVALID_ADDRESS";
+    readonly InvalidHandle: "VALIDATION_INVALID_HANDLE";
+    readonly InvalidHex: "VALIDATION_INVALID_HEX";
+    readonly EmptyInput: "VALIDATION_EMPTY_INPUT";
+    readonly Network: "NETWORK_ERROR";
+    readonly Timeout: "NETWORK_TIMEOUT";
+    readonly HttpError: "NETWORK_HTTP";
+    readonly RateLimited: "NETWORK_RATE_LIMITED";
+    readonly Aborted: "NETWORK_ABORTED";
+    readonly AuthMissing: "AUTH_MISSING";
+    readonly AuthInvalid: "AUTH_INVALID";
+    readonly PermissionDenied: "AUTH_PERMISSION_DENIED";
+    readonly JazzRequestRejected: "JAZZ_REQUEST_REJECTED";
+    readonly JazzJobFailed: "JAZZ_JOB_FAILED";
+    readonly JazzUnexpectedResponse: "JAZZ_UNEXPECTED_RESPONSE";
+    readonly EncryptionFailed: "ENCRYPTION_FAILED";
+    readonly DecryptionFailed: "DECRYPTION_FAILED";
+    readonly KmsNotInitialized: "KMS_NOT_INITIALIZED";
+    readonly WasmNotInitialized: "WASM_NOT_INITIALIZED";
+    readonly WasmTimeout: "WASM_INIT_TIMEOUT";
+    readonly ProofVerificationFailed: "PROOF_VERIFICATION_FAILED";
+    readonly ThresholdNotMet: "THRESHOLD_NOT_MET";
+    readonly UnknownSigner: "SIGNER_UNKNOWN";
+    readonly PermitNotFound: "PERMIT_NOT_FOUND";
+    readonly PermitInvalid: "PERMIT_INVALID";
+    readonly KeyPairNotFound: "KEYPAIR_NOT_FOUND";
+    readonly CacheFailure: "CACHE_FAILURE";
+    readonly CacheMiss: "CACHE_MISS";
+    readonly TransactionReverted: "TX_REVERTED";
+    readonly TransactionFailed: "TX_FAILED";
+    readonly FeeEstimationFailed: "FEE_ESTIMATION_FAILED";
+    readonly ContractCallFailed: "CONTRACT_CALL_FAILED";
+    readonly NotImplemented: "NOT_IMPLEMENTED";
+    readonly Unsupported: "UNSUPPORTED";
+    readonly Internal: "INTERNAL";
+    readonly Unknown: "UNKNOWN";
+};
+export type FheErrorCode = (typeof FheErrorCode)[keyof typeof FheErrorCode];

package/dist/core/errors/error-codes.js

@@ -0,0 +1,61 @@
+/**
+ * Stable, machine-readable error identifiers.
+ *
+ * Codes are UPPER_SNAKE strings grouped by domain. They are part of the
+ * public contract: clients switch on these values, so a code must never be
+ * renamed or reused for a different meaning after release.
+ */
+export const FheErrorCode = {
+    // Configuration / construction
+    InvalidConfig: "CONFIG_INVALID",
+    MissingProvider: "CONFIG_MISSING_PROVIDER",
+    MissingSigner: "CONFIG_MISSING_SIGNER",
+    MissingJazzUrl: "CONFIG_MISSING_JAZZ_URL",
+    UnsupportedChain: "CHAIN_UNSUPPORTED",
+    // Input validation
+    InvalidArgument: "VALIDATION_INVALID_ARGUMENT",
+    InvalidAddress: "VALIDATION_INVALID_ADDRESS",
+    InvalidHandle: "VALIDATION_INVALID_HANDLE",
+    InvalidHex: "VALIDATION_INVALID_HEX",
+    EmptyInput: "VALIDATION_EMPTY_INPUT",
+    // Network / transport
+    Network: "NETWORK_ERROR",
+    Timeout: "NETWORK_TIMEOUT",
+    HttpError: "NETWORK_HTTP",
+    RateLimited: "NETWORK_RATE_LIMITED",
+    Aborted: "NETWORK_ABORTED",
+    // Authentication / authorization
+    AuthMissing: "AUTH_MISSING",
+    AuthInvalid: "AUTH_INVALID",
+    PermissionDenied: "AUTH_PERMISSION_DENIED",
+    // Jazz / API protocol
+    JazzRequestRejected: "JAZZ_REQUEST_REJECTED",
+    JazzJobFailed: "JAZZ_JOB_FAILED",
+    JazzUnexpectedResponse: "JAZZ_UNEXPECTED_RESPONSE",
+    // Crypto / FHE
+    EncryptionFailed: "ENCRYPTION_FAILED",
+    DecryptionFailed: "DECRYPTION_FAILED",
+    KmsNotInitialized: "KMS_NOT_INITIALIZED",
+    WasmNotInitialized: "WASM_NOT_INITIALIZED",
+    WasmTimeout: "WASM_INIT_TIMEOUT",
+    ProofVerificationFailed: "PROOF_VERIFICATION_FAILED",
+    ThresholdNotMet: "THRESHOLD_NOT_MET",
+    UnknownSigner: "SIGNER_UNKNOWN",
+    // Permits / keys
+    PermitNotFound: "PERMIT_NOT_FOUND",
+    PermitInvalid: "PERMIT_INVALID",
+    KeyPairNotFound: "KEYPAIR_NOT_FOUND",
+    CacheFailure: "CACHE_FAILURE",
+    CacheMiss: "CACHE_MISS",
+    // On-chain
+    TransactionReverted: "TX_REVERTED",
+    TransactionFailed: "TX_FAILED",
+    FeeEstimationFailed: "FEE_ESTIMATION_FAILED",
+    ContractCallFailed: "CONTRACT_CALL_FAILED",
+    // General
+    NotImplemented: "NOT_IMPLEMENTED",
+    Unsupported: "UNSUPPORTED",
+    Internal: "INTERNAL",
+    Unknown: "UNKNOWN",
+};
+//# sourceMappingURL=error-codes.js.map

package/dist/core/errors/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../../src/core/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,+BAA+B;IAC/B,aAAa,EAAE,gBAAgB;IAC/B,eAAe,EAAE,yBAAyB;IAC1C,aAAa,EAAE,uBAAuB;IACtC,cAAc,EAAE,yBAAyB;IACzC,gBAAgB,EAAE,mBAAmB;IAErC,mBAAmB;IACnB,eAAe,EAAE,6BAA6B;IAC9C,cAAc,EAAE,4BAA4B;IAC5C,aAAa,EAAE,2BAA2B;IAC1C,UAAU,EAAE,wBAAwB;IACpC,UAAU,EAAE,wBAAwB;IAEpC,sBAAsB;IACtB,OAAO,EAAE,eAAe;IACxB,OAAO,EAAE,iBAAiB;IAC1B,SAAS,EAAE,cAAc;IACzB,WAAW,EAAE,sBAAsB;IACnC,OAAO,EAAE,iBAAiB;IAE1B,iCAAiC;IACjC,WAAW,EAAE,cAAc;IAC3B,WAAW,EAAE,cAAc;IAC3B,gBAAgB,EAAE,wBAAwB;IAE1C,sBAAsB;IACtB,mBAAmB,EAAE,uBAAuB;IAC5C,aAAa,EAAE,iBAAiB;IAChC,sBAAsB,EAAE,0BAA0B;IAElD,eAAe;IACf,gBAAgB,EAAE,mBAAmB;IACrC,gBAAgB,EAAE,mBAAmB;IACrC,iBAAiB,EAAE,qBAAqB;IACxC,kBAAkB,EAAE,sBAAsB;IAC1C,WAAW,EAAE,mBAAmB;IAChC,uBAAuB,EAAE,2BAA2B;IACpD,eAAe,EAAE,mBAAmB;IACpC,aAAa,EAAE,gBAAgB;IAE/B,iBAAiB;IACjB,cAAc,EAAE,kBAAkB;IAClC,aAAa,EAAE,gBAAgB;IAC/B,eAAe,EAAE,mBAAmB;IACpC,YAAY,EAAE,eAAe;IAC7B,SAAS,EAAE,YAAY;IAEvB,WAAW;IACX,mBAAmB,EAAE,aAAa;IAClC,iBAAiB,EAAE,WAAW;IAC9B,mBAAmB,EAAE,uBAAuB;IAC5C,kBAAkB,EAAE,sBAAsB;IAE1C,UAAU;IACV,cAAc,EAAE,iBAAiB;IACjC,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/core/errors/error-utils.d.ts

@@ -0,0 +1,27 @@
+import { FheErrorContext } from "./error-catalog.js";
+import { FheError, FheErrorOptions } from "./fhe-error.js";
+/**
+ * Wraps any thrown value into an FheError.
+ *
+ * - Already-FheError values are returned unchanged.
+ * - Plain Error instances become INTERNAL errors with the original as cause.
+ * - Message-like objects and primitives are stringified.
+ */
+export declare function toFheError(error: unknown, options?: Partial<FheErrorOptions>): FheError;
+export declare function isFheError(error: unknown): error is FheError;
+export declare function getErrorCode(error: unknown): string;
+export declare function getErrorMessage(error: unknown): string;
+export interface ErrorRetryPolicy {
+    retryable: boolean;
+    retryAfterMs?: number;
+}
+/**
+ * Single retry decision point. FheErrors carry their retryability directly;
+ * legacy errors fall back to a conservative non-retryable answer.
+ */
+export declare function getErrorRetryPolicy(error: unknown): ErrorRetryPolicy;
+/**
+ * Wraps an async operation, attaching operation/context on failure.
+ * Existing FheErrors with an operation are rethrown unchanged.
+ */
+export declare function withFheError<T>(operation: string, fn: () => Promise<T>, context?: FheErrorContext, debugContext?: FheErrorContext): Promise<T>;

package/dist/core/errors/error-utils.js

@@ -0,0 +1,110 @@
+import { FheErrorCode } from "./error-codes.js";
+import { FheError } from "./fhe-error.js";
+/**
+ * Wraps any thrown value into an FheError.
+ *
+ * - Already-FheError values are returned unchanged.
+ * - Plain Error instances become INTERNAL errors with the original as cause.
+ * - Message-like objects and primitives are stringified.
+ */
+export function toFheError(error, options) {
+    if (isFheError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new FheError({
+            code: options?.code ?? FheErrorCode.Internal,
+            message: options?.message ?? error.message,
+            cause: error,
+            context: options?.context,
+            debugContext: options?.debugContext,
+            operation: options?.operation,
+            operationId: options?.operationId,
+            retryable: options?.retryable,
+            retryAfterMs: options?.retryAfterMs,
+            captureStack: options?.captureStack,
+        });
+    }
+    if (typeof error === "object" && error !== null && "message" in error) {
+        const message = String(error.message);
+        return new FheError({
+            code: options?.code ?? FheErrorCode.Internal,
+            message: options?.message ?? message,
+            cause: error,
+            context: options?.context,
+            debugContext: options?.debugContext,
+            operation: options?.operation,
+            operationId: options?.operationId,
+            retryable: options?.retryable,
+            retryAfterMs: options?.retryAfterMs,
+            captureStack: options?.captureStack,
+        });
+    }
+    return new FheError({
+        code: options?.code ?? FheErrorCode.Unknown,
+        message: options?.message ?? String(error),
+        cause: error,
+        context: options?.context,
+        debugContext: options?.debugContext,
+        operation: options?.operation,
+        operationId: options?.operationId,
+        retryable: options?.retryable,
+        retryAfterMs: options?.retryAfterMs,
+        captureStack: options?.captureStack,
+    });
+}
+export function isFheError(error) {
+    return error instanceof FheError;
+}
+export function getErrorCode(error) {
+    return isFheError(error) ? error.code : FheErrorCode.Unknown;
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "object" && error !== null && "message" in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Single retry decision point. FheErrors carry their retryability directly;
+ * legacy errors fall back to a conservative non-retryable answer.
+ */
+export function getErrorRetryPolicy(error) {
+    if (isFheError(error)) {
+        return { retryable: error.retryable, retryAfterMs: error.retryAfterMs };
+    }
+    return { retryable: false };
+}
+/**
+ * Wraps an async operation, attaching operation/context on failure.
+ * Existing FheErrors with an operation are rethrown unchanged.
+ */
+export async function withFheError(operation, fn, context, debugContext) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (isFheError(error)) {
+            if (error.operation) {
+                throw error;
+            }
+            throw new FheError({
+                code: error.code,
+                message: error.message,
+                context: { ...error.context, ...context },
+                debugContext: { ...error.debugContext, ...debugContext },
+                cause: error.cause,
+                operation,
+                operationId: error.operationId,
+                retryable: error.retryable,
+                retryAfterMs: error.retryAfterMs,
+                captureStack: error.captureStack,
+            });
+        }
+        throw toFheError(error, { operation, context, debugContext });
+    }
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/core/errors/error-utils.js.map

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

package/dist/core/errors/fhe-error.d.ts

@@ -0,0 +1,98 @@
+import { FheErrorCode } from "./error-codes.js";
+import { FheErrorContext } from "./error-catalog.js";
+export interface FheErrorOptions {
+    code: FheErrorCode;
+    /** Overrides the catalog message template; usually omitted. */
+    message?: string;
+    /** Public context - sanitized, frozen, and serialized. */
+    context?: FheErrorContext;
+    /** Debug context - rich data that never appears in the public payload. */
+    debugContext?: FheErrorContext;
+    cause?: unknown;
+    operation?: string;
+    operationId?: string;
+    /** Overrides the catalog retryable default. */
+    retryable?: boolean;
+    retryAfterMs?: number;
+    /**
+     * Controls whether the stack trace is included in `toJSON()`.
+     * Defaults to enabled outside production builds.
+     */
+    captureStack?: boolean;
+}
+export interface SanitizedCause {
+    name?: string;
+    code?: string;
+    message: string;
+}
+export interface FheErrorPayload {
+    error: {
+        name: "FheError";
+        code: string;
+        message: string;
+        messageKey: string;
+        operation?: string;
+        operationId?: string;
+        context?: FheErrorContext;
+        retryable: boolean;
+        retryAfterMs?: number;
+        docsUrl: string;
+        httpStatus: number;
+        cause?: SanitizedCause;
+        stack?: string;
+        timestamp: string;
+    };
+}
+/**
+ * Unified, production-ready SDK error.
+ *
+ * Every SDK failure should surface as an FheError so clients can switch on
+ * `code` instead of matching message text. The serialized payload is JSON-safe
+ * and deliberately never contains secrets or debug-only context.
+ */
+export declare class FheError extends Error {
+    readonly code: FheErrorCode;
+    readonly messageKey: string;
+    readonly docsUrl: string;
+    readonly httpStatus: number;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly operation?: string;
+    readonly operationId?: string;
+    readonly context: Readonly<FheErrorContext> | undefined;
+    readonly debugContext: Readonly<FheErrorContext> | undefined;
+    readonly captureStack: boolean;
+    readonly timestamp: string;
+    private _causeChain?;
+    private _public?;
+    private _full?;
+    constructor(options: FheErrorOptions);
+    /**
+     * Full envelope including the stack trace when captureStack is enabled.
+     * The result is memoized per instance.
+     */
+    toJSON(): FheErrorPayload;
+    /**
+     * Sanitized payload without stack traces or debug context. Safe to expose
+     * to external clients and APIs. Memoized per instance.
+     */
+    getPublicPayload(): FheErrorPayload["error"];
+    /** HTTP boundary helper: maps the error to a status code and JSON body. */
+    toHttpResponse(): {
+        status: number;
+        body: FheErrorPayload;
+    };
+    /**
+     * Lazy, cycle-safe cause chain (immediate cause first), capped at
+     * MAX_CAUSE_DEPTH. Memoized per instance.
+     */
+    getCauseChain(): SanitizedCause[];
+    static invalidArgument(context?: FheErrorContext, cause?: unknown): FheError;
+    static network(cause?: unknown, context?: FheErrorContext): FheError;
+    static transactionReverted(context: FheErrorContext & {
+        txHash?: string;
+    }, cause?: unknown): FheError;
+    static permissionDenied(context?: FheErrorContext): FheError;
+    static internal(cause?: unknown, context?: FheErrorContext): FheError;
+    static notImplemented(context?: FheErrorContext): FheError;
+}