@cofhe/sdk 0.8.0 → 1.0.0

package/dist/chunk-WJGTPW7K.js

@@ -0,0 +1,228 @@
+import { CofheError } from './chunk-J23FYAI2.js';
+import 'viem';
+
+// core/types.ts
+var FheTypes = /* @__PURE__ */ ((FheTypes2) => {
+  FheTypes2[FheTypes2["Bool"] = 0] = "Bool";
+  FheTypes2[FheTypes2["Uint4"] = 1] = "Uint4";
+  FheTypes2[FheTypes2["Uint8"] = 2] = "Uint8";
+  FheTypes2[FheTypes2["Uint16"] = 3] = "Uint16";
+  FheTypes2[FheTypes2["Uint32"] = 4] = "Uint32";
+  FheTypes2[FheTypes2["Uint64"] = 5] = "Uint64";
+  FheTypes2[FheTypes2["Uint128"] = 6] = "Uint128";
+  FheTypes2[FheTypes2["Uint160"] = 7] = "Uint160";
+  FheTypes2[FheTypes2["Uint256"] = 8] = "Uint256";
+  FheTypes2[FheTypes2["Uint512"] = 9] = "Uint512";
+  FheTypes2[FheTypes2["Uint1024"] = 10] = "Uint1024";
+  FheTypes2[FheTypes2["Uint2048"] = 11] = "Uint2048";
+  FheTypes2[FheTypes2["Uint2"] = 12] = "Uint2";
+  FheTypes2[FheTypes2["Uint6"] = 13] = "Uint6";
+  FheTypes2[FheTypes2["Uint10"] = 14] = "Uint10";
+  FheTypes2[FheTypes2["Uint12"] = 15] = "Uint12";
+  FheTypes2[FheTypes2["Uint14"] = 16] = "Uint14";
+  FheTypes2[FheTypes2["Int2"] = 17] = "Int2";
+  FheTypes2[FheTypes2["Int4"] = 18] = "Int4";
+  FheTypes2[FheTypes2["Int6"] = 19] = "Int6";
+  FheTypes2[FheTypes2["Int8"] = 20] = "Int8";
+  FheTypes2[FheTypes2["Int10"] = 21] = "Int10";
+  FheTypes2[FheTypes2["Int12"] = 22] = "Int12";
+  FheTypes2[FheTypes2["Int14"] = 23] = "Int14";
+  FheTypes2[FheTypes2["Int16"] = 24] = "Int16";
+  FheTypes2[FheTypes2["Int32"] = 25] = "Int32";
+  FheTypes2[FheTypes2["Int64"] = 26] = "Int64";
+  FheTypes2[FheTypes2["Int128"] = 27] = "Int128";
+  FheTypes2[FheTypes2["Int160"] = 28] = "Int160";
+  FheTypes2[FheTypes2["Int256"] = 29] = "Int256";
+  return FheTypes2;
+})(FheTypes || {});
+var FheUintUTypes = [
+  2 /* Uint8 */,
+  3 /* Uint16 */,
+  4 /* Uint32 */,
+  5 /* Uint64 */,
+  6 /* Uint128 */
+  // [U256-DISABLED]
+  // FheTypes.Uint256,
+];
+var FheAllUTypes = [
+  0 /* Bool */,
+  2 /* Uint8 */,
+  3 /* Uint16 */,
+  4 /* Uint32 */,
+  5 /* Uint64 */,
+  6 /* Uint128 */,
+  // [U256-DISABLED]
+  // FheTypes.Uint256,
+  7 /* Uint160 */
+];
+var EncryptableFactoriesImpl = {
+  bool: (data, securityZone = 0) => ({ data, securityZone, utype: 0 /* Bool */ }),
+  address: (data, securityZone = 0) => ({ data, securityZone, utype: 7 /* Uint160 */ }),
+  uint8: (data, securityZone = 0) => ({ data, securityZone, utype: 2 /* Uint8 */ }),
+  uint16: (data, securityZone = 0) => ({ data, securityZone, utype: 3 /* Uint16 */ }),
+  uint32: (data, securityZone = 0) => ({ data, securityZone, utype: 4 /* Uint32 */ }),
+  uint64: (data, securityZone = 0) => ({ data, securityZone, utype: 5 /* Uint64 */ }),
+  uint128: (data, securityZone = 0) => ({ data, securityZone, utype: 6 /* Uint128 */ })
+  // [U256-DISABLED]
+  // uint256: (data: EncryptableUint256['data'], securityZone = 0) =>
+  //   ({ data, securityZone, utype: FheTypes.Uint256 }) as EncryptableUint256,
+};
+function createEncryptableByLiteral(type, data, securityZone = 0) {
+  switch (type) {
+    case "bool": {
+      if (typeof data !== "boolean")
+        throw new Error("Bool encryptable data must be boolean");
+      return EncryptableFactoriesImpl.bool(data, securityZone);
+    }
+    case "address":
+    case "uint8":
+    case "uint16":
+    case "uint32":
+    case "uint64":
+    case "uint128": {
+      if (typeof data === "boolean")
+        throw new Error("Uint encryptable data must be string or bigint");
+      return EncryptableFactoriesImpl[type](data, securityZone);
+    }
+    default: {
+      const _exhaustive = type;
+      throw new Error(`Unsupported encryptable type: ${_exhaustive}`);
+    }
+  }
+}
+var Encryptable = {
+  ...EncryptableFactoriesImpl,
+  create: createEncryptableByLiteral
+};
+function isEncryptableItem(value) {
+  return (
+    // Is object and exists
+    typeof value === "object" && value !== null && // Has securityZone
+    "securityZone" in value && typeof value.securityZone === "number" && // Has utype
+    "utype" in value && FheAllUTypes.includes(value.utype) && // Has data
+    "data" in value && ["string", "number", "bigint", "boolean"].includes(typeof value.data)
+  );
+}
+var EncryptStep = /* @__PURE__ */ ((EncryptStep2) => {
+  EncryptStep2["InitTfhe"] = "initTfhe";
+  EncryptStep2["FetchKeys"] = "fetchKeys";
+  EncryptStep2["Pack"] = "pack";
+  EncryptStep2["Prove"] = "prove";
+  EncryptStep2["Verify"] = "verify";
+  return EncryptStep2;
+})(EncryptStep || {});
+function isLastEncryptionStep(step) {
+  return step === "verify" /* Verify */;
+}
+var toHexString = (bytes) => bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, "0"), "");
+var HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
+var fromHexString = (hexString) => {
+  const body = hexString.replace(/^0x/, "");
+  if (!HEX_BODY_REGEX.test(body)) {
+    throw new Error("Invalid hex string: contains non-hexadecimal characters");
+  }
+  const padded = body.length % 2 === 1 ? `0${body}` : body;
+  const arr = padded.match(/.{1,2}/g);
+  if (!arr)
+    return new Uint8Array();
+  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
+};
+var toBigIntOrThrow = (value) => {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  try {
+    return BigInt(value);
+  } catch (error) {
+    throw new Error("Invalid input: Unable to convert to bigint");
+  }
+};
+var validateBigIntInRange = (value, max, min = 0n) => {
+  if (typeof value !== "bigint") {
+    throw new Error("Value must be of type bigint");
+  }
+  if (value > max || value < min) {
+    throw new Error(`Value out of range: ${max} - ${min}, try a different uint type`);
+  }
+};
+var hexToBytes = (hex) => fromHexString(hex);
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function getPublicClientChainID(publicClient) {
+  let chainId = null;
+  try {
+    chainId = publicClient.chain?.id ?? await publicClient.getChainId();
+  } catch (e) {
+    throw new CofheError({
+      code: "PUBLIC_WALLET_GET_CHAIN_ID_FAILED" /* PublicWalletGetChainIdFailed */,
+      message: "getting chain ID from public client failed",
+      cause: e instanceof Error ? e : void 0
+    });
+  }
+  if (chainId === null) {
+    throw new CofheError({
+      code: "PUBLIC_WALLET_GET_CHAIN_ID_FAILED" /* PublicWalletGetChainIdFailed */,
+      message: "chain ID from public client is null"
+    });
+  }
+  return chainId;
+}
+async function getWalletClientAccount(walletClient) {
+  let address;
+  try {
+    address = walletClient.account?.address;
+    if (!address) {
+      address = (await walletClient.getAddresses())?.[0];
+    }
+  } catch (e) {
+    throw new CofheError({
+      code: "PUBLIC_WALLET_GET_ADDRESSES_FAILED" /* PublicWalletGetAddressesFailed */,
+      message: "getting address from wallet client failed",
+      cause: e instanceof Error ? e : void 0
+    });
+  }
+  if (!address) {
+    throw new CofheError({
+      code: "PUBLIC_WALLET_GET_ADDRESSES_FAILED" /* PublicWalletGetAddressesFailed */,
+      message: "address from wallet client is null"
+    });
+  }
+  return address;
+}
+function fheTypeToString(utype) {
+  switch (utype) {
+    case 0 /* Bool */:
+      return "bool";
+    case 1 /* Uint4 */:
+      return "uint4";
+    case 2 /* Uint8 */:
+      return "uint8";
+    case 3 /* Uint16 */:
+      return "uint16";
+    case 4 /* Uint32 */:
+      return "uint32";
+    case 5 /* Uint64 */:
+      return "uint64";
+    case 6 /* Uint128 */:
+      return "uint128";
+    case 7 /* Uint160 */:
+      return "uint160";
+    case 8 /* Uint256 */:
+      return "uint256";
+    case 9 /* Uint512 */:
+      return "uint512";
+    case 10 /* Uint1024 */:
+      return "uint1024";
+    case 11 /* Uint2048 */:
+      return "uint2048";
+    case 12 /* Uint2 */:
+      return "uint2";
+    case 13 /* Uint6 */:
+      return "uint6";
+    case 14 /* Uint10 */:
+      return "uint10";
+    default:
+      throw new Error(`Unknown FheType: ${utype}`);
+  }
+}
+
+export { EncryptStep, Encryptable, FheAllUTypes, FheTypes, FheUintUTypes, fheTypeToString, fromHexString, getPublicClientChainID, getWalletClientAccount, hexToBytes, isEncryptableItem, isLastEncryptionStep, sleep, toBigIntOrThrow, toHexString, validateBigIntInRange };

package/dist/{clientTypes-D3aIXmUp.d.cts → clientTypes-IO6b5Um8.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-CgOslubH.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-b1pOxOUE.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-CgOslubH.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. */