@cofhe/sdk 0.8.0 → 1.0.0

package/acps/share-metadata/decode.ts

@@ -0,0 +1,120 @@
+import { getAddress, hexToBigInt, hexToNumber, size, sliceHex, type Hex } from 'viem';
+import { APP_KEY_TAG, ARGS_CODE, ARG_TAG, ENTRY_KIND, LAYOUT_VERSION, BYTE_WIDTH } from './layout';
+import type { ShareLabel, ShareLabelReadArg } from './schema.js';
+
+/** Sequential reads over a blob. Each take throws when the blob ends before the field does. */
+type Reader = {
+  take: (width: number) => Hex;
+  takeNumber: (width: number) => number;
+  done: () => boolean;
+  remaining: () => number;
+};
+
+const readerOf = (blob: Hex): Reader => {
+  let offset = 0;
+  const take = (width: number): Hex => {
+    if (offset + width > size(blob)) throw new Error('share metadata: the blob ends in the middle of a field');
+    offset += width;
+    return sliceHex(blob, offset - width, offset);
+  };
+  return {
+    take,
+    takeNumber: (width) => hexToNumber(take(width)),
+    done: () => offset === size(blob),
+    remaining: () => size(blob) - offset,
+  };
+};
+
+/** A counted list: its length in one byte, then that many items. */
+const takeList = <T>(reader: Reader, takeItem: () => T): T[] =>
+  Array.from({ length: reader.takeNumber(BYTE_WIDTH.count) }, takeItem);
+
+/** The item an entry points to. Throws when the position is outside the list. */
+const takeFrom = <T>(reader: Reader, list: readonly T[], what: string): T => {
+  const position = reader.takeNumber(BYTE_WIDTH.index);
+  if (position >= list.length) {
+    throw new Error(`share metadata: ${what} ${position} is outside the ${what} list`);
+  }
+  return list[position];
+};
+
+const decodeArg = (reader: Reader): ShareLabelReadArg => {
+  const tag = reader.takeNumber(BYTE_WIDTH.argTag);
+  if (tag === ARG_TAG.issuer) return { type: 'issuer' };
+  if (tag === ARG_TAG.word) return { type: 'word', value: reader.take(BYTE_WIDTH.word) };
+  throw new Error(`share metadata: unknown argument tag ${tag}`);
+};
+
+const decodeArgs = (reader: Reader): { args: ShareLabelReadArg[]; returnWord: number } => {
+  const code = reader.takeNumber(BYTE_WIDTH.argsCode);
+  if (code === ARGS_CODE.none) return { args: [], returnWord: 0 };
+  if (code === ARGS_CODE.issuer) return { args: [{ type: 'issuer' }], returnWord: 0 };
+  if (code !== ARGS_CODE.explicit) throw new Error(`share metadata: unknown args code ${code}`);
+  const returnWord = reader.takeNumber(BYTE_WIDTH.returnWord);
+  return { args: takeList(reader, () => decodeArg(reader)), returnWord };
+};
+
+/** The optional app key that closes the blob: nothing, or the tag byte and 32 bytes. */
+const takeAppKey = (reader: Reader): Hex | undefined => {
+  if (reader.done()) return undefined;
+  const isKey =
+    reader.remaining() === BYTE_WIDTH.count + BYTE_WIDTH.word && reader.takeNumber(BYTE_WIDTH.count) === APP_KEY_TAG;
+  if (!isKey) throw new Error('share metadata: the blob has more entries than the share has ctHashes');
+  return reader.take(BYTE_WIDTH.word);
+};
+
+/** The two things a blob holds: one label per ctHash, and the app key when the share names an app. */
+export type DecodedShareMetadata = { labels: ShareLabel[]; appKey: Hex | undefined };
+
+/**
+ * Decodes a version 3 blob: one label per ctHash, in the order of `acp.handles`, and the app key
+ * when there is one. The exact inverse of `encodeShareMetadata`. Throws on another version, an
+ * unknown kind, code or tag, a position outside its list, and unless the blob holds exactly one
+ * entry per ctHash.
+ */
+export const decodeShareMetadataFull = (blob: Hex, handles: readonly Hex[]): DecodedShareMetadata => {
+  const reader = readerOf(blob);
+  const version = reader.takeNumber(BYTE_WIDTH.version);
+  if (version !== LAYOUT_VERSION) throw new Error(`share metadata: unsupported version ${version}`);
+
+  const contracts = takeList(reader, () => getAddress(reader.take(BYTE_WIDTH.address)));
+  const selectors = takeList(reader, () => reader.take(BYTE_WIDTH.selector));
+  const transactions = takeList(reader, () => ({
+    block: hexToBigInt(reader.take(BYTE_WIDTH.block)),
+    txIndex: reader.takeNumber(BYTE_WIDTH.txIndex),
+  }));
+
+  const labels = handles.map((): ShareLabel => {
+    const kind = reader.takeNumber(BYTE_WIDTH.kind);
+    switch (kind) {
+      case ENTRY_KIND.stored: {
+        const contract = takeFrom(reader, contracts, 'contract');
+        const selector = takeFrom(reader, selectors, 'selector');
+        const block = hexToBigInt(reader.take(BYTE_WIDTH.block));
+        return { kind: 'stored', contract, selector, ...decodeArgs(reader), block };
+      }
+      case ENTRY_KIND.event: {
+        const contract = takeFrom(reader, contracts, 'contract');
+        const { block, txIndex } = takeFrom(reader, transactions, 'transaction');
+        const logIndex = reader.takeNumber(BYTE_WIDTH.logIndex);
+        const selector = takeFrom(reader, selectors, 'selector');
+        return { kind: 'event', contract, block, txIndex, logIndex, selector };
+      }
+      case ENTRY_KIND.unlabelled:
+        return { kind: 'unlabelled' };
+      default:
+        throw new Error(`share metadata: unknown entry kind ${kind}`);
+    }
+  });
+  const appKey = takeAppKey(reader);
+  if (!reader.done()) throw new Error('share metadata: the blob has more entries than the share has ctHashes');
+  return { labels, appKey };
+};
+
+/** The labels of a blob, one per ctHash in the order of `acp.handles` (see `decodeShareMetadataFull`). */
+export const decodeShareMetadata = (blob: Hex, handles: readonly Hex[]): ShareLabel[] =>
+  decodeShareMetadataFull(blob, handles).labels;
+
+/** The app key a share was posted with, or undefined: for a share without metadata, or without a key. */
+export const decodeShareAppKey = (metadata: Hex | undefined, handles: readonly Hex[]): Hex | undefined =>
+  metadata == null || metadata === '0x' ? undefined : decodeShareMetadataFull(metadata, handles).appKey;

package/acps/share-metadata/describe.ts

@@ -0,0 +1,198 @@
+import {
+  decodeAbiParameters,
+  padHex,
+  toEventSelector,
+  toEventSignature,
+  toFunctionSelector,
+  toFunctionSignature,
+  type Abi,
+  type AbiEvent,
+  type AbiFunction,
+  type AbiParameter,
+  type Address,
+  type Hex,
+} from 'viem';
+import { decodeShareMetadata } from './decode.js';
+import type { EventValueLabel, ShareLabel, StoredValueLabel } from './schema.js';
+import type { LabelledShare } from '../types';
+
+/** A parameter as the ABI names it. `name` is absent when the ABI leaves it unnamed. */
+export type ShareLabelParam = { name?: string; type: string; indexed?: boolean };
+
+/** One argument of a stored-value read, decoded with the function's input type when the ABI has one. */
+export type ShareLabelArg = ShareLabelParam & {
+  /** The argument stands for the share issuer. */
+  isIssuer: boolean;
+  /** The 32-byte ABI word, or undefined for an issuer argument when no issuer was given. */
+  raw: Hex | undefined;
+  /** The decoded value (an address, a bigint, ...), or the raw word when there is no ABI type for it. */
+  value: unknown;
+};
+
+type DescriptionBase = {
+  /** Position of the ctHash in `acp.handles`. */
+  index: number;
+  handle: Hex;
+};
+
+export type StoredValueDescription = DescriptionBase & {
+  kind: 'stored';
+  label: StoredValueLabel;
+  contract: Address;
+  block: bigint;
+  selector: Hex;
+  /** The view function, or null when the ABI of the contract is missing or has no function with this selector. */
+  function: { name: string; signature: string; inputs: ShareLabelParam[] } | null;
+  args: ShareLabelArg[];
+  /** The returned field that holds the ctHash, when the ABI names the outputs. */
+  output: ShareLabelParam | null;
+};
+
+export type EventValueDescription = DescriptionBase & {
+  kind: 'event';
+  label: EventValueLabel;
+  contract: Address;
+  block: bigint;
+  txIndex: number;
+  logIndex: number;
+  selector: Hex;
+  /**
+   * The event, or null when the ABI of the contract is missing or has no event with this selector.
+   * Parameter values are not in the label; they come with the log fetched to verify it.
+   */
+  event: { name: string; signature: string; inputs: ShareLabelParam[] } | null;
+};
+
+export type UnlabelledDescription = DescriptionBase & {
+  kind: 'unlabelled';
+  label: ShareLabel & { kind: 'unlabelled' };
+};
+
+export type ShareLabelDescription = StoredValueDescription | EventValueDescription | UnlabelledDescription;
+
+/** ABIs by contract address; addresses compare case-insensitively. */
+export type ShareLabelAbis = Readonly<Record<Address, Abi>>;
+
+const abiOf = (abis: ShareLabelAbis, contract: Address): Abi | undefined => {
+  const wanted = contract.toLowerCase();
+  const key = (Object.keys(abis) as Address[]).find((address) => address.toLowerCase() === wanted);
+  return key ? abis[key] : undefined;
+};
+
+const paramOf = ({ name, type, ...rest }: AbiParameter): ShareLabelParam => {
+  const param: ShareLabelParam = { type };
+  if (name) param.name = name;
+  if ('indexed' in rest && typeof rest.indexed === 'boolean') param.indexed = rest.indexed;
+  return param;
+};
+
+const findFunction = (abi: Abi | undefined, selector: Hex): AbiFunction | undefined =>
+  abi?.find(
+    (item): item is AbiFunction =>
+      item.type === 'function' && toFunctionSelector(item).toLowerCase() === selector.toLowerCase()
+  );
+
+const findEvent = (abi: Abi | undefined, selector: Hex): AbiEvent | undefined =>
+  abi?.find(
+    (item): item is AbiEvent =>
+      item.type === 'event' && toEventSelector(item).toLowerCase().startsWith(selector.toLowerCase())
+  );
+
+const decodeWord = (input: AbiParameter | undefined, raw: Hex): unknown => {
+  if (input == null) return raw;
+  try {
+    return decodeAbiParameters([input], raw)[0];
+  } catch {
+    return raw;
+  }
+};
+
+const describeStored = (
+  base: DescriptionBase,
+  label: StoredValueLabel,
+  abis: ShareLabelAbis,
+  issuer: Address | undefined
+): StoredValueDescription => {
+  const fn = findFunction(abiOf(abis, label.contract), label.selector);
+  const args = label.args.map((arg, i): ShareLabelArg => {
+    const input = fn?.inputs[i];
+    const param = input ? paramOf(input) : { type: 'bytes32' };
+    if (arg.type === 'issuer') {
+      return {
+        ...param,
+        isIssuer: true,
+        raw: issuer ? padHex(issuer, { size: 32 }) : undefined,
+        value: issuer,
+      };
+    }
+    return { ...param, isIssuer: false, raw: arg.value, value: decodeWord(input, arg.value) };
+  });
+  const output = fn?.outputs[label.returnWord];
+  return {
+    ...base,
+    kind: 'stored',
+    label,
+    contract: label.contract,
+    block: label.block,
+    selector: label.selector,
+    function: fn ? { name: fn.name, signature: toFunctionSignature(fn), inputs: fn.inputs.map(paramOf) } : null,
+    args,
+    output: output ? paramOf(output) : null,
+  };
+};
+
+const describeEvent = (base: DescriptionBase, label: EventValueLabel, abis: ShareLabelAbis): EventValueDescription => {
+  const event = findEvent(abiOf(abis, label.contract), label.selector);
+  return {
+    ...base,
+    kind: 'event',
+    label,
+    contract: label.contract,
+    block: label.block,
+    txIndex: label.txIndex,
+    logIndex: label.logIndex,
+    selector: label.selector,
+    event: event ? { name: event.name, signature: toEventSignature(event), inputs: event.inputs.map(paramOf) } : null,
+  };
+};
+
+/**
+ * Turns decoded labels into structured, human-readable items, one per ctHash in the order of
+ * `handles`: the function name and decoded arguments of a stored value, the event name and
+ * parameters of an event value. A contract without an ABI, or a selector its ABI doesn't have,
+ * leaves the item in raw form (`function` / `event` null); this never throws. `issuer` (the share
+ * issuer) fills in the arguments that stand for it.
+ */
+export const describeShareLabels = (
+  labels: readonly ShareLabel[],
+  handles: readonly Hex[],
+  abis: ShareLabelAbis = {},
+  options: { issuer?: Address } = {}
+): ShareLabelDescription[] =>
+  labels.map((label, index): ShareLabelDescription => {
+    const base = { index, handle: handles[index] };
+    switch (label.kind) {
+      case 'stored':
+        return describeStored(base, label, abis, options.issuer);
+      case 'event':
+        return describeEvent(base, label, abis);
+      case 'unlabelled':
+        return { ...base, kind: 'unlabelled', label };
+    }
+  });
+
+/**
+ * Decodes a share's metadata blob and describes it: `decodeShareMetadata` then
+ * `describeShareLabels`, with the share's issuer filling in the arguments that stand for it. The
+ * share is one read from the registry or an acp imported from exported JSON. Null for a share
+ * without labels (no metadata, or `0x`). Throws only when the blob itself is malformed; missing
+ * ABIs leave items in raw form.
+ */
+export const describeShareMetadata = (
+  share: LabelledShare,
+  abis: ShareLabelAbis = {}
+): ShareLabelDescription[] | null => {
+  const { issuer, handles, metadata } = share;
+  if (metadata == null || metadata === '0x') return null;
+  return describeShareLabels(decodeShareMetadata(metadata, handles), handles, abis, { issuer });
+};

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