@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/dist/{clientTypes-BN3nbzYM.d.ts → clientTypes-CcU5WvdV.d.ts}

@@ -1,10 +1,17 @@
 import { WalletClient, PublicClient, Hex } from 'viem';
 import { C as CofheChain } from './types-C07FK-cL.js';
 import { z } from 'zod';
-import { A as ACP, h as EIP712Domain, C as CreateSelfACPOptions, p as SelfACP, d as CreateSharingACPOptions, q as SharingACP, I as ImportSharedACPOptions, R as RecipientACP, v as ACPHashFields, S as SerializedACP, g as IncomingShare, i as ACPUtils } from './acp-Wi6isVQI.js';
+import { A as ACP, k as EIP712Domain, C as CreateSelfACPOptions, J as SelfACP, g as CreateSharingACPOptions, K as SharingACP, I as ImportSharedACPOptions, R as RecipientACP, P as ACPHashFields, f as SerializedACP, O as ACPAccessStatus, S as ShareLabel, j as IncomingShare, p as AclServedAddresses, L as LabelledShare, w as ShareLabelVerifyMode, x as ShareLabelCheck, l as ACPUtils } from './onchain-utils-D9Z33IP7.js';
 import { StoreApi } from 'zustand/vanilla';
 
 type TfheInitializer = () => Promise<boolean>;
+/**
+ * How many threads tfhe's rayon pool may use for ZK proof generation (web only).
+ * - `'auto'` (default): derive from `navigator.hardwareConcurrency`, capped
+ * - a positive number: request exactly that many
+ * - `false`: stay single-threaded
+ */
+type TfheThreadsSetting = number | 'auto' | false;
 interface IStorage {
     getItem: (name: string) => Promise<any>;
     setItem: (name: string, value: any) => Promise<void>;
@@ -229,6 +236,25 @@ type CofheConfig = {
      * Default: true
      */
     useWorkers: boolean;
+    /**
+     * How many threads tfhe's rayon pool may use for ZK proof generation
+     * (web platform only; ignored on node/hardhat).
+     *
+     * Proving dominates the cost of `encryptInputs`, and tfhe's wasm is built with
+     * rayon, so spreading it across threads is a large win — roughly 5x on an
+     * 8-thread pool.
+     *
+     * Requires a cross-origin-isolated page (`Cross-Origin-Opener-Policy: same-origin`
+     * plus `Cross-Origin-Embedder-Policy: require-corp` or `credentialless`). When the
+     * page isn't isolated the pool is skipped and proving stays single-threaded, so
+     * this is safe to leave on.
+     *
+     * `'auto'` derives the count from `navigator.hardwareConcurrency` (capped, since
+     * the speedup flattens out); a number requests exactly that many; `false` keeps
+     * tfhe single-threaded.
+     * Default: 'auto'
+     */
+    tfheThreads: TfheThreadsSetting;
     /** ACP acp defaults, applied when creating acps (user options always win) */
     acp: {
         /**
@@ -254,6 +280,13 @@ type CofheConfig = {
          * names a registry.
          */
         sharingRegistry?: Record<number, `0x${string}`>;
+        /**
+         * The name of this app, e.g. 'explorer.fhenix.io'. Set, every share the client creates
+         * carries the app's key (`shareAppKey(app)`, kept in the share metadata), and
+         * `getIncomingShares` lists only the shares posted for this app. Unset, shares carry no
+         * key and every importable share is listed.
+         */
+        app?: string;
     };
     /** Mocks configs */
     mocks: {
@@ -310,10 +343,12 @@ declare const CofheConfigSchema: z.ZodObject<{
         removeItem: z.ZodCustom<(name: string) => Promise<void>, (name: string) => Promise<void>>;
     }, z.core.$strip>, z.ZodNull]>>;
     useWorkers: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    tfheThreads: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">, z.ZodLiteral<false>]>>>;
     acp: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         defaultRevoker: z.ZodOptional<z.ZodCustom<Record<number, `0x${string}`>, Record<number, `0x${string}`>>>;
         defaultContractScopes: z.ZodOptional<z.ZodCustom<Record<number, `0x${string}`[]>, Record<number, `0x${string}`[]>>>;
         sharingRegistry: z.ZodOptional<z.ZodCustom<Record<number, `0x${string}`>, Record<number, `0x${string}`>>>;
+        app: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     mocks: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         decryptDelay: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
@@ -665,6 +700,12 @@ interface ZkProveWorkerRequest {
         data: any;
     }>;
     metadata: number[];
+    /**
+     * Forwarded from `config.tfheThreads`. The worker applies it the first time it
+     * initialises tfhe — `initThreadPool` can only run once per wasm instance, so
+     * later requests carrying a different value have no effect.
+     */
+    tfheThreads?: TfheThreadsSetting;
 }
 /**
  * Message sent from worker back to main thread with proof result
@@ -712,14 +753,14 @@ type ChainRecord<T> = Record<string, T>;
 type SecurityZoneRecord<T> = Record<number, T>;
 type KeysStore = {
     fhe: ChainRecord<SecurityZoneRecord<string | undefined>>;
-    crs: ChainRecord<string | undefined>;
+    crs: ChainRecord<SecurityZoneRecord<string | undefined>>;
 };
 type KeysStorage = {
     store: StoreApi<KeysStore>;
     getFheKey: (chainId: number | undefined, securityZone?: number) => string | undefined;
-    getCrs: (chainId: number | undefined) => string | undefined;
+    getCrs: (chainId: number | undefined, securityZone?: number) => string | undefined;
     setFheKey: (chainId: number, securityZone: number, key: string) => void;
-    setCrs: (chainId: number, crs: string) => void;
+    setCrs: (chainId: number, securityZone: number, crs: string) => void;
     clearKeysStorage: () => Promise<void>;
     rehydrateKeysStore: () => Promise<void>;
 };
@@ -753,6 +794,7 @@ type EncryptInputsBuilderParams<T extends EncryptableItem[]> = BaseBuilderParams
     zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator | undefined;
     initTfhe: TfheInitializer | undefined;
     zkProveWorkerFn: ZkProveWorkerFunction | undefined;
+    beforeMainThreadProve?: (() => Promise<void>) | undefined;
     keysStorage: KeysStorage | undefined;
 };
 /**
@@ -779,6 +821,7 @@ declare class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuil
     private zkBuilderAndCrsGenerator;
     private initTfhe;
     private zkProveWorkerFn;
+    private beforeMainThreadProve;
     private keysStorage;
     private useWorker;
     private stepTimestamps;
@@ -971,10 +1014,34 @@ declare class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuil
     execute(): Promise<HashPlusProofResult<T>>;
 }
 
-interface AclServedAddresses {
-    defaultRevoker?: Hex;
-    shareRegistry?: Hex;
-}
+/** Options for importing a shared acp. */
+type ImportActivationOptions = {
+    /**
+     * Make the imported acp the active one. Defaults to `true`.
+     * With `false` the acp is only stored: decrypts that use the active acp keep using the current one,
+     * and the imported acp is used only where it is passed explicitly (e.g. `.withACP(acp)`).
+     */
+    activate?: boolean;
+};
+/** Options for importing a shared acp: activation, and the recipient's own name for it. */
+type ImportSharedOptions = ImportActivationOptions & {
+    /**
+     * The name of the imported acp. Defaults to "Shared by 0x1234…abcd" (its issuer); the issuer's
+     * own name for the share is not exported and is ignored if present.
+     */
+    name?: string;
+};
+/**
+ * What `shareOnChain` posts with a share: the labels of its handles (one per handle, in order;
+ * encoded with `encodeShareMetadata`), or an already encoded metadata blob. Written once, with the
+ * share. Omitted, the labels the acp was created with are posted (`createSharing({ labels })`),
+ * or none. `appKey` goes with given labels; a client configured with `acp: { app }` fills it in.
+ */
+type ShareOnChainOptions = {
+    labels?: readonly ShareLabel[];
+    metadata?: Hex;
+    appKey?: Hex;
+};
 declare const acps: {
     getSnapshot: () => {
         acps: {
@@ -985,6 +1052,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1016,6 +1084,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1046,6 +1115,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1070,7 +1140,7 @@ declare const acps: {
     }) => void) => () => void;
     createSelf: (options: CreateSelfACPOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SelfACP>;
     createSharing: (options: CreateSharingACPOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SharingACP>;
-    importShared: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientACP>;
+    importShared: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient, { activate, name }?: ImportSharedOptions) => Promise<RecipientACP>;
     getOrCreateSelfACP: (publicClient: PublicClient, walletClient: WalletClient, chainId?: number, account?: string, options?: CreateSelfACPOptions) => Promise<ACP>;
     getOrCreateSharingACP: (publicClient: PublicClient, walletClient: WalletClient, options: CreateSharingACPOptions, chainId?: number, account?: string) => Promise<ACP>;
     getHash: (acp: ACPHashFields) => string;
@@ -1080,6 +1150,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1098,6 +1169,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1121,24 +1193,18 @@ declare const acps: {
     revokeACP: (acp: ACP, walletClient: WalletClient) => Promise<Hex>;
     revokeAllACPs: (walletClient: WalletClient, publicClient: PublicClient, revokerContract?: Hex) => Promise<Hex>;
     isACPRevoked: (acp: ACP, publicClient: PublicClient) => Promise<boolean>;
-    shareOnChain: (acp: ACP, walletClient: WalletClient, registry: Hex) => Promise<{
+    checkAccess: (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex) => Promise<ACPAccessStatus>;
+    shareOnChain: (acp: ACP, walletClient: WalletClient, registry: Hex, options?: ShareOnChainOptions) => Promise<{
         txHash: Hex;
         shareId: Hex;
     }>;
-    getIncomingShares: (publicClient: PublicClient, registry: Hex, recipient: Hex) => Promise<IncomingShare[]>;
-    importFromChain: (share: IncomingShare, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientACP>;
+    getIncomingShares: (publicClient: PublicClient, registry: Hex, recipient: Hex, { appKey }?: {
+        appKey?: Hex;
+    }) => Promise<IncomingShare[]>;
+    getShareFromChain: (publicClient: PublicClient, registry: Hex, shareId: Hex) => Promise<IncomingShare | null>;
+    importFromChain: (share: IncomingShare, publicClient: PublicClient, walletClient: WalletClient, importOptions?: ImportSharedOptions) => Promise<RecipientACP>;
     removeShareOnChain: (shareId: Hex, walletClient: WalletClient, registry: Hex) => Promise<Hex>;
     computeShareId: (acp: ACP) => Hex;
-    applyACPDefaults: <T extends {
-        revokerData?: number;
-        revokerContract?: string;
-        scope?: number;
-        contracts?: string[];
-        handles?: (bigint | number | string)[];
-    }>(options: T, acpConfig: {
-        defaultRevoker?: Record<number, Hex>;
-        defaultContractScopes?: Record<number, Hex[]>;
-    } | undefined, chainId: number) => T;
     applyACPDefaultsFromChain: <T extends {
         revokerData?: number;
         revokerContract?: string;
@@ -1195,12 +1261,21 @@ type CofheClientACPsClients = {
     publicClient: PublicClient;
     walletClient: WalletClient;
 };
+/**
+ * Options for `importShared`. `activate: false` stores the imported acp without making it the active
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
+ */
+type CofheClientImportSharedOptions = ImportSharedOptions & (CofheClientACPsClients | {
+    publicClient?: undefined;
+    walletClient?: undefined;
+});
 type CofheClientACPs = {
     getSnapshot: typeof acps.getSnapshot;
     subscribe: typeof acps.subscribe;
     createSelf: (options: CreateSelfACPOptions, clients?: CofheClientACPsClients) => Promise<SelfACP>;
     createSharing: (options: CreateSharingACPOptions, clients?: CofheClientACPsClients) => Promise<SharingACP>;
-    importShared: (options: ImportSharedACPOptions | string, clients?: CofheClientACPsClients) => Promise<RecipientACP>;
+    importShared: (options: ImportSharedACPOptions | string, importOptions?: CofheClientImportSharedOptions) => Promise<RecipientACP>;
     getACP: (hash: string, chainId?: number, account?: string) => ACP | undefined;
     getACPs: (chainId?: number, account?: string) => Record<string, ACP>;
     getActiveACP: (chainId?: number, account?: string) => ACP | undefined;
@@ -1213,15 +1288,36 @@ type CofheClientACPs = {
     revokeACP: (acp: ACP) => Promise<`0x${string}`>;
     revokeAllACPs: (revokerContract?: `0x${string}`) => Promise<`0x${string}`>;
     isACPRevoked: (acp: ACP) => Promise<boolean>;
-    /** Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`). */
-    shareOnChain: (acp: ACP) => Promise<{
+    /**
+     * The ACP on-chain status as a value instead of a revert. Without a handle: 'valid', or
+     * 'expired' / 'revoked' / an invalid signature. With a handle, a valid ACP reports
+     * 'allowed', 'out-of-scope' or 'issuer-not-allowed'. For the issuer copy of a share (type
+     * 'sharing', no recipient signature yet) the handle-less check covers expiry and revocation only.
+     */
+    checkAccess: (acp: ACP, handle?: bigint | `0x${string}`) => Promise<ACPAccessStatus>;
+    /**
+     * Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`),
+     * optionally with the labels of its handles (`options.labels`, one per handle) or an encoded blob.
+     */
+    shareOnChain: (acp: ACP, options?: ShareOnChainOptions) => Promise<{
         txHash: `0x${string}`;
         shareId: `0x${string}`;
     }>;
-    /** Importable shares addressed to the connected account (unexpired, not revoked). */
+    /** Importable shares addressed to the connected account (unexpired, not revoked), with their metadata. */
     getIncomingShares: () => Promise<IncomingShare[]>;
-    /** Import a share read from the registry: sign as recipient, store and activate. */
-    importFromChain: (share: IncomingShare) => Promise<RecipientACP>;
+    /** One share by id, as posted; null when unknown or removed. */
+    getShareFromChain: (shareId: `0x${string}`) => Promise<IncomingShare | null>;
+    /**
+     * Check a share's labels against the chain, index for index with its handles, as far as
+     * `verify` says (default 'all'). Takes a share read from the registry or an acp imported from
+     * exported JSON (or the issuer's sharing acp). Null for a share without metadata. Throws on a
+     * malformed blob.
+     */
+    verifyShareLabels: (share: LabelledShare, options?: {
+        verify?: ShareLabelVerifyMode;
+    }) => Promise<ShareLabelCheck[] | null>;
+    /** Import a share read from the registry: sign as recipient, store and (unless `activate: false`) activate. */
+    importFromChain: (share: IncomingShare, options?: ImportSharedOptions) => Promise<RecipientACP>;
     /** Recipient-side: remove a share from the registry (after import, or to decline). */
     dismissShare: (shareId: `0x${string}`) => Promise<`0x${string}`>;
     /** Issuer-side: retract a pending share from the registry. */
@@ -1238,6 +1334,13 @@ type CofheClientParams<TConfig extends CofheConfig> = {
     compactPkeCrsDeserializer: FheKeyDeserializer;
     initTfhe: TfheInitializer;
     zkProveWorkerFn?: ZkProveWorkerFunction;
+    /**
+     * Runs right before a ZK proof is generated on the calling thread, i.e. only
+     * when the worker path is disabled, unavailable or has failed. Platforms use
+     * it for setup that only pays off when that thread does the proving (web
+     * starts tfhe's rayon thread pool here).
+     */
+    beforeMainThreadProve?: () => Promise<void>;
 };
 
-export { EncryptInputsBuilder as $, type AnyExternalHash as A, type EncryptableToExternalHashMap as B, type CofheInputConfig as C, type ExternalItemHashes as D, type EncryptableItem as E, FheTypes as F, type DecryptPollCallbackFunction as G, type HashPlusProofResult as H, type IStorage as I, type DecryptPollCallbackContext as J, type DecryptEndpoint as K, type LiteralToPrimitive as L, type EncryptStepCallbackFunction as M, type EncryptStepCallbackContext as N, FheUintUTypes as O, type Primitive as P, FheAllUTypes as Q, Encryptable as R, isEncryptableItem as S, EncryptStep as T, type UnsealedItem as U, isLastEncryptionStep as V, fetchKeys as W, type FheKeyDeserializer as X, createKeysStore as Y, type KeysStorage as Z, type KeysStore as _, type CofheConfig as a, type EncryptInputsBuilderUnset as a0, DecryptForViewBuilder as a1, DecryptForTxBuilder as a2, type DecryptForTxResult as a3, type ZkBuilderAndCrsGenerator as a4, type ZkProveWorkerFunction as a5, type ZkProveWorkerRequest as a6, type ZkProveWorkerResponse as a7, zkProveWithWorker as a8, type CofheClient as b, type CofheClientParams as c, type CofheClientConnectionState as d, createCofheConfigBase as e, assertNoRenamedConfigKeys as f, getCofheConfigItem as g, type CofheInternalConfig as h, type CofheClientACPs as i, type EncryptableBool as j, type EncryptableUint8 as k, type EncryptableUint16 as l, type EncryptableUint32 as m, type EncryptableUint64 as n, type EncryptableUint128 as o, type EncryptableAddress as p, type EncryptedNumber as q, type FheTypeValue as r, type ExternalBoolHash as s, type ExternalUint8Hash as t, type ExternalUint16Hash as u, type ExternalUint32Hash as v, type ExternalUint64Hash as w, type ExternalUint128Hash as x, type ExternalAddressHash as y, type ExternalHashProof as z };
+export { type KeysStorage as $, type AnyExternalHash as A, type EncryptableToExternalHashMap as B, type CofheInputConfig as C, type ExternalItemHashes as D, type EncryptableItem as E, FheTypes as F, type DecryptPollCallbackFunction as G, type HashPlusProofResult as H, type IStorage as I, type DecryptPollCallbackContext as J, type DecryptEndpoint as K, type LiteralToPrimitive as L, type EncryptStepCallbackFunction as M, type EncryptStepCallbackContext as N, type TfheThreadsSetting as O, type Primitive as P, FheUintUTypes as Q, FheAllUTypes as R, Encryptable as S, type TfheInitializer as T, type UnsealedItem as U, isEncryptableItem as V, EncryptStep as W, isLastEncryptionStep as X, fetchKeys as Y, type FheKeyDeserializer as Z, createKeysStore as _, type CofheConfig as a, type KeysStore as a0, EncryptInputsBuilder as a1, type EncryptInputsBuilderUnset as a2, DecryptForViewBuilder as a3, DecryptForTxBuilder as a4, type DecryptForTxResult as a5, type ZkBuilderAndCrsGenerator as a6, type ZkProveWorkerFunction as a7, type ZkProveWorkerRequest as a8, type ZkProveWorkerResponse as a9, zkProveWithWorker as aa, type CofheClient as b, type CofheClientParams as c, type CofheClientConnectionState as d, createCofheConfigBase as e, assertNoRenamedConfigKeys as f, getCofheConfigItem as g, type CofheInternalConfig as h, type CofheClientACPs as i, type EncryptableBool as j, type EncryptableUint8 as k, type EncryptableUint16 as l, type EncryptableUint32 as m, type EncryptableUint64 as n, type EncryptableUint128 as o, type EncryptableAddress as p, type EncryptedNumber as q, type FheTypeValue as r, type ExternalBoolHash as s, type ExternalUint8Hash as t, type ExternalUint16Hash as u, type ExternalUint32Hash as v, type ExternalUint64Hash as w, type ExternalUint128Hash as x, type ExternalAddressHash as y, type ExternalHashProof as z };