@cofhe/sdk 0.8.0 → 1.0.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/aclServedAddresses.test.ts

@@ -0,0 +1,65 @@
+import { ContractFunctionRevertedError, HttpRequestError, parseAbi } from 'viem';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearTaskManagerAddressCache } from '../../core/taskManager.js';
+import { clearAclServedAddresses, getAclServedAddresses } from '../onchain-utils.js';
+
+const CHAIN_ID = 421614;
+const TASK_MANAGER = '0x0000000000000000000000000000000000005000';
+const ACL = '0x00000000000000000000000000000000000000dd';
+const REVOKER = '0x00000000000000000000000000000000000000cc';
+const REGISTRY = '0x00000000000000000000000000000000000000ee';
+
+const GETTERS_ABI = parseAbi([
+  'function defaultRevokerContract() view returns (address)',
+  'function shareRegistry() view returns (address)',
+]);
+
+function clientWithGetters(getter: (functionName: string) => Promise<unknown>) {
+  return {
+    readContract: vi.fn(async ({ functionName }: { functionName: string }) => {
+      if (functionName === 'getTm') return TASK_MANAGER;
+      if (functionName === 'acl') return ACL;
+      return getter(functionName);
+    }),
+  } as any;
+}
+
+describe('getAclServedAddresses', () => {
+  beforeEach(() => {
+    clearAclServedAddresses();
+    clearTaskManagerAddressCache();
+  });
+
+  it('does not cache a transient failure of the ACL getters', async () => {
+    let down = true;
+    const publicClient = clientWithGetters(async (functionName) => {
+      if (down) throw new HttpRequestError({ url: 'http://rpc', status: 429 });
+      return functionName === 'defaultRevokerContract' ? REVOKER : REGISTRY;
+    });
+
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual({
+      defaultRevoker: undefined,
+      shareRegistry: undefined,
+    });
+
+    down = false;
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual({
+      defaultRevoker: REVOKER,
+      shareRegistry: REGISTRY,
+    });
+  });
+
+  it('caches a pre-upgrade ACL whose getters revert', async () => {
+    const publicClient = clientWithGetters(async (functionName) => {
+      throw new ContractFunctionRevertedError({ abi: GETTERS_ABI, functionName, data: '0x' });
+    });
+
+    const expected = { defaultRevoker: undefined, shareRegistry: undefined };
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual(expected);
+    const calls = publicClient.readContract.mock.calls.length;
+
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual(expected);
+    expect(publicClient.readContract.mock.calls.length).toBe(calls);
+  });
+});