@primuslabs/fhetransform-sdk 0.4.0

package/dist/jazz/read-contract.js

@@ -0,0 +1,125 @@
+import { ethers } from "ethers";
+import { TTLCache } from "../core/ttl-cache.js";
+import { spaceBridgeConfigAbi } from "../abis/space_bridge_config.abi.js";
+import { logger } from "../core/logger.js";
+/**
+ * Cache instance for Alphatrion signers information.
+ * Uses default TTL (24 hours) as this data changes infrequently.
+ */
+const readAlphatrionSignersInfoCache = new TTLCache();
+/**
+ * Retrieves Alphatrion signers and threshold from the SpaceBridge configuration contract.
+ * Results are cached to minimize expensive blockchain RPC calls.
+ *
+ * @param client - The Jazz client instance providing SDK and provider access
+ * @param forceRefresh - If true, bypasses cache and fetches fresh data from the contract
+ * @returns Promise containing Alphatrion signers array and threshold
+ *
+ * @example
+ * ```typescript
+ * // Get cached data (or fetch if expired)
+ * const info = await readAlphatrionSignersInfo(client);
+ *
+ * // Force fresh data from contract
+ * const freshInfo = await readAlphatrionSignersInfo(client, true);
+ * ```
+ */
+export async function readAlphatrionSignersInfo(client, forceRefresh = false) {
+    return await readAlphatrionSignersInfoCache.get(async () => {
+        logger.debug('[readAlphatrionSignersInfo] Fetching Alphatrion signers info from contract');
+        // Get contract configuration and provider
+        const sysContractInfo = await client.sdk.getSystemContractInfo();
+        const provider = await client.sdk.requireProvider();
+        // Initialize contract instance
+        const contract = new ethers.Contract(sysContractInfo.spaceBridgeConfigAddress, spaceBridgeConfigAbi, provider);
+        // Fetch both values in parallel for efficiency
+        const [alphatrionSigners, alphatrionThreshold] = await Promise.all([
+            contract.getAlphatrionSigners(),
+            contract.getAlphatrionThreshold(),
+        ]);
+        logger.debug('[readAlphatrionSignersInfo] Alphatrion signers info retrieved', {
+            alphatrionSigners,
+            alphatrionThreshold
+        });
+        return { alphatrionSigners, alphatrionThreshold };
+    }, forceRefresh);
+}
+/**
+ * Cache instance for KMS signers information.
+ * Uses default TTL (24 hours) as this data changes infrequently.
+ */
+const readKmsSignersInfoCache = new TTLCache();
+/**
+ * Retrieves KMS signers and decryption thresholds from the SpaceBridge configuration contract.
+ * Results are cached to minimize expensive blockchain RPC calls.
+ *
+ * @param client - The Jazz client instance providing SDK and provider access
+ * @param forceRefresh - If true, bypasses cache and fetches fresh data from the contract
+ * @returns Promise containing KMS signers array and decryption thresholds
+ *
+ * @example
+ * ```typescript
+ * // Get cached data (or fetch if expired)
+ * const info = await readKmsSignersInfo(client);
+ *
+ * // Force fresh data from contract
+ * const freshInfo = await readKmsSignersInfo(client, true);
+ * ```
+ */
+export async function readKmsSignersInfo(client, forceRefresh = false) {
+    return await readKmsSignersInfoCache.get(async () => {
+        logger.debug('[readKmsSignersInfo] Fetching KMS signers info from contract');
+        // Get contract configuration and provider
+        const sysContractInfo = await client.sdk.getSystemContractInfo();
+        const provider = await client.sdk.requireProvider();
+        // Initialize contract instance
+        const contract = new ethers.Contract(sysContractInfo.spaceBridgeConfigAddress, spaceBridgeConfigAbi, provider);
+        // Fetch all three values in parallel for efficiency
+        const [kmsSigners, publicDecryptionThreshold, userDecryptionThreshold] = await Promise.all([
+            contract.getKmsSigners(),
+            contract.getPublicDecryptionThreshold(),
+            contract.getUserDecryptionThreshold(),
+        ]);
+        logger.debug('[readKmsSignersInfo] KMS signers info retrieved', {
+            kmsSigners,
+            publicDecryptionThreshold,
+            userDecryptionThreshold
+        });
+        return { kmsSigners, publicDecryptionThreshold, userDecryptionThreshold };
+    }, forceRefresh);
+}
+/**
+ * Utility function to clear all cached contract information.
+ * Useful when the contract configuration is known to have changed.
+ *
+ * @example
+ * ```typescript
+ * // Clear all caches after a contract upgrade
+ * clearAllContractCaches();
+ * ```
+ */
+export function clearAllContractCaches() {
+    readAlphatrionSignersInfoCache.clear();
+    readKmsSignersInfoCache.clear();
+    logger.debug('[ContractCache] All contract caches cleared');
+}
+/**
+ * Utility function to refresh all cached contract information simultaneously.
+ *
+ * @param client - The Jazz client instance
+ * @returns Promise that resolves when all data has been refreshed
+ *
+ * @example
+ * ```typescript
+ * // Force refresh all cached contract data
+ * await refreshAllContractCaches(client);
+ * ```
+ */
+export async function refreshAllContractCaches(client) {
+    await Promise.all([
+        readAlphatrionSignersInfo(client, true),
+        readKmsSignersInfo(client, true),
+    ]);
+    logger.debug('[ContractCache] All contract caches refreshed');
+}
+//# sourceMappingURL=read-contract.js.map

package/dist/jazz/read-contract.js.map

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

package/dist/jazz/types/common.d.ts

@@ -0,0 +1,17 @@
+import { TimeoutRetryOptions } from "../../core/retryable-handler.js";
+export type JazzOnProgressArgs = {
+    operation?: string;
+    status?: string;
+    elapsed?: number;
+    jobId?: string;
+    error?: string;
+};
+export type JazzProcessOptions = {
+    onJazzProgress?: (args: JazzOnProgressArgs) => void;
+    /** Retry configuration options */
+    jazzRetryOptions?: TimeoutRetryOptions;
+};
+export type FetchInputProofOptions = JazzProcessOptions & {};
+export type FetchUserDecryptOptions = JazzProcessOptions & {};
+export type FetchPublicDecryptOptions = JazzProcessOptions & {};
+export type FetchKeyUrlOptions = JazzProcessOptions & {};

package/dist/jazz/types/common.js

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

package/dist/jazz/types/common.js.map

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

package/dist/jazz/types/input-proof.d.ts

@@ -0,0 +1,76 @@
+import { Address, Bytes, Bytes65Hex, BytesHex, BytesHexNo0x, Hex0x } from "../../core/primitives.js";
+import { FetchInputProofOptions } from "./common.js";
+/**
+ * ZK Proof data structure containing all information needed for input proof verification.
+ *
+ * This interface represents the zero-knowledge proof data that will be submitted
+ * to the Jazz service for verification. It includes chain information, contract
+ * addresses, user address, and the ciphertext with ZK proof.
+ */
+export interface ZkProof {
+    /** Chain ID as a bigint */
+    readonly chainId: bigint;
+    /** ACL contract address (0x-prefixed hex string) */
+    readonly aclContractAddress: Address;
+    /** Target contract address (0x-prefixed hex string) */
+    readonly contractAddress: Address;
+    /** User address (0x-prefixed hex string) */
+    readonly userAddress: Address;
+    /** Ciphertext with embedded ZK proof as Bytes */
+    readonly ciphertextWithZkProof: Bytes;
+}
+/**
+ * Parameters for fetching an input proof from the Jazz service.
+ */
+export type FetchInputProofParameters = {
+    /** Payload containing the ZK proof data */
+    readonly payload: {
+        readonly zkProof: ZkProof;
+    };
+    /** Additional options for the request */
+    readonly options?: FetchInputProofOptions;
+};
+/**
+ * Result of a successful input proof fetch operation.
+ */
+export type FetchInputProofResult = {
+    /** Ordered list of hex-encoded handles with 0x prefix */
+    readonly handles: readonly BytesHex[];
+    /** EIP-712 signatures from the alphatrion, ordered to match handles */
+    readonly alphatrionEip712Signatures: readonly Bytes65Hex[];
+    /** Additional contextual data as hex with 0x prefix */
+    readonly extraData: BytesHex;
+};
+/**
+ * Payload structure sent to the Jazz `/v2/input-proof` endpoint.
+ *
+ * This is the raw payload format expected by the Jazz API. It differs
+ * from FetchInputProofParameters in that it uses specific hex formats
+ * expected by the service.
+ */
+export type JazzInputProofPayload = {
+    /** Hex-encoded uint256 string with 0x prefix (e.g., "0x1" for chainId 1) */
+    readonly contractChainId: Hex0x;
+    /** Hex-encoded address with 0x prefix */
+    readonly contractAddress: Address;
+    /** Hex-encoded address with 0x prefix */
+    readonly userAddress: Address;
+    /** Hex-encoded binary proof without 0x prefix */
+    readonly ciphertextWithInputVerification: BytesHexNo0x;
+    /** Hex-encoded bytes with 0x prefix, defaults to "0x00" */
+    readonly extraData: BytesHex;
+};
+/**
+ * Result structure returned by the Jazz `/v2/input-proof` endpoint.
+ *
+ * This is the raw result format from the Jazz API before transformation
+ * into FetchInputProofResult.
+ */
+export type JazzInputProofResult = {
+    /** Ordered list of hex-encoded handles with 0x prefix */
+    readonly handles: readonly any[];
+    /** Attestation signatures for input verification, ordered to match handles, with 0x prefix */
+    readonly signatures: readonly Bytes65Hex[];
+    /** Additional contextual data as hex with 0x prefix */
+    readonly extraData: BytesHex;
+};

package/dist/jazz/types/input-proof.js

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

package/dist/jazz/types/input-proof.js.map

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

package/dist/jazz/types/key-url.d.ts

@@ -0,0 +1,68 @@
+import { FetchKeyUrlOptions } from "./common.js";
+/**
+ * Parameters for fetching key URLs from the Jazz service.
+ * Currently only supports optional request options.
+ */
+export type FetchKeyUrlParameters = {
+    /** Additional options for the request */
+    readonly options?: FetchKeyUrlOptions;
+};
+/**
+ * Configuration for fetching a TFHE public key from a remote URL.
+ *
+ * Typically obtained from the `/keyurl` response, which provides
+ * the URLs for fetching the public key data.
+ */
+export type FheEncryptionPublicKeySource = {
+    /** Unique identifier for the public key provided by the Jazz service */
+    readonly id: string;
+    /** URL from which to fetch the public key bytes */
+    readonly url: string;
+};
+/**
+ * Configuration for fetching a TFHE Public Key Encryption (PKE) Common Reference
+ * String (CRS) from a remote URL.
+ *
+ * Typically obtained from the `/keyurl` response, which provides
+ * the URLs for fetching the CRS data.
+ */
+export type FheEncryptionCrsSource = {
+    /** Unique identifier for the CRS provided by the Jazz service */
+    readonly id: string;
+    /** URL from which to fetch the CRS bytes */
+    readonly url: string;
+    /** The CRS capacity (always 2048 in the current configuration) */
+    readonly capacity: number;
+};
+/**
+ * Metadata about the FHE encryption key origin.
+ * Used for tracking the source and context of the key.
+ */
+export type FheEncryptionKeyMetadata = {
+    /** The Jazz service URL where the key was obtained */
+    readonly jazzUrl: string;
+    /** The chain ID associated with this key */
+    readonly chainId: number;
+};
+/**
+ * Complete URL configuration for fetching TFHE PKE (Public Key Encryption) parameters.
+ *
+ * This type combines the public key source, CRS source, and optional metadata
+ * into a single configuration object for easy access.
+ */
+export type FheEncryptionKeySource = {
+    /** URL configuration for the TFHE compact public key */
+    readonly publicKeySource: FheEncryptionPublicKeySource;
+    /** URL configuration for the PKE CRS (Common Reference String) */
+    readonly crsSource: FheEncryptionCrsSource;
+};
+/**
+ * Result of a successful key URL fetch operation.
+ * This is the user-facing result type.
+ */
+export type FetchKeyUrlResult = FheEncryptionKeySource;
+/**
+ * Result type returned by the Jazz `/v2/keyurl` endpoint.
+ * This is the raw result from the Jazz API (same structure).
+ */
+export type JazzKeyUrlResult = FheEncryptionKeySource;

package/dist/jazz/types/key-url.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// Fetch Key URL Types
+// ============================================================================
+export {};
+//# sourceMappingURL=key-url.js.map

package/dist/jazz/types/key-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-url.js","sourceRoot":"","sources":["../../../src/jazz/types/key-url.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E"}

package/dist/jazz/types/public-decrypt.d.ts

@@ -0,0 +1,61 @@
+import { HandleLike } from "../../core/fhe-type.js";
+import { Bytes65Hex, BytesHex, BytesHexNo0x } from "../../core/primitives.js";
+import { FetchPublicDecryptOptions } from "./common.js";
+/**
+ * Parameters for fetching public decryption results from the Jazz service.
+ *
+ * This type defines the input required to request public decryption of
+ * ciphertext handles, returning the decrypted values with their signatures.
+ */
+export type FetchPublicDecryptParameters = {
+    /** Payload containing the ordered list of ciphertext handles and extra data */
+    readonly payload: {
+        /** Ordered list of ciphertext handles to decrypt (HandleLike objects) */
+        readonly orderedHandles: readonly HandleLike[];
+        /** Additional contextual data as hex with 0x prefix */
+        readonly extraData: BytesHex;
+    };
+    /** Additional options for the request */
+    readonly options?: FetchPublicDecryptOptions;
+};
+/**
+ * Result of a successful public decryption fetch operation.
+ *
+ * This is the user-facing result type, containing decrypted values with
+ * their EIP-712 signatures and associated metadata.
+ */
+export type FetchPublicDecryptResult = {
+    /** Ordered list of ABI-encoded clear values with 0x prefix */
+    readonly orderedAbiEncodedClearValues: BytesHex;
+    /** EIP-712 signatures from KMS public decryption, ordered to match decrypted values */
+    readonly kmsPublicDecryptEIP712Signatures: Bytes65Hex[];
+    /** Additional contextual data as hex with 0x prefix */
+    readonly extraData: BytesHex;
+};
+/**
+ * Payload structure sent to the Jazz `/v2/public-decrypt` endpoint.
+ *
+ * This is the raw payload format expected by the Jazz API. It uses
+ * BytesHex format without 0x prefix for the ciphertext handles.
+ */
+export type JazzPublicDecryptPayload = {
+    /** Ordered list of ciphertext handles as hex with 0x prefix */
+    readonly ciphertextHandles: readonly BytesHex[];
+    /** Hex-encoded bytes with 0x prefix, defaults to "0x00" */
+    readonly extraData: BytesHex;
+};
+/**
+ * Result structure returned by the Jazz `/v2/public-decrypt` endpoint.
+ *
+ * This is the raw result format from the Jazz API before transformation
+ * into FetchPublicDecryptResult. Note that signatures and decrypted values
+ * are returned without 0x prefix.
+ */
+export type JazzPublicDecryptResult = {
+    /** List of signatures as hex without 0x prefix */
+    readonly signatures: readonly BytesHexNo0x[];
+    /** The decrypted value as hex without 0x prefix */
+    readonly decryptedValue: BytesHexNo0x;
+    /** Additional contextual data as hex with 0x prefix */
+    readonly extraData: BytesHex;
+};

package/dist/jazz/types/public-decrypt.js

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

package/dist/jazz/types/public-decrypt.js.map

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

package/dist/jazz/types/user-decrypt.d.ts

@@ -0,0 +1,123 @@
+import { Address, Bytes32Hex, Bytes65Hex, Bytes65HexNo0x, BytesHex, BytesHexNo0x } from "../../core/primitives.js";
+import { FetchUserDecryptOptions } from "./common.js";
+/**
+ * EIP-712 message structure for KMS user decryption requests.
+ *
+ * This defines the structured data that is signed by the user to authorize
+ * KMS decryption of their encrypted shares.
+ */
+export type KmsUserDecryptEip712Message = Readonly<{
+    /** Public key as hex with 0x prefix */
+    publicKey: BytesHex;
+    /** List of contract addresses with 0x prefix */
+    contractAddresses: readonly Address[];
+    /** Start timestamp as string (Unix timestamp) */
+    startTimestamp: string;
+    /** Duration in days as string */
+    durationDays: string;
+    /** Additional contextual data as hex with 0x prefix */
+    extraData: BytesHex;
+}>;
+/**
+ * Parameters for fetching user decryption results from the Jazz service.
+ *
+ * This type defines the input required to request user decryption of
+ * ciphertext handles, including the EIP-712 signed authorization.
+ */
+export type FetchUserDecryptParameters = {
+    /** Payload containing handle-contract pairs and signed authorization */
+    readonly payload: {
+        /** List of handle-contract pairs to decrypt */
+        readonly handleContractPairs: readonly HandleContractPair[];
+        /** Address of the EIP-712 signer with 0x prefix */
+        readonly kmsDecryptEip712Signer: Address;
+        /** EIP-712 message containing the decryption request parameters */
+        readonly kmsDecryptEip712Message: KmsUserDecryptEip712Message;
+        /** EIP-712 signature as 65-byte hex with 0x prefix */
+        readonly kmsDecryptEip712Signature: Bytes65Hex;
+    };
+    /** Additional options for the request */
+    readonly options?: FetchUserDecryptOptions;
+};
+/**
+ * A KMS signcrypted share containing the decrypted payload with its signature.
+ *
+ * This represents a single decrypted share from the KMS, containing the
+ * payload, signature, and associated metadata.
+ */
+export interface KmsSigncryptedShare {
+    /** The decrypted payload as hex without 0x prefix */
+    readonly payload: BytesHexNo0x;
+    /** The signature as 65-byte hex without 0x prefix */
+    readonly signature: Bytes65HexNo0x;
+    /** Additional contextual data as hex without 0x prefix */
+    readonly extraData: BytesHexNo0x;
+}
+/**
+ * Result of a successful user decryption fetch operation.
+ *
+ * This is the user-facing result type, containing an array of
+ * KmsSigncryptedShare objects.
+ */
+export type FetchUserDecryptResult = readonly KmsSigncryptedShare[];
+/**
+ * A pairing of a handle with its associated contract address.
+ *
+ * This is used to identify which contract each handle belongs to
+ * for proper decryption and verification.
+ */
+export type HandleContractPair = {
+    /** Hex-encoded bytes32 handle with 0x prefix */
+    readonly handle: Bytes32Hex;
+    /** Hex-encoded contract address with 0x prefix */
+    readonly contractAddress: Address;
+};
+/**
+ * Payload structure sent to the Jazz `/v2/user-decrypt` endpoint.
+ *
+ * This is the raw payload format expected by the Jazz API.
+ */
+export type JazzUserDecryptPayload = {
+    /** List of handle-contract pairs to decrypt */
+    readonly handleContractPairs: readonly HandleContractPair[];
+    /** Validity period for the decryption request */
+    readonly requestValidity: {
+        /** Start timestamp as a string (Unix timestamp) */
+        readonly startTimestamp: string;
+        /** Duration in days as a string */
+        readonly durationDays: string;
+    };
+    /** Chain ID as a string */
+    readonly contractsChainId: string;
+    /** List of contract addresses with 0x prefix */
+    readonly contractAddresses: readonly Address[];
+    /** User address with 0x prefix */
+    readonly userAddress: Address;
+    /** EIP-712 signature without 0x prefix */
+    readonly signature: Bytes65HexNo0x;
+    /** Public key without 0x prefix */
+    readonly publicKey: BytesHexNo0x;
+    /** Additional contextual data with 0x prefix, defaults to "0x00" */
+    readonly extraData: BytesHex;
+};
+/**
+ * Individual item in the Jazz user decrypt response.
+ *
+ * This represents a single decrypted share from the Jazz API.
+ */
+export type JazzUserDecryptItem = {
+    /** The decrypted payload as hex without 0x prefix */
+    readonly payload: BytesHexNo0x;
+    /** The signature as 65-byte hex without 0x prefix */
+    readonly signature: Bytes65HexNo0x;
+    /** Additional contextual data as hex with 0x prefix */
+    readonly extraData: BytesHex;
+};
+/**
+ * Result structure returned by the Jazz `/v2/user-decrypt` endpoint.
+ *
+ * This is the raw result format from the Jazz API before transformation
+ * into FetchUserDecryptResult. Note that extraData has 0x prefix in the
+ * API response but is transformed to no prefix in the user-facing result.
+ */
+export type JazzUserDecryptResult = readonly JazzUserDecryptItem[];

package/dist/jazz/types/user-decrypt.js

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

package/dist/jazz/types/user-decrypt.js.map

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

package/dist/jazz/user-decrypt-p.d.ts

@@ -0,0 +1,111 @@
+import { HandleLike, Plaintext } from "../core/fhe-type.js";
+import { TransportKeyPair } from "./key-pair.js";
+import { KmsSigncryptedShare } from "./types/user-decrypt.js";
+import { Address, Bytes32Hex, BytesHex } from "../core/primitives.js";
+import type { IJazzClient } from "./jazz-client-i.js";
+/**
+ * EIP-712 message for KMS user decryption response.
+ */
+export type KmsUserDecryptEip712Message = Readonly<{
+    /** Public key used for E2E encryption */
+    publicKey: BytesHex;
+    /** List of ciphertext handles */
+    ctHandles: readonly Bytes32Hex[];
+    /** User-decrypted data as hex with 0x prefix */
+    userDecryptedData: BytesHex;
+    /** Additional contextual data as hex with 0x prefix */
+    extraData: BytesHex;
+}>;
+/**
+ * EIP-712 type definitions for KMS user decryption.
+ */
+export type KmsUserDecryptEip712Types = {
+    readonly EIP712Domain: readonly [
+        {
+            readonly name: 'name';
+            readonly type: 'string';
+        },
+        {
+            readonly name: 'version';
+            readonly type: 'string';
+        },
+        {
+            readonly name: 'chainId';
+            readonly type: 'uint256';
+        },
+        {
+            readonly name: 'verifyingContract';
+            readonly type: 'address';
+        }
+    ];
+    readonly ResponseUserDecryptSignData: readonly [
+        {
+            readonly name: 'publicKey';
+            readonly type: 'bytes';
+        },
+        {
+            readonly name: 'ctHandles';
+            readonly type: 'bytes32[]';
+        },
+        {
+            readonly name: 'userDecryptedData';
+            readonly type: 'bytes';
+        },
+        {
+            readonly name: 'extraData';
+            readonly type: 'bytes';
+        }
+    ];
+};
+/**
+ * EIP-712 type definitions for KMS user decryption.
+ *
+ * CRITICAL: Field order is authoritative — it determines the EIP-712 type hash.
+ * Changing the order will produce a different signature and break on-chain verification.
+ * Must match the Solidity struct definition exactly.
+ */
+export declare const kmsUserDecryptEip712Types: KmsUserDecryptEip712Types;
+/**
+ * Verifies KMS user decryption EIP-712 signatures.
+ *
+ * This function:
+ * 1. Reconstructs the EIP-712 message from each share
+ * 2. Recovers the signer addresses from each signature
+ * 3. Verifies all recovered addresses are in the KMS signer set
+ * 4. Verifies the threshold is met
+ *
+ * @param client - The Jazz client instance
+ * @param params - Verification parameters (chainId, verifyingContract, handles, publicKey)
+ * @param shares - Array of KMS signcrypted shares
+ * @throws Error if verification fails (unknown signer, threshold not met, invalid signature)
+ */
+export declare function verifyUserDecryptionSignatures(client: IJazzClient, params: {
+    chainId: bigint;
+    verifyingContract: Address;
+    handles: BytesHex[];
+    publicKey: BytesHex;
+}, shares: readonly KmsSigncryptedShare[]): Promise<void>;
+/**
+ * Decrypts KMS signcrypted shares to recover plaintext values.
+ *
+ * This function:
+ * 1. Unsigncrypts each share using the KMS
+ * 2. Combines the shares to recover the secret
+ * 3. Decodes the recovered bytes to plaintext values
+ *
+ * @param handles - List of handles corresponding to the shares
+ * @param shares - Array of KMS signcrypted shares
+ * @param keypair - Transport key pair for decryption
+ * @returns Array of plaintext values
+ * @throws Error if decryption fails or shares are insufficient
+ */
+export declare function decryptKmsSignedcryptedShares(handles: HandleLike[], shares: KmsSigncryptedShare[], keypair: TransportKeyPair, kmsDecryptionSignerAddress: Address): Promise<Plaintext[]>;
+export declare function checkUserDecryptPermission(client: IJazzClient, params: {
+    aclContractAddress: Address;
+    userAddress: Address;
+    ctHandles: BytesHex[];
+    sanitizedPairs: {
+        handle: BytesHex;
+        contractAddress: BytesHex;
+    }[];
+}): Promise<void>;