@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/acps/test/store.test.ts

@@ -12,6 +12,8 @@ import {
   removeACP,
   getActiveACPHash,
   setActiveACPHash,
+  clearStaleStore,
+  ACP_STORE_DEFAULTS,
   ACPUtils,
 } from '../index.js';
 
@@ -85,4 +87,73 @@ describe('Storage Tests', () => {
       expect(activeHash).toBeUndefined();
     });
   });
+
+  describe('Stale Store Detection', () => {
+    // `typeof null` and `typeof []` are both 'object', so these shapes used to pass the
+    // structure guard and stay in the store; a `null` record then throws on `acps[chainId]`.
+    const seedRawState = (state: unknown) => {
+      acpStore.store.setState(state as never, true);
+    };
+
+    it('should clear the store when acps is null', () => {
+      seedRawState({ acps: null, activeACPHash: {} });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+      expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+    });
+
+    it('should clear the store when acps is an array', () => {
+      seedRawState({ acps: [], activeACPHash: {} });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getACP(chainId, account, '0xdeadbeef')).not.toThrow();
+      expect(getACP(chainId, account, '0xdeadbeef')).toBeUndefined();
+    });
+
+    it('should clear the store when activeACPHash is null', () => {
+      seedRawState({ acps: {}, activeACPHash: null });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+      expect(() => getActiveACP(chainId, account)).not.toThrow();
+      expect(getActiveACP(chainId, account)).toBeUndefined();
+    });
+
+    it('should clear the store when activeACPHash is an array', () => {
+      seedRawState({ acps: {}, activeACPHash: [] });
+
+      clearStaleStore();
+
+      expect(acpStore.store.getState()).toEqual(ACP_STORE_DEFAULTS);
+    });
+
+    it('should let setACP recover a store whose acps is null', async () => {
+      const acp = await createMockACP();
+      seedRawState({ acps: null, activeACPHash: {} });
+
+      expect(() => setACP(chainId, account, acp)).not.toThrow();
+      expect(ACPUtils.serialize(getACP(chainId, account, acp.hash)!)).toEqual(ACPUtils.serialize(acp));
+    });
+
+    it('should leave a valid store untouched', async () => {
+      const acp = await createMockACP();
+      setACP(chainId, account, acp);
+      setActiveACPHash(chainId, account, acp.hash);
+
+      const before = acpStore.store.getState();
+
+      clearStaleStore();
+
+      // Same reference: a valid store must not be rewritten at all.
+      expect(acpStore.store.getState()).toBe(before);
+      expect(ACPUtils.serialize(getACP(chainId, account, acp.hash)!)).toEqual(ACPUtils.serialize(acp));
+      expect(getActiveACPHash(chainId, account)).toBe(acp.hash);
+    });
+  });
 });

package/acps/test/utils.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { fromHexString, toBeArray, toHexString } from '../utils.js';
+
+describe('fromHexString', () => {
+  it('strips the 0x prefix before padding an odd-length string', () => {
+    // Regression: padding first produced `00x123`, which decoded to [0x00, NaN->0, 0x23].
+    expect(Array.from(fromHexString('0x123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('pads odd-length strings without a prefix', () => {
+    expect(Array.from(fromHexString('123'))).toEqual([0x01, 0x23]);
+  });
+
+  it('decodes even-length strings with and without the 0x prefix identically', () => {
+    expect(Array.from(fromHexString('0x1234'))).toEqual([0x12, 0x34]);
+    expect(Array.from(fromHexString('1234'))).toEqual([0x12, 0x34]);
+  });
+
+  it('decodes uppercase hex', () => {
+    expect(Array.from(fromHexString('0xDEADBEEF'))).toEqual([0xde, 0xad, 0xbe, 0xef]);
+  });
+
+  it('returns an empty array for empty input', () => {
+    expect(fromHexString('')).toEqual(new Uint8Array());
+    expect(fromHexString('0x')).toEqual(new Uint8Array());
+  });
+
+  it('round-trips a 32-byte sealing key through toHexString', () => {
+    const privateKey = 'a3'.repeat(32);
+
+    const bytes = fromHexString(privateKey);
+
+    expect(bytes.length).toBe(32);
+    expect(toHexString(bytes)).toBe(privateKey);
+  });
+
+  it('throws instead of silently producing zero bytes for non-hex characters', () => {
+    expect(() => fromHexString('zzzz')).toThrow('Invalid hex string');
+  });
+
+  it('throws for hex strings with a single invalid character', () => {
+    expect(() => fromHexString('0x12g4')).toThrow('Invalid hex string');
+  });
+
+  it('only strips a lowercase 0x prefix, matching the sealing key and ACP schema checks', () => {
+    expect(() => fromHexString('0X12')).toThrow('Invalid hex string');
+  });
+
+  it('does not leak the value in the error message', () => {
+    const secret = 'f'.repeat(63) + 'z';
+
+    expect(() => fromHexString(secret)).toThrow(
+      expect.objectContaining({ message: expect.not.stringContaining(secret) })
+    );
+  });
+});
+
+describe('toBeArray', () => {
+  it('still encodes values that need an odd-length hex representation', () => {
+    expect(Array.from(toBeArray(0x123))).toEqual([0x01, 0x23]);
+    expect(Array.from(toBeArray(255n))).toEqual([0xff]);
+  });
+});

package/acps/test/validation.test.ts

@@ -91,7 +91,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x1234567890abcdef',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).not.toThrow();
@@ -102,7 +101,6 @@ describe('Validation Tests', () => {
         issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x1234567890abcdef',
-        name: 'Import ACP',
       };
       expect(() => validateImportACPOptions(options)).toThrow();
     });
@@ -113,7 +111,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).toThrow();
@@ -125,7 +122,6 @@ describe('Validation Tests', () => {
         expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
         recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
         issuerSignature: '0x',
-        name: 'Import ACP',
       };
 
       expect(() => validateImportACPOptions(options)).toThrow();

package/acps/types.ts

@@ -1,5 +1,6 @@
 import { type EthEncryptedData } from './sealing.js';
 import { type Hex } from 'viem';
+import type { ShareLabel } from './share-metadata/schema.js';
 
 /**
  * EIP712 related types
@@ -46,6 +47,12 @@ export interface ACPPrivate {
    * Never leaves the client.
    */
   sealingPrivateKey: Hex;
+  /**
+   * (sharing / recipient) The share metadata: the labels of its handles, a v3 blob
+   * (`decodeShareMetadata` / `describeShareMetadata`). Not signed; travels with the share, in the
+   * exported JSON or in the registry's `Shared` event. Absent when the share has none.
+   */
+  metadata?: Hex;
   /**
    * EIP712 domain used to sign this acp.
    * Should not be set manually, included in metadata as part of serialization flows.
@@ -191,17 +198,30 @@ export type CreateSharingACPOptions = ACPScopeOptions & {
   expiration?: number;
   revokerData?: number;
   revokerContract?: string;
+  /**
+   * The labels of the handles, one per handle in order. Kept on the acp as `metadata`, then
+   * written into `export()` and posted by `shareOnChain`.
+   */
+  labels?: readonly ShareLabel[];
+  /**
+   * The key of the app the share is for (`shareAppKey(app)`), kept in `metadata` with the labels.
+   * A client configured with `acp: { app }` fills it in; a recipient client with the same `app`
+   * lists the share, one with another app does not.
+   */
+  appKey?: Hex;
 };
 
+/** A share as exported (`SharedACP`) or read from the registry. A `name` in it is ignored. */
 export type ImportSharedACPOptions = ACPScopeOptions & {
   type?: 'sharing';
   issuer: string;
   recipient: string;
   issuerSignature: string;
-  name?: string;
   expiration: number;
   revokerData?: number;
   revokerContract?: string;
+  /** The share metadata (labels blob), kept on the recipient acp; `0x` or absent for none. */
+  metadata?: string;
 };
 
 /** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
@@ -210,22 +230,55 @@ export type SerializedACP = ACP;
 /**
  * The share payload produced by `ACPUtils.export()` — the full public component
  * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
- * the display name and acp type. Fixed shape: every field is always present
+ * the acp type. The issuer's `name` is not exported: it is their own note, and the
+ * recipient names the share themselves. Fixed shape: every field is always present
  * (zero-values instead of omissions), so importers can parse a single schema.
- * Mirrors the on-chain sharing payload struct field-for-field.
+ * Mirrors the on-chain sharing payload struct field-for-field. The one optional
+ * field is `metadata`, the labels of the handles, present only when the share has them.
  */
 export type SharedACP = Expand<
   Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
-    name: string;
     type: 'sharing';
+    metadata?: Hex;
   }
 >;
 
+/**
+ * An ACP on-chain status, as `client.acp.checkAccess` reports it instead of a revert.
+ * Without a handle: 'valid' or the reason it is not. With a handle, a valid ACP reports
+ * 'allowed', 'out-of-scope' (the ACP scope does not cover the handle) or
+ * 'issuer-not-allowed' (the issuer itself may not read the handle, so no ACP of theirs can).
+ */
+export type ACPAccessStatus =
+  | 'valid'
+  | 'allowed'
+  | 'out-of-scope'
+  | 'issuer-not-allowed'
+  | 'expired'
+  | 'revoked'
+  | 'invalid-issuer-signature'
+  | 'invalid-recipient-signature';
+
 /**
  * A share read back from the on-chain ACPShareRegistry: the posted payload
- * (SharedACP minus the client-side name/type) plus its registry id.
+ * (SharedACP minus its type), its registry id, and the
+ * metadata blob posted with it (`0x` when none) — for a SNAPSHOT share, the
+ * labels of its handles (`decodeShareMetadata` / `describeShareMetadata`).
+ */
+export type IncomingShare = Expand<
+  Omit<SharedACP, 'type' | 'metadata'> & {
+    shareId: Hex;
+    metadata: Hex;
+    /** The key of the app the share was posted for (`shareAppKey(app)`), when it names one. */
+    appKey?: Hex;
+  }
+>;
+
+/**
+ * What the share label helpers read: the handles, their issuer and the metadata blob. An
+ * `IncomingShare` (on-chain route) and a sharing or recipient `ACP` (exported JSON route) both fit.
  */
-export type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & { shareId: Hex }>;
+export type LabelledShare = { issuer: Hex; handles: readonly Hex[]; metadata?: Hex };
 
 /**
  * A type representing the acp fields that are used to generate the hash

package/acps/utils.ts

@@ -2,9 +2,22 @@
 
 declare const BigInt: (value: string | number | bigint) => bigint;
 
+const HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
+
 export const fromHexString = (hexString: string): Uint8Array => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
+  // Strip `0x` before padding: padding first turns `0x123` into `00x123`, which no
+  // longer matches the prefix and decodes to garbage bytes.
+  const body = hexString.replace(/^0x/, '');
+
+  // `parseInt` maps a non-hex pair to NaN, which `Uint8Array` stores as 0. Without this check a
+  // malformed sealing key silently becomes zero bytes instead of failing.
+  if (!HEX_BODY_REGEX.test(body)) {
+    // The value is omitted on purpose: this helper also receives sealing private keys.
+    throw new Error('Invalid hex string: contains non-hexadecimal characters');
+  }
+
+  const padded = body.length % 2 === 1 ? `0${body}` : body;
+  const arr = padded.match(/.{1,2}/g);
   if (!arr) return new Uint8Array();
   return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
 };

package/acps/validation.ts

@@ -85,6 +85,7 @@ const zACPWithDefaults = z.object({
   handles: handlesSchema,
   issuerSignature: bytesSchema.optional().default('0x'),
   recipientSignature: bytesSchema.optional().default('0x'),
+  metadata: bytesSchema.optional(),
 });
 
 const zACPWithSealingKeys = zACPWithDefaults.extend({
@@ -228,7 +229,6 @@ export const ImportACPOptionsValidator = z
     type: z.literal('recipient').optional().default('recipient'),
     issuer: addressNotZeroSchema,
     recipient: addressNotZeroSchema,
-    name: z.string().optional().default('Unnamed ACP'),
     expiration: z.int(),
     revokerData: z.int().optional().default(0),
     revokerContract: addressSchema.optional().default(zeroAddress),
@@ -237,6 +237,8 @@ export const ImportACPOptionsValidator = z
     handles: handlesSchema,
     issuerSignature: bytesNotEmptySchema,
     recipientSignature: bytesSchema.optional().default('0x'),
+    /** The share metadata (labels blob); `0x` means none and is dropped */
+    metadata: bytesSchema.optional().transform((val) => (val === '0x' ? undefined : val)),
   })
   .refine(...ExternalValidatorRefinement)
   .transform(withDerivedScope)

package/chains/chains/arbitrum.ts

@@ -0,0 +1,14 @@
+import { defineChain } from '../defineChain.js';
+
+/**
+ * Arbitrum One mainnet chain configuration
+ */
+export const arbitrum = defineChain({
+  id: 42161,
+  name: 'Arbitrum One',
+  network: 'arbitrum',
+  coFheUrl: 'https://cofhe.mainnet.fhenix.zone',
+  verifierUrl: 'https://cofhe-vrf.mainnet.fhenix.zone',
+  thresholdNetworkUrl: 'https://cofhe-tn.mainnet.fhenix.zone',
+  environment: 'MAINNET',
+});

package/chains/chains/ethereum.ts

@@ -0,0 +1,14 @@
+import { defineChain } from '../defineChain.js';
+
+/**
+ * Ethereum mainnet chain configuration
+ */
+export const ethereum = defineChain({
+  id: 1,
+  name: 'Ethereum',
+  network: 'ethereum',
+  coFheUrl: 'https://cofhe.mainnet.fhenix.zone',
+  verifierUrl: 'https://cofhe-vrf.mainnet.fhenix.zone',
+  thresholdNetworkUrl: 'https://cofhe-tn.mainnet.fhenix.zone',
+  environment: 'MAINNET',
+});

package/chains/index.ts

@@ -5,17 +5,21 @@ export type { CofheChain, Environment } from './types.js';
 import { sepolia } from './chains/sepolia.js';
 import { arbSepolia } from './chains/arbSepolia.js';
 import { baseSepolia } from './chains/baseSepolia.js';
+import { ethereum } from './chains/ethereum.js';
+import { arbitrum } from './chains/arbitrum.js';
 import { hardhat } from './chains/hardhat.js';
 import { localcofhe } from './chains/localcofhe.js';
 import { stagingCofhe } from './chains/stagingCofhe.js';
 
-export { sepolia, arbSepolia, baseSepolia, hardhat, localcofhe, stagingCofhe };
+export { sepolia, arbSepolia, baseSepolia, ethereum, arbitrum, hardhat, localcofhe, stagingCofhe };
 
 // Export all chains as a collection
 export const chains = {
   sepolia,
   arbSepolia,
   baseSepolia,
+  ethereum,
+  arbitrum,
   hardhat,
   localcofhe,
   stagingCofhe,

package/chains/test/chains.test.ts

@@ -1,12 +1,24 @@
 import { describe, it, expect } from 'vitest';
-import { sepolia, arbSepolia, baseSepolia, hardhat, chains, getChainById, getChainByName } from '../index.js';
+import {
+  sepolia,
+  arbSepolia,
+  baseSepolia,
+  ethereum,
+  arbitrum,
+  hardhat,
+  chains,
+  getChainById,
+  getChainByName,
+} from '../index.js';
 
 describe('Chains', () => {
   it('should export all chains', () => {
-    expect(Object.keys(chains)).toHaveLength(6);
+    expect(Object.keys(chains)).toHaveLength(8);
     expect(chains).toHaveProperty('sepolia');
     expect(chains).toHaveProperty('arbSepolia');
     expect(chains).toHaveProperty('baseSepolia');
+    expect(chains).toHaveProperty('ethereum');
+    expect(chains).toHaveProperty('arbitrum');
     expect(chains).toHaveProperty('hardhat');
     expect(chains).toHaveProperty('localcofhe');
     expect(chains).toHaveProperty('stagingCofhe');
@@ -17,6 +29,11 @@ describe('Chains', () => {
     expect(sepolia.name).toBe('Sepolia');
     expect(sepolia.environment).toBe('TESTNET');
 
+    expect(ethereum.id).toBe(1);
+    expect(ethereum.environment).toBe('MAINNET');
+    expect(arbitrum.id).toBe(42161);
+    expect(arbitrum.environment).toBe('MAINNET');
+
     expect(hardhat.id).toBe(31337);
     expect(hardhat.name).toBe('Hardhat');
     expect(hardhat.environment).toBe('MOCK');
@@ -24,6 +41,8 @@ describe('Chains', () => {
 
   it('should find chains by ID', () => {
     expect(getChainById(11155111)).toBe(sepolia);
+    expect(getChainById(1)).toBe(ethereum);
+    expect(getChainById(42161)).toBe(arbitrum);
     expect(getChainById(31337)).toBe(hardhat);
     expect(getChainById(999999)).toBeUndefined();
   });
@@ -31,12 +50,14 @@ describe('Chains', () => {
   it('should find chains by name', () => {
     expect(getChainByName('sepolia')).toBe(sepolia);
     expect(getChainByName('Sepolia')).toBe(sepolia);
+    expect(getChainByName('ethereum')).toBe(ethereum);
+    expect(getChainByName('arbitrum')).toBe(arbitrum);
     expect(getChainByName('hardhat')).toBe(hardhat);
     expect(getChainByName('nonexistent')).toBeUndefined();
   });
 
   it('should validate chain properties', () => {
-    const allChains = [sepolia, arbSepolia, baseSepolia, hardhat];
+    const allChains = [sepolia, arbSepolia, baseSepolia, ethereum, arbitrum, hardhat];
 
     allChains.forEach((chain) => {
       expect(typeof chain.id).toBe('number');