@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

package/dist/chunk-XQ32JG3T.js

@@ -0,0 +1,174 @@
+// core/consts.ts
+var COFHE_ADDRESS_BOOK_ADDRESS = "0xC0F4e00E531a2B086492Ae3DCC1515038307196b";
+var TASK_MANAGER_ID = 1n;
+var MOCKS_TASK_MANAGER_ADDRESS = "0x0000000000000000000000000000000000005000";
+var MOCKS_ZK_VERIFIER_ADDRESS = "0x0000000000000000000000000000000000005001";
+var MOCKS_THRESHOLD_NETWORK_ADDRESS = "0x0000000000000000000000000000000000005002";
+var MOCKS_ZK_VERIFIER_SIGNER_PRIVATE_KEY = "0x6C8D7F768A6BB4AAFE85E8A2F5A9680355239C7E14646ED62B044E39DE154512";
+var MOCKS_ZK_VERIFIER_SIGNER_ADDRESS = "0x6E12D8C87503D4287c294f2Fdef96ACd9DFf6bd2";
+var MOCKS_DECRYPT_RESULT_SIGNER_PRIVATE_KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+var TFHE_RS_ZK_MAX_BITS = 2048;
+var TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT = BigInt(1 << 30);
+var TFHE_RS_KEY_VERSION = 2;
+
+// core/error.ts
+var CofheErrorCode = /* @__PURE__ */ ((CofheErrorCode2) => {
+  CofheErrorCode2["InternalError"] = "INTERNAL_ERROR";
+  CofheErrorCode2["UnknownEnvironment"] = "UNKNOWN_ENVIRONMENT";
+  CofheErrorCode2["InitTfheFailed"] = "INIT_TFHE_FAILED";
+  CofheErrorCode2["InitViemFailed"] = "INIT_VIEM_FAILED";
+  CofheErrorCode2["InitEthersFailed"] = "INIT_ETHERS_FAILED";
+  CofheErrorCode2["NotConnected"] = "NOT_CONNECTED";
+  CofheErrorCode2["MissingPublicClient"] = "MISSING_PUBLIC_CLIENT";
+  CofheErrorCode2["MissingWalletClient"] = "MISSING_WALLET_CLIENT";
+  CofheErrorCode2["MissingProviderParam"] = "MISSING_PROVIDER_PARAM";
+  CofheErrorCode2["EmptySecurityZonesParam"] = "EMPTY_SECURITY_ZONES_PARAM";
+  CofheErrorCode2["InvalidACPData"] = "INVALID_ACP_DATA";
+  CofheErrorCode2["InvalidACPDomain"] = "INVALID_ACP_DOMAIN";
+  CofheErrorCode2["ACPNotFound"] = "ACP_NOT_FOUND";
+  CofheErrorCode2["CannotRemoveLastACP"] = "CANNOT_REMOVE_LAST_ACP";
+  CofheErrorCode2["AccountUninitialized"] = "ACCOUNT_UNINITIALIZED";
+  CofheErrorCode2["ChainIdUninitialized"] = "CHAIN_ID_UNINITIALIZED";
+  CofheErrorCode2["ConsumingContractUninitialized"] = "CONSUMING_CONTRACT_UNINITIALIZED";
+  CofheErrorCode2["SealOutputFailed"] = "SEAL_OUTPUT_FAILED";
+  CofheErrorCode2["SealOutputReturnedNull"] = "SEAL_OUTPUT_RETURNED_NULL";
+  CofheErrorCode2["InvalidUtype"] = "INVALID_UTYPE";
+  CofheErrorCode2["DecryptFailed"] = "DECRYPT_FAILED";
+  CofheErrorCode2["DecryptReturnedNull"] = "DECRYPT_RETURNED_NULL";
+  CofheErrorCode2["ZkMocksInsertCtHashesFailed"] = "ZK_MOCKS_INSERT_CT_HASHES_FAILED";
+  CofheErrorCode2["ZkMocksCalcCtHashesFailed"] = "ZK_MOCKS_CALC_CT_HASHES_FAILED";
+  CofheErrorCode2["ZkMocksVerifySignFailed"] = "ZK_MOCKS_VERIFY_SIGN_FAILED";
+  CofheErrorCode2["ZkMocksCreateProofSignatureFailed"] = "ZK_MOCKS_CREATE_PROOF_SIGNATURE_FAILED";
+  CofheErrorCode2["ZkVerifyFailed"] = "ZK_VERIFY_FAILED";
+  CofheErrorCode2["ZkPackFailed"] = "ZK_PACK_FAILED";
+  CofheErrorCode2["ZkProveFailed"] = "ZK_PROVE_FAILED";
+  CofheErrorCode2["EncryptRemainingInItems"] = "ENCRYPT_REMAINING_IN_ITEMS";
+  CofheErrorCode2["ZkUninitialized"] = "ZK_UNINITIALIZED";
+  CofheErrorCode2["ZkVerifierUrlUninitialized"] = "ZK_VERIFIER_URL_UNINITIALIZED";
+  CofheErrorCode2["ThresholdNetworkUrlUninitialized"] = "THRESHOLD_NETWORK_URL_UNINITIALIZED";
+  CofheErrorCode2["MissingConfig"] = "MISSING_CONFIG";
+  CofheErrorCode2["UnsupportedChain"] = "UNSUPPORTED_CHAIN";
+  CofheErrorCode2["MissingZkBuilderAndCrsGenerator"] = "MISSING_ZK_BUILDER_AND_CRS_GENERATOR";
+  CofheErrorCode2["MissingTfhePublicKeyDeserializer"] = "MISSING_TFHE_PUBLIC_KEY_DESERIALIZER";
+  CofheErrorCode2["MissingCompactPkeCrsDeserializer"] = "MISSING_COMPACT_PKE_CRS_DESERIALIZER";
+  CofheErrorCode2["MissingFheKey"] = "MISSING_FHE_KEY";
+  CofheErrorCode2["MissingCrs"] = "MISSING_CRS";
+  CofheErrorCode2["FetchKeysFailed"] = "FETCH_KEYS_FAILED";
+  CofheErrorCode2["PublicWalletGetChainIdFailed"] = "PUBLIC_WALLET_GET_CHAIN_ID_FAILED";
+  CofheErrorCode2["PublicWalletGetAddressesFailed"] = "PUBLIC_WALLET_GET_ADDRESSES_FAILED";
+  CofheErrorCode2["RehydrateKeysStoreFailed"] = "REHYDRATE_KEYS_STORE_FAILED";
+  CofheErrorCode2["TaskManagerUnresolved"] = "TASK_MANAGER_UNRESOLVED";
+  CofheErrorCode2["BadRequest"] = "BAD_REQUEST";
+  CofheErrorCode2["UnknownChain"] = "UNKNOWN_CHAIN";
+  CofheErrorCode2["ACPMalformed"] = "ACP_MALFORMED";
+  CofheErrorCode2["ACPDenied"] = "ACP_DENIED";
+  CofheErrorCode2["ACPExpired"] = "ACP_EXPIRED";
+  CofheErrorCode2["ACPInvalid"] = "ACP_INVALID";
+  CofheErrorCode2["ACPRevoked"] = "ACP_REVOKED";
+  CofheErrorCode2["NotPubliclyAllowed"] = "NOT_PUBLICLY_ALLOWED";
+  CofheErrorCode2["CtNotFound"] = "CT_NOT_FOUND";
+  CofheErrorCode2["UnsupportedSecurityZone"] = "UNSUPPORTED_SECURITY_ZONE";
+  CofheErrorCode2["UnsupportedType"] = "UNSUPPORTED_TYPE";
+  CofheErrorCode2["SigningFailed"] = "SIGNING_FAILED";
+  CofheErrorCode2["CtSourceError"] = "CT_SOURCE_ERROR";
+  CofheErrorCode2["ACPVerifierError"] = "ACP_VERIFIER_ERROR";
+  CofheErrorCode2["CtSourceTimeout"] = "CT_SOURCE_TIMEOUT";
+  CofheErrorCode2["ACPVerifierTimeout"] = "ACP_VERIFIER_TIMEOUT";
+  CofheErrorCode2["ACPRequired"] = "ACP_REQUIRED";
+  CofheErrorCode2["SealFailed"] = "SEAL_FAILED";
+  return CofheErrorCode2;
+})(CofheErrorCode || {});
+var CofheError = class _CofheError extends Error {
+  code;
+  cause;
+  hint;
+  context;
+  apiErrorCode;
+  constructor({ code, message, cause, hint, context, apiErrorCode }) {
+    const fullMessage = cause ? `${message} | Caused by: ${cause.message}` : message;
+    super(fullMessage);
+    this.name = "CofheError";
+    this.code = code;
+    this.cause = cause;
+    this.hint = hint;
+    this.context = context;
+    this.apiErrorCode = apiErrorCode;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _CofheError);
+    }
+  }
+  /**
+   * Creates a CofheError from an unknown error
+   * If the error is a CofheError, it is returned unchanged, else a new CofheError is created
+   * If a wrapperError is provided, it is used to create the new CofheError, else a default is used
+   */
+  static fromError(error, wrapperError) {
+    if (isCofheError(error))
+      return error;
+    const cause = error instanceof Error ? error : new Error(`${error}`);
+    return new _CofheError({
+      code: wrapperError?.code ?? "INTERNAL_ERROR" /* InternalError */,
+      message: wrapperError?.message ?? "An internal error occurred",
+      hint: wrapperError?.hint,
+      context: wrapperError?.context,
+      apiErrorCode: wrapperError?.apiErrorCode,
+      cause
+    });
+  }
+  /**
+   * Serializes the error to JSON string with proper handling of Error objects
+   */
+  serialize() {
+    return bigintSafeJsonStringify({
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+      context: this.context,
+      apiErrorCode: this.apiErrorCode,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : void 0,
+      stack: this.stack
+    });
+  }
+  /**
+   * Returns a human-readable string representation of the error
+   */
+  toString() {
+    const codeSuffix = this.apiErrorCode ? ` (api: ${this.apiErrorCode})` : "";
+    const parts = [`${this.name} [${this.code}]${codeSuffix}: ${this.message}`];
+    if (this.hint) {
+      parts.push(`Hint: ${this.hint}`);
+    }
+    if (this.context && Object.keys(this.context).length > 0) {
+      parts.push(`Context: ${bigintSafeJsonStringify(this.context)}`);
+    }
+    if (this.stack) {
+      parts.push(`
+Stack trace:`);
+      parts.push(this.stack);
+    }
+    if (this.cause) {
+      parts.push(`
+Caused by: ${this.cause.name}: ${this.cause.message}`);
+      if (this.cause.stack) {
+        parts.push(this.cause.stack);
+      }
+    }
+    return parts.join("\n");
+  }
+};
+var bigintSafeJsonStringify = (value) => {
+  return JSON.stringify(value, (key, value2) => {
+    if (typeof value2 === "bigint") {
+      return `${value2}n`;
+    }
+    return value2;
+  });
+};
+var isCofheError = (error) => error instanceof CofheError;
+
+export { COFHE_ADDRESS_BOOK_ADDRESS, CofheError, CofheErrorCode, MOCKS_DECRYPT_RESULT_SIGNER_PRIVATE_KEY, MOCKS_TASK_MANAGER_ADDRESS, MOCKS_THRESHOLD_NETWORK_ADDRESS, MOCKS_ZK_VERIFIER_ADDRESS, MOCKS_ZK_VERIFIER_SIGNER_ADDRESS, MOCKS_ZK_VERIFIER_SIGNER_PRIVATE_KEY, TASK_MANAGER_ID, TFHE_RS_KEY_VERSION, TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT, TFHE_RS_ZK_MAX_BITS, isCofheError };

package/dist/{clientTypes-D3aIXmUp.d.cts → clientTypes-C0A9ji5O.d.cts}

@@ -1,7 +1,7 @@
 import { WalletClient, PublicClient, Hex } from 'viem';
 import { C as CofheChain } from './types-C07FK-cL.cjs';
 import { z } from 'zod';
-import { A as ACP, h as EIP712Domain, C as CreateSelfACPOptions, v as SelfACP, d as CreateSharingACPOptions, w as SharingACP, I as ImportSharedACPOptions, R as RecipientACP, B as ACPHashFields, S as SerializedACP, z as ACPAccessStatus, g as IncomingShare, m as AclServedAddresses, i as ACPUtils } from './onchain-utils-CUAK8glx.cjs';
+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.cjs';
 import { StoreApi } from 'zustand/vanilla';
 
 type TfheInitializer = () => Promise<boolean>;
@@ -280,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: {
@@ -341,6 +348,7 @@ declare const CofheConfigSchema: 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>>;
@@ -1015,6 +1023,25 @@ type ImportActivationOptions = {
      */
     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: {
@@ -1025,6 +1052,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1056,6 +1084,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1086,6 +1115,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1110,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, { activate }?: ImportActivationOptions) => 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;
@@ -1120,6 +1150,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1138,6 +1169,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1162,24 +1194,17 @@ declare const acps: {
     revokeAllACPs: (walletClient: WalletClient, publicClient: PublicClient, revokerContract?: Hex) => Promise<Hex>;
     isACPRevoked: (acp: ACP, publicClient: PublicClient) => Promise<boolean>;
     checkAccess: (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex) => Promise<ACPAccessStatus>;
-    shareOnChain: (acp: ACP, walletClient: WalletClient, registry: Hex) => Promise<{
+    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, importOptions?: ImportActivationOptions) => 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;
@@ -1238,9 +1263,10 @@ type CofheClientACPsClients = {
 };
 /**
  * Options for `importShared`. `activate: false` stores the imported acp without making it the active
- * one (default `true`). Clients default to the connected ones; pass both to override.
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
  */
-type CofheClientImportSharedOptions = ImportActivationOptions & (CofheClientACPsClients | {
+type CofheClientImportSharedOptions = ImportSharedOptions & (CofheClientACPsClients | {
     publicClient?: undefined;
     walletClient?: undefined;
 });
@@ -1269,15 +1295,29 @@ type CofheClientACPs = {
      * '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`). */
-    shareOnChain: (acp: ACP) => Promise<{
+    /**
+     * 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[]>;
+    /** 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?: ImportActivationOptions) => Promise<RecipientACP>;
+    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. */

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

@@ -1,7 +1,7 @@
 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, v as SelfACP, d as CreateSharingACPOptions, w as SharingACP, I as ImportSharedACPOptions, R as RecipientACP, B as ACPHashFields, S as SerializedACP, z as ACPAccessStatus, g as IncomingShare, m as AclServedAddresses, i as ACPUtils } from './onchain-utils-CUAK8glx.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>;
@@ -280,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: {
@@ -341,6 +348,7 @@ declare const CofheConfigSchema: 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>>;
@@ -1015,6 +1023,25 @@ type ImportActivationOptions = {
      */
     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: {
@@ -1025,6 +1052,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1056,6 +1084,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1086,6 +1115,7 @@ declare const acps: {
                         name: string;
                         type: "self" | "sharing" | "recipient";
                         sealingPrivateKey: Hex;
+                        metadata?: Hex | undefined;
                         _signedDomain?: EIP712Domain | undefined;
                         issuer: Hex;
                         expiration: number;
@@ -1110,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, { activate }?: ImportActivationOptions) => 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;
@@ -1120,6 +1150,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1138,6 +1169,7 @@ declare const acps: {
         name: string;
         type: "self" | "sharing" | "recipient";
         sealingPrivateKey: Hex;
+        metadata?: Hex | undefined;
         _signedDomain?: EIP712Domain | undefined;
         issuer: Hex;
         expiration: number;
@@ -1162,24 +1194,17 @@ declare const acps: {
     revokeAllACPs: (walletClient: WalletClient, publicClient: PublicClient, revokerContract?: Hex) => Promise<Hex>;
     isACPRevoked: (acp: ACP, publicClient: PublicClient) => Promise<boolean>;
     checkAccess: (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex) => Promise<ACPAccessStatus>;
-    shareOnChain: (acp: ACP, walletClient: WalletClient, registry: Hex) => Promise<{
+    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, importOptions?: ImportActivationOptions) => 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;
@@ -1238,9 +1263,10 @@ type CofheClientACPsClients = {
 };
 /**
  * Options for `importShared`. `activate: false` stores the imported acp without making it the active
- * one (default `true`). Clients default to the connected ones; pass both to override.
+ * one (default `true`). `name` names it (default "Shared by 0x1234…abcd"). Clients default to the
+ * connected ones; pass both to override.
  */
-type CofheClientImportSharedOptions = ImportActivationOptions & (CofheClientACPsClients | {
+type CofheClientImportSharedOptions = ImportSharedOptions & (CofheClientACPsClients | {
     publicClient?: undefined;
     walletClient?: undefined;
 });
@@ -1269,15 +1295,29 @@ type CofheClientACPs = {
      * '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`). */
-    shareOnChain: (acp: ACP) => Promise<{
+    /**
+     * 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[]>;
+    /** 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?: ImportActivationOptions) => Promise<RecipientACP>;
+    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. */