@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

package/dist/acps.cjs

@@ -14,9 +14,14 @@ var nacl__default = /*#__PURE__*/_interopDefault(nacl);
 // acps/acp.ts
 
 // acps/utils.ts
+var HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
 var fromHexString = (hexString) => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, "").match(/.{1,2}/g);
+  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)));
@@ -73,7 +78,7 @@ var GenerateSealingKey = () => {
 var seal = (value, publicKey) => {
   isString(publicKey);
   isBigIntOrNumber(value);
-  assertKeyLength(publicKey, "Public");
+  assertSealingKey(publicKey, "Public");
   const ephemeralKeyPair = nacl__default.default.box.keyPair();
   const nonce = nacl__default.default.randomBytes(nacl__default.default.box.nonceLength);
   const encryptedMessage = nacl__default.default.box(toBeArray(value), nonce, fromHexString(publicKey), ephemeralKeyPair.secretKey);
@@ -84,7 +89,7 @@ var seal = (value, publicKey) => {
   };
 };
 var unsealWithPrivateKey = (privateKey, parsedData) => {
-  assertKeyLength(privateKey, "Private");
+  assertSealingKey(privateKey, "Private");
   const nonce = parsedData.nonce instanceof Uint8Array ? parsedData.nonce : new Uint8Array(parsedData.nonce);
   const ephemPublicKey = parsedData.public_key instanceof Uint8Array ? parsedData.public_key : new Uint8Array(parsedData.public_key);
   const dataToDecrypt = parsedData.data instanceof Uint8Array ? parsedData.data : new Uint8Array(parsedData.data);
@@ -94,11 +99,14 @@ var unsealWithPrivateKey = (privateKey, parsedData) => {
   }
   return toBigInt(decryptedMessage);
 };
-var assertKeyLength = (key, kind) => {
+var assertSealingKey = (key, kind) => {
   const bare = key.startsWith("0x") ? key.slice(2) : key;
   if (bare.length !== KEY_HEX_LENGTH) {
     throw new Error(`${kind} key must be of length ${KEY_HEX_LENGTH}`);
   }
+  if (!/^[0-9a-fA-F]+$/.test(bare)) {
+    throw new Error(`${kind} key must contain only hex characters`);
+  }
 };
 var ACPScope = {
   Global: 0,
@@ -151,7 +159,8 @@ var zACPWithDefaults = zod.z.object({
   contracts: contractsSchema,
   handles: handlesSchema,
   issuerSignature: bytesSchema.optional().default("0x"),
-  recipientSignature: bytesSchema.optional().default("0x")
+  recipientSignature: bytesSchema.optional().default("0x"),
+  metadata: bytesSchema.optional()
 });
 var zACPWithSealingKeys = zACPWithDefaults.extend({
   /** X25519 private key, 0x-prefixed 32-byte hex; never leaves the client */
@@ -222,7 +231,6 @@ var ImportACPOptionsValidator = zod.z.object({
   type: zod.z.literal("recipient").optional().default("recipient"),
   issuer: addressNotZeroSchema,
   recipient: addressNotZeroSchema,
-  name: zod.z.string().optional().default("Unnamed ACP"),
   expiration: zod.z.int(),
   revokerData: zod.z.int().optional().default(0),
   revokerContract: addressSchema.optional().default(viem.zeroAddress),
@@ -230,7 +238,9 @@ var ImportACPOptionsValidator = zod.z.object({
   contracts: contractsSchema,
   handles: handlesSchema,
   issuerSignature: bytesNotEmptySchema,
-  recipientSignature: bytesSchema.optional().default("0x")
+  recipientSignature: bytesSchema.optional().default("0x"),
+  /** The share metadata (labels blob); `0x` means none and is dropped */
+  metadata: bytesSchema.optional().transform((val) => val === "0x" ? void 0 : val)
 }).refine(...ExternalValidatorRefinement).transform(withDerivedScope).refine(...ScopeConsistencyRefinement);
 var ImportACPValidator = zACPWithSealingKeys.refine((data) => data.type === "recipient", {
   error: "Type must be 'recipient'"
@@ -815,7 +825,210 @@ var getAclServedAddresses = async (publicClient, chainId) => {
   return resolved;
 };
 
+// acps/share-metadata/layout.ts
+var LAYOUT_VERSION = 3;
+var ENTRY_KIND = {
+  stored: 0,
+  event: 1,
+  unlabelled: 255
+};
+var ARGS_CODE = {
+  none: 0,
+  issuer: 1,
+  explicit: 255
+};
+var ARG_TAG = {
+  word: 0,
+  issuer: 1
+};
+var APP_KEY_TAG = 1;
+var BYTE_WIDTH = {
+  version: 1,
+  /** Length of a list, and a position in it: at most 255 of each per share. */
+  count: 1,
+  index: 1,
+  address: 20,
+  selector: 4,
+  /** uint32: 4.29 billion blocks. */
+  block: 4,
+  /** uint16: the position of a transaction within its block. */
+  txIndex: 2,
+  /** uint16: the block-wide position of a log (a busy block passes 255 logs). */
+  logIndex: 2,
+  kind: 1,
+  argsCode: 1,
+  returnWord: 1,
+  argTag: 1,
+  word: 32
+};
+
+// acps/share-metadata/encode.ts
+var uint = (value, width) => viem.numberToHex(value, { size: width });
+var BYTES_FIELD = {
+  contract: { width: BYTE_WIDTH.address, name: "a contract address" },
+  selector: { width: BYTE_WIDTH.selector, name: "a selector" },
+  viewCallArgument: { width: BYTE_WIDTH.word, name: "a view call argument" },
+  appKey: { width: BYTE_WIDTH.word, name: "an app key" }
+};
+var bytesField = (field, value) => {
+  const { width, name } = BYTES_FIELD[field];
+  if (!viem.isHex(value, { strict: true }) || viem.size(value) !== width) {
+    throw new Error(`share metadata: ${name} must be ${width} bytes`);
+  }
+  return value.toLowerCase();
+};
+var listOf = (keyOf, what) => {
+  const items = [];
+  const positions = /* @__PURE__ */ new Map();
+  const insert = (item) => {
+    const key = keyOf(item);
+    if (positions.has(key))
+      return;
+    positions.set(key, items.length);
+    items.push(item);
+  };
+  const positionOf = (item) => {
+    const position = positions.get(keyOf(item));
+    if (position === void 0)
+      throw new Error(`share metadata: ${what} ${keyOf(item)} was not collected`);
+    return position;
+  };
+  return { items, insert, positionOf };
+};
+var keyOfContract = (contract) => contract.toLowerCase();
+var keyOfSelector = (selector) => selector.toLowerCase();
+var keyOfTransaction = ({ block, txIndex }) => `${block}:${txIndex}`;
+var transactionOf = ({ block, txIndex }) => ({ block, txIndex });
+var encodeArg = (arg) => {
+  if (arg.type === "issuer")
+    return uint(ARG_TAG.issuer, BYTE_WIDTH.argTag);
+  return viem.concatHex([uint(ARG_TAG.word, BYTE_WIDTH.argTag), bytesField("viewCallArgument", arg.value)]);
+};
+var issuerWordOf = (issuer) => issuer == null ? void 0 : viem.padHex(issuer, { size: BYTE_WIDTH.word }).toLowerCase();
+var asIssuer = (arg, issuerWord) => arg.type === "word" && issuerWord != null && arg.value.toLowerCase() === issuerWord ? { type: "issuer" } : arg;
+var encodeArgs = ({ args: given, returnWord }, issuerWord) => {
+  const args = given.map((arg) => asIssuer(arg, issuerWord));
+  if (returnWord === 0 && args.length === 0)
+    return uint(ARGS_CODE.none, BYTE_WIDTH.argsCode);
+  if (returnWord === 0 && args.length === 1 && args[0].type === "issuer") {
+    return uint(ARGS_CODE.issuer, BYTE_WIDTH.argsCode);
+  }
+  return viem.concatHex([
+    uint(ARGS_CODE.explicit, BYTE_WIDTH.argsCode),
+    uint(returnWord, BYTE_WIDTH.returnWord),
+    uint(args.length, BYTE_WIDTH.count),
+    ...args.map(encodeArg)
+  ]);
+};
+var encodeShareMetadata = (labels, { issuer, appKey } = {}) => {
+  const issuerWord = issuerWordOf(issuer);
+  const contracts = listOf(keyOfContract, "contract");
+  const selectors = listOf(keyOfSelector, "selector");
+  const transactions = listOf(keyOfTransaction, "transaction");
+  for (const label of labels) {
+    if (label.kind === "unlabelled")
+      continue;
+    contracts.insert(label.contract);
+    selectors.insert(label.selector);
+    if (label.kind === "event")
+      transactions.insert(transactionOf(label));
+  }
+  const entries = labels.map((label) => {
+    switch (label.kind) {
+      case "stored":
+        return viem.concatHex([
+          uint(ENTRY_KIND.stored, BYTE_WIDTH.kind),
+          uint(contracts.positionOf(label.contract), BYTE_WIDTH.index),
+          uint(selectors.positionOf(label.selector), BYTE_WIDTH.index),
+          uint(label.block, BYTE_WIDTH.block),
+          encodeArgs(label, issuerWord)
+        ]);
+      case "event":
+        return viem.concatHex([
+          uint(ENTRY_KIND.event, BYTE_WIDTH.kind),
+          uint(contracts.positionOf(label.contract), BYTE_WIDTH.index),
+          uint(transactions.positionOf(transactionOf(label)), BYTE_WIDTH.index),
+          uint(label.logIndex, BYTE_WIDTH.logIndex),
+          uint(selectors.positionOf(label.selector), BYTE_WIDTH.index)
+        ]);
+      case "unlabelled":
+        return uint(ENTRY_KIND.unlabelled, BYTE_WIDTH.kind);
+    }
+  });
+  return viem.concatHex([
+    uint(LAYOUT_VERSION, BYTE_WIDTH.version),
+    uint(contracts.items.length, BYTE_WIDTH.count),
+    ...contracts.items.map((contract) => bytesField("contract", contract)),
+    uint(selectors.items.length, BYTE_WIDTH.count),
+    ...selectors.items.map((selector) => bytesField("selector", selector)),
+    uint(transactions.items.length, BYTE_WIDTH.count),
+    ...transactions.items.map(
+      (tx) => viem.concatHex([uint(tx.block, BYTE_WIDTH.block), uint(tx.txIndex, BYTE_WIDTH.txIndex)])
+    ),
+    ...entries,
+    ...appKey == null ? [] : [uint(APP_KEY_TAG, BYTE_WIDTH.count), bytesField("appKey", appKey)]
+  ]);
+};
+var findViewFunction = (abi, name, arity) => {
+  const named = abi.filter((item) => item.type === "function" && item.name === name);
+  if (named.length === 0)
+    throw new Error(`share metadata: the ABI has no function ${name}`);
+  const fitting = named.filter((fn2) => fn2.inputs.length === arity);
+  if (fitting.length !== 1) {
+    throw new Error(
+      named.length === 1 ? `share metadata: ${name} takes ${named[0].inputs.length} arguments, ${arity} given` : `share metadata: no single overload of ${name} takes ${arity} arguments`
+    );
+  }
+  const [fn] = fitting;
+  if (fn.stateMutability !== "view" && fn.stateMutability !== "pure") {
+    throw new Error(`share metadata: ${name} is not a view function`);
+  }
+  return fn;
+};
+var encodeReadArg = (fn, index, value) => {
+  const input = fn.inputs[index];
+  const word = viem.encodeAbiParameters([input], [value]);
+  if (viem.size(word) !== BYTE_WIDTH.word) {
+    throw new Error(
+      `share metadata: argument ${index} of ${fn.name} is ${input.type}; only arguments of one static 32-byte word can be labelled`
+    );
+  }
+  return { type: "word", value: word };
+};
+var viewFunctionLabel = (options) => {
+  const { contract, block, returnWord = 0 } = options;
+  const values = options.args ?? [];
+  const fn = findViewFunction(options.abi, options.functionName, values.length);
+  return {
+    kind: "stored",
+    contract,
+    selector: viem.toFunctionSelector(fn),
+    args: values.map((value, i) => encodeReadArg(fn, i, value)),
+    returnWord,
+    block
+  };
+};
+var eventLogLabel = (log) => {
+  const { address, blockNumber, transactionIndex, logIndex, topics } = log;
+  const topic0 = topics[0];
+  if (blockNumber == null || transactionIndex == null || logIndex == null) {
+    throw new Error("share metadata: a pending log has no position to label");
+  }
+  if (topic0 == null || viem.size(topic0) !== 32)
+    throw new Error("share metadata: an anonymous log has no event selector");
+  return {
+    kind: "event",
+    contract: address,
+    block: blockNumber,
+    txIndex: transactionIndex,
+    logIndex,
+    selector: viem.sliceHex(topic0, 0, 4)
+  };
+};
+var UNLABELLED = { kind: "unlabelled" };
+
 // acps/acp.ts
+var sharedByName = (issuer) => `Shared by ${issuer.slice(0, 6)}\u2026${issuer.slice(-4)}`;
 var ACPUtils = {
   /**
    * Create a self acp for personal use
@@ -837,10 +1050,16 @@ var ACPUtils = {
    */
   createSharing: (options) => {
     const validation = validateSharingACPOptions(options);
+    const { labels, appKey } = options;
+    if (labels != null && labels.length !== validation.handles.length) {
+      throw new Error(`Cannot label a share of ${validation.handles.length} handles with ${labels.length} labels`);
+    }
+    const metadata = labels != null || appKey != null ? encodeShareMetadata(labels ?? validation.handles.map(() => UNLABELLED), { issuer: validation.issuer, appKey }) : void 0;
     const sealingPair = GenerateSealingKey();
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      ...metadata != null && { metadata },
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: void 0
@@ -848,9 +1067,10 @@ var ACPUtils = {
     return acp;
   },
   /**
-   * 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) => {
+  importShared: (options, { name } = {}) => {
     let parsedOptions;
     if (typeof options === "string") {
       try {
@@ -871,6 +1091,7 @@ var ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      name: name?.trim() || sharedByName(validation.issuer),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: void 0
@@ -929,8 +1150,8 @@ var ACPUtils = {
   /**
    * Import and sign a shared acp in one operation from various input formats
    */
-  importSharedAndSign: async (options, publicClient, walletClient) => {
-    const acp = ACPUtils.importShared(options);
+  importSharedAndSign: async (options, publicClient, walletClient, importOptions = {}) => {
+    const acp = ACPUtils.importShared(options, importOptions);
     return ACPUtils.sign(acp, publicClient, walletClient);
   },
   /**
@@ -959,7 +1180,8 @@ var ACPUtils = {
       issuerSignature: acp.issuerSignature,
       recipientSignature: acp.recipientSignature,
       _signedDomain: acp._signedDomain,
-      sealingPrivateKey: acp.sealingPrivateKey
+      sealingPrivateKey: acp.sealingPrivateKey,
+      ...acp.metadata != null && { metadata: acp.metadata }
     };
   },
   /**
@@ -1033,7 +1255,7 @@ var 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) => {
     if (acp.type !== "sharing") {
@@ -1047,7 +1269,6 @@ var ACPUtils = {
       );
     }
     const shared = {
-      name: acp.name,
       type: acp.type,
       issuer: acp.issuer,
       expiration: acp.expiration,
@@ -1057,7 +1278,8 @@ var ACPUtils = {
       scope: acp.scope,
       contracts: acp.contracts,
       handles: acp.handles,
-      issuerSignature: acp.issuerSignature
+      issuerSignature: acp.issuerSignature,
+      ...acp.metadata != null && acp.metadata !== "0x" && { metadata: acp.metadata }
     };
     return JSON.stringify(shared, void 0, 2);
   },
@@ -1143,11 +1365,14 @@ var ACP_REVOKER_ABI = viem.parseAbi([
 ]);
 var ACP_SHARE_REGISTRY_ABI = viem.parseAbi([
   "struct ACP { address issuer; uint64 expiration; address recipient; uint256 revokerData; address revokerContract; uint8 scope; address[] contracts; bytes32[] handles; bytes32 sealingKey; bytes issuerSignature; bytes recipientSignature; }",
-  "function share(ACP calldata acp) external returns (bytes32)",
+  "struct ShareHeader { address issuer; uint64 expiration; address recipient; uint64 blockNumber; address revokerContract; uint256 revokerData; }",
+  "function share(ACP calldata acp, bytes calldata metadata) external returns (bytes32)",
   "function removeShare(bytes32 shareId) external",
-  "function sharesFor(address recipient) external view returns (ACP[] memory)",
-  "function getShare(bytes32 shareId) external view returns (ACP memory)",
-  "function isShareValid(bytes32 shareId) external view returns (bool)"
+  "function sharesFor(address recipient) external view returns (bytes32[] shareIds, ShareHeader[] headers)",
+  "function getShare(bytes32 shareId) external view returns (ShareHeader memory)",
+  "function isShareValid(bytes32 shareId) external view returns (bool)",
+  "event Shared(address indexed recipient, address indexed issuer, bytes32 indexed shareId, ACP acp, bytes metadata)",
+  "event ShareRemoved(address indexed recipient, address indexed issuer, bytes32 indexed shareId)"
 ]);
 var ACP_SHARE_TUPLE_ABI = [
   {
@@ -1183,11 +1408,393 @@ var computeShareId = (acp) => {
   return viem.keccak256(viem.encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [p]));
 };
 var shareIdOfChainShare = (share) => viem.keccak256(viem.encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [share]));
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+var readPostedShares = async (publicClient, registry, headers) => {
+  const idsByBlock = /* @__PURE__ */ new Map();
+  for (const { shareId, header } of headers) {
+    idsByBlock.set(header.blockNumber, [...idsByBlock.get(header.blockNumber) ?? [], shareId]);
+  }
+  const found = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...idsByBlock].map(async ([block, shareIds]) => {
+      let logs;
+      try {
+        logs = await publicClient.getContractEvents({
+          address: registry,
+          abi: ACP_SHARE_REGISTRY_ABI,
+          eventName: "Shared",
+          args: { shareId: shareIds },
+          fromBlock: block,
+          toBlock: block,
+          strict: true
+        });
+      } catch (error) {
+        for (const shareId of shareIds) {
+          found.set(shareId.toLowerCase(), {
+            reason: `the Shared events of block ${block} could not be read: ${messageOf(error)}`
+          });
+        }
+        return;
+      }
+      for (const { args } of logs) {
+        const hashes = shareIdOfChainShare(args.acp).toLowerCase() === args.shareId.toLowerCase();
+        found.set(
+          args.shareId.toLowerCase(),
+          hashes ? { share: args.acp, metadata: args.metadata } : { reason: "the payload in its Shared event does not hash to its id" }
+        );
+      }
+    })
+  );
+  const result = { posted: [], unreadable: [] };
+  for (const { shareId, header } of headers) {
+    const entry = found.get(shareId.toLowerCase());
+    if (entry == null) {
+      result.unreadable.push({
+        shareId,
+        header,
+        reason: `no Shared event in block ${header.blockNumber}, where the registry points`
+      });
+    } else if ("reason" in entry) {
+      result.unreadable.push({ shareId, header, reason: entry.reason });
+    } else {
+      result.posted.push({ shareId, header, ...entry });
+    }
+  }
+  return result;
+};
+var readSharesFor = async (publicClient, registry, recipient) => {
+  const [shareIds, headers] = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: "sharesFor",
+    args: [recipient]
+  });
+  return readPostedShares(
+    publicClient,
+    registry,
+    shareIds.map((shareId, i) => ({ shareId, header: headers[i] }))
+  );
+};
+var readShare = async (publicClient, registry, shareId) => {
+  const header = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: "getShare",
+    args: [shareId]
+  });
+  if (header.issuer === "0x0000000000000000000000000000000000000000")
+    return null;
+  const { posted, unreadable } = await readPostedShares(publicClient, registry, [{ shareId, header }]);
+  if (unreadable.length > 0)
+    throw new Error(`Share ${shareId}: ${unreadable[0].reason}`);
+  return posted[0];
+};
+var readerOf = (blob) => {
+  let offset = 0;
+  const take = (width) => {
+    if (offset + width > viem.size(blob))
+      throw new Error("share metadata: the blob ends in the middle of a field");
+    offset += width;
+    return viem.sliceHex(blob, offset - width, offset);
+  };
+  return {
+    take,
+    takeNumber: (width) => viem.hexToNumber(take(width)),
+    done: () => offset === viem.size(blob),
+    remaining: () => viem.size(blob) - offset
+  };
+};
+var takeList = (reader, takeItem) => Array.from({ length: reader.takeNumber(BYTE_WIDTH.count) }, takeItem);
+var takeFrom = (reader, list, what) => {
+  const position = reader.takeNumber(BYTE_WIDTH.index);
+  if (position >= list.length) {
+    throw new Error(`share metadata: ${what} ${position} is outside the ${what} list`);
+  }
+  return list[position];
+};
+var decodeArg = (reader) => {
+  const tag = reader.takeNumber(BYTE_WIDTH.argTag);
+  if (tag === ARG_TAG.issuer)
+    return { type: "issuer" };
+  if (tag === ARG_TAG.word)
+    return { type: "word", value: reader.take(BYTE_WIDTH.word) };
+  throw new Error(`share metadata: unknown argument tag ${tag}`);
+};
+var decodeArgs = (reader) => {
+  const code = reader.takeNumber(BYTE_WIDTH.argsCode);
+  if (code === ARGS_CODE.none)
+    return { args: [], returnWord: 0 };
+  if (code === ARGS_CODE.issuer)
+    return { args: [{ type: "issuer" }], returnWord: 0 };
+  if (code !== ARGS_CODE.explicit)
+    throw new Error(`share metadata: unknown args code ${code}`);
+  const returnWord = reader.takeNumber(BYTE_WIDTH.returnWord);
+  return { args: takeList(reader, () => decodeArg(reader)), returnWord };
+};
+var takeAppKey = (reader) => {
+  if (reader.done())
+    return void 0;
+  const isKey = reader.remaining() === BYTE_WIDTH.count + BYTE_WIDTH.word && reader.takeNumber(BYTE_WIDTH.count) === APP_KEY_TAG;
+  if (!isKey)
+    throw new Error("share metadata: the blob has more entries than the share has ctHashes");
+  return reader.take(BYTE_WIDTH.word);
+};
+var decodeShareMetadataFull = (blob, handles) => {
+  const reader = readerOf(blob);
+  const version = reader.takeNumber(BYTE_WIDTH.version);
+  if (version !== LAYOUT_VERSION)
+    throw new Error(`share metadata: unsupported version ${version}`);
+  const contracts = takeList(reader, () => viem.getAddress(reader.take(BYTE_WIDTH.address)));
+  const selectors = takeList(reader, () => reader.take(BYTE_WIDTH.selector));
+  const transactions = takeList(reader, () => ({
+    block: viem.hexToBigInt(reader.take(BYTE_WIDTH.block)),
+    txIndex: reader.takeNumber(BYTE_WIDTH.txIndex)
+  }));
+  const labels = handles.map(() => {
+    const kind = reader.takeNumber(BYTE_WIDTH.kind);
+    switch (kind) {
+      case ENTRY_KIND.stored: {
+        const contract = takeFrom(reader, contracts, "contract");
+        const selector = takeFrom(reader, selectors, "selector");
+        const block = viem.hexToBigInt(reader.take(BYTE_WIDTH.block));
+        return { kind: "stored", contract, selector, ...decodeArgs(reader), block };
+      }
+      case ENTRY_KIND.event: {
+        const contract = takeFrom(reader, contracts, "contract");
+        const { block, txIndex } = takeFrom(reader, transactions, "transaction");
+        const logIndex = reader.takeNumber(BYTE_WIDTH.logIndex);
+        const selector = takeFrom(reader, selectors, "selector");
+        return { kind: "event", contract, block, txIndex, logIndex, selector };
+      }
+      case ENTRY_KIND.unlabelled:
+        return { kind: "unlabelled" };
+      default:
+        throw new Error(`share metadata: unknown entry kind ${kind}`);
+    }
+  });
+  const appKey = takeAppKey(reader);
+  if (!reader.done())
+    throw new Error("share metadata: the blob has more entries than the share has ctHashes");
+  return { labels, appKey };
+};
+var decodeShareMetadata = (blob, handles) => decodeShareMetadataFull(blob, handles).labels;
+var decodeShareAppKey = (metadata, handles) => metadata == null || metadata === "0x" ? void 0 : decodeShareMetadataFull(metadata, handles).appKey;
+var sameWord = (a, b) => a.toLowerCase() === b.toLowerCase();
+var wordsOf = (data) => {
+  const count = Math.floor(viem.size(data) / BYTE_WIDTH.word);
+  return Array.from(
+    { length: count },
+    (_, index) => viem.sliceHex(data, index * BYTE_WIDTH.word, (index + 1) * BYTE_WIDTH.word)
+  );
+};
+var storedCallData = (label, issuer) => viem.concatHex([
+  label.selector,
+  ...label.args.map((arg) => arg.type === "issuer" ? viem.padHex(issuer, { size: BYTE_WIDTH.word }) : arg.value)
+]);
+var checkStored = (label, handle, data) => {
+  const found = data ? wordsOf(data)[label.returnWord] : void 0;
+  return found && sameWord(found, handle) ? "verified" : "mismatch";
+};
+var checkEvent = (label, handle, logs) => {
+  const log = logs.find((l) => l.logIndex === label.logIndex);
+  if (log == null)
+    return "mismatch";
+  if (log.transactionIndex !== label.txIndex)
+    return "mismatch";
+  const topic0 = log.topics[0];
+  if (topic0 == null || !topic0.toLowerCase().startsWith(label.selector.toLowerCase()))
+    return "mismatch";
+  const carried = [...log.topics.slice(1), ...wordsOf(log.data)].some((word) => word != null && sameWord(word, handle));
+  return carried ? "verified" : "mismatch";
+};
+var callAt = async (publicClient, to, data, blockNumber) => (await publicClient.call({ to, data, blockNumber })).data;
+var logsAt = (publicClient, address, block) => publicClient.getLogs({ address, fromBlock: block, toBlock: block });
+var verifyShareLabel = async (label, handle, publicClient, issuer) => {
+  try {
+    switch (label.kind) {
+      case "stored":
+        return checkStored(
+          label,
+          handle,
+          await callAt(publicClient, label.contract, storedCallData(label, issuer), label.block)
+        );
+      case "event":
+        return checkEvent(label, handle, await logsAt(publicClient, label.contract, label.block));
+      case "unlabelled":
+        return "unverifiable";
+    }
+  } catch {
+    return "unverifiable";
+  }
+};
+var verifyShareLabels = async ({
+  labels,
+  handles,
+  issuer,
+  publicClient,
+  verify = "all"
+}) => {
+  if (labels.length !== handles.length) {
+    throw new Error(`share metadata: ${labels.length} labels for ${handles.length} ctHashes`);
+  }
+  const requests = /* @__PURE__ */ new Map();
+  const once = (key, request) => {
+    if (!requests.has(key))
+      requests.set(key, request());
+    return requests.get(key);
+  };
+  return Promise.all(
+    labels.map(async (label, i) => {
+      const handle = handles[i];
+      try {
+        switch (label.kind) {
+          case "stored": {
+            if (verify !== "all")
+              return "skipped";
+            const data = storedCallData(label, issuer);
+            const key = `call:${label.contract.toLowerCase()}:${label.block}:${data}`;
+            return checkStored(
+              label,
+              handle,
+              await once(key, () => callAt(publicClient, label.contract, data, label.block))
+            );
+          }
+          case "event": {
+            if (verify === "none")
+              return "skipped";
+            const key = `logs:${label.contract.toLowerCase()}:${label.block}`;
+            return checkEvent(label, handle, await once(key, () => logsAt(publicClient, label.contract, label.block)));
+          }
+          case "unlabelled":
+            return verify === "none" ? "skipped" : "unverifiable";
+        }
+      } catch {
+        return "unverifiable";
+      }
+    })
+  );
+};
+var abiOf = (abis, contract) => {
+  const wanted = contract.toLowerCase();
+  const key = Object.keys(abis).find((address) => address.toLowerCase() === wanted);
+  return key ? abis[key] : void 0;
+};
+var paramOf = ({ name, type, ...rest }) => {
+  const param = { type };
+  if (name)
+    param.name = name;
+  if ("indexed" in rest && typeof rest.indexed === "boolean")
+    param.indexed = rest.indexed;
+  return param;
+};
+var findFunction = (abi, selector) => abi?.find(
+  (item) => item.type === "function" && viem.toFunctionSelector(item).toLowerCase() === selector.toLowerCase()
+);
+var findEvent = (abi, selector) => abi?.find(
+  (item) => item.type === "event" && viem.toEventSelector(item).toLowerCase().startsWith(selector.toLowerCase())
+);
+var decodeWord = (input, raw) => {
+  if (input == null)
+    return raw;
+  try {
+    return viem.decodeAbiParameters([input], raw)[0];
+  } catch {
+    return raw;
+  }
+};
+var describeStored = (base, label, abis, issuer) => {
+  const fn = findFunction(abiOf(abis, label.contract), label.selector);
+  const args = label.args.map((arg, i) => {
+    const input = fn?.inputs[i];
+    const param = input ? paramOf(input) : { type: "bytes32" };
+    if (arg.type === "issuer") {
+      return {
+        ...param,
+        isIssuer: true,
+        raw: issuer ? viem.padHex(issuer, { size: 32 }) : void 0,
+        value: issuer
+      };
+    }
+    return { ...param, isIssuer: false, raw: arg.value, value: decodeWord(input, arg.value) };
+  });
+  const output = fn?.outputs[label.returnWord];
+  return {
+    ...base,
+    kind: "stored",
+    label,
+    contract: label.contract,
+    block: label.block,
+    selector: label.selector,
+    function: fn ? { name: fn.name, signature: viem.toFunctionSignature(fn), inputs: fn.inputs.map(paramOf) } : null,
+    args,
+    output: output ? paramOf(output) : null
+  };
+};
+var describeEvent = (base, label, abis) => {
+  const event = findEvent(abiOf(abis, label.contract), label.selector);
+  return {
+    ...base,
+    kind: "event",
+    label,
+    contract: label.contract,
+    block: label.block,
+    txIndex: label.txIndex,
+    logIndex: label.logIndex,
+    selector: label.selector,
+    event: event ? { name: event.name, signature: viem.toEventSignature(event), inputs: event.inputs.map(paramOf) } : null
+  };
+};
+var describeShareLabels = (labels, handles, abis = {}, options = {}) => labels.map((label, index) => {
+  const base = { index, handle: handles[index] };
+  switch (label.kind) {
+    case "stored":
+      return describeStored(base, label, abis, options.issuer);
+    case "event":
+      return describeEvent(base, label, abis);
+    case "unlabelled":
+      return { ...base, kind: "unlabelled", label };
+  }
+});
+var describeShareMetadata = (share, abis = {}) => {
+  const { issuer, handles, metadata } = share;
+  if (metadata == null || metadata === "0x")
+    return null;
+  return describeShareLabels(decodeShareMetadata(metadata, handles), handles, abis, { issuer });
+};
+
+// acps/share-metadata/erc7984.ts
+var ERC7984_ABI = [
+  {
+    type: "function",
+    name: "confidentialBalanceOf",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address", internalType: "address" }],
+    outputs: [{ name: "", type: "bytes32", internalType: "euint64" }]
+  },
+  {
+    type: "event",
+    name: "ConfidentialTransfer",
+    anonymous: false,
+    inputs: [
+      { name: "from", type: "address", indexed: true, internalType: "address" },
+      { name: "to", type: "address", indexed: true, internalType: "address" },
+      { name: "amount", type: "bytes32", indexed: true, internalType: "euint64" }
+    ]
+  }
+];
+var shareAppKey = (app) => viem.keccak256(viem.stringToHex(app));
 var ACP_STORE_DEFAULTS = {
   acps: {},
   activeACPHash: {}
 };
 var ACP_STORE_VERSION = 3;
+var isRecord = (value) => value != null && typeof value === "object" && !Array.isArray(value);
+var resolveAccountKey = (records, account) => {
+  if (records == null || account in records)
+    return account;
+  const lower = account.toLowerCase();
+  return Object.keys(records).find((key) => key.toLowerCase() === lower) ?? account;
+};
 var _acpStore = vanilla.createStore()(
   middleware.persist(() => ACP_STORE_DEFAULTS, {
     name: "cofhesdk-acps",
@@ -1196,12 +1803,23 @@ var _acpStore = vanilla.createStore()(
       if (version < ACP_STORE_VERSION)
         return ACP_STORE_DEFAULTS;
       return persistedState;
+    },
+    // Runs on every rehydrate, including a corrupt state saved at the current version that
+    // `migrate` passes through unchanged. Consumers that read the raw snapshot (e.g. the React
+    // hooks) never go through `clearStaleStore`, so the shape has to be fixed here.
+    merge: (persistedState, currentState) => {
+      const persisted = isRecord(persistedState) ? persistedState : {};
+      return {
+        ...currentState,
+        acps: isRecord(persisted.acps) ? persisted.acps : currentState.acps,
+        activeACPHash: isRecord(persisted.activeACPHash) ? persisted.activeACPHash : currentState.activeACPHash
+      };
     }
   })
 );
 var clearStaleStore = () => {
   const state = _acpStore.getState();
-  const hasExpectedStructure = state && typeof state === "object" && "acps" in state && "activeACPHash" in state && typeof state.acps === "object" && typeof state.activeACPHash === "object";
+  const hasExpectedStructure = isRecord(state) && isRecord(state.acps) && isRecord(state.activeACPHash);
   if (hasExpectedStructure)
     return;
   _acpStore.setState({ acps: {}, activeACPHash: {} });
@@ -1210,7 +1828,8 @@ var getACP = (chainId, account, hash) => {
   clearStaleStore();
   if (chainId == null || account == null || hash == null)
     return;
-  const savedACP = _acpStore.getState().acps[chainId]?.[account]?.[hash];
+  const accountACPs = _acpStore.getState().acps[chainId];
+  const savedACP = accountACPs?.[resolveAccountKey(accountACPs, account)]?.[hash];
   if (savedACP == null)
     return;
   return ACPUtils.deserialize(savedACP);
@@ -1219,14 +1838,16 @@ var getActiveACP = (chainId, account) => {
   clearStaleStore();
   if (chainId == null || account == null)
     return;
-  const activeACPHash = _acpStore.getState().activeACPHash[chainId]?.[account];
+  const activeHashes = _acpStore.getState().activeACPHash[chainId];
+  const activeACPHash = activeHashes?.[resolveAccountKey(activeHashes, account)];
   return getACP(chainId, account, activeACPHash);
 };
 var getACPs = (chainId, account) => {
   clearStaleStore();
   if (chainId == null || account == null)
     return {};
-  return Object.entries(_acpStore.getState().acps[chainId]?.[account] ?? {}).reduce(
+  const accountACPs = _acpStore.getState().acps[chainId];
+  return Object.entries(accountACPs?.[resolveAccountKey(accountACPs, account)] ?? {}).reduce(
     (acc, [hash, acp]) => {
       if (acp == void 0)
         return acc;
@@ -1241,9 +1862,10 @@ var setACP = (chainId, account, acp) => {
     immer.produce((state) => {
       if (state.acps[chainId] == null)
         state.acps[chainId] = {};
-      if (state.acps[chainId][account] == null)
-        state.acps[chainId][account] = {};
-      state.acps[chainId][account][acp.hash] = ACPUtils.serialize(acp);
+      const key = resolveAccountKey(state.acps[chainId], account);
+      if (state.acps[chainId][key] == null)
+        state.acps[chainId][key] = {};
+      state.acps[chainId][key][acp.hash] = ACPUtils.serialize(acp);
     })
   );
 };
@@ -1255,13 +1877,14 @@ var removeACP = (chainId, account, hash) => {
         state.acps[chainId] = {};
       if (state.activeACPHash[chainId] == null)
         state.activeACPHash[chainId] = {};
-      const accountACPs = state.acps[chainId][account];
+      const accountACPs = state.acps[chainId][resolveAccountKey(state.acps[chainId], account)];
       if (accountACPs == null)
         return;
       if (accountACPs[hash] == null)
         return;
-      if (state.activeACPHash[chainId][account] === hash) {
-        state.activeACPHash[chainId][account] = void 0;
+      const activeKey = resolveAccountKey(state.activeACPHash[chainId], account);
+      if (state.activeACPHash[chainId][activeKey] === hash) {
+        state.activeACPHash[chainId][activeKey] = void 0;
       }
       accountACPs[hash] = void 0;
     })
@@ -1271,7 +1894,8 @@ var getActiveACPHash = (chainId, account) => {
   clearStaleStore();
   if (chainId == null || account == null)
     return void 0;
-  return _acpStore.getState().activeACPHash[chainId]?.[account];
+  const activeHashes = _acpStore.getState().activeACPHash[chainId];
+  return activeHashes?.[resolveAccountKey(activeHashes, account)];
 };
 var setActiveACPHash = (chainId, account, hash) => {
   clearStaleStore();
@@ -1279,7 +1903,7 @@ var setActiveACPHash = (chainId, account, hash) => {
     immer.produce((state) => {
       if (state.activeACPHash[chainId] == null)
         state.activeACPHash[chainId] = {};
-      state.activeACPHash[chainId][account] = hash;
+      state.activeACPHash[chainId][resolveAccountKey(state.activeACPHash[chainId], account)] = hash;
     })
   );
 };
@@ -1288,7 +1912,7 @@ var removeActiveACPHash = (chainId, account) => {
   _acpStore.setState(
     immer.produce((state) => {
       if (state.activeACPHash[chainId])
-        state.activeACPHash[chainId][account] = void 0;
+        state.activeACPHash[chainId][resolveAccountKey(state.activeACPHash[chainId], account)] = void 0;
     })
   );
 };
@@ -1315,15 +1939,18 @@ exports.ACP_REVOKER_ABI = ACP_REVOKER_ABI;
 exports.ACP_SHARE_REGISTRY_ABI = ACP_SHARE_REGISTRY_ABI;
 exports.ACP_SHARE_TUPLE_ABI = ACP_SHARE_TUPLE_ABI;
 exports.ACP_STORE_DEFAULTS = ACP_STORE_DEFAULTS;
+exports.ERC7984_ABI = ERC7984_ABI;
 exports.GenerateSealingKey = GenerateSealingKey;
 exports.ImportACPOptionsValidator = ImportACPOptionsValidator;
 exports.ImportACPValidator = ImportACPValidator;
+exports.SHARE_METADATA_VERSION = LAYOUT_VERSION;
 exports.SelfACPOptionsValidator = SelfACPOptionsValidator;
 exports.SelfACPValidator = SelfACPValidator;
 exports.SharingACPOptionsValidator = SharingACPOptionsValidator;
 exports.SharingACPValidator = SharingACPValidator;
 exports.SignatureTypes = SignatureTypes;
 exports.SignatureUtils = SignatureUtils;
+exports.UNLABELLED = UNLABELLED;
 exports.ValidationUtils = ValidationUtils;
 exports._acpStore = _acpStore;
 exports.acpStore = acpStore;
@@ -1335,6 +1962,13 @@ exports.clearAclServedAddresses = clearAclServedAddresses;
 exports.clearStaleStore = clearStaleStore;
 exports.computeShareId = computeShareId;
 exports.contractsSchema = contractsSchema;
+exports.decodeShareAppKey = decodeShareAppKey;
+exports.decodeShareMetadata = decodeShareMetadata;
+exports.decodeShareMetadataFull = decodeShareMetadataFull;
+exports.describeShareLabels = describeShareLabels;
+exports.describeShareMetadata = describeShareMetadata;
+exports.encodeShareMetadata = encodeShareMetadata;
+exports.eventLogLabel = eventLogLabel;
 exports.getACP = getACP;
 exports.getACPs = getACPs;
 exports.getAclAddress = getAclAddress;
@@ -1343,12 +1977,16 @@ exports.getActiveACP = getActiveACP;
 exports.getActiveACPHash = getActiveACPHash;
 exports.getSignatureTypesAndMessage = getSignatureTypesAndMessage;
 exports.handlesSchema = handlesSchema;
+exports.readPostedShares = readPostedShares;
+exports.readShare = readShare;
+exports.readSharesFor = readSharesFor;
 exports.removeACP = removeACP;
 exports.removeActiveACPHash = removeActiveACPHash;
 exports.resetStore = resetStore;
 exports.seal = seal;
 exports.setACP = setACP;
 exports.setActiveACPHash = setActiveACPHash;
+exports.shareAppKey = shareAppKey;
 exports.shareIdOfChainShare = shareIdOfChainShare;
 exports.toChainShare = toChainShare;
 exports.unsealWithPrivateKey = unsealWithPrivateKey;
@@ -1358,3 +1996,6 @@ exports.validateSelfACP = validateSelfACP;
 exports.validateSelfACPOptions = validateSelfACPOptions;
 exports.validateSharingACP = validateSharingACP;
 exports.validateSharingACPOptions = validateSharingACPOptions;
+exports.verifyShareLabel = verifyShareLabel;
+exports.verifyShareLabels = verifyShareLabels;
+exports.viewFunctionLabel = viewFunctionLabel;