@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

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();
+  });
 });

package/acps/test/onchainAccessStatus.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+import { checkACPValidityOnChain, getACPAccessStatusOnChain } from '../onchain-utils';
+import type { ACPPublic } from '../types';
+
+const TASK_MANAGER = '0x0000000000000000000000000000000000005000';
+const ACL = '0x00000000000000000000000000000000000000ac';
+const ISSUER = '0x00000000000000000000000000000000000000b0';
+
+const acp: ACPPublic = {
+  issuer: ISSUER,
+  expiration: 2_000_000_000,
+  recipient: '0x00000000000000000000000000000000000000a1',
+  revokerData: 1,
+  revokerContract: '0x00000000000000000000000000000000000000cc',
+  scope: 2,
+  contracts: [],
+  handles: [],
+  sealingKey: `0x${'0'.repeat(64)}`,
+  issuerSignature: '0x01',
+  recipientSignature: '0x02',
+} as unknown as ACPPublic;
+
+/**
+ * A revert as a viem copy OTHER than the SDK one reports it: the same shape, but no class
+ * identity the SDK could match with `instanceof`.
+ */
+function foreignRevert(errorName: string) {
+  const reverted = { name: 'ContractFunctionRevertedError', data: { errorName } };
+  return Object.assign(new Error(`The contract function reverted: ${errorName}`), {
+    walk: (fn: (e: unknown) => boolean) => (fn(reverted) ? reverted : null),
+  });
+}
+
+function client({ simulate, reads = {} }: { simulate?: () => unknown; reads?: Record<string, () => unknown> }) {
+  return {
+    chain: { id: 31337 },
+    readContract: vi.fn(async ({ functionName }: { functionName: string }) => {
+      if (functionName === 'getTm') return TASK_MANAGER;
+      if (functionName === 'acl') return ACL;
+      const read = reads[functionName];
+      if (!read) throw new Error(`unexpected read ${functionName}`);
+      return read();
+    }),
+    simulateContract: vi.fn(async () => simulate?.()),
+  } as unknown as PublicClient;
+}
+
+describe('getACPAccessStatusOnChain', () => {
+  it('returns valid when the ACL accepts the ACP', async () => {
+    expect(await getACPAccessStatusOnChain(acp, client({}))).toBe('valid');
+  });
+
+  it.each([
+    ['PermissionInvalid_Expired', 'expired'],
+    ['PermissionInvalid_Disabled', 'revoked'],
+    ['PermissionInvalid_IssuerSignature', 'invalid-issuer-signature'],
+    ['PermissionInvalid_RecipientSignature', 'invalid-recipient-signature'],
+  ])('maps %s to %s, even from another viem copy', async (errorName, status) => {
+    const publicClient = client({
+      simulate: () => {
+        throw foreignRevert(errorName);
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient)).toBe(status);
+  });
+
+  it('tells out-of-scope from issuer-not-allowed with the issuer own allowance', async () => {
+    const outOfScope = client({ reads: { isAllowedWithPermission: () => false, isAllowed: () => true } });
+    const notAllowed = client({ reads: { isAllowedWithPermission: () => false, isAllowed: () => false } });
+    const allowed = client({ reads: { isAllowedWithPermission: () => true } });
+    expect(await getACPAccessStatusOnChain(acp, outOfScope, 1n)).toBe('out-of-scope');
+    expect(await getACPAccessStatusOnChain(acp, notAllowed, '0x01')).toBe('issuer-not-allowed');
+    expect(await getACPAccessStatusOnChain(acp, allowed, 1n)).toBe('allowed');
+  });
+
+  it('maps a revert on the handle check too', async () => {
+    const publicClient = client({
+      reads: {
+        isAllowedWithPermission: () => {
+          throw foreignRevert('PermissionInvalid_Disabled');
+        },
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient, 1n)).toBe('revoked');
+  });
+
+  it('reads a revert reported only as text with the error selector', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw new Error('Execution reverted with reason: RPC eth_call failed: custom error 0xcbd3a966.');
+      },
+    });
+    expect(await getACPAccessStatusOnChain(acp, publicClient)).toBe('revoked');
+  });
+
+  it('still throws what is not an ACL revert', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw new Error('fetch failed');
+      },
+    });
+    await expect(getACPAccessStatusOnChain(acp, publicClient)).rejects.toThrow('fetch failed');
+  });
+});
+
+describe('checkACPValidityOnChain', () => {
+  it('names the revert from another viem copy instead of rethrowing it raw', async () => {
+    const publicClient = client({
+      simulate: () => {
+        throw foreignRevert('PermissionInvalid_Disabled');
+      },
+    });
+    await expect(checkACPValidityOnChain(acp, publicClient)).rejects.toThrow(/^PermissionInvalid_Disabled$/);
+  });
+});

package/acps/test/registry.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PublicClient } from 'viem';
+import {
+  readPostedShares,
+  readShare,
+  readSharesFor,
+  shareIdOfChainShare,
+  type ChainShare,
+  type ShareHeader,
+} from '../registry';
+
+const REGISTRY = '0x00000000000000000000000000000000000000e0';
+const ISSUER = '0x00000000000000000000000000000000000000b0';
+const RECIPIENT = '0x00000000000000000000000000000000000000a1';
+const ZERO = '0x0000000000000000000000000000000000000000';
+
+const chainShare = (handle: number): ChainShare => ({
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  revokerData: 0n,
+  revokerContract: ZERO,
+  scope: 2,
+  contracts: [],
+  handles: [`0x${handle.toString(16).padStart(64, '0')}`],
+  sealingKey: `0x${'0'.repeat(64)}`,
+  issuerSignature: '0x11',
+  recipientSignature: '0x',
+});
+
+const headerAt = (blockNumber: bigint): ShareHeader => ({
+  issuer: ISSUER,
+  expiration: 2_000_000_000n,
+  recipient: RECIPIENT,
+  blockNumber,
+  revokerContract: ZERO,
+  revokerData: 0n,
+});
+
+/** Three shares: two posted in block 10, one in block 20. */
+const shares = [chainShare(1), chainShare(2), chainShare(3)];
+const ids = shares.map(shareIdOfChainShare);
+const headers = [headerAt(10n), headerAt(10n), headerAt(20n)];
+const metadata: `0x${string}`[] = ['0x03aa', '0x', '0x03bb'];
+
+const clientWith = (
+  events = shares.map((acp, i) => ({ block: headers[i].blockNumber, acp, id: ids[i], metadata: metadata[i] }))
+) => {
+  const getContractEvents = vi.fn(async ({ fromBlock, args }: { fromBlock: bigint; args: { shareId: string[] } }) =>
+    events
+      .filter((e) => e.block === fromBlock && args.shareId.includes(e.id))
+      .map((e) => ({ args: { shareId: e.id, acp: e.acp, metadata: e.metadata } }))
+  );
+  const readContract = vi.fn(async ({ functionName, args }: { functionName: string; args: [string] }) => {
+    if (functionName === 'sharesFor') return [ids, headers];
+    const i = ids.indexOf(args[0] as `0x${string}`);
+    return i === -1 ? { ...headerAt(0n), issuer: ZERO } : headers[i];
+  });
+  return { client: { getContractEvents, readContract } as unknown as PublicClient, getContractEvents };
+};
+
+describe('registry reads', () => {
+  it('reads the inbox with one getLogs per distinct block, in sharesFor order', async () => {
+    const { client, getContractEvents } = clientWith();
+    const { posted, unreadable } = await readSharesFor(client, REGISTRY, RECIPIENT);
+
+    expect(unreadable).toEqual([]);
+    expect(posted.map((p) => p.shareId)).toEqual(ids);
+    expect(posted.map((p) => p.share)).toEqual(shares);
+    expect(posted.map((p) => p.metadata)).toEqual([...metadata]);
+    expect(getContractEvents).toHaveBeenCalledTimes(2);
+    expect(getContractEvents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        eventName: 'Shared',
+        fromBlock: 10n,
+        toBlock: 10n,
+        args: { shareId: [ids[0], ids[1]] },
+      })
+    );
+  });
+
+  it('reads one share, and null for an unknown one', async () => {
+    const { client } = clientWith();
+    expect((await readShare(client, REGISTRY, ids[2]))?.metadata).toBe('0x03bb');
+    expect(await readShare(client, REGISTRY, `0x${'f'.repeat(64)}`)).toBeNull();
+  });
+
+  it('takes the last Shared event when a share was removed and posted again in the same block', async () => {
+    const { client } = clientWith([
+      { block: 10n, acp: shares[0], id: ids[0], metadata: '0x03aa' },
+      { block: 10n, acp: shares[0], id: ids[0], metadata: '0x03cc' },
+    ]);
+    const {
+      posted: [posted],
+    } = await readPostedShares(client, REGISTRY, [{ shareId: ids[0], header: headers[0] }]);
+    expect(posted.metadata).toBe('0x03cc');
+  });
+
+  describe('one share never hides the rest', () => {
+    const all = () => shares.map((_, i) => ({ shareId: ids[i], header: headers[i] }));
+
+    it('a share whose block has no Shared event of it is unreadable, the others are posted', async () => {
+      // the node answered sharesFor from a newer block than the one it serves logs for
+      const { client } = clientWith(
+        shares.slice(0, 2).map((acp, i) => ({ block: headers[i].blockNumber, acp, id: ids[i], metadata: metadata[i] }))
+      );
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.map((p) => p.shareId)).toEqual([ids[0], ids[1]]);
+      expect(unreadable).toEqual([
+        { shareId: ids[2], header: headers[2], reason: 'no Shared event in block 20, where the registry points' },
+      ]);
+    });
+
+    it('a share whose event payload does not hash to its id is unreadable, the others are posted', async () => {
+      const { client } = clientWith([
+        { block: 10n, acp: shares[1], id: ids[0], metadata: '0x' }, // the payload of share 2 under the id of share 1
+        { block: 10n, acp: shares[1], id: ids[1], metadata: '0x' },
+        { block: 20n, acp: shares[2], id: ids[2], metadata: '0x03bb' },
+      ]);
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.map((p) => p.shareId)).toEqual([ids[1], ids[2]]);
+      expect(unreadable.map((u) => [u.shareId, u.reason])).toEqual([
+        [ids[0], 'the payload in its Shared event does not hash to its id'],
+      ]);
+    });
+
+    it('a block the node cannot serve makes its shares unreadable, with the error, and the others are posted', async () => {
+      const { client, getContractEvents } = clientWith();
+      getContractEvents.mockImplementationOnce(async () => {
+        throw new Error('block not found');
+      });
+      const { posted, unreadable } = await readPostedShares(client, REGISTRY, all());
+      expect(posted.length + unreadable.length).toBe(3);
+      expect(unreadable.length).toBeGreaterThan(0);
+      for (const u of unreadable)
+        expect(u.reason).toMatch(/Shared events of block \d+ could not be read: block not found/);
+    });
+
+    it('readShare throws, with the reason, for a listed share whose event cannot be read', async () => {
+      const { client } = clientWith([]);
+      await expect(readShare(client, REGISTRY, ids[0])).rejects.toThrow('no Shared event in block 10');
+    });
+  });
+});

package/acps/test/sealing.test.ts

@@ -34,6 +34,14 @@ describe('seal / unsealWithPrivateKey', () => {
     expect(unsealWithPrivateKey(pair.privateKey.slice(2), sealed)).toBe(value);
   });
 
+  it('accepts uppercase hex keys', () => {
+    const pair = GenerateSealingKey();
+    const value = BigInt(7);
+
+    const sealed = seal(value, `0x${pair.publicKey.slice(2).toUpperCase()}`);
+    expect(unsealWithPrivateKey(`0x${pair.privateKey.slice(2).toUpperCase()}`, sealed)).toBe(value);
+  });
+
   it('should throw error for invalid public key in seal', () => {
     expect(() => {
       seal(BigInt(12345), 'invalid');
@@ -49,6 +57,21 @@ describe('seal / unsealWithPrivateKey', () => {
     }).toThrow('Private key must be of length 64');
   });
 
+  it('rejects a correct-length public key with non-hex characters instead of sealing to a zeroed key', () => {
+    expect(() => {
+      seal(BigInt(12345), 'z'.repeat(64));
+    }).toThrow('Public key must contain only hex characters');
+  });
+
+  it('rejects a correct-length private key with non-hex characters in unseal', () => {
+    const pair = GenerateSealingKey();
+    const sealed = seal(BigInt(1), pair.publicKey);
+
+    expect(() => {
+      unsealWithPrivateKey(`0x${'z'.repeat(64)}`, sealed);
+    }).toThrow('Private key must contain only hex characters');
+  });
+
   it('should throw error for invalid value in seal', () => {
     const publicKey = `0x${'b'.repeat(64)}`;