@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/acps/share-metadata/encode.ts

@@ -0,0 +1,147 @@
+import { concatHex, isHex, numberToHex, padHex, size, type Address, type Hex } from 'viem';
+import { APP_KEY_TAG, ARGS_CODE, ARG_TAG, ENTRY_KIND, LAYOUT_VERSION, BYTE_WIDTH } from './layout';
+import type { ShareLabel, ShareLabelReadArg, StoredValueLabel } from './schema';
+
+/** An unsigned big-endian integer in exactly that many bytes. Throws when the value does not fit. */
+const uint = (value: number | bigint, width: number): Hex => numberToHex(value, { size: width });
+
+/** The byte-string fields of the blob: the width each must have, and how an error names it. */
+const BYTES_FIELD = {
+  contract: { width: BYTE_WIDTH.address, name: 'a contract address' },
+  selector: { width: BYTE_WIDTH.selector, name: 'a selector' },
+  viewCallArgument: { width: BYTE_WIDTH.word, name: 'a view call argument' },
+  appKey: { width: BYTE_WIDTH.word, name: 'an app key' },
+} as const;
+
+/** A byte string for that field, checked to be exactly as wide as the field. */
+const bytesField = (field: keyof typeof BYTES_FIELD, value: Hex): Hex => {
+  const { width, name } = BYTES_FIELD[field];
+  if (!isHex(value, { strict: true }) || size(value) !== width) {
+    throw new Error(`share metadata: ${name} must be ${width} bytes`);
+  }
+  return value.toLowerCase() as Hex;
+};
+
+/**
+ * A list of distinct items in order of first use. `insert` adds an item unless an equal one is
+ * already listed; `positionOf` looks an item up and throws when it was never inserted.
+ */
+const listOf = <T>(keyOf: (item: T) => string, what: string) => {
+  const items: T[] = [];
+  const positions = new Map<string, number>();
+  const insert = (item: T): void => {
+    const key = keyOf(item);
+    if (positions.has(key)) return;
+    positions.set(key, items.length);
+    items.push(item);
+  };
+  const positionOf = (item: T): number => {
+    const position = positions.get(keyOf(item));
+    if (position === undefined) throw new Error(`share metadata: ${what} ${keyOf(item)} was not collected`);
+    return position;
+  };
+  return { items, insert, positionOf };
+};
+
+type Transaction = { block: bigint; txIndex: number };
+
+const keyOfContract = (contract: Address): string => contract.toLowerCase();
+const keyOfSelector = (selector: Hex): string => selector.toLowerCase();
+const keyOfTransaction = ({ block, txIndex }: Transaction): string => `${block}:${txIndex}`;
+
+const transactionOf = ({ block, txIndex }: Transaction): Transaction => ({ block, txIndex });
+
+const encodeArg = (arg: ShareLabelReadArg): Hex => {
+  if (arg.type === 'issuer') return uint(ARG_TAG.issuer, BYTE_WIDTH.argTag);
+  return concatHex([uint(ARG_TAG.word, BYTE_WIDTH.argTag), bytesField('viewCallArgument', arg.value)]);
+};
+
+/** The issuer's address as a 32-byte word: the value `ARGS_CODE.issuer` and `ARG_TAG.issuer` stand for. */
+const issuerWordOf = (issuer: Address | undefined): Hex | undefined =>
+  issuer == null ? undefined : (padHex(issuer, { size: BYTE_WIDTH.word }).toLowerCase() as Hex);
+
+/** A literal argument that is the issuer's address becomes "the issuer": one byte, and no address in the blob. */
+const asIssuer = (arg: ShareLabelReadArg, issuerWord: Hex | undefined): ShareLabelReadArg =>
+  arg.type === 'word' && issuerWord != null && arg.value.toLowerCase() === issuerWord ? { type: 'issuer' } : arg;
+
+/**
+ * The two common shapes take one byte: no arguments, or the share issuer alone, both with the
+ * ctHash as the first return word. Anything else is spelled out.
+ */
+const encodeArgs = ({ args: given, returnWord }: StoredValueLabel, issuerWord: Hex | undefined): Hex => {
+  const args = given.map((arg) => asIssuer(arg, issuerWord));
+  if (returnWord === 0 && args.length === 0) return uint(ARGS_CODE.none, BYTE_WIDTH.argsCode);
+  if (returnWord === 0 && args.length === 1 && args[0].type === 'issuer') {
+    return uint(ARGS_CODE.issuer, BYTE_WIDTH.argsCode);
+  }
+  return concatHex([
+    uint(ARGS_CODE.explicit, BYTE_WIDTH.argsCode),
+    uint(returnWord, BYTE_WIDTH.returnWord),
+    uint(args.length, BYTE_WIDTH.count),
+    ...args.map(encodeArg),
+  ]);
+};
+
+/**
+ * Encodes the labels of a share into a version 3 blob: one label per ctHash, in the order of
+ * `acp.handles`. The contracts, selectors and transactions the labels name are listed once each,
+ * in order of first use; function and event selectors share one list. Throws on a value that does
+ * not fit its field (more than 255 contracts, a block past uint32, ...). Given the share `issuer`, a
+ * stored-value argument equal to their address is stored as "the issuer" instead of the address.
+ * Given an `appKey` (`shareAppKey(app)`), it closes the blob, so the app can tell its shares apart.
+ */
+export const encodeShareMetadata = (
+  labels: readonly ShareLabel[],
+  { issuer, appKey }: { issuer?: Address; appKey?: Hex } = {}
+): Hex => {
+  const issuerWord = issuerWordOf(issuer);
+
+  // First pass: collect what the labels name, so each list is complete before any entry points into it.
+  const contracts = listOf(keyOfContract, 'contract');
+  const selectors = listOf(keyOfSelector, 'selector');
+  const transactions = listOf(keyOfTransaction, 'transaction');
+  for (const label of labels) {
+    if (label.kind === 'unlabelled') continue;
+    contracts.insert(label.contract);
+    selectors.insert(label.selector);
+    if (label.kind === 'event') transactions.insert(transactionOf(label));
+  }
+
+  // Second pass: one entry per label, pointing into the lists by position.
+  const entries = labels.map((label): Hex => {
+    switch (label.kind) {
+      case 'stored':
+        return concatHex([
+          uint(ENTRY_KIND.stored, BYTE_WIDTH.kind),
+          uint(contracts.positionOf(label.contract), BYTE_WIDTH.index),
+          uint(selectors.positionOf(label.selector), BYTE_WIDTH.index),
+          uint(label.block, BYTE_WIDTH.block),
+          encodeArgs(label, issuerWord),
+        ]);
+      case 'event':
+        return concatHex([
+          uint(ENTRY_KIND.event, BYTE_WIDTH.kind),
+          uint(contracts.positionOf(label.contract), BYTE_WIDTH.index),
+          uint(transactions.positionOf(transactionOf(label)), BYTE_WIDTH.index),
+          uint(label.logIndex, BYTE_WIDTH.logIndex),
+          uint(selectors.positionOf(label.selector), BYTE_WIDTH.index),
+        ]);
+      case 'unlabelled':
+        return uint(ENTRY_KIND.unlabelled, BYTE_WIDTH.kind);
+    }
+  });
+
+  return concatHex([
+    uint(LAYOUT_VERSION, BYTE_WIDTH.version),
+    uint(contracts.items.length, BYTE_WIDTH.count),
+    ...contracts.items.map((contract) => bytesField('contract', contract)),
+    uint(selectors.items.length, BYTE_WIDTH.count),
+    ...selectors.items.map((selector) => bytesField('selector', selector)),
+    uint(transactions.items.length, BYTE_WIDTH.count),
+    ...transactions.items.map((tx) =>
+      concatHex([uint(tx.block, BYTE_WIDTH.block), uint(tx.txIndex, BYTE_WIDTH.txIndex)])
+    ),
+    ...entries,
+    ...(appKey == null ? [] : [uint(APP_KEY_TAG, BYTE_WIDTH.count), bytesField('appKey', appKey)]),
+  ]);
+};

package/acps/share-metadata/erc7984.ts

@@ -0,0 +1,26 @@
+import type { Abi } from 'viem';
+
+/**
+ * The parts of ERC-7984 (confidential tokens) that share labels most often point at: the balance
+ * read and the transfer event. One definition for the SDK's label presets and for apps, with
+ * `internalType` kept so `@cofhe/abi` recognises the encrypted values.
+ */
+export const ERC7984_ABI = [
+  {
+    type: 'function',
+    name: 'confidentialBalanceOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'account', type: 'address', internalType: 'address' }],
+    outputs: [{ name: '', type: 'bytes32', internalType: 'euint64' }],
+  },
+  {
+    type: 'event',
+    name: 'ConfidentialTransfer',
+    anonymous: false,
+    inputs: [
+      { name: 'from', type: 'address', indexed: true, internalType: 'address' },
+      { name: 'to', type: 'address', indexed: true, internalType: 'address' },
+      { name: 'amount', type: 'bytes32', indexed: true, internalType: 'euint64' },
+    ],
+  },
+] as const satisfies Abi;

package/acps/share-metadata/index.ts

@@ -0,0 +1,9 @@
+export * from './schema';
+export { LAYOUT_VERSION as SHARE_METADATA_VERSION } from './layout';
+export * from './encode';
+export * from './decode';
+export * from './verify';
+export * from './describe';
+export * from './presets';
+export * from './erc7984';
+export * from './appKey';

package/acps/share-metadata/layout.ts

@@ -0,0 +1,69 @@
+/**
+ * Byte layout of a share metadata blob, version 3. Integers are big-endian; sizes in bytes.
+ *
+ *   blob         = version (1)
+ *                | contract count (1)    | contracts (20 each)
+ *                | selector count (1)    | selectors (4 each)       function selectors, and event
+ *                                                                   selectors (first 4 bytes of topic0)
+ *                | transaction count (1) | transactions (6 each: block 4, tx index 2)
+ *                | entries, one per ctHash, in the order of acp.handles
+ *                | app key, optional: 0x01 | key (32)       keccak256 of the name of the app the
+ *                                                           share is for; absent when the blob ends
+ *
+ *   stored value = 0x00 | contract (1) | selector (1) | block (4) | args                  8 bytes or more
+ *   event value  = 0x01 | contract (1) | transaction (1) | log index (2) | selector (1)   6 bytes
+ *   unlabelled   = 0xff                                                                   1 byte
+ *
+ *   args         = 0x00                                   no arguments, return word 0
+ *                | 0x01                                   one argument, the share issuer, return word 0
+ *                | 0xff | return word (1) | count (1) | argument, count times
+ *   argument     = 0x00 | word (32)                       a literal ABI word
+ *                | 0x01                                   the share issuer
+ *
+ * Contracts, selectors and transactions are listed once; entries refer to them by position.
+ * The log index is block-wide, as RPC nodes return it.
+ */
+
+export const LAYOUT_VERSION = 0x03;
+
+export const ENTRY_KIND = {
+  stored: 0x00,
+  event: 0x01,
+  unlabelled: 0xff,
+} as const;
+
+/** The args byte of a stored-value entry: the two common shapes in one byte, or an explicit list. */
+export const ARGS_CODE = {
+  none: 0x00,
+  issuer: 0x01,
+  explicit: 0xff,
+} as const;
+
+export const ARG_TAG = {
+  word: 0x00,
+  issuer: 0x01,
+} as const;
+
+/** The one byte that opens the optional app key section at the end of the blob. */
+export const APP_KEY_TAG = 0x01;
+
+/** Field widths in bytes. */
+export const BYTE_WIDTH = {
+  version: 1,
+  /** Length of a list, and a position in it: at most 255 of each per share. */
+  count: 1,
+  index: 1,
+  address: 20,
+  selector: 4,
+  /** uint32: 4.29 billion blocks. */
+  block: 4,
+  /** uint16: the position of a transaction within its block. */
+  txIndex: 2,
+  /** uint16: the block-wide position of a log (a busy block passes 255 logs). */
+  logIndex: 2,
+  kind: 1,
+  argsCode: 1,
+  returnWord: 1,
+  argTag: 1,
+  word: 32,
+} as const;

package/acps/share-metadata/presets.ts

@@ -0,0 +1,116 @@
+import {
+  encodeAbiParameters,
+  size,
+  sliceHex,
+  toFunctionSelector,
+  type Abi,
+  type AbiFunction,
+  type Address,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type Log,
+} from 'viem';
+import { BYTE_WIDTH } from './layout';
+import type { EventValueLabel, ShareLabel, ShareLabelReadArg, StoredValueLabel } from './schema';
+
+/**
+ * Builders for labels. The format knows nothing about tokens: a balance is the value a view
+ * function returned, a transfer amount the value of one event.
+ */
+
+export type ViewFunctionLabelOptions<
+  abi extends Abi,
+  functionName extends ContractFunctionName<abi, 'pure' | 'view'>,
+> = {
+  contract: Address;
+  abi: abi;
+  functionName: functionName;
+  /**
+   * The arguments of the call, static ABI types only. One equal to the share issuer's address
+   * (your own, when you share your balance) is stored as "the issuer" when the labels are encoded.
+   */
+  args?: ContractFunctionArgs<abi, 'pure' | 'view', functionName>;
+  /** Block the value was read at (on Arbitrum: the L2 block number). */
+  block: bigint;
+  /** Which 32-byte word of the return data is the ctHash; 0 (the default) for a single return value. */
+  returnWord?: number;
+};
+
+const findViewFunction = (abi: Abi, name: string, arity: number): AbiFunction => {
+  const named = abi.filter((item): item is AbiFunction => item.type === 'function' && item.name === name);
+  if (named.length === 0) throw new Error(`share metadata: the ABI has no function ${name}`);
+  const fitting = named.filter((fn) => fn.inputs.length === arity);
+  if (fitting.length !== 1) {
+    throw new Error(
+      named.length === 1
+        ? `share metadata: ${name} takes ${named[0].inputs.length} arguments, ${arity} given`
+        : `share metadata: no single overload of ${name} takes ${arity} arguments`
+    );
+  }
+  const [fn] = fitting;
+  if (fn.stateMutability !== 'view' && fn.stateMutability !== 'pure') {
+    throw new Error(`share metadata: ${name} is not a view function`);
+  }
+  return fn;
+};
+
+const encodeReadArg = (fn: AbiFunction, index: number, value: unknown): ShareLabelReadArg => {
+  const input = fn.inputs[index];
+  const word = encodeAbiParameters([input], [value]);
+  if (size(word) !== BYTE_WIDTH.word) {
+    throw new Error(
+      `share metadata: argument ${index} of ${fn.name} is ${input.type}; only arguments of one static 32-byte word can be labelled`
+    );
+  }
+  return { type: 'word', value: word };
+};
+
+/**
+ * The label of a value a view function returned at a block, built from the contract's ABI: the
+ * function's selector, and each argument ABI-encoded to its word. Throws when the ABI has no such
+ * function, the arity is off, or an argument is not one static word.
+ */
+export const viewFunctionLabel = <
+  const abi extends Abi,
+  functionName extends ContractFunctionName<abi, 'pure' | 'view'>,
+>(
+  options: ViewFunctionLabelOptions<abi, functionName>
+): StoredValueLabel => {
+  const { contract, block, returnWord = 0 } = options;
+  const values = (options.args ?? []) as readonly unknown[];
+  const fn = findViewFunction(options.abi, options.functionName, values.length);
+  return {
+    kind: 'stored',
+    contract,
+    selector: toFunctionSelector(fn),
+    args: values.map((value, i) => encodeReadArg(fn, i, value)),
+    returnWord,
+    block,
+  };
+};
+
+/**
+ * The label of a value carried by a log, as viem returns it from `getLogs` / `getContractEvents`:
+ * its contract, block, transaction and log index, and its event selector. Throws for a pending log.
+ */
+export const eventLogLabel = (
+  log: Pick<Log, 'address' | 'blockNumber' | 'transactionIndex' | 'logIndex' | 'topics'>
+): EventValueLabel => {
+  const { address, blockNumber, transactionIndex, logIndex, topics } = log;
+  const topic0 = topics[0];
+  if (blockNumber == null || transactionIndex == null || logIndex == null) {
+    throw new Error('share metadata: a pending log has no position to label');
+  }
+  if (topic0 == null || size(topic0) !== 32) throw new Error('share metadata: an anonymous log has no event selector');
+  return {
+    kind: 'event',
+    contract: address,
+    block: blockNumber,
+    txIndex: transactionIndex,
+    logIndex,
+    selector: sliceHex(topic0, 0, 4),
+  };
+};
+
+/** The label of a ctHash the issuer chooses not to describe. */
+export const UNLABELLED: ShareLabel = { kind: 'unlabelled' };

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