@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

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

@@ -0,0 +1,157 @@
+import type { Address, Hex } from 'viem';
+import type { ShareLabel } from '../schema';
+
+/**
+ * Shared test fixtures: two confidential tokens on Arbitrum Sepolia, labels with the exact blob
+ * each encodes to, and one real share whose labels the chain confirms.
+ */
+
+export const FUSD: Address = '0x389be1Eb842290F264A6851f49c0149b8035a052';
+export const FUSDY: Address = '0x06a52cf2e0cEAFc7d1f522400500ca7f3df18754';
+export const ISSUER: Address = '0x1F547C0A6088856B9d58F843d9dd8C6e26f4969d';
+/** confidentialBalanceOf(address) */
+export const BALANCE_OF: Hex = '0x344ff101';
+/** ConfidentialTransfer(address indexed from, address indexed to, bytes32 indexed amount), first 4 bytes of topic0 */
+export const CONFIDENTIAL_TRANSFER: Hex = '0x67500e8d';
+export const CONFIDENTIAL_TRANSFER_TOPIC0: Hex = '0x67500e8d0ed826d2194f514dd0d8124f35648ab6e3fb5e6ed867134cffe661e9';
+export const WORD: Hex = '0x00000000000000000000000000000000000000000000000000000000000000aa';
+
+const fusd = FUSD.slice(2).toLowerCase();
+const fusdy = FUSDY.slice(2).toLowerCase();
+
+/** Label lists with the blob each must encode to, written field by field. */
+export const CASES: { name: string; labels: ShareLabel[]; blob: string }[] = [
+  {
+    name: 'a stored value read with the issuer as its one argument',
+    labels: [
+      {
+        kind: 'stored',
+        contract: FUSD,
+        selector: BALANCE_OF,
+        args: [{ type: 'issuer' }],
+        returnWord: 0,
+        block: 0x12ba88b2n,
+      },
+    ],
+    blob: '0x03' + '01' + fusd + '01' + '344ff101' + '00' + ('00' + '00' + '00' + '12ba88b2' + '01'),
+  },
+  {
+    name: 'a stored value read with no arguments',
+    labels: [{ kind: 'stored', contract: FUSD, selector: '0x18160ddd', args: [], returnWord: 0, block: 1n }],
+    blob: '0x03' + '01' + fusd + '01' + '18160ddd' + '00' + ('00' + '00' + '00' + '00000001' + '00'),
+  },
+  {
+    name: 'a stored value with explicit arguments and a later return word',
+    labels: [
+      {
+        kind: 'stored',
+        contract: FUSDY,
+        selector: '0x70a08231',
+        args: [{ type: 'issuer' }, { type: 'word', value: WORD }],
+        returnWord: 1,
+        block: 0x12ba88b2n,
+      },
+    ],
+    blob:
+      '0x03' +
+      '01' +
+      fusdy +
+      '01' +
+      '70a08231' +
+      '00' +
+      ('00' + '00' + '00' + '12ba88b2' + 'ff' + '01' + '02' + '01' + '00' + WORD.slice(2)),
+  },
+  {
+    name: 'an event value',
+    labels: [
+      { kind: 'event', contract: FUSD, block: 0x12ba9304n, txIndex: 7, logIndex: 300, selector: CONFIDENTIAL_TRANSFER },
+    ],
+    blob: '0x03' + '01' + fusd + '01' + '67500e8d' + '01' + '12ba9304' + '0007' + ('01' + '00' + '00' + '012c' + '00'),
+  },
+  {
+    name: 'two event values of one transaction on two contracts',
+    labels: [
+      {
+        kind: 'event',
+        contract: FUSD,
+        block: 0x12ba9375n,
+        txIndex: 12,
+        logIndex: 106,
+        selector: CONFIDENTIAL_TRANSFER,
+      },
+      {
+        kind: 'event',
+        contract: FUSDY,
+        block: 0x12ba9375n,
+        txIndex: 12,
+        logIndex: 115,
+        selector: CONFIDENTIAL_TRANSFER,
+      },
+    ],
+    blob:
+      '0x03' +
+      ('02' + fusd + fusdy) +
+      ('01' + '67500e8d') +
+      ('01' + '12ba9375' + '000c') +
+      ('01' + '00' + '00' + '006a' + '00') +
+      ('01' + '01' + '00' + '0073' + '00'),
+  },
+  {
+    name: 'an unlabelled value',
+    labels: [{ kind: 'unlabelled' }],
+    blob: '0x03' + '00' + '00' + '00' + 'ff',
+  },
+];
+
+/**
+ * A real share on Arbitrum Sepolia: two balances read at one block, and five transfer amounts from
+ * four transactions. The last two are the two values of one vault deposit (the fUSD that left and
+ * the fUSDy that was minted), so they name the same transaction. The fUSDy amount is carried by two
+ * logs of that transaction (115, the ConfidentialTransfer, and 118); the label names the first.
+ */
+export const SAMPLE = {
+  issuer: ISSUER,
+  blob: ('0x03' +
+    ('02' + fusd + fusdy) +
+    ('02' + '344ff101' + '67500e8d') +
+    ('04' + '12ba93040005' + '12ba93070008' + '12ba9309000a' + '12ba9375000c') +
+    '00000012bb9d0f01' +
+    '00010012bb9d0f01' +
+    '010000001e01' +
+    '010001004101' +
+    '010002008a01' +
+    '010003006a01' +
+    '010103007301') as Hex,
+  handles: [
+    '0xabaaf65246a7b1763ed4f04486115a27ffbd7abac4a0d10f139cfdac9a910500',
+    '0x987a1e51721082556753153555c4f2242a8a592d80ff9551fb471f7427660500',
+    '0xbb0c6b1feb27e5c2aec9667ce478006db331205407c754c7a47befa4b2c28500',
+    '0x409fec2a564efb61ad75d544ca1933fe2d450e5d9ba847089b15375d1c0d8500',
+    '0x39a2c1973989ae9e52dc4d0eed55ceb761d8b83dae6c1a8a66aa9d1defda8500',
+    '0xf726d299727dd5c150ce1f31f42447495b3f4f42204d043ab9d21e78aced0500',
+    '0x9b0420892380838a0d1fc858c0c2314f9248adb4cacaa766fe869645c1830500',
+  ] as Hex[],
+  labels: [
+    {
+      kind: 'stored',
+      contract: FUSD,
+      selector: BALANCE_OF,
+      args: [{ type: 'issuer' }],
+      returnWord: 0,
+      block: 314285327n,
+    },
+    {
+      kind: 'stored',
+      contract: FUSDY,
+      selector: BALANCE_OF,
+      args: [{ type: 'issuer' }],
+      returnWord: 0,
+      block: 314285327n,
+    },
+    { kind: 'event', contract: FUSD, block: 314217220n, txIndex: 5, logIndex: 30, selector: CONFIDENTIAL_TRANSFER },
+    { kind: 'event', contract: FUSD, block: 314217223n, txIndex: 8, logIndex: 65, selector: CONFIDENTIAL_TRANSFER },
+    { kind: 'event', contract: FUSD, block: 314217225n, txIndex: 10, logIndex: 138, selector: CONFIDENTIAL_TRANSFER },
+    { kind: 'event', contract: FUSD, block: 314217333n, txIndex: 12, logIndex: 106, selector: CONFIDENTIAL_TRANSFER },
+    { kind: 'event', contract: FUSDY, block: 314217333n, txIndex: 12, logIndex: 115, selector: CONFIDENTIAL_TRANSFER },
+  ] as ShareLabel[],
+};

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { createPublicClient, http, type PublicClient } from 'viem';
+import { arbitrumSepolia } from 'viem/chains';
+import { TEST_PRIVATE_KEY } from '@cofhe/test-setup';
+import { decodeShareMetadata } from '../decode';
+import { verifyShareLabels } from '../verify';
+import { SAMPLE } from './fixtures';
+
+/**
+ * The real sample against Arbitrum Sepolia, read from the public RPC. A live-chain suite like
+ * `core/test/decrypt.test.ts`: it runs where TEST_PRIVATE_KEY is set (the key itself is not used),
+ * so `pnpm test` stays offline and `pnpm test:live` covers it.
+ */
+describe.skipIf(!TEST_PRIVATE_KEY)('share metadata against Arbitrum Sepolia', () => {
+  const publicClient = createPublicClient({
+    chain: arbitrumSepolia,
+    transport: http(arbitrumSepolia.rpcUrls.default.http[0]),
+  }) as PublicClient;
+
+  it('confirms every event label of the sample at its log index', async () => {
+    const labels = decodeShareMetadata(SAMPLE.blob, SAMPLE.handles);
+    const checks = await verifyShareLabels({
+      labels,
+      handles: SAMPLE.handles,
+      issuer: SAMPLE.issuer,
+      publicClient,
+      verify: 'events',
+    });
+    expect(checks).toEqual(['skipped', 'skipped', 'verified', 'verified', 'verified', 'verified', 'verified']);
+  });
+
+  it('rejects the fUSDy amount labelled at the deposit’s other log that carries it', async () => {
+    const labels = decodeShareMetadata(SAMPLE.blob, SAMPLE.handles);
+    const last = labels[6];
+    if (last.kind !== 'event') throw new Error('expected an event label');
+    const [check] = await verifyShareLabels({
+      labels: [{ ...last, logIndex: 118 }],
+      handles: [SAMPLE.handles[6]],
+      issuer: SAMPLE.issuer,
+      publicClient,
+    });
+    // log 118 carries the ctHash but is not a ConfidentialTransfer: the selector check fails it
+    expect(check).toBe('mismatch');
+  });
+
+  it('checks the stored values while a node still has the state of their block', async () => {
+    const labels = decodeShareMetadata(SAMPLE.blob, SAMPLE.handles);
+    const checks = await verifyShareLabels({
+      labels: labels.slice(0, 2),
+      handles: SAMPLE.handles.slice(0, 2),
+      issuer: SAMPLE.issuer,
+      publicClient,
+    });
+    for (const check of checks) expect(['verified', 'unverifiable']).toContain(check);
+  });
+});

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { padHex, parseAbi, toEventSelector, toFunctionSelector, type Log } from 'viem';
+import { encodeShareMetadata } from '../encode';
+import { ERC7984_ABI } from '../erc7984';
+import { eventLogLabel, viewFunctionLabel } from '../presets';
+import {
+  BALANCE_OF,
+  CONFIDENTIAL_TRANSFER,
+  CONFIDENTIAL_TRANSFER_TOPIC0,
+  FUSD,
+  FUSDY,
+  ISSUER,
+  SAMPLE,
+  WORD,
+} from './fixtures';
+
+const ISSUER_WORD = padHex(ISSUER, { size: 32 }).toLowerCase();
+
+describe('label presets', () => {
+  it('labels a log with its position and event selector', () => {
+    const log = {
+      address: FUSD,
+      blockNumber: 314217220n,
+      transactionIndex: 5,
+      logIndex: 30,
+      topics: [CONFIDENTIAL_TRANSFER_TOPIC0],
+    } as unknown as Log;
+    expect(eventLogLabel(log)).toEqual(SAMPLE.labels[2]);
+    expect(eventLogLabel(log).selector).toBe(CONFIDENTIAL_TRANSFER);
+  });
+
+  it('refuses a pending or anonymous log', () => {
+    const base = {
+      address: FUSD,
+      blockNumber: 1n,
+      transactionIndex: 0,
+      logIndex: 0,
+      topics: [CONFIDENTIAL_TRANSFER_TOPIC0],
+    };
+    expect(() => eventLogLabel({ ...base, blockNumber: null } as unknown as Log)).toThrow('pending');
+    expect(() => eventLogLabel({ ...base, topics: [] } as unknown as Log)).toThrow('anonymous');
+  });
+
+  it('labels the ERC-7984 balance read from its ABI; the issuer argument compresses to the real share', () => {
+    const [balanceOf, transfer] = ERC7984_ABI;
+    expect(toFunctionSelector(balanceOf)).toBe(BALANCE_OF);
+    expect(toEventSelector(transfer)).toBe(CONFIDENTIAL_TRANSFER_TOPIC0);
+
+    const label = viewFunctionLabel({
+      contract: FUSD,
+      abi: ERC7984_ABI,
+      functionName: 'confidentialBalanceOf',
+      args: [ISSUER],
+      block: 314285327n,
+    });
+    expect(label).toEqual({ ...SAMPLE.labels[0], args: [{ type: 'word', value: ISSUER_WORD }] });
+    // encoded for a share by ISSUER, the address becomes "the issuer": the sample's own bytes
+    expect(encodeShareMetadata([label], { issuer: ISSUER })).toBe(encodeShareMetadata([SAMPLE.labels[0]]));
+    // for anyone else's share it stays a literal address
+    expect(encodeShareMetadata([label], { issuer: FUSDY })).toBe(encodeShareMetadata([label]));
+    expect(encodeShareMetadata([label])).not.toBe(encodeShareMetadata([SAMPLE.labels[0]]));
+  });
+
+  it('labels any view function from its ABI, encoding literal arguments to words', () => {
+    const abi = parseAbi([
+      'function balanceOfAt(address account, uint256 snapshot) view returns (uint256 total, bytes32 encrypted)',
+      'function totalSupply() view returns (bytes32)',
+    ]);
+    expect(
+      viewFunctionLabel({
+        contract: FUSDY,
+        abi,
+        functionName: 'balanceOfAt',
+        args: [ISSUER, 0xaan],
+        returnWord: 1,
+        block: 0x12ba88b2n,
+      })
+    ).toEqual({
+      kind: 'stored',
+      contract: FUSDY,
+      selector: toFunctionSelector(abi[0]),
+      args: [
+        { type: 'word', value: ISSUER_WORD },
+        { type: 'word', value: WORD },
+      ],
+      returnWord: 1,
+      block: 0x12ba88b2n,
+    });
+    expect(viewFunctionLabel({ contract: FUSD, abi, functionName: 'totalSupply', block: 1n })).toEqual({
+      kind: 'stored',
+      contract: FUSD,
+      selector: '0x18160ddd',
+      args: [],
+      returnWord: 0,
+      block: 1n,
+    });
+  });
+
+  it('refuses what the layout cannot carry or the ABI does not have', () => {
+    const abi = parseAbi([
+      'function nameOf(string key) view returns (bytes32)',
+      'function balanceOf(address account) view returns (bytes32)',
+      'function balanceOf(address account, uint256 id) view returns (bytes32)',
+      'function mint(address to) returns (bytes32)',
+    ]);
+    const base = { contract: FUSD, abi, block: 1n } as const;
+    expect(() => viewFunctionLabel({ ...base, functionName: 'nameOf', args: ['x'] })).toThrow('static 32-byte word');
+    expect(() => viewFunctionLabel({ ...base, functionName: 'balanceOf', args: [] as never })).toThrow(
+      'no single overload'
+    );
+    expect(() =>
+      viewFunctionLabel({ ...base, abi: parseAbi(['function f(address a) view returns (bytes32)']), functionName: 'f' })
+    ).toThrow('takes 1 arguments, 0 given');
+    expect(() => viewFunctionLabel({ ...base, functionName: 'missing' as never })).toThrow('no function missing');
+    expect(() => viewFunctionLabel({ ...base, functionName: 'mint' as never, args: [ISSUER] as never })).toThrow(
+      'not a view function'
+    );
+  });
+});

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