@primuslabs/fhetransform-sdk 0.4.0

package/dist/jazz/permit.d.ts

@@ -0,0 +1,200 @@
+import { ethers } from "ethers";
+import { Address, Bytes65Hex, BytesHex } from "../core/primitives.js";
+import { TransportKeyPair } from "./key-pair.js";
+import { FheTransformSDK } from "../sdk/fhetransform-sdk.js";
+/**
+ * Native signer type (ethers.Signer or compatible).
+ */
+export type NativeSigner = unknown;
+/**
+ * Parameters for signing a decryption permit.
+ */
+export type SignDecryptionPermitParameters = {
+    /** List of contract addresses covered by this permit */
+    readonly contractAddresses: readonly BytesHex[];
+    /** Start timestamp (Unix timestamp in seconds) */
+    readonly startTimestamp: number;
+    /** Duration in days */
+    readonly durationDays: number;
+    /** Address of the signer */
+    readonly signerAddress: Address;
+    /** ethers.Signer instance for signing */
+    readonly signer: ethers.Signer;
+    /** Transport key pair for E2E encryption */
+    readonly transportKeyPair: TransportKeyPair;
+};
+/**
+ * Base structure for a signed decryption permit.
+ */
+export type SignedDecryptionPermitBase = {
+    /** The EIP-712 signature as 65-byte hex with 0x prefix */
+    readonly signature: Bytes65Hex;
+    /** The account that signed the permit */
+    readonly signerAddress: Address;
+    /**
+     * The account that owns the encrypted data this permit covers.
+     *
+     * - **Self permit:** equals `signerAddress` — the signer authorizes decryption
+     *   of their own data.
+     *
+     * - **Delegated permit:** differs from `signerAddress`. Step by step:
+     *   1. Alice owns encrypted values on-chain (ebool, euint8, etc.).
+     *   2. Alice calls the ACL contract to grant Bob permission to decrypt her data.
+     *   3. Bob signs an EIP-712 delegated decryption permit referencing Alice as the
+     *      `encryptedDataOwnerAddress` (= `delegatorAddress` in the EIP-712 message).
+     *   4. The KMS verifies Bob's signature (`signerAddress`) and that Alice
+     *      (`encryptedDataOwnerAddress`) has granted him on-chain permission.
+     *   5. Bob can now decrypt Alice's encrypted values using this permit.
+     */
+    readonly encryptedDataOwnerAddress: Address;
+    /** The E2E transport public key embedded in the EIP-712 message */
+    readonly transportPublicKey: BytesHex;
+};
+/**
+ * EIP-712 domain for KMS decryption.
+ */
+export type KmsEip712Domain = Readonly<{
+    name: 'Decryption';
+    version: '1';
+    chainId: bigint;
+    verifyingContract: Address;
+}>;
+/**
+ * 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 RequestUserDecryptSignData: readonly [
+        {
+            readonly name: 'publicKey';
+            readonly type: 'bytes';
+        },
+        {
+            readonly name: 'contractAddresses';
+            readonly type: 'address[]';
+        },
+        {
+            readonly name: 'startTimestamp';
+            readonly type: 'uint256';
+        },
+        {
+            readonly name: 'durationDays';
+            readonly type: 'uint256';
+        },
+        {
+            readonly name: 'extraData';
+            readonly type: 'bytes';
+        }
+    ];
+};
+/**
+ * EIP-712 message for KMS user decryption.
+ */
+export type KmsUserDecryptEip712Message = Readonly<{
+    publicKey: BytesHex;
+    contractAddresses: readonly Address[];
+    startTimestamp: string;
+    durationDays: string;
+    extraData: BytesHex;
+}>;
+/**
+ * Complete EIP-712 structure for KMS user decryption.
+ */
+export type KmsUserDecryptEip712 = {
+    readonly domain: KmsEip712Domain;
+    readonly types: KmsUserDecryptEip712Types;
+    readonly primaryType: 'RequestUserDecryptSignData';
+    readonly message: KmsUserDecryptEip712Message;
+};
+/**
+ * Signed decryption permit with EIP-712 data.
+ */
+export type SignedDecryptionPermit = SignedDecryptionPermitBase & {
+    readonly eip712: KmsUserDecryptEip712;
+};
+/**
+ * Result of signing a decryption permit.
+ */
+export type SignedDecryptionPermitResult = SignedDecryptionPermit;
+/**
+ * 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;
+/**
+ * Parameters for creating a KMS user decrypt EIP-712 structure.
+ */
+export type CreateKmsUserDecryptEip712Parameters = {
+    /** Contract address that verifies decryption permits */
+    readonly verifyingContractAddressDecryption: BytesHex;
+    /** Chain ID */
+    readonly chainId: bigint;
+    /** Public key for E2E encryption */
+    readonly publicKey: BytesHex;
+    /** List of contract addresses covered by this permit */
+    readonly contractAddresses: readonly BytesHex[];
+    /** Start timestamp (Unix timestamp in seconds) */
+    readonly startTimestamp: number;
+    /** Duration in days */
+    readonly durationDays: number;
+    /** Additional contextual data */
+    readonly extraData: BytesHex;
+};
+/**
+ * Creates a KMS user decrypt EIP-712 structure.
+ *
+ * @param parameters - Parameters for creating the EIP-712 structure
+ * @returns Frozen KmsUserDecryptEip712 object
+ */
+export declare function createKmsUserDecryptEip712(parameters: CreateKmsUserDecryptEip712Parameters): KmsUserDecryptEip712;
+/**
+ * Signs a decryption permit using EIP-712.
+ *
+ * @param parameters - Signing parameters
+ * @returns SignedDecryptionPermitResult containing signature and EIP-712 data
+ * @throws Error if signing fails
+ */
+export declare function signDecryptionPermit(sdk: FheTransformSDK, parameters: SignDecryptionPermitParameters): Promise<SignedDecryptionPermitResult>;
+/**
+ * Container for transport key pair with its associated permit.
+ */
+export interface TransportKeyPairWithPermits {
+    /** The transport key pair */
+    readonly keypair: TransportKeyPair;
+    /** The signed decryption permit */
+    readonly permit: SignedDecryptionPermit;
+}
+/**
+ * Gets an existing permit from cache, or creates a new one.
+ *
+ * This function implements a caching strategy:
+ * 1. Checks if a valid permit exists in cache for the signer+chain
+ * 2. Validates the cached permit (same public key, contract subset, not expired, etc.)
+ * 3. If valid, returns the cached permit
+ * 4. If not valid or missing, signs a new permit and caches it
+ *
+ * @param contractAddresses - List of contract addresses to include in the permit
+ * @returns TransportKeyPairWithPermits containing keypair and permit
+ * @throws Error if signing fails
+ */
+export declare function getOrCreateTKeyPairWithPermit(sdk: FheTransformSDK, contractAddresses: readonly BytesHex[]): Promise<TransportKeyPairWithPermits>;

package/dist/jazz/permit.js

@@ -0,0 +1,319 @@
+import { getOrCreateKeyPair } from "./key-pair.js";
+import { formatValue } from "../core/pretty-print.js";
+import { DEFAULT_PERMIT_TTL_DAYS, SECONDS_PER_DAY } from "../core/constants.js";
+import { JSONWithBigInt } from "../core/json-utils.js";
+import { logger } from "../core/logger.js";
+import { assertChecksumAddress } from "../core/address.js";
+import { FheErrorCode } from "../core/errors/error-codes.js";
+import { FheError } from "../core/errors/fhe-error.js";
+// ============================================================================
+// EIP-712 Constants
+// ============================================================================
+/**
+ * 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 const kmsUserDecryptEip712Types = {
+    EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+    ],
+    // 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.
+    RequestUserDecryptSignData: [
+        { name: 'publicKey', type: 'bytes' },
+        { name: 'contractAddresses', type: 'address[]' },
+        { name: 'startTimestamp', type: 'uint256' },
+        { name: 'durationDays', type: 'uint256' },
+        { name: 'extraData', type: 'bytes' },
+    ],
+};
+/**
+ * Creates a KMS user decrypt EIP-712 structure.
+ *
+ * @param parameters - Parameters for creating the EIP-712 structure
+ * @returns Frozen KmsUserDecryptEip712 object
+ */
+export function createKmsUserDecryptEip712(parameters) {
+    // Enter method
+    const { verifyingContractAddressDecryption, chainId, publicKey, contractAddresses, startTimestamp, durationDays, extraData, } = parameters;
+    logger.debug('[createKmsUserDecryptEip712] Enter', {
+        verifyingContract: verifyingContractAddressDecryption,
+        chainId: chainId.toString(),
+        publicKeyLength: publicKey.length,
+        contractAddressesCount: contractAddresses.length,
+        startTimestamp,
+        durationDays,
+    });
+    const primaryType = 'RequestUserDecryptSignData';
+    const domain = {
+        name: 'Decryption',
+        version: '1',
+        chainId: chainId,
+        verifyingContract: verifyingContractAddressDecryption,
+    };
+    const eip712 = {
+        domain,
+        types: kmsUserDecryptEip712Types,
+        primaryType,
+        message: {
+            publicKey: publicKey,
+            contractAddresses: contractAddresses,
+            startTimestamp: startTimestamp.toString(),
+            durationDays: durationDays.toString(),
+            extraData,
+        },
+    };
+    // Freeze all objects for immutability
+    Object.freeze(eip712);
+    Object.freeze(eip712.domain);
+    Object.freeze(eip712.types);
+    Object.freeze(eip712.types.EIP712Domain);
+    Object.freeze(eip712.types.RequestUserDecryptSignData);
+    Object.freeze(eip712.message);
+    Object.freeze(eip712.message.contractAddresses);
+    logger.trace('[createKmsUserDecryptEip712] EIP-712 structure created and frozen');
+    return eip712;
+}
+// ============================================================================
+// Permit Signing
+// ============================================================================
+/**
+ * Signs a decryption permit using EIP-712.
+ *
+ * @param parameters - Signing parameters
+ * @returns SignedDecryptionPermitResult containing signature and EIP-712 data
+ * @throws Error if signing fails
+ */
+export async function signDecryptionPermit(sdk, parameters) {
+    // Enter method
+    logger.debug('[signDecryptionPermit] Enter', {
+        contractAddressesCount: parameters.contractAddresses.length,
+        startTimestamp: parameters.startTimestamp,
+        durationDays: parameters.durationDays,
+        signerAddress: parameters.signerAddress,
+    });
+    // ============================================================================
+    // Step 1: Fetch Chain and Contract Info
+    // ============================================================================
+    const chainId = await sdk.getChainID();
+    const sysContractInfo = await sdk.getSystemContractInfo();
+    const extraData = "0x00";
+    logger.trace('[signDecryptionPermit] Chain and contract info fetched', {
+        chainId: chainId.toString(),
+        decryptionContract: sysContractInfo.decryptionContractAddress,
+    });
+    // ============================================================================
+    // Step 2: Build EIP-712 Structure
+    // ============================================================================
+    const { contractAddresses, startTimestamp, durationDays, signerAddress, transportKeyPair, signer } = parameters;
+    const commonMessage = {
+        verifyingContractAddressDecryption: sysContractInfo.decryptionContractAddress,
+        chainId: chainId,
+        contractAddresses,
+        durationDays,
+        startTimestamp,
+        extraData,
+        publicKey: transportKeyPair.publicKey,
+    };
+    const eip712 = createKmsUserDecryptEip712(commonMessage);
+    logger.debug(() => ['[signDecryptionPermit] EIP-712 structure created', formatValue({ eip712 })]);
+    // ============================================================================
+    // Step 3: Sign the EIP-712 Message
+    // ============================================================================
+    const primaryTypeFields = eip712.types[eip712.primaryType];
+    if (primaryTypeFields === undefined) {
+        logger.error('[signDecryptionPermit] Primary type not found', {
+            primaryType: eip712.primaryType,
+        });
+        throw new FheError({ code: FheErrorCode.Internal, message: `Primary type "${eip712.primaryType}" not found in types` });
+    }
+    const typesToSign = {
+        [eip712.primaryType]: [...primaryTypeFields],
+    };
+    logger.debug('[signDecryptionPermit] Signing EIP-712 message');
+    const signature = await signer.signTypedData(eip712.domain, typesToSign, eip712.message);
+    logger.debug('[signDecryptionPermit] Signature generated', {
+        signatureLength: signature.length,
+    });
+    // ============================================================================
+    // Step 4: Build Result
+    // ============================================================================
+    const result = {
+        signature: signature,
+        signerAddress: signerAddress,
+        encryptedDataOwnerAddress: "0x0000000000000000000000000000000000000000", // not used
+        transportPublicKey: transportKeyPair.publicKey,
+        eip712
+    };
+    logger.info('[signDecryptionPermit] Decryption permit signed successfully', {
+        signerAddress,
+        contractAddressesCount: contractAddresses.length,
+        durationDays,
+    });
+    return result;
+}
+/**
+ * Gets an existing permit from cache, or creates a new one.
+ *
+ * This function implements a caching strategy:
+ * 1. Checks if a valid permit exists in cache for the signer+chain
+ * 2. Validates the cached permit (same public key, contract subset, not expired, etc.)
+ * 3. If valid, returns the cached permit
+ * 4. If not valid or missing, signs a new permit and caches it
+ *
+ * @param contractAddresses - List of contract addresses to include in the permit
+ * @returns TransportKeyPairWithPermits containing keypair and permit
+ * @throws Error if signing fails
+ */
+export async function getOrCreateTKeyPairWithPermit(sdk, contractAddresses) {
+    // Enter method
+    logger.debug('[getOrCreateTKeyPairWithPermit] Enter', { contractAddresses });
+    contractAddresses.forEach(item => { assertChecksumAddress(item, "contractAddresses"); });
+    // ============================================================================
+    // Step 1: Fetch Chain and Signer Info
+    // ============================================================================
+    const chainId = await sdk.getChainID();
+    const sysContractInfo = await sdk.getSystemContractInfo();
+    const signer = await sdk.requireSigner();
+    const signerAddress = await signer.getAddress();
+    const extraData = "0x00";
+    logger.debug('[getOrCreateTKeyPairWithPermit] Context fetched', {
+        chainId: chainId.toString(),
+        signerAddress,
+        decryptionContract: sysContractInfo.decryptionContractAddress,
+        extraData,
+    });
+    // ============================================================================
+    // Step 2: Get or Create Key Pair
+    // ============================================================================
+    const keypair = await getOrCreateKeyPair(sdk, signerAddress);
+    logger.debug('[getOrCreateTKeyPairWithPermit] Key pair ready', {
+        publicKeyLength: keypair.publicKey.length,
+    });
+    // ============================================================================
+    // Step 3: Check Cache for Existing Permit
+    // ============================================================================
+    /**
+     * ### Permit Update Mechanism
+     *
+     * **Scope Key:** `signerAddress + chainId`
+     *
+     * **Delete Policy (scope key mismatch):**
+     * - Old `signerAddress` != new `signerAddress`
+     * - Old `chainId` != new `chainId`
+     *
+     * **New Permit:** Create if scope key not found
+     *
+     * **Replace Policy (cache invalidation) — trigger on ANY of:**
+     * - Old `publicKey` != new `publicKey`
+     * - `now` >= `old.startTimestamp + old.durationDays` (expired)
+     * - New `contractAddresses` not subset of old `contractAddresses`
+     *  - new set = deduplicated union of old and new contract addresses
+     *  - Example: old=[A,B], new=[B,C] => new is not subset of old ([C] is new),
+     *  - so replace is triggered. The stored new set becomes [A,B,C] (deduplicated union).
+     * - Old `extraData` != new `extraData`
+     */
+    const permitKey = `permit:${signerAddress}:${chainId}`;
+    logger.trace('[getOrCreateTKeyPairWithPermit] Permit cache key', { permitKey });
+    // List existing permits and clean up old ones
+    const permitKeys = await sdk.cacheManager.listKeys("permit:");
+    const exists = permitKeys.includes(permitKey);
+    if (!exists) {
+        logger.debug('[getOrCreateTKeyPairWithPermit] No existing permit found, clearing old cache');
+        // delete all, since permit scope key: (`signerAddress + chainId`) not match
+        await sdk.cacheManager.clear("permit:");
+    }
+    // ============================================================================
+    // Step 4: Load and Validate Cached Permit
+    // ============================================================================
+    let oldPermit;
+    const data = await sdk.cacheManager.loadString(permitKey);
+    logger.trace('[getOrCreateTKeyPairWithPermit] Cache load result', {
+        hasData: !!data,
+        dataLength: data?.length,
+    });
+    let uniqueContractAddresses = [...new Set([...contractAddresses])];
+    if (data) {
+        try {
+            const parsed = JSONWithBigInt.parse(data);
+            oldPermit = parsed;
+            // Validate cached permit against current state
+            const old = oldPermit.eip712.message;
+            const isSamePublicKey = old.publicKey === keypair.publicKey;
+            const isContractSubset = contractAddresses.every(item => old.contractAddresses.includes(item));
+            const isExpired = Math.floor(Date.now() / 1000) >=
+                Number(old.startTimestamp) + Number(old.durationDays) * SECONDS_PER_DAY;
+            const isSameExtraData = old.extraData === extraData;
+            const isSameVerifyContract = oldPermit.eip712.domain.verifyingContract === sysContractInfo.decryptionContractAddress;
+            const isValid = isSamePublicKey && isContractSubset && !isExpired && isSameExtraData && isSameVerifyContract;
+            logger.debug('[getOrCreateTKeyPairWithPermit] Cache validation results', {
+                isSamePublicKey,
+                isContractSubset,
+                isExpired,
+                isSameExtraData,
+                isSameVerifyContract,
+                isValid,
+            });
+            // Return cached permit if all validations pass
+            if (isValid) {
+                logger.debug('[getOrCreateTKeyPairWithPermit] Valid permit found in cache');
+                return {
+                    keypair,
+                    permit: oldPermit,
+                };
+            }
+            uniqueContractAddresses = [...new Set([...old.contractAddresses, ...contractAddresses])];
+            logger.debug('[getOrCreateTKeyPairWithPermit] Cached permit invalid, generating new one.', {
+                contractAddresses: uniqueContractAddresses,
+            });
+        }
+        catch (error) {
+            logger.warn('[getOrCreateTKeyPairWithPermit] Failed to parse cached permit', {
+                error: error.message,
+            });
+        }
+    }
+    else {
+        logger.debug('[getOrCreateTKeyPairWithPermit] No cached permit found');
+    }
+    // ============================================================================
+    // Step 5: Sign New Permit
+    // ============================================================================
+    const now = Math.floor(Date.now() / 1000);
+    const PERMIT_TTL_DAYS = sdk.config.permitTTL ?? DEFAULT_PERMIT_TTL_DAYS;
+    logger.debug('[getOrCreateTKeyPairWithPermit] Signing new permit', {
+        contractAddresses: uniqueContractAddresses,
+        startTimestamp: now,
+        durationDays: PERMIT_TTL_DAYS,
+        signerAddress,
+    });
+    const permit = await signDecryptionPermit(sdk, {
+        contractAddresses: uniqueContractAddresses,
+        startTimestamp: now,
+        durationDays: PERMIT_TTL_DAYS,
+        signerAddress,
+        transportKeyPair: keypair,
+        signer
+    });
+    // ============================================================================
+    // Step 6: Save New Permit to Cache
+    // ============================================================================
+    await sdk.cacheManager.save(permitKey, JSONWithBigInt.stringify(permit));
+    logger.debug('[getOrCreateTKeyPairWithPermit] New permit signed and cached', {
+        permitKey,
+        startTimestamp: now,
+        durationDays: PERMIT_TTL_DAYS,
+    });
+    return {
+        keypair,
+        permit,
+    };
+}
+//# sourceMappingURL=permit.js.map

package/dist/jazz/permit.js.map

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

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

@@ -0,0 +1,96 @@
+import { Address, Bytes32Hex, BytesHex } from "../core/primitives.js";
+import { FetchPublicDecryptResult } from "./types/public-decrypt.js";
+import type { IJazzClient } from "./jazz-client-i.js";
+/**
+ * EIP-712 message for KMS public decryption.
+ */
+export type KmsPublicDecryptEip712Message = Readonly<{
+    /** List of ciphertext handles (32-byte hex with 0x prefix) */
+    ctHandles: readonly Bytes32Hex[];
+    /** Decrypted result as hex with 0x prefix */
+    decryptedResult: BytesHex;
+    /** Additional contextual data as hex with 0x prefix */
+    extraData: BytesHex;
+}>;
+/**
+ * EIP-712 type definitions for KMS public decryption.
+ */
+export type KmsPublicDecryptEip712Types = {
+    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 PublicDecryptSignData: readonly [
+        {
+            readonly name: 'ctHandles';
+            readonly type: 'bytes32[]';
+        },
+        {
+            readonly name: 'decryptedResult';
+            readonly type: 'bytes';
+        },
+        {
+            readonly name: 'extraData';
+            readonly type: 'bytes';
+        }
+    ];
+};
+/**
+ * EIP-712 type definitions for KMS public 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 kmsPublicDecryptEip712Types: KmsPublicDecryptEip712Types;
+/**
+ * Verifies KMS public decryption EIP-712 signatures.
+ *
+ * This function:
+ * 1. Reconstructs the EIP-712 message from the result
+ * 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)
+ * @param result - Public decryption result containing signatures and decrypted data
+ * @throws Error if verification fails (unknown signer, threshold not met, invalid signature)
+ */
+export declare function verifyPublicDecryptionSignatures(client: IJazzClient, params: {
+    chainId: bigint;
+    verifyingContract: Address;
+    handles: BytesHex[];
+}, result: FetchPublicDecryptResult): Promise<void>;
+/**
+ * Creates a public decryption proof by encoding signatures and extra data.
+ *
+ * Format:
+ *     Byte 0             : numSigners (uint8)
+ *     Bytes 1 .. 65*N    : N × 65-byte ECDSA signatures
+ *     Bytes 65*N+1 .. end: extraData
+ *
+ * @param signatures - Array of signatures (hex strings with 0x prefix)
+ * @param extraData - Additional contextual data as Uint8Array
+ * @returns Encoded proof as Uint8Array
+ * @throws Error if numSigners exceeds 255 or signature length is invalid
+ */
+export declare function createPublicDecryptionProof(signatures: string[], extraData: Uint8Array): Uint8Array;
+export declare function checkPublicDecryptPermission(client: IJazzClient, params: {
+    aclContractAddress: Address;
+    ctHandles: BytesHex[];
+}): Promise<void>;