@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

package/acps/share-metadata/test/verify.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest';
+import { concatHex, padHex, type Hex, type Log, type PublicClient } from 'viem';
+import { verifyShareLabel, verifyShareLabels } from '../verify';
+import type { ShareLabel } from '../schema';
+import { BALANCE_OF, CONFIDENTIAL_TRANSFER, CONFIDENTIAL_TRANSFER_TOPIC0, FUSD, FUSDY, ISSUER } from './fixtures';
+
+const AMOUNT = `0x${'11'.repeat(32)}` as Hex;
+const BALANCE = `0x${'22'.repeat(32)}` as Hex;
+const OTHER = `0x${'33'.repeat(32)}` as Hex;
+const ALICE = padHex('0xa11ce', { size: 32 });
+
+const transferLog = (overrides: Partial<Log> = {}): Log =>
+  ({
+    address: FUSD,
+    blockNumber: 100n,
+    transactionIndex: 3,
+    logIndex: 9,
+    topics: [CONFIDENTIAL_TRANSFER_TOPIC0, ALICE, ALICE, AMOUNT],
+    data: '0x',
+    ...overrides,
+  }) as Log;
+
+const eventLabel = (overrides: Partial<ShareLabel & { kind: 'event' }> = {}): ShareLabel => ({
+  kind: 'event',
+  contract: FUSD,
+  block: 100n,
+  txIndex: 3,
+  logIndex: 9,
+  selector: CONFIDENTIAL_TRANSFER,
+  ...overrides,
+});
+
+const balanceLabel: ShareLabel = {
+  kind: 'stored',
+  contract: FUSDY,
+  selector: BALANCE_OF,
+  args: [{ type: 'issuer' }],
+  returnWord: 0,
+  block: 90n,
+};
+
+const clientWith = ({ logs = [transferLog()], callResult = BALANCE }: { logs?: Log[]; callResult?: Hex } = {}) => {
+  const getLogs = vi.fn(async () => logs);
+  const call = vi.fn(async () => ({ data: callResult }));
+  return { client: { getLogs, call } as unknown as PublicClient, getLogs, call };
+};
+
+describe('verifyShareLabel', () => {
+  it('verifies an event value at its log index', async () => {
+    const { client, getLogs } = clientWith();
+    expect(await verifyShareLabel(eventLabel(), AMOUNT, client, ISSUER)).toBe('verified');
+    expect(getLogs).toHaveBeenCalledWith({ address: FUSD, fromBlock: 100n, toBlock: 100n });
+  });
+
+  it('finds the ctHash among the data words too', async () => {
+    const { client } = clientWith({
+      logs: [transferLog({ topics: [CONFIDENTIAL_TRANSFER_TOPIC0], data: concatHex([OTHER, AMOUNT]) })],
+    });
+    expect(await verifyShareLabel(eventLabel(), AMOUNT, client, ISSUER)).toBe('verified');
+  });
+
+  it.each([
+    ['another log index', eventLabel({ logIndex: 8 })],
+    ['another transaction', eventLabel({ txIndex: 4 })],
+    ['another event selector', eventLabel({ selector: '0xddf252ad' })],
+  ])('rejects an event value naming %s', async (_, label) => {
+    const { client } = clientWith();
+    expect(await verifyShareLabel(label, AMOUNT, client, ISSUER)).toBe('mismatch');
+  });
+
+  it('rejects an event value whose log does not carry the ctHash', async () => {
+    const { client } = clientWith();
+    expect(await verifyShareLabel(eventLabel(), OTHER, client, ISSUER)).toBe('mismatch');
+  });
+
+  it('verifies a stored value by repeating the call with the issuer at the labelled block', async () => {
+    const { client, call } = clientWith();
+    expect(await verifyShareLabel(balanceLabel, BALANCE, client, ISSUER)).toBe('verified');
+    expect(call).toHaveBeenCalledWith({
+      to: FUSDY,
+      data: concatHex([BALANCE_OF, padHex(ISSUER, { size: 32 })]),
+      blockNumber: 90n,
+    });
+  });
+
+  it('rejects a stored value the call does not return', async () => {
+    const { client } = clientWith({ callResult: OTHER });
+    expect(await verifyShareLabel(balanceLabel, BALANCE, client, ISSUER)).toBe('mismatch');
+  });
+
+  it('reports a failed request, and an unlabelled value, as unverifiable', async () => {
+    const client = { call: vi.fn().mockRejectedValue(new Error('missing trie node')) } as unknown as PublicClient;
+    expect(await verifyShareLabel(balanceLabel, BALANCE, client, ISSUER)).toBe('unverifiable');
+    expect(await verifyShareLabel({ kind: 'unlabelled' }, BALANCE, client, ISSUER)).toBe('unverifiable');
+  });
+});
+
+describe('verifyShareLabels', () => {
+  const labels: ShareLabel[] = [balanceLabel, eventLabel(), eventLabel({ logIndex: 10 }), { kind: 'unlabelled' }];
+  const handles = [BALANCE, AMOUNT, OTHER, OTHER];
+  const logs = [
+    transferLog(),
+    transferLog({ logIndex: 10, topics: [CONFIDENTIAL_TRANSFER_TOPIC0, ALICE, ALICE, OTHER] }),
+  ];
+
+  it("checks everything with 'all', one getLogs per contract and block", async () => {
+    const { client, getLogs, call } = clientWith({ logs });
+    expect(await verifyShareLabels({ labels, handles, issuer: ISSUER, publicClient: client })).toEqual([
+      'verified',
+      'verified',
+      'verified',
+      'unverifiable',
+    ]);
+    expect(getLogs).toHaveBeenCalledTimes(1);
+    expect(call).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips stored values with 'events'", async () => {
+    const { client, call } = clientWith({ logs });
+    expect(
+      await verifyShareLabels({ labels, handles, issuer: ISSUER, publicClient: client, verify: 'events' })
+    ).toEqual(['skipped', 'verified', 'verified', 'unverifiable']);
+    expect(call).not.toHaveBeenCalled();
+  });
+
+  it("makes no request with 'none'", async () => {
+    const { client, call, getLogs } = clientWith({ logs });
+    expect(await verifyShareLabels({ labels, handles, issuer: ISSUER, publicClient: client, verify: 'none' })).toEqual([
+      'skipped',
+      'skipped',
+      'skipped',
+      'skipped',
+    ]);
+    expect(call).not.toHaveBeenCalled();
+    expect(getLogs).not.toHaveBeenCalled();
+  });
+
+  it('refuses labels that do not match the handles one for one', async () => {
+    const { client } = clientWith();
+    await expect(
+      verifyShareLabels({ labels, handles: [BALANCE], issuer: ISSUER, publicClient: client })
+    ).rejects.toThrow('4 labels for 1 ctHashes');
+  });
+});

package/acps/share-metadata/verify.ts

@@ -0,0 +1,155 @@
+import { concatHex, padHex, size, sliceHex, type Address, type Hex, type Log, type PublicClient } from 'viem';
+import { BYTE_WIDTH } from './layout';
+import type { EventValueLabel, ShareLabel, StoredValueLabel } from './schema.js';
+
+/**
+ * - `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.
+ */
+export 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).
+ */
+export type ShareLabelVerifyMode = 'all' | 'events' | 'none';
+
+/** A label's verification, or `skipped` when the verify mode leaves it unchecked. */
+export type ShareLabelCheck = LabelVerification | 'skipped';
+
+const sameWord = (a: Hex, b: Hex): boolean => a.toLowerCase() === b.toLowerCase();
+
+/** The 32-byte words of a byte string, in order. A trailing partial word is left out. */
+const wordsOf = (data: Hex): Hex[] => {
+  const count = Math.floor(size(data) / BYTE_WIDTH.word);
+  return Array.from({ length: count }, (_, index) =>
+    sliceHex(data, index * BYTE_WIDTH.word, (index + 1) * BYTE_WIDTH.word)
+  );
+};
+
+/** The view call a stored-value label names, with the issuer argument filled in. */
+const storedCallData = (label: StoredValueLabel, issuer: Address): Hex =>
+  concatHex([
+    label.selector,
+    ...label.args.map((arg) => (arg.type === 'issuer' ? padHex(issuer, { size: BYTE_WIDTH.word }) : arg.value)),
+  ]);
+
+/** Whether the ctHash is the labelled return word of the call's result. */
+const checkStored = (label: StoredValueLabel, handle: Hex, data: Hex | undefined): LabelVerification => {
+  const found = data ? wordsOf(data)[label.returnWord] : undefined;
+  return found && sameWord(found, handle) ? 'verified' : 'mismatch';
+};
+
+/**
+ * Whether the labelled log is there and carries the ctHash: among the logs of the contract in the
+ * labelled block, the one at the labelled log index must belong to the labelled transaction, its
+ * topic0 must start with the labelled selector, and the ctHash must be one of its topics or data
+ * words.
+ */
+const checkEvent = (label: EventValueLabel, handle: Hex, logs: readonly Log[]): LabelVerification => {
+  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';
+};
+
+const callAt = async (publicClient: PublicClient, to: Address, data: Hex, blockNumber: bigint) =>
+  (await publicClient.call({ to, data, blockNumber })).data;
+
+const logsAt = (publicClient: PublicClient, address: Address, block: bigint) =>
+  publicClient.getLogs({ address, fromBlock: block, toBlock: block });
+
+/**
+ * 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.
+ */
+export const verifyShareLabel = async (
+  label: ShareLabel,
+  handle: Hex,
+  publicClient: PublicClient,
+  issuer: Address
+): Promise<LabelVerification> => {
+  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';
+  }
+};
+
+/**
+ * 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.
+ */
+export const verifyShareLabels = async ({
+  labels,
+  handles,
+  issuer,
+  publicClient,
+  verify = 'all',
+}: {
+  labels: readonly ShareLabel[];
+  handles: readonly Hex[];
+  issuer: Address;
+  publicClient: PublicClient;
+  verify?: ShareLabelVerifyMode;
+}): Promise<ShareLabelCheck[]> => {
+  if (labels.length !== handles.length) {
+    throw new Error(`share metadata: ${labels.length} labels for ${handles.length} ctHashes`);
+  }
+
+  const requests = new Map<string, Promise<unknown>>();
+  const once = <T>(key: string, request: () => Promise<T>): Promise<T> => {
+    if (!requests.has(key)) requests.set(key, request());
+    return requests.get(key) as Promise<T>;
+  };
+
+  return Promise.all(
+    labels.map(async (label, i): Promise<ShareLabelCheck> => {
+      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';
+      }
+    })
+  );
+};

package/acps/store.ts

@@ -28,6 +28,24 @@ export const ACP_STORE_DEFAULTS: ACPsStore = {
  */
 const ACP_STORE_VERSION = 3;
 
+// `typeof null` and `typeof []` are both 'object', so a bare typeof check lets a broken
+// persisted store through. A `null` record then throws on the first `acps[chainId]` lookup.
+// Defined above the store: localStorage rehydrates synchronously inside `createStore`.
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value != null && typeof value === 'object' && !Array.isArray(value);
+
+// Accounts are addresses, so their case carries no meaning: the same account may arrive
+// checksummed (from the wallet client) or lowercased (from an indexer, a URL, user input).
+// Resolve to the key the account is already stored under, so a lookup in another case still
+// finds it and a write does not split one account's acps across two buckets. A new account
+// keeps the spelling it was first written with (the connected wallet's address in practice),
+// which is the key the React hooks read from the raw snapshot.
+const resolveAccountKey = (records: Record<string, unknown> | undefined, account: string): string => {
+  if (records == null || account in records) return account;
+  const lower = account.toLowerCase();
+  return Object.keys(records).find((key) => key.toLowerCase() === lower) ?? account;
+};
+
 export const _acpStore = createStore<ACPsStore>()(
   persist(() => ACP_STORE_DEFAULTS, {
     name: 'cofhesdk-acps',
@@ -36,6 +54,17 @@ export const _acpStore = createStore<ACPsStore>()(
       if (version < ACP_STORE_VERSION) return ACP_STORE_DEFAULTS;
       return persistedState as ACPsStore;
     },
+    // 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 : {}) as Partial<ACPsStore>;
+      return {
+        ...currentState,
+        acps: isRecord(persisted.acps) ? persisted.acps : currentState.acps,
+        activeACPHash: isRecord(persisted.activeACPHash) ? persisted.activeACPHash : currentState.activeACPHash,
+      };
+    },
   })
 );
 
@@ -44,13 +73,7 @@ export const clearStaleStore = () => {
   const state = _acpStore.getState() as any;
 
   // Check if the store has the expected structure
-  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;
   // Invalid structure detected - clear the store
@@ -65,7 +88,8 @@ export const getACP = (
   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);
@@ -75,7 +99,8 @@ export const getActiveACP = (chainId: number | undefined, account: string | unde
   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);
 };
 
@@ -83,7 +108,8 @@ export const getACPs = (chainId: number | undefined, account: string | undefined
   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 == undefined) return acc;
       return { ...acc, [hash]: ACPUtils.deserialize(acp) };
@@ -97,8 +123,9 @@ export const setACP = (chainId: number, account: string, acp: ACP) => {
   _acpStore.setState(
     produce<ACPsStore>((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);
     })
   );
 };
@@ -110,14 +137,15 @@ export const removeACP = (chainId: number, account: string, hash: string) => {
       if (state.acps[chainId] == null) 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) {
+      const activeKey = resolveAccountKey(state.activeACPHash[chainId], account);
+      if (state.activeACPHash[chainId][activeKey] === hash) {
         // if the active acp is the one to be removed - unset it
-        state.activeACPHash[chainId][account] = undefined;
+        state.activeACPHash[chainId][activeKey] = undefined;
       }
       // Remove the acp
       accountACPs[hash] = undefined;
@@ -128,7 +156,8 @@ export const removeACP = (chainId: number, account: string, hash: string) => {
 export const getActiveACPHash = (chainId: number | undefined, account: string | undefined): string | undefined => {
   clearStaleStore();
   if (chainId == null || account == null) return undefined;
-  return _acpStore.getState().activeACPHash[chainId]?.[account];
+  const activeHashes = _acpStore.getState().activeACPHash[chainId];
+  return activeHashes?.[resolveAccountKey(activeHashes, account)];
 };
 
 export const setActiveACPHash = (chainId: number, account: string, hash: string) => {
@@ -136,7 +165,7 @@ export const setActiveACPHash = (chainId: number, account: string, hash: string)
   _acpStore.setState(
     produce<ACPsStore>((state) => {
       if (state.activeACPHash[chainId] == null) state.activeACPHash[chainId] = {};
-      state.activeACPHash[chainId][account] = hash;
+      state.activeACPHash[chainId][resolveAccountKey(state.activeACPHash[chainId], account)] = hash;
     })
   );
 };
@@ -145,7 +174,8 @@ export const removeActiveACPHash = (chainId: number, account: string) => {
   clearStaleStore();
   _acpStore.setState(
     produce<ACPsStore>((state) => {
-      if (state.activeACPHash[chainId]) state.activeACPHash[chainId][account] = undefined;
+      if (state.activeACPHash[chainId])
+        state.activeACPHash[chainId][resolveAccountKey(state.activeACPHash[chainId], account)] = undefined;
     })
   );
 };

package/acps/test/acp.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect, vi } from 'vitest';
+import { UNLABELLED, decodeShareAppKey, shareAppKey } from '../share-metadata';
 import {
   ACPUtils,
+  encodeShareMetadata,
   type CreateSelfACPOptions,
   type CreateSharingACPOptions,
   type ImportSharedACPOptions,
+  type ShareLabel,
 } from '../index.js';
 
 // ACP domain resolution requires an upgraded on-chain ACL (domain ("ACL","2") served by the ACL itself).
@@ -86,6 +89,21 @@ describe('ACPUtils Tests', () => {
   });
 
   describe('createSharing', () => {
+    it('keeps the app key in the metadata, with the labels or with the handles listed as unlabelled', () => {
+      const handle = `0x${'aa'.repeat(32)}` as const;
+      const appKey = shareAppKey('explorer.fhenix.io');
+      const base = { type: 'sharing' as const, issuer: bobAddress, recipient: aliceAddress, handles: [handle] };
+
+      const keyOnly = ACPUtils.createSharing({ ...base, appKey });
+      expect(keyOnly.metadata).toBe(encodeShareMetadata([UNLABELLED], { appKey }));
+      expect(decodeShareAppKey(keyOnly.metadata, [handle])).toBe(appKey);
+
+      const labelled = ACPUtils.createSharing({ ...base, appKey, labels: [UNLABELLED] });
+      expect(labelled.metadata).toBe(keyOnly.metadata);
+
+      expect(ACPUtils.createSharing(base).metadata).toBeUndefined();
+    });
+
     it('should create a sharing acp with valid options', async () => {
       const options: CreateSharingACPOptions = {
         type: 'sharing',
@@ -129,14 +147,13 @@ describe('ACPUtils Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: aliceAddress,
         issuerSignature: '0x1234567890abcdef',
-        name: 'Test Import ACP',
       };
 
       const acp = ACPUtils.importShared(options);
 
       expect(acp.hash).toBe(ACPUtils.getHash(acp));
       expect(acp.type).toBe('recipient');
-      expect(acp.name).toBe('Test Import ACP');
+      expect(acp.name).toBe(`Shared by ${bobAddress.slice(0, 6)}…${bobAddress.slice(-4)}`);
       expect(acp.issuer).toBe(bobAddress);
       expect(acp.recipient).toBe(aliceAddress);
       expect(acp.issuerSignature).toBe('0x1234567890abcdef');
@@ -147,6 +164,19 @@ describe('ACPUtils Tests', () => {
       expect(acp.recipientSignature).toBe('0x');
     });
 
+    it("ignores the issuer's name in the share; the recipient may give their own", async () => {
+      const share = JSON.stringify({
+        issuer: bobAddress,
+        expiration: Math.floor(Date.now() / 1000) + 3600,
+        recipient: aliceAddress,
+        issuerSignature: '0x1234567890abcdef',
+        name: "Bob's note",
+      });
+
+      expect(ACPUtils.importShared(share).name).toBe(`Shared by ${bobAddress.slice(0, 6)}…${bobAddress.slice(-4)}`);
+      expect(ACPUtils.importShared(share, { name: ' Payroll from Bob ' }).name).toBe('Payroll from Bob');
+    });
+
     it('should import a shared acp with valid options as string', async () => {
       const options: ImportSharedACPOptions = {
         issuer: bobAddress,
@@ -188,7 +218,6 @@ describe('ACPUtils Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: aliceAddress,
         issuerSignature: '0x', // Invalid empty signature
-        name: 'Test Import ACP',
       };
 
       expect(() => ACPUtils.importShared(options)).toThrow();
@@ -246,7 +275,6 @@ describe('ACPUtils Tests', () => {
         recipient: aliceAddress,
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         issuerSignature: '0x1234567890abcdef',
-        name: 'Test Import ACP',
       };
 
       const acp = await ACPUtils.importSharedAndSign(options, publicClient, aliceWalletClient);
@@ -315,7 +343,6 @@ describe('ACPUtils Tests', () => {
         recipient: aliceAddress,
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         issuerSignature: '0x1111111111111111111111111111111111111111111111111111111111111111',
-        name: 'Test ACP',
       });
 
       const signedACP = await ACPUtils.sign(acp, publicClient, aliceWalletClient);
@@ -431,7 +458,7 @@ describe('ACPUtils Tests', () => {
       const exported = ACPUtils.export(acp);
       const parsed = JSON.parse(exported);
 
-      expect(parsed.name).toBe('Test Sharing ACP');
+      expect(parsed).not.toHaveProperty('name'); // the issuer's own note stays with them
       expect(parsed.type).toBe('sharing');
       expect(parsed.issuer).toBe(bobAddress);
       expect(parsed.recipient).toBe(aliceAddress);
@@ -456,7 +483,6 @@ describe('ACPUtils Tests', () => {
 
       expect(Object.keys(parsed).sort()).toEqual(
         [
-          'name',
           'type',
           'issuer',
           'expiration',
@@ -475,6 +501,7 @@ describe('ACPUtils Tests', () => {
       expect(parsed.handles).toEqual([]);
       expect(parsed.revokerData).toBe(0);
       // private component never leaves the client
+      expect(parsed).not.toHaveProperty('name');
       expect(parsed).not.toHaveProperty('sealingPrivateKey');
       expect(parsed).not.toHaveProperty('sealingKey');
       expect(parsed).not.toHaveProperty('hash');
@@ -482,6 +509,74 @@ describe('ACPUtils Tests', () => {
     });
   });
 
+  describe('share labels in exported JSON', () => {
+    const HANDLE = `0x${'ab'.repeat(32)}` as const;
+    const label: ShareLabel = {
+      kind: 'stored',
+      contract: '0x2222222222222222222222222222222222222222',
+      selector: '0x344ff101',
+      args: [{ type: 'issuer' }],
+      returnWord: 0,
+      block: 123n,
+    };
+    const signed = (acp: ReturnType<typeof ACPUtils.createSharing>) => ({
+      ...acp,
+      issuerSignature: `0x${'11'.repeat(65)}` as const,
+    });
+
+    it('createSharing keeps the labels on the acp as metadata', () => {
+      const acp = ACPUtils.createSharing({
+        issuer: bobAddress,
+        recipient: aliceAddress,
+        handles: [HANDLE],
+        labels: [label],
+      });
+      expect(acp.metadata).toBe(encodeShareMetadata([label]));
+      expect(ACPUtils.deserialize(ACPUtils.serialize(acp)).metadata).toBe(acp.metadata);
+    });
+
+    it('createSharing rejects a label count that does not match the handles', () => {
+      expect(() =>
+        ACPUtils.createSharing({
+          issuer: bobAddress,
+          recipient: aliceAddress,
+          handles: [HANDLE],
+          labels: [label, label],
+        })
+      ).toThrow('Cannot label a share of 1 handles with 2 labels');
+    });
+
+    it('export writes the metadata and importShared keeps it on the recipient acp', () => {
+      const sharing = signed(
+        ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE], labels: [label] })
+      );
+      const json = ACPUtils.export(sharing);
+      expect(JSON.parse(json).metadata).toBe(sharing.metadata);
+
+      const recipient = ACPUtils.importShared(json);
+      expect(recipient.metadata).toBe(sharing.metadata);
+      expect(recipient.hash).toBe(ACPUtils.importShared({ ...JSON.parse(json), metadata: undefined }).hash);
+    });
+
+    it('imports JSON without metadata, or with an empty one, as a share without labels', () => {
+      const sharing = signed(
+        ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE] })
+      );
+      const json = ACPUtils.export(sharing);
+      expect(JSON.parse(json)).not.toHaveProperty('metadata');
+
+      expect(ACPUtils.importShared(json).metadata).toBeUndefined();
+      expect(ACPUtils.importShared({ ...JSON.parse(json), metadata: '0x' }).metadata).toBeUndefined();
+    });
+
+    it('importShared rejects metadata that is not hex', () => {
+      const json = ACPUtils.export(
+        signed(ACPUtils.createSharing({ issuer: bobAddress, recipient: aliceAddress, handles: [HANDLE] }))
+      );
+      expect(() => ACPUtils.importShared({ ...JSON.parse(json), metadata: 'labels' })).toThrow(/metadata/);
+    });
+  });
+
   describe('updateName', () => {
     it('should update acp name immutably', async () => {
       const acp = ACPUtils.createSelf({

package/acps/test/localstorage.test.ts

@@ -3,7 +3,16 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { getACP, setACP, removeACP, getActiveACPHash, setActiveACPHash, ACPUtils, acpStore } from '../index.js';
+import {
+  getACP,
+  setACP,
+  removeACP,
+  getActiveACPHash,
+  setActiveACPHash,
+  ACPUtils,
+  acpStore,
+  ACP_STORE_DEFAULTS,
+} from '../index.js';
 import { createMockACP } from '../test-utils.js';
 
 // Type declarations for happy-dom environment
@@ -102,4 +111,22 @@ describe('ACPs localStorage Tests', () => {
     expect(parsedData.state.acps[chainId][account][acp.hash]).toBeUndefined();
     expect(parsedData.state.activeACPHash[chainId][account]).toBeUndefined();
   });
+
+  it('should recover from a corrupt store persisted at the current version', async () => {
+    // `migrate` only runs for older versions, so a corrupt state saved at the current
+    // version reaches the store unless it is cleaned on rehydrate.
+    localStorage.setItem(
+      'cofhesdk-acps',
+      JSON.stringify({ state: { acps: null, activeACPHash: {} }, version: acpStore.store.persist.getOptions().version })
+    );
+    await acpStore.store.persist.rehydrate();
+
+    // Fixed on load, so consumers that read the raw snapshot (the React hooks) are covered too.
+    expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+    const snapshot = acpStore.store.getState();
+    expect(() => snapshot.acps[chainId]?.[account]).not.toThrow();
+
+    expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+    expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+  });
 });