@cofhe/sdk 0.8.0 → 1.0.0

package/dist/node.d.cts

@@ -1,8 +1,8 @@
-import { C as CofheInputConfig, a as CofheConfig, b as CofheClient } from './clientTypes-D3aIXmUp.cjs';
+import { C as CofheInputConfig, a as CofheConfig, b as CofheClient } from './clientTypes-IO6b5Um8.cjs';
 import 'viem';
 import './types-C07FK-cL.cjs';
 import 'zod';
-import './onchain-utils-CUAK8glx.cjs';
+import './onchain-utils-CgOslubH.cjs';
 import 'zustand/vanilla';
 
 /**

package/dist/node.d.ts

@@ -1,8 +1,8 @@
-import { C as CofheInputConfig, a as CofheConfig, b as CofheClient } from './clientTypes-5YPPR16m.js';
+import { C as CofheInputConfig, a as CofheConfig, b as CofheClient } from './clientTypes-b1pOxOUE.js';
 import 'viem';
 import './types-C07FK-cL.js';
 import 'zod';
-import './onchain-utils-CUAK8glx.js';
+import './onchain-utils-CgOslubH.js';
 import 'zustand/vanilla';
 
 /**

package/dist/node.js

@@ -1,18 +1,25 @@
-import { createCofheConfigBase, createCofheClientBase } from './chunk-GGI7Y6AW.js';
+import { createCofheConfigBase, createCofheClientBase } from './chunk-O2ITEUEU.js';
 import './chunk-UKQAJK4N.js';
-import './chunk-UJYOBHYA.js';
-import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-NMKMCAI3.js';
+import './chunk-3L2IVPMI.js';
+import { fromHexString } from './chunk-WJGTPW7K.js';
+import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-J23FYAI2.js';
 import { promises } from 'fs';
 import { join } from 'path';
 import { init_panic_hook, ProvenCompactCiphertextList, CompactPkeCrs, TfheCompactPublicKey } from 'node-tfhe';
 
 var memoryStorage = {};
+var getStorageDir = () => join(process.env.HOME || process.env.USERPROFILE || ".", ".cofhesdk");
+var ensureStorageDir = async (storageDir) => {
+  await promises.mkdir(storageDir, { recursive: true, mode: 448 });
+  await promises.chmod(storageDir, 448).catch(() => {
+  });
+};
 var createNodeStorage = () => {
   return {
     getItem: async (name) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || ".", ".cofhesdk");
-        await promises.mkdir(storageDir, { recursive: true });
+        const storageDir = getStorageDir();
+        await ensureStorageDir(storageDir);
         const filePath = join(storageDir, `${name}.json`);
         const data = await promises.readFile(filePath, "utf8").catch(() => null);
         return data ? JSON.parse(data) : null;
@@ -23,10 +30,12 @@ var createNodeStorage = () => {
     },
     setItem: async (name, value) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || ".", ".cofhesdk");
-        await promises.mkdir(storageDir, { recursive: true });
+        const storageDir = getStorageDir();
+        await ensureStorageDir(storageDir);
         const filePath = join(storageDir, `${name}.json`);
-        await promises.writeFile(filePath, JSON.stringify(value));
+        await promises.writeFile(filePath, JSON.stringify(value), { mode: 384 });
+        await promises.chmod(filePath, 384).catch(() => {
+        });
       } catch (e) {
         console.warn("Node.js filesystem modules not available, falling back to memory storage" + e);
         memoryStorage[name] = value;
@@ -34,8 +43,7 @@ var createNodeStorage = () => {
     },
     removeItem: async (name) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || ".", ".cofhesdk");
-        const filePath = join(storageDir, `${name}.json`);
+        const filePath = join(getStorageDir(), `${name}.json`);
         await promises.unlink(filePath).catch(() => {
         });
       } catch (e) {
@@ -53,13 +61,6 @@ async function initTfhe() {
   tfheInitialized = true;
   return true;
 }
-var fromHexString = (hexString) => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, "").match(/.{1,2}/g);
-  if (!arr)
-    return new Uint8Array();
-  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
-};
 var _deserializeTfhePublicKey = (buff) => {
   return TfheCompactPublicKey.safe_deserialize(fromHexString(buff), TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT);
 };

package/dist/{onchain-utils-CUAK8glx.d.cts → onchain-utils-CgOslubH.d.cts}

@@ -1,4 +1,4 @@
-import { Hex, PublicClient, WalletClient } from 'viem';
+import { Hex, Address, PublicClient, WalletClient } from 'viem';
 
 type EthEncryptedData = {
     data: Uint8Array;
@@ -35,6 +35,52 @@ declare const seal: (value: bigint | number, publicKey: string) => EthEncryptedD
  */
 declare const unsealWithPrivateKey: (privateKey: string, parsedData: EthEncryptedData) => bigint;
 
+/**
+ * A label says where one ctHash of a SNAPSHOT share came from, as something the recipient can
+ * check against the chain. It speaks of contracts, selectors and positions in the chain only:
+ * it does not know what a token, a balance or a transfer is. A reader that recognises a selector
+ * can present the value accordingly (see `describeShareMetadata`). A share carries one label per
+ * ctHash, in the order of `acp.handles`, so the ctHashes themselves are never repeated.
+ */
+/** One argument of a stored-value read: the share issuer, or a literal 32-byte ABI word. */
+type ShareLabelReadArg = {
+    type: 'issuer';
+} | {
+    type: 'word';
+    value: Hex;
+};
+/** A stored value: what a view function of a contract returned at a block. */
+type StoredValueLabel = {
+    kind: 'stored';
+    contract: Address;
+    /** 4-byte selector of the view function. */
+    selector: Hex;
+    /** Static ABI types only: each argument is one 32-byte word. */
+    args: ShareLabelReadArg[];
+    /** Which 32-byte word of the return data is the ctHash (0 for a single return value). */
+    returnWord: number;
+    /** Block the value was read at (on Arbitrum: the L2 block number). */
+    block: bigint;
+};
+/** An event value: a value carried by one event (log) that a contract emitted. */
+type EventValueLabel = {
+    kind: 'event';
+    contract: Address;
+    /** Block of the log (on Arbitrum: the L2 block number). */
+    block: bigint;
+    /** Index of the log's transaction within its block. */
+    txIndex: number;
+    /** Block-wide index of the log, as RPC nodes return it. */
+    logIndex: number;
+    /** First 4 bytes of the log's topic0: the event selector. */
+    selector: Hex;
+};
+/** The issuer chose not to say where the ctHash came from. */
+type UnlabelledLabel = {
+    kind: 'unlabelled';
+};
+type ShareLabel = StoredValueLabel | EventValueLabel | UnlabelledLabel;
+
 /**
  * EIP712 related types
  */
@@ -76,6 +122,12 @@ interface ACPPrivate {
      * Never leaves the client.
      */
     sealingPrivateKey: Hex;
+    /**
+     * (sharing / recipient) The share metadata: the labels of its handles, a v3 blob
+     * (`decodeShareMetadata` / `describeShareMetadata`). Not signed; travels with the share, in the
+     * exported JSON or in the registry's `Shared` event. Absent when the share has none.
+     */
+    metadata?: Hex;
     /**
      * EIP712 domain used to sign this acp.
      * Should not be set manually, included in metadata as part of serialization flows.
@@ -211,29 +263,44 @@ type CreateSharingACPOptions = ACPScopeOptions & {
     expiration?: number;
     revokerData?: number;
     revokerContract?: string;
+    /**
+     * The labels of the handles, one per handle in order. Kept on the acp as `metadata`, then
+     * written into `export()` and posted by `shareOnChain`.
+     */
+    labels?: readonly ShareLabel[];
+    /**
+     * The key of the app the share is for (`shareAppKey(app)`), kept in `metadata` with the labels.
+     * A client configured with `acp: { app }` fills it in; a recipient client with the same `app`
+     * lists the share, one with another app does not.
+     */
+    appKey?: Hex;
 };
+/** A share as exported (`SharedACP`) or read from the registry. A `name` in it is ignored. */
 type ImportSharedACPOptions = ACPScopeOptions & {
     type?: 'sharing';
     issuer: string;
     recipient: string;
     issuerSignature: string;
-    name?: string;
     expiration: number;
     revokerData?: number;
     revokerContract?: string;
+    /** The share metadata (labels blob), kept on the recipient acp; `0x` or absent for none. */
+    metadata?: string;
 };
 /** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
 type SerializedACP = ACP;
 /**
  * The share payload produced by `ACPUtils.export()` — the full public component
  * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
- * the display name and acp type. Fixed shape: every field is always present
+ * the acp type. The issuer's `name` is not exported: it is their own note, and the
+ * recipient names the share themselves. Fixed shape: every field is always present
  * (zero-values instead of omissions), so importers can parse a single schema.
- * Mirrors the on-chain sharing payload struct field-for-field.
+ * Mirrors the on-chain sharing payload struct field-for-field. The one optional
+ * field is `metadata`, the labels of the handles, present only when the share has them.
  */
 type SharedACP = Expand<Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
-    name: string;
     type: 'sharing';
+    metadata?: Hex;
 }>;
 /**
  * An ACP on-chain status, as `client.acp.checkAccess` reports it instead of a revert.
@@ -244,11 +311,25 @@ type SharedACP = Expand<Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
 type ACPAccessStatus = 'valid' | 'allowed' | 'out-of-scope' | 'issuer-not-allowed' | 'expired' | 'revoked' | 'invalid-issuer-signature' | 'invalid-recipient-signature';
 /**
  * A share read back from the on-chain ACPShareRegistry: the posted payload
- * (SharedACP minus the client-side name/type) plus its registry id.
+ * (SharedACP minus its type), its registry id, and the
+ * metadata blob posted with it (`0x` when none) — for a SNAPSHOT share, the
+ * labels of its handles (`decodeShareMetadata` / `describeShareMetadata`).
  */
-type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & {
+type IncomingShare = Expand<Omit<SharedACP, 'type' | 'metadata'> & {
     shareId: Hex;
+    metadata: Hex;
+    /** The key of the app the share was posted for (`shareAppKey(app)`), when it names one. */
+    appKey?: Hex;
 }>;
+/**
+ * What the share label helpers read: the handles, their issuer and the metadata blob. An
+ * `IncomingShare` (on-chain route) and a sharing or recipient `ACP` (exported JSON route) both fit.
+ */
+type LabelledShare = {
+    issuer: Hex;
+    handles: readonly Hex[];
+    metadata?: Hex;
+};
 /**
  * A type representing the acp fields that are used to generate the hash
  */
@@ -281,9 +362,12 @@ declare const ACPUtils: {
      */
     createSharing: (options: CreateSharingACPOptions) => SharingACP;
     /**
-     * Import a shared acp from various input formats
+     * Import a shared acp from various input formats. The acp is named `name`, or after its issuer
+     * ("Shared by 0x1234…abcd"); a `name` in the share itself is ignored.
      */
-    importShared: (options: ImportSharedACPOptions | string) => RecipientACP;
+    importShared: (options: ImportSharedACPOptions | string, { name }?: {
+        name?: string;
+    }) => RecipientACP;
     /**
      * Sign an ACP with the provided wallet client
      */
@@ -299,7 +383,9 @@ declare const ACPUtils: {
     /**
      * Import and sign a shared acp in one operation from various input formats
      */
-    importSharedAndSign: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientACP>;
+    importSharedAndSign: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient, importOptions?: {
+        name?: string;
+    }) => Promise<RecipientACP>;
     /**
      * Deserialize an ACP from serialized data
      */
@@ -324,6 +410,7 @@ declare const ACPUtils: {
         handles: `0x${string}`[];
         issuerSignature: `0x${string}`;
         recipientSignature: `0x${string}`;
+        metadata?: `0x${string}` | undefined;
         sealingPrivateKey?: string | undefined;
         sealingKey?: string | undefined;
     };
@@ -350,6 +437,7 @@ declare const ACPUtils: {
         handles: `0x${string}`[];
         issuerSignature: `0x${string}`;
         recipientSignature: `0x${string}`;
+        metadata?: `0x${string}` | undefined;
         sealingPrivateKey?: string | undefined;
         sealingKey?: string | undefined;
     };
@@ -365,7 +453,7 @@ declare const ACPUtils: {
     /**
      * Export acp data for sharing (strips the private component).
      * Fixed `SharedACP` shape — every field always present, aligned with
-     * `ACPPublic` and the on-chain sharing payload.
+     * `ACPPublic` and the on-chain sharing payload — plus `metadata` when the acp has labels.
      */
     export: (acp: ACP) => string;
     /**
@@ -416,6 +504,42 @@ declare const ACPUtils: {
     checkAccessOnChain: (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex) => Promise<ACPAccessStatus>;
 };
 
+/**
+ * - `verified`: the chain confirms the label.
+ * - `mismatch`: the chain contradicts it.
+ * - `unverifiable`: the chain could not be asked — an unlabelled ctHash, a node without the
+ *   state of that block (a stored value needs an archive node once its block is old), or a
+ *   failed request.
+ */
+type LabelVerification = 'verified' | 'mismatch' | 'unverifiable';
+/**
+ * How much of a share's labels a reader checks against the chain. Labels are the issuer's claim:
+ * - `all` (default): every label — one `getLogs` per contract and block, one call per stored value;
+ * - `events`: event values only, which any node can answer however old the block;
+ * - `none`: trust the labels as written, no requests (the issuer previewing their own share).
+ */
+type ShareLabelVerifyMode = 'all' | 'events' | 'none';
+/** A label's verification, or `skipped` when the verify mode leaves it unchecked. */
+type ShareLabelCheck = LabelVerification | 'skipped';
+/**
+ * Checks one label against the chain: does the ctHash really come from where the label says?
+ * `issuer` is the share issuer (`acp.issuer`), which an issuer argument of a stored value stands
+ * for. One request.
+ */
+declare const verifyShareLabel: (label: ShareLabel, handle: Hex, publicClient: PublicClient, issuer: Address) => Promise<LabelVerification>;
+/**
+ * Checks the labels of a share, index for index with `handles`, as far as `verify` says. Requests
+ * are shared: one `getLogs` per contract and block, however many values it carries, and one call
+ * per distinct stored read.
+ */
+declare const verifyShareLabels: ({ labels, handles, issuer, publicClient, verify, }: {
+    labels: readonly ShareLabel[];
+    handles: readonly Hex[];
+    issuer: Address;
+    publicClient: PublicClient;
+    verify?: ShareLabelVerifyMode;
+}) => Promise<ShareLabelCheck[]>;
+
 declare const getAclAddress: (publicClient: PublicClient) => Promise<Hex>;
 interface AclServedAddresses {
     defaultRevoker?: Hex;
@@ -428,10 +552,10 @@ declare const clearAclServedAddresses: () => void;
  * TaskManager -> acl() -> getters). Zero addresses and pre-upgrade ACLs (getters absent -> revert)
  * resolve to `undefined` — callers fall back to `acp.*` config.
  *
- * Resolutions are cached per chainId. A failure to reach the TaskManager (network
- * error, no CoFHE deployment) is NOT cached, so a transient outage does not pin
- * an empty result for the whole session.
+ * Resolutions are cached per chainId. A failure to reach the TaskManager or the ACL
+ * getters (network error, no CoFHE deployment) is NOT cached, so a transient outage
+ * does not pin an empty result for the whole session.
  */
 declare const getAclServedAddresses: (publicClient: PublicClient, chainId: number) => Promise<AclServedAddresses>;
 
-export { type ACP as A, type ACPHashFields as B, type CreateSelfACPOptions as C, type Expand as D, type EIP712Types as E, GenerateSealingKey as G, type ImportSharedACPOptions as I, type RecipientACP as R, type SerializedACP as S, type ValidationResult as V, type ACPPublic as a, type ACPSignaturePrimaryType as b, type EIP712Message as c, type CreateSharingACPOptions as d, type ACPMetadata as e, type SharedACP as f, type IncomingShare as g, type EIP712Domain as h, ACPUtils as i, getAclAddress as j, getAclServedAddresses as k, clearAclServedAddresses as l, type AclServedAddresses as m, type SealingKeyPair as n, type EthEncryptedData as o, type EIP712Type as p, type ACPPrivate as q, type ACPType as r, seal as s, type ACPOf as t, unsealWithPrivateKey as u, type SelfACP as v, type SharingACP as w, ACPScope as x, type ACPScopeOptions as y, type ACPAccessStatus as z };
+export { type ACP as A, type EIP712Type as B, type CreateSelfACPOptions as C, type ACPPrivate as D, type EventValueLabel as E, type ACPType as F, GenerateSealingKey as G, type ACPOf as H, type ImportSharedACPOptions as I, type SelfACP as J, type SharingACP as K, type LabelledShare as L, ACPScope as M, type ACPScopeOptions as N, type ACPAccessStatus as O, type ACPHashFields as P, type Expand as Q, type RecipientACP as R, type ShareLabel as S, type UnlabelledLabel as U, type ValidationResult as V, type StoredValueLabel as a, type ACPPublic as b, type ACPSignaturePrimaryType as c, type EIP712Types as d, type EIP712Message as e, type SerializedACP as f, type CreateSharingACPOptions as g, type ACPMetadata as h, type SharedACP as i, type IncomingShare as j, type EIP712Domain as k, ACPUtils as l, getAclAddress as m, getAclServedAddresses as n, clearAclServedAddresses as o, type AclServedAddresses as p, type SealingKeyPair as q, type EthEncryptedData as r, seal as s, type ShareLabelReadArg as t, unsealWithPrivateKey as u, type LabelVerification as v, type ShareLabelVerifyMode as w, type ShareLabelCheck as x, verifyShareLabel as y, verifyShareLabels as z };

package/dist/{onchain-utils-CUAK8glx.d.ts → onchain-utils-CgOslubH.d.ts}

@@ -1,4 +1,4 @@
-import { Hex, PublicClient, WalletClient } from 'viem';
+import { Hex, Address, PublicClient, WalletClient } from 'viem';
 
 type EthEncryptedData = {
     data: Uint8Array;
@@ -35,6 +35,52 @@ declare const seal: (value: bigint | number, publicKey: string) => EthEncryptedD
  */
 declare const unsealWithPrivateKey: (privateKey: string, parsedData: EthEncryptedData) => bigint;
 
+/**
+ * A label says where one ctHash of a SNAPSHOT share came from, as something the recipient can
+ * check against the chain. It speaks of contracts, selectors and positions in the chain only:
+ * it does not know what a token, a balance or a transfer is. A reader that recognises a selector
+ * can present the value accordingly (see `describeShareMetadata`). A share carries one label per
+ * ctHash, in the order of `acp.handles`, so the ctHashes themselves are never repeated.
+ */
+/** One argument of a stored-value read: the share issuer, or a literal 32-byte ABI word. */
+type ShareLabelReadArg = {
+    type: 'issuer';
+} | {
+    type: 'word';
+    value: Hex;
+};
+/** A stored value: what a view function of a contract returned at a block. */
+type StoredValueLabel = {
+    kind: 'stored';
+    contract: Address;
+    /** 4-byte selector of the view function. */
+    selector: Hex;
+    /** Static ABI types only: each argument is one 32-byte word. */
+    args: ShareLabelReadArg[];
+    /** Which 32-byte word of the return data is the ctHash (0 for a single return value). */
+    returnWord: number;
+    /** Block the value was read at (on Arbitrum: the L2 block number). */
+    block: bigint;
+};
+/** An event value: a value carried by one event (log) that a contract emitted. */
+type EventValueLabel = {
+    kind: 'event';
+    contract: Address;
+    /** Block of the log (on Arbitrum: the L2 block number). */
+    block: bigint;
+    /** Index of the log's transaction within its block. */
+    txIndex: number;
+    /** Block-wide index of the log, as RPC nodes return it. */
+    logIndex: number;
+    /** First 4 bytes of the log's topic0: the event selector. */
+    selector: Hex;
+};
+/** The issuer chose not to say where the ctHash came from. */
+type UnlabelledLabel = {
+    kind: 'unlabelled';
+};
+type ShareLabel = StoredValueLabel | EventValueLabel | UnlabelledLabel;
+
 /**
  * EIP712 related types
  */
@@ -76,6 +122,12 @@ interface ACPPrivate {
      * Never leaves the client.
      */
     sealingPrivateKey: Hex;
+    /**
+     * (sharing / recipient) The share metadata: the labels of its handles, a v3 blob
+     * (`decodeShareMetadata` / `describeShareMetadata`). Not signed; travels with the share, in the
+     * exported JSON or in the registry's `Shared` event. Absent when the share has none.
+     */
+    metadata?: Hex;
     /**
      * EIP712 domain used to sign this acp.
      * Should not be set manually, included in metadata as part of serialization flows.
@@ -211,29 +263,44 @@ type CreateSharingACPOptions = ACPScopeOptions & {
     expiration?: number;
     revokerData?: number;
     revokerContract?: string;
+    /**
+     * The labels of the handles, one per handle in order. Kept on the acp as `metadata`, then
+     * written into `export()` and posted by `shareOnChain`.
+     */
+    labels?: readonly ShareLabel[];
+    /**
+     * The key of the app the share is for (`shareAppKey(app)`), kept in `metadata` with the labels.
+     * A client configured with `acp: { app }` fills it in; a recipient client with the same `app`
+     * lists the share, one with another app does not.
+     */
+    appKey?: Hex;
 };
+/** A share as exported (`SharedACP`) or read from the registry. A `name` in it is ignored. */
 type ImportSharedACPOptions = ACPScopeOptions & {
     type?: 'sharing';
     issuer: string;
     recipient: string;
     issuerSignature: string;
-    name?: string;
     expiration: number;
     revokerData?: number;
     revokerContract?: string;
+    /** The share metadata (labels blob), kept on the recipient acp; `0x` or absent for none. */
+    metadata?: string;
 };
 /** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
 type SerializedACP = ACP;
 /**
  * The share payload produced by `ACPUtils.export()` — the full public component
  * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
- * the display name and acp type. Fixed shape: every field is always present
+ * the acp type. The issuer's `name` is not exported: it is their own note, and the
+ * recipient names the share themselves. Fixed shape: every field is always present
  * (zero-values instead of omissions), so importers can parse a single schema.
- * Mirrors the on-chain sharing payload struct field-for-field.
+ * Mirrors the on-chain sharing payload struct field-for-field. The one optional
+ * field is `metadata`, the labels of the handles, present only when the share has them.
  */
 type SharedACP = Expand<Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
-    name: string;
     type: 'sharing';
+    metadata?: Hex;
 }>;
 /**
  * An ACP on-chain status, as `client.acp.checkAccess` reports it instead of a revert.
@@ -244,11 +311,25 @@ type SharedACP = Expand<Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
 type ACPAccessStatus = 'valid' | 'allowed' | 'out-of-scope' | 'issuer-not-allowed' | 'expired' | 'revoked' | 'invalid-issuer-signature' | 'invalid-recipient-signature';
 /**
  * A share read back from the on-chain ACPShareRegistry: the posted payload
- * (SharedACP minus the client-side name/type) plus its registry id.
+ * (SharedACP minus its type), its registry id, and the
+ * metadata blob posted with it (`0x` when none) — for a SNAPSHOT share, the
+ * labels of its handles (`decodeShareMetadata` / `describeShareMetadata`).
  */
-type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & {
+type IncomingShare = Expand<Omit<SharedACP, 'type' | 'metadata'> & {
     shareId: Hex;
+    metadata: Hex;
+    /** The key of the app the share was posted for (`shareAppKey(app)`), when it names one. */
+    appKey?: Hex;
 }>;
+/**
+ * What the share label helpers read: the handles, their issuer and the metadata blob. An
+ * `IncomingShare` (on-chain route) and a sharing or recipient `ACP` (exported JSON route) both fit.
+ */
+type LabelledShare = {
+    issuer: Hex;
+    handles: readonly Hex[];
+    metadata?: Hex;
+};
 /**
  * A type representing the acp fields that are used to generate the hash
  */
@@ -281,9 +362,12 @@ declare const ACPUtils: {
      */
     createSharing: (options: CreateSharingACPOptions) => SharingACP;
     /**
-     * Import a shared acp from various input formats
+     * Import a shared acp from various input formats. The acp is named `name`, or after its issuer
+     * ("Shared by 0x1234…abcd"); a `name` in the share itself is ignored.
      */
-    importShared: (options: ImportSharedACPOptions | string) => RecipientACP;
+    importShared: (options: ImportSharedACPOptions | string, { name }?: {
+        name?: string;
+    }) => RecipientACP;
     /**
      * Sign an ACP with the provided wallet client
      */
@@ -299,7 +383,9 @@ declare const ACPUtils: {
     /**
      * Import and sign a shared acp in one operation from various input formats
      */
-    importSharedAndSign: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientACP>;
+    importSharedAndSign: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient, importOptions?: {
+        name?: string;
+    }) => Promise<RecipientACP>;
     /**
      * Deserialize an ACP from serialized data
      */
@@ -324,6 +410,7 @@ declare const ACPUtils: {
         handles: `0x${string}`[];
         issuerSignature: `0x${string}`;
         recipientSignature: `0x${string}`;
+        metadata?: `0x${string}` | undefined;
         sealingPrivateKey?: string | undefined;
         sealingKey?: string | undefined;
     };
@@ -350,6 +437,7 @@ declare const ACPUtils: {
         handles: `0x${string}`[];
         issuerSignature: `0x${string}`;
         recipientSignature: `0x${string}`;
+        metadata?: `0x${string}` | undefined;
         sealingPrivateKey?: string | undefined;
         sealingKey?: string | undefined;
     };
@@ -365,7 +453,7 @@ declare const ACPUtils: {
     /**
      * Export acp data for sharing (strips the private component).
      * Fixed `SharedACP` shape — every field always present, aligned with
-     * `ACPPublic` and the on-chain sharing payload.
+     * `ACPPublic` and the on-chain sharing payload — plus `metadata` when the acp has labels.
      */
     export: (acp: ACP) => string;
     /**
@@ -416,6 +504,42 @@ declare const ACPUtils: {
     checkAccessOnChain: (acp: ACP, publicClient: PublicClient, handle?: bigint | Hex) => Promise<ACPAccessStatus>;
 };
 
+/**
+ * - `verified`: the chain confirms the label.
+ * - `mismatch`: the chain contradicts it.
+ * - `unverifiable`: the chain could not be asked — an unlabelled ctHash, a node without the
+ *   state of that block (a stored value needs an archive node once its block is old), or a
+ *   failed request.
+ */
+type LabelVerification = 'verified' | 'mismatch' | 'unverifiable';
+/**
+ * How much of a share's labels a reader checks against the chain. Labels are the issuer's claim:
+ * - `all` (default): every label — one `getLogs` per contract and block, one call per stored value;
+ * - `events`: event values only, which any node can answer however old the block;
+ * - `none`: trust the labels as written, no requests (the issuer previewing their own share).
+ */
+type ShareLabelVerifyMode = 'all' | 'events' | 'none';
+/** A label's verification, or `skipped` when the verify mode leaves it unchecked. */
+type ShareLabelCheck = LabelVerification | 'skipped';
+/**
+ * Checks one label against the chain: does the ctHash really come from where the label says?
+ * `issuer` is the share issuer (`acp.issuer`), which an issuer argument of a stored value stands
+ * for. One request.
+ */
+declare const verifyShareLabel: (label: ShareLabel, handle: Hex, publicClient: PublicClient, issuer: Address) => Promise<LabelVerification>;
+/**
+ * Checks the labels of a share, index for index with `handles`, as far as `verify` says. Requests
+ * are shared: one `getLogs` per contract and block, however many values it carries, and one call
+ * per distinct stored read.
+ */
+declare const verifyShareLabels: ({ labels, handles, issuer, publicClient, verify, }: {
+    labels: readonly ShareLabel[];
+    handles: readonly Hex[];
+    issuer: Address;
+    publicClient: PublicClient;
+    verify?: ShareLabelVerifyMode;
+}) => Promise<ShareLabelCheck[]>;
+
 declare const getAclAddress: (publicClient: PublicClient) => Promise<Hex>;
 interface AclServedAddresses {
     defaultRevoker?: Hex;
@@ -428,10 +552,10 @@ declare const clearAclServedAddresses: () => void;
  * TaskManager -> acl() -> getters). Zero addresses and pre-upgrade ACLs (getters absent -> revert)
  * resolve to `undefined` — callers fall back to `acp.*` config.
  *
- * Resolutions are cached per chainId. A failure to reach the TaskManager (network
- * error, no CoFHE deployment) is NOT cached, so a transient outage does not pin
- * an empty result for the whole session.
+ * Resolutions are cached per chainId. A failure to reach the TaskManager or the ACL
+ * getters (network error, no CoFHE deployment) is NOT cached, so a transient outage
+ * does not pin an empty result for the whole session.
  */
 declare const getAclServedAddresses: (publicClient: PublicClient, chainId: number) => Promise<AclServedAddresses>;
 
-export { type ACP as A, type ACPHashFields as B, type CreateSelfACPOptions as C, type Expand as D, type EIP712Types as E, GenerateSealingKey as G, type ImportSharedACPOptions as I, type RecipientACP as R, type SerializedACP as S, type ValidationResult as V, type ACPPublic as a, type ACPSignaturePrimaryType as b, type EIP712Message as c, type CreateSharingACPOptions as d, type ACPMetadata as e, type SharedACP as f, type IncomingShare as g, type EIP712Domain as h, ACPUtils as i, getAclAddress as j, getAclServedAddresses as k, clearAclServedAddresses as l, type AclServedAddresses as m, type SealingKeyPair as n, type EthEncryptedData as o, type EIP712Type as p, type ACPPrivate as q, type ACPType as r, seal as s, type ACPOf as t, unsealWithPrivateKey as u, type SelfACP as v, type SharingACP as w, ACPScope as x, type ACPScopeOptions as y, type ACPAccessStatus as z };
+export { type ACP as A, type EIP712Type as B, type CreateSelfACPOptions as C, type ACPPrivate as D, type EventValueLabel as E, type ACPType as F, GenerateSealingKey as G, type ACPOf as H, type ImportSharedACPOptions as I, type SelfACP as J, type SharingACP as K, type LabelledShare as L, ACPScope as M, type ACPScopeOptions as N, type ACPAccessStatus as O, type ACPHashFields as P, type Expand as Q, type RecipientACP as R, type ShareLabel as S, type UnlabelledLabel as U, type ValidationResult as V, type StoredValueLabel as a, type ACPPublic as b, type ACPSignaturePrimaryType as c, type EIP712Types as d, type EIP712Message as e, type SerializedACP as f, type CreateSharingACPOptions as g, type ACPMetadata as h, type SharedACP as i, type IncomingShare as j, type EIP712Domain as k, ACPUtils as l, getAclAddress as m, getAclServedAddresses as n, clearAclServedAddresses as o, type AclServedAddresses as p, type SealingKeyPair as q, type EthEncryptedData as r, seal as s, type ShareLabelReadArg as t, unsealWithPrivateKey as u, type LabelVerification as v, type ShareLabelVerifyMode as w, type ShareLabelCheck as x, verifyShareLabel as y, verifyShareLabels as z };