@cofhe/sdk 0.8.0 → 1.0.0

package/acps/share-metadata/schema.ts

@@ -0,0 +1,47 @@
+import type { Address, Hex } from 'viem';
+
+/**
+ * A label says where one ctHash of a SNAPSHOT share came from, as something the recipient can
+ * check against the chain. It speaks of contracts, selectors and positions in the chain only:
+ * it does not know what a token, a balance or a transfer is. A reader that recognises a selector
+ * can present the value accordingly (see `describeShareMetadata`). A share carries one label per
+ * ctHash, in the order of `acp.handles`, so the ctHashes themselves are never repeated.
+ */
+
+/** One argument of a stored-value read: the share issuer, or a literal 32-byte ABI word. */
+export type ShareLabelReadArg = { type: 'issuer' } | { type: 'word'; value: Hex };
+
+/** A stored value: what a view function of a contract returned at a block. */
+export type StoredValueLabel = {
+  kind: 'stored';
+  contract: Address;
+  /** 4-byte selector of the view function. */
+  selector: Hex;
+  /** Static ABI types only: each argument is one 32-byte word. */
+  args: ShareLabelReadArg[];
+  /** Which 32-byte word of the return data is the ctHash (0 for a single return value). */
+  returnWord: number;
+  /** Block the value was read at (on Arbitrum: the L2 block number). */
+  block: bigint;
+};
+
+/** An event value: a value carried by one event (log) that a contract emitted. */
+export type EventValueLabel = {
+  kind: 'event';
+  contract: Address;
+  /** Block of the log (on Arbitrum: the L2 block number). */
+  block: bigint;
+  /** Index of the log's transaction within its block. */
+  txIndex: number;
+  /** Block-wide index of the log, as RPC nodes return it. */
+  logIndex: number;
+  /** First 4 bytes of the log's topic0: the event selector. */
+  selector: Hex;
+};
+
+/** The issuer chose not to say where the ctHash came from. */
+export type UnlabelledLabel = {
+  kind: 'unlabelled';
+};
+
+export type ShareLabel = StoredValueLabel | EventValueLabel | UnlabelledLabel;

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

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+import { keccak256, size, stringToHex, type Hex } from 'viem';
+import { encodeShareMetadata } from '../encode';
+import { decodeShareAppKey, decodeShareMetadata, decodeShareMetadataFull } from '../decode';
+import { shareAppKey } from '../appKey';
+import type { ShareLabel } from '../schema';
+import { CASES, CONFIDENTIAL_TRANSFER, FUSD, SAMPLE, WORD } from './fixtures';
+
+const handles = (count: number): Hex[] => Array.from({ length: count }, () => WORD);
+
+describe('share metadata codec (v3)', () => {
+  for (const { name, labels, blob } of CASES) {
+    it(`encodes ${name}`, () => {
+      expect(encodeShareMetadata(labels)).toBe(blob);
+    });
+
+    it(`decodes ${name}`, () => {
+      expect(decodeShareMetadata(blob as Hex, handles(labels.length))).toEqual(labels);
+    });
+  }
+
+  it('encodes the real sample into the 122-byte blob, function and event selectors in one list', () => {
+    const blob = encodeShareMetadata(SAMPLE.labels);
+    expect(blob).toBe(SAMPLE.blob);
+    expect(size(blob)).toBe(122);
+    expect(decodeShareMetadata(blob, SAMPLE.handles)).toEqual(SAMPLE.labels);
+  });
+
+  describe('app key', () => {
+    const appKey = shareAppKey('explorer.fhenix.io');
+
+    it('closes the blob with 0x01 and the 32-byte key, after the entries', () => {
+      const blob = encodeShareMetadata(SAMPLE.labels, { appKey });
+      expect(blob).toBe(SAMPLE.blob + '01' + appKey.slice(2));
+      expect(size(blob)).toBe(122 + 33);
+    });
+
+    it('decodes to the same labels, with the key alongside', () => {
+      const blob = encodeShareMetadata(SAMPLE.labels, { appKey });
+      expect(decodeShareMetadata(blob, SAMPLE.handles)).toEqual(SAMPLE.labels);
+      expect(decodeShareMetadataFull(blob, SAMPLE.handles)).toEqual({ labels: SAMPLE.labels, appKey });
+      expect(decodeShareAppKey(blob, SAMPLE.handles)).toBe(appKey);
+    });
+
+    it('is absent from a blob encoded without one, and from a share without metadata', () => {
+      expect(decodeShareAppKey(SAMPLE.blob, SAMPLE.handles)).toBeUndefined();
+      expect(decodeShareAppKey('0x', [])).toBeUndefined();
+      expect(decodeShareAppKey(undefined, [])).toBeUndefined();
+    });
+
+    it('fits a share with no handles: a blob of the key alone', () => {
+      const blob = encodeShareMetadata([], { appKey });
+      expect(blob).toBe('0x03' + '00' + '00' + '00' + '01' + appKey.slice(2));
+      expect(decodeShareMetadataFull(blob, [])).toEqual({ labels: [], appKey });
+    });
+
+    it('is the keccak256 of the app name', () => {
+      expect(appKey).toBe(keccak256(stringToHex('explorer.fhenix.io')));
+      expect(shareAppKey('other.app')).not.toBe(appKey);
+    });
+
+    it('rejects a key that is not 32 bytes, and a trailer that is not a key', () => {
+      expect(() => encodeShareMetadata([], { appKey: '0x1234' })).toThrow('an app key must be 32 bytes');
+      expect(() => decodeShareMetadata((SAMPLE.blob + '02' + appKey.slice(2)) as Hex, SAMPLE.handles)).toThrow(
+        'more entries'
+      );
+    });
+  });
+
+  it('lists a transaction once however many labels name it', () => {
+    const labels: ShareLabel[] = [
+      { kind: 'event', contract: FUSD, block: 10n, txIndex: 1, logIndex: 2, selector: CONFIDENTIAL_TRANSFER },
+      { kind: 'event', contract: FUSD, block: 10n, txIndex: 1, logIndex: 5, selector: CONFIDENTIAL_TRANSFER },
+    ];
+    // version, 1 contract, 1 selector, 1 transaction, two 6-byte entries
+    expect(size(encodeShareMetadata(labels))).toBe(1 + 21 + 5 + 7 + 12);
+  });
+
+  describe('rejects', () => {
+    it('another version', () => {
+      expect(() => decodeShareMetadata('0x02000000ff', handles(1))).toThrow('unsupported version 2');
+    });
+
+    it('a blob that ends in the middle of a field', () => {
+      expect(() => decodeShareMetadata(SAMPLE.blob.slice(0, -2) as Hex, SAMPLE.handles)).toThrow('ends in the middle');
+    });
+
+    it('more entries than ctHashes', () => {
+      expect(() => decodeShareMetadata(SAMPLE.blob, SAMPLE.handles.slice(1))).toThrow('more entries');
+    });
+
+    it('fewer entries than ctHashes', () => {
+      expect(() => decodeShareMetadata(SAMPLE.blob, [...SAMPLE.handles, WORD])).toThrow('ends in the middle');
+    });
+
+    it('a position outside its list', () => {
+      // one contract, no selectors: the event entry points at selector 0
+      const blob = ('0x03' +
+        '01' +
+        FUSD.slice(2) +
+        '00' +
+        '01' +
+        '0000000a0001' +
+        '01' +
+        '00' +
+        '00' +
+        '0002' +
+        '00') as Hex;
+      expect(() => decodeShareMetadata(blob, handles(1))).toThrow('selector 0 is outside the selector list');
+    });
+
+    it('an unknown entry kind', () => {
+      expect(() => decodeShareMetadata(('0x03000000' + '07') as Hex, handles(1))).toThrow('unknown entry kind 7');
+    });
+
+    it('a log index past uint16 when encoding', () => {
+      const label: ShareLabel = {
+        kind: 'event',
+        contract: FUSD,
+        block: 1n,
+        txIndex: 0,
+        logIndex: 70_000,
+        selector: CONFIDENTIAL_TRANSFER,
+      };
+      expect(() => encodeShareMetadata([label])).toThrow();
+    });
+
+    it('a selector that is not 4 bytes when encoding', () => {
+      const label: ShareLabel = {
+        kind: 'stored',
+        contract: FUSD,
+        selector: '0x1234',
+        args: [],
+        returnWord: 0,
+        block: 1n,
+      };
+      expect(() => encodeShareMetadata([label])).toThrow('a selector must be 4 bytes');
+    });
+  });
+});

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

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+import { padHex, parseAbi, toFunctionSelector, type Hex } from 'viem';
+import { describeShareMetadata } from '../describe';
+import { encodeShareMetadata } from '../encode';
+import { BALANCE_OF, CONFIDENTIAL_TRANSFER, FUSD, FUSDY, ISSUER, SAMPLE } from './fixtures';
+
+const TOKEN_ABI = parseAbi([
+  'function confidentialBalanceOf(address account) view returns (bytes32 balance)',
+  'function allowanceAt(address owner, uint256 epoch) view returns (bytes32 previous, bytes32 current)',
+  'event ConfidentialTransfer(address indexed from, address indexed to, bytes32 indexed amount)',
+]);
+
+/** A share by the sample issuer carrying that blob. */
+const share = (metadata: Hex | undefined, handles: readonly Hex[] = SAMPLE.handles) => ({
+  issuer: ISSUER,
+  handles,
+  metadata,
+});
+
+describe('describeShareMetadata', () => {
+  it('names the functions and events of the real sample from the ABIs', () => {
+    const items = describeShareMetadata(share(SAMPLE.blob), { [FUSD]: TOKEN_ABI, [FUSDY]: TOKEN_ABI })!;
+    expect(items).toHaveLength(7);
+
+    const [balance] = items;
+    expect(balance).toMatchObject({
+      kind: 'stored',
+      index: 0,
+      handle: SAMPLE.handles[0],
+      contract: FUSD,
+      block: 314285327n,
+      selector: BALANCE_OF,
+      function: { name: 'confidentialBalanceOf', signature: 'confidentialBalanceOf(address)' },
+      args: [{ name: 'account', type: 'address', isIssuer: true, value: ISSUER, raw: padHex(ISSUER, { size: 32 }) }],
+      output: { name: 'balance', type: 'bytes32' },
+    });
+
+    const transfer = items[6];
+    expect(transfer).toMatchObject({
+      kind: 'event',
+      index: 6,
+      contract: FUSDY,
+      block: 314217333n,
+      txIndex: 12,
+      logIndex: 115,
+      selector: CONFIDENTIAL_TRANSFER,
+      event: {
+        name: 'ConfidentialTransfer',
+        signature: 'ConfidentialTransfer(address,address,bytes32)',
+        inputs: [
+          { name: 'from', type: 'address', indexed: true },
+          { name: 'to', type: 'address', indexed: true },
+          { name: 'amount', type: 'bytes32', indexed: true },
+        ],
+      },
+    });
+  });
+
+  it('matches ABI addresses case-insensitively', () => {
+    const [item] = describeShareMetadata(share(SAMPLE.blob), {
+      [FUSD.toLowerCase() as `0x${string}`]: TOKEN_ABI,
+    })!;
+    expect(item.kind === 'stored' && item.function?.name).toBe('confidentialBalanceOf');
+  });
+
+  it('decodes literal arguments with their ABI types, and names a later return word', () => {
+    const blob = encodeShareMetadata([
+      {
+        kind: 'stored',
+        contract: FUSD,
+        selector: toFunctionSelector('allowanceAt(address,uint256)'),
+        args: [{ type: 'issuer' }, { type: 'word', value: padHex('0x07', { size: 32 }) }],
+        returnWord: 1,
+        block: 1n,
+      },
+    ]);
+    const [item] = describeShareMetadata(share(blob, [SAMPLE.handles[0]]), { [FUSD]: TOKEN_ABI })!;
+    expect(item).toMatchObject({
+      kind: 'stored',
+      function: { name: 'allowanceAt' },
+      args: [
+        { name: 'owner', type: 'address', isIssuer: true, value: ISSUER },
+        { name: 'epoch', type: 'uint256', isIssuer: false, value: 7n },
+      ],
+      output: { name: 'current', type: 'bytes32' },
+    });
+  });
+
+  it('leaves an item raw without an ABI, and never throws for it', () => {
+    const items = describeShareMetadata(share(SAMPLE.blob))!;
+    expect(items[0]).toMatchObject({ kind: 'stored', function: null, output: null, selector: BALANCE_OF });
+    // the issuer comes from the share, ABI or not
+    expect(items[0].kind === 'stored' && items[0].args[0]).toMatchObject({
+      isIssuer: true,
+      raw: padHex(ISSUER, { size: 32 }),
+      value: ISSUER,
+    });
+    expect(items[2]).toMatchObject({ kind: 'event', event: null, selector: CONFIDENTIAL_TRANSFER, logIndex: 30 });
+  });
+
+  it('marks an unlabelled value', () => {
+    const blob = encodeShareMetadata([{ kind: 'unlabelled' }]);
+    expect(describeShareMetadata(share(blob, [SAMPLE.handles[0]]))).toEqual([
+      { kind: 'unlabelled', index: 0, handle: SAMPLE.handles[0], label: { kind: 'unlabelled' } },
+    ]);
+  });
+
+  it('is null for a share without labels', () => {
+    expect(describeShareMetadata(share('0x'))).toBeNull();
+    expect(describeShareMetadata(share(undefined))).toBeNull();
+  });
+});

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