@cofhe/sdk 0.8.0 → 1.0.0-alpha.0

package/acps/acp.ts

@@ -27,6 +27,11 @@ import {
 import { SignatureUtils } from './signature.js';
 import { GenerateSealingKey, unsealWithPrivateKey } from './sealing.js';
 import { checkACPValidityOnChain, getACPAccessStatusOnChain, getAclEIP712Domain } from './onchain-utils.js';
+import { encodeShareMetadata } from './share-metadata/encode.js';
+import { UNLABELLED } from './share-metadata/presets';
+
+/** The name of an imported acp unless the recipient gives one: who it came from. */
+const sharedByName = (issuer: Hex): string => `Shared by ${issuer.slice(0, 6)}…${issuer.slice(-4)}`;
 
 /**
  * Main ACP utilities - functional approach for React compatibility
@@ -57,6 +62,15 @@ export const ACPUtils = {
    */
   createSharing: (options: CreateSharingACPOptions): SharingACP => {
     const validation = validateSharingACPOptions(options);
+    const { labels, appKey } = options;
+    if (labels != null && labels.length !== validation.handles.length) {
+      throw new Error(`Cannot label a share of ${validation.handles.length} handles with ${labels.length} labels`);
+    }
+    // With an app key but no labels, the handles are listed as unlabelled so the key has a blob to sit in.
+    const metadata =
+      labels != null || appKey != null
+        ? encodeShareMetadata(labels ?? validation.handles.map(() => UNLABELLED), { issuer: validation.issuer, appKey })
+        : undefined;
 
     // Always generate a new sealing key - users cannot provide their own
     const sealingPair = GenerateSealingKey();
@@ -64,6 +78,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      ...(metadata != null && { metadata }),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -73,9 +88,10 @@ export const ACPUtils = {
   },
 
   /**
-   * Import a shared acp from various input formats
+   * Import a shared acp from various input formats. The acp is named `name`, or after its issuer
+   * ("Shared by 0x1234…abcd"); a `name` in the share itself is ignored.
    */
-  importShared: (options: ImportSharedACPOptions | string): RecipientACP => {
+  importShared: (options: ImportSharedACPOptions | string, { name }: { name?: string } = {}): RecipientACP => {
     let parsedOptions: ImportSharedACPOptions;
 
     // Handle different input types
@@ -106,6 +122,7 @@ export const ACPUtils = {
     const acp = {
       hash: ACPUtils.getHash(validation),
       ...validation,
+      name: name?.trim() || sharedByName(validation.issuer),
       sealingPrivateKey: sealingPair.privateKey,
       sealingKey: sealingPair.publicKey,
       _signedDomain: undefined,
@@ -184,9 +201,10 @@ export const ACPUtils = {
   importSharedAndSign: async (
     options: ImportSharedACPOptions | string,
     publicClient: PublicClient,
-    walletClient: WalletClient
+    walletClient: WalletClient,
+    importOptions: { name?: string } = {}
   ): Promise<RecipientACP> => {
-    const acp = ACPUtils.importShared(options);
+    const acp = ACPUtils.importShared(options, importOptions);
     return ACPUtils.sign(acp, publicClient, walletClient);
   },
 
@@ -218,6 +236,7 @@ export const ACPUtils = {
       recipientSignature: acp.recipientSignature,
       _signedDomain: acp._signedDomain,
       sealingPrivateKey: acp.sealingPrivateKey,
+      ...(acp.metadata != null && { metadata: acp.metadata }),
     };
   },
 
@@ -297,7 +316,7 @@ export const ACPUtils = {
   /**
    * Export acp data for sharing (strips the private component).
    * Fixed `SharedACP` shape — every field always present, aligned with
-   * `ACPPublic` and the on-chain sharing payload.
+   * `ACPPublic` and the on-chain sharing payload — plus `metadata` when the acp has labels.
    */
   export: (acp: ACP): string => {
     if (acp.type !== 'sharing') {
@@ -312,7 +331,6 @@ export const ACPUtils = {
     }
 
     const shared: SharedACP = {
-      name: acp.name,
       type: acp.type,
       issuer: acp.issuer,
       expiration: acp.expiration,
@@ -323,6 +341,7 @@ export const ACPUtils = {
       contracts: acp.contracts,
       handles: acp.handles,
       issuerSignature: acp.issuerSignature,
+      ...(acp.metadata != null && acp.metadata !== '0x' && { metadata: acp.metadata }),
     };
 
     return JSON.stringify(shared, undefined, 2);

package/acps/index.ts

@@ -9,18 +9,23 @@ export type {
   ACPPublic,
   SharedACP,
   IncomingShare,
+  LabelledShare,
   EIP712Domain,
   EIP712Types,
   EIP712Message,
   ValidationResult,
   ACPSignaturePrimaryType,
-} from './types.js';
+} from './types';
 
 // Main utilities
-export { ACPUtils } from './acp.js';
+export { ACPUtils } from './acp';
 
-// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP
-export * from './registry.js';
+// On-chain sharing: registry / revoker ABIs, the registry payload and share id of a sharing ACP,
+// and the read of posted shares from their Shared events
+export * from './registry';
+
+// Share metadata: labels saying where each handle of a SNAPSHOT share came from
+export * from './share-metadata/index';
 
 // Addresses the chain ACL serves (TaskManager -> acl() -> default revoker, share registry)
 export {
@@ -28,7 +33,7 @@ export {
   getAclServedAddresses,
   clearAclServedAddresses,
   type AclServedAddresses,
-} from './onchain-utils.js';
+} from './onchain-utils';
 
 // Validation utilities
 export {
@@ -49,10 +54,10 @@ export {
   validateImportACP,
   // Common utilities
   ValidationUtils,
-} from './validation.js';
+} from './validation';
 
 // Signature utilities
-export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature.js';
+export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature';
 
 // Storage utilities
 export {
@@ -67,15 +72,15 @@ export {
   removeActiveACPHash,
   clearStaleStore,
   ACP_STORE_DEFAULTS,
-} from './store.js';
+} from './store';
 
 // Sealing utilities
-export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing.js';
-export type { EthEncryptedData } from './sealing.js';
+export { GenerateSealingKey, seal, unsealWithPrivateKey, type SealingKeyPair } from './sealing';
+export type { EthEncryptedData } from './sealing';
 
 // Re-export everything for convenience
-export * from './types.js';
-export * from './acp.js';
-export * from './validation.js';
-export * from './signature.js';
-export * from './store.js';
+export * from './types';
+export * from './acp';
+export * from './validation';
+export * from './signature';
+export * from './store';

package/acps/registry.ts

@@ -1,11 +1,25 @@
-import { encodeAbiParameters, keccak256, parseAbi, type AbiParameterToPrimitiveType, type Hex } from 'viem';
+import {
+  encodeAbiParameters,
+  keccak256,
+  parseAbi,
+  type AbiParameterToPrimitiveType,
+  type Address,
+  type Hex,
+  type PublicClient,
+} from 'viem';
 import { ACPUtils } from './acp.js';
 import type { ACP } from './types.js';
 
 /**
  * The on-chain sharing pieces: the share registry and revoker ABIs, the registry payload of a
- * sharing ACP and its share id. Exported so an app can send these writes through its own
- * transaction path and still agree with the registry on ids.
+ * sharing ACP and its share id, and the read of a share from its `Shared` event. Exported so an
+ * app can send these writes through its own transaction path and still agree with the registry
+ * on ids.
+ *
+ * The registry is pointer-based: storage keeps a share header (issuer, expiration, recipient,
+ * revoker, and the block of its `Shared` event); the full payload and the metadata blob travel in
+ * that event. A reader takes headers from `sharesFor` / `getShare` and fetches the events with one
+ * single-block `getLogs` per block.
  */
 
 // ACP default revoker (timestamp-based revocation) — interface shared by all revokers
@@ -19,11 +33,14 @@ export const ACP_REVOKER_ABI = parseAbi([
 
 export const ACP_SHARE_REGISTRY_ABI = parseAbi([
   'struct ACP { address issuer; uint64 expiration; address recipient; uint256 revokerData; address revokerContract; uint8 scope; address[] contracts; bytes32[] handles; bytes32 sealingKey; bytes issuerSignature; bytes recipientSignature; }',
-  'function share(ACP calldata acp) external returns (bytes32)',
+  'struct ShareHeader { address issuer; uint64 expiration; address recipient; uint64 blockNumber; address revokerContract; uint256 revokerData; }',
+  'function share(ACP calldata acp, bytes calldata metadata) external returns (bytes32)',
   'function removeShare(bytes32 shareId) external',
-  'function sharesFor(address recipient) external view returns (ACP[] memory)',
-  'function getShare(bytes32 shareId) external view returns (ACP memory)',
+  'function sharesFor(address recipient) external view returns (bytes32[] shareIds, ShareHeader[] headers)',
+  'function getShare(bytes32 shareId) external view returns (ShareHeader memory)',
   'function isShareValid(bytes32 shareId) external view returns (bool)',
+  'event Shared(address indexed recipient, address indexed issuer, bytes32 indexed shareId, ACP acp, bytes metadata)',
+  'event ShareRemoved(address indexed recipient, address indexed issuer, bytes32 indexed shareId)',
 ]);
 
 export const ACP_SHARE_TUPLE_ABI = [
@@ -68,6 +85,147 @@ export const computeShareId = (acp: ACP): Hex => {
   return keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [p]));
 };
 
-/** The share id of a registry payload as read back from `sharesFor` / `getShare`. */
-export const shareIdOfChainShare = (share: AbiParameterToPrimitiveType<(typeof ACP_SHARE_TUPLE_ABI)[0]>): Hex =>
+/** The share id of a registry payload as read back from a `Shared` event. */
+export const shareIdOfChainShare = (share: ChainShare): Hex =>
   keccak256(encodeAbiParameters(ACP_SHARE_TUPLE_ABI, [share]));
+
+/** A registry payload, as decoded from a `Shared` event (or passed to `share`). */
+export type ChainShare = AbiParameterToPrimitiveType<(typeof ACP_SHARE_TUPLE_ABI)[0]>;
+
+/** What the registry stores of a share: the fields it checks, and the block of its `Shared` event. */
+export type ShareHeader = {
+  issuer: Address;
+  expiration: bigint;
+  recipient: Address;
+  /** Block of the `Shared` event (the L2 block on Arbitrum). */
+  blockNumber: bigint;
+  revokerContract: Address;
+  revokerData: bigint;
+};
+
+/** A share as posted: its payload and the metadata blob that came with it (`0x` when none). */
+export type PostedShare = { shareId: Hex; header: ShareHeader; share: ChainShare; metadata: Hex };
+
+/** A share the registry lists but whose `Shared` event could not be read, and why. */
+export type UnreadableShare = { shareId: Hex; header: ShareHeader; reason: string };
+
+/** Shares read from their events, and those that could not be; each share is on its own. */
+export type PostedShares = { posted: PostedShare[]; unreadable: UnreadableShare[] };
+
+const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/**
+ * Fetches the `Shared` events of shares from the blocks their headers name: one single-block
+ * `getLogs` per distinct block, filtered by registry and share ids, so any node answers it. Returns
+ * the shares in the order given; where a block holds several events for one share id, the last.
+ * Never fails as a whole: a share whose block the node cannot serve yet, whose event is missing
+ * from it, or whose event payload does not hash to its id is returned as `unreadable`, with the
+ * reason, and the rest are posted as usual.
+ */
+export const readPostedShares = async (
+  publicClient: PublicClient,
+  registry: Address,
+  headers: readonly { shareId: Hex; header: ShareHeader }[]
+): Promise<PostedShares> => {
+  const idsByBlock = new Map<bigint, Hex[]>();
+  for (const { shareId, header } of headers) {
+    idsByBlock.set(header.blockNumber, [...(idsByBlock.get(header.blockNumber) ?? []), shareId]);
+  }
+
+  type Found = { share: ChainShare; metadata: Hex } | { reason: string };
+  const found = new Map<string, Found>();
+  await Promise.all(
+    [...idsByBlock].map(async ([block, shareIds]) => {
+      let logs;
+      try {
+        logs = await publicClient.getContractEvents({
+          address: registry,
+          abi: ACP_SHARE_REGISTRY_ABI,
+          eventName: 'Shared',
+          args: { shareId: shareIds },
+          fromBlock: block,
+          toBlock: block,
+          strict: true,
+        });
+      } catch (error) {
+        for (const shareId of shareIds) {
+          found.set(shareId.toLowerCase(), {
+            reason: `the Shared events of block ${block} could not be read: ${messageOf(error)}`,
+          });
+        }
+        return;
+      }
+      // Logs come in log-index order. A share removed and posted again within one block has two
+      // Shared events there; the later one is the share, so each log overwrites the previous.
+      for (const { args } of logs) {
+        const hashes = shareIdOfChainShare(args.acp).toLowerCase() === args.shareId.toLowerCase();
+        found.set(
+          args.shareId.toLowerCase(),
+          hashes
+            ? { share: args.acp, metadata: args.metadata }
+            : { reason: 'the payload in its Shared event does not hash to its id' }
+        );
+      }
+    })
+  );
+
+  const result: PostedShares = { posted: [], unreadable: [] };
+  for (const { shareId, header } of headers) {
+    const entry = found.get(shareId.toLowerCase());
+    if (entry == null) {
+      result.unreadable.push({
+        shareId,
+        header,
+        reason: `no Shared event in block ${header.blockNumber}, where the registry points`,
+      });
+    } else if ('reason' in entry) {
+      result.unreadable.push({ shareId, header, reason: entry.reason });
+    } else {
+      result.posted.push({ shareId, header, ...entry });
+    }
+  }
+  return result;
+};
+
+/**
+ * The importable shares addressed to `recipient` (unexpired, not revoked), read from their events;
+ * those whose event could not be read are listed apart, so one of them never hides the rest.
+ */
+export const readSharesFor = async (
+  publicClient: PublicClient,
+  registry: Address,
+  recipient: Address
+): Promise<PostedShares> => {
+  const [shareIds, headers] = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: 'sharesFor',
+    args: [recipient],
+  });
+  return readPostedShares(
+    publicClient,
+    registry,
+    shareIds.map((shareId, i) => ({ shareId, header: headers[i] }))
+  );
+};
+
+/**
+ * One share by id, read from its event; null when the registry has no such share (unknown or
+ * removed). Throws, with the reason, when the registry lists it but its event could not be read.
+ */
+export const readShare = async (
+  publicClient: PublicClient,
+  registry: Address,
+  shareId: Hex
+): Promise<PostedShare | null> => {
+  const header = await publicClient.readContract({
+    address: registry,
+    abi: ACP_SHARE_REGISTRY_ABI,
+    functionName: 'getShare',
+    args: [shareId],
+  });
+  if (header.issuer === '0x0000000000000000000000000000000000000000') return null;
+  const { posted, unreadable } = await readPostedShares(publicClient, registry, [{ shareId, header }]);
+  if (unreadable.length > 0) throw new Error(`Share ${shareId}: ${unreadable[0].reason}`);
+  return posted[0];
+};

package/acps/sealing.ts

@@ -46,7 +46,7 @@ export const GenerateSealingKey = (): SealingKeyPair => {
 export const seal = (value: bigint | number, publicKey: string): EthEncryptedData => {
   isString(publicKey);
   isBigIntOrNumber(value);
-  assertKeyLength(publicKey, 'Public');
+  assertSealingKey(publicKey, 'Public');
 
   // generate ephemeral keypair
   const ephemeralKeyPair = nacl.box.keyPair();
@@ -67,7 +67,7 @@ export const seal = (value: bigint | number, publicKey: string): EthEncryptedDat
  * The ephemeral public key travels inside the payload, so the private key alone suffices.
  */
 export const unsealWithPrivateKey = (privateKey: string, parsedData: EthEncryptedData): bigint => {
-  assertKeyLength(privateKey, 'Private');
+  assertSealingKey(privateKey, 'Private');
 
   const nonce = parsedData.nonce instanceof Uint8Array ? parsedData.nonce : new Uint8Array(parsedData.nonce);
   const ephemPublicKey =
@@ -82,9 +82,15 @@ export const unsealWithPrivateKey = (privateKey: string, parsedData: EthEncrypte
   return toBigInt(decryptedMessage);
 };
 
-const assertKeyLength = (key: string, kind: 'Private' | 'Public'): void => {
+const assertSealingKey = (key: string, kind: 'Private' | 'Public'): void => {
   const bare = key.startsWith('0x') ? key.slice(2) : key;
   if (bare.length !== KEY_HEX_LENGTH) {
     throw new Error(`${kind} key must be of length ${KEY_HEX_LENGTH}`);
   }
+  // A correct-length key with non-hex characters would otherwise decode those characters to
+  // zero bytes. An entirely invalid public key becomes the all-zero key, a low-order point, so
+  // anything sealed to it could be opened without the matching private key.
+  if (!/^[0-9a-fA-F]+$/.test(bare)) {
+    throw new Error(`${kind} key must contain only hex characters`);
+  }
 };

package/acps/share-metadata/appKey.ts

@@ -0,0 +1,8 @@
+import { keccak256, stringToHex, type Hex } from 'viem';
+
+/**
+ * The key an app marks its shares with: keccak256 of its name, e.g. `shareAppKey('explorer.fhenix.io')`.
+ * A client configured with `acp: { app }` puts it on every share it creates and lists only the
+ * shares that carry it; the name itself is never on-chain.
+ */
+export const shareAppKey = (app: string): Hex => keccak256(stringToHex(app));

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;