@cofhe/sdk 1.0.0-alpha.0 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @cofhe/sdk Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- d711ce2: 1.0.0, the first stable release. Breaking changes since 0.8, detailed in their own entries below:
+
+  - The on-chain share registry has a new layout (`share(acp, metadata)`, header-only `sharesFor` / `getShare`), and shared ACPs no longer carry a `name`.
+  - The mocks need Solidity 0.8.25 or later and `@openzeppelin/contracts-upgradeable`.
+  - `CofheProvider` takes either `config` or `cofheClient`, not both.
+
+### Minor Changes
+
+- 6dcfb7d: ACPs sharing SNAPSHOTs (ctHashes rather than live data) can use the new on-chain ACP Sharing Registry `metadata` field to cite the origin of the snapshotted data (contract address + view-function / event), and the recipient can verify it on-chain. [Docs](https://cofhesdk.fhenix.io/sdk/acp#labelling-a-snapshot-share)
+
+  **@cofhe/sdk**
+
+  - `createSharing({ labels })`, `shareOnChain(acp, { labels | metadata })`; labels travel in `export()` / `importShared` as `SharedACP.metadata`.
+  - New `client.acp.verifyShareLabels`, `client.acp.getShareFromChain`, and `describeShareMetadata`. `IncomingShare` gains `metadata` and `appKey`.
+  - New `acp.app` config option: shares are tagged with the app's key and `getIncomingShares` lists only that app's shares ([docs](https://cofhesdk.fhenix.io/sdk/acp#mark-shares-for-your-app)).
+  - `@cofhe/sdk/acps` exports the metadata codec, label builders (`viewFunctionLabel`, `eventLogLabel`, `UNLABELLED`), verifiers, registry readers, `shareAppKey` and `ERC7984_ABI`.
+
+  **@cofhe/react**
+
+  - New `useCofheShareLabels`. `useCofheShareOnChain` accepts `{ acp, labels | metadata }`.
+  - The inbox shows each share's labels and their verification. [Docs](https://cofhesdk.fhenix.io/react/acp#share-labels)
+
+  **Mocks and plugins**
+
+  - `ACPShareRegistry`, `ACPTimestampRevoker` and `Permissioned` are copied verbatim from a pinned cofhe-contracts commit (`pnpm update:cofhe-contracts <commit>`). The share registry is deployed behind `MockERC1967Proxy`.
+  - Mocks now need Solidity ≥0.8.25 and `@openzeppelin/contracts-upgradeable` (new Hardhat plugin peer dependency; Foundry users add its remapping).
+
+### Patch Changes
+
+- d711ce2: The mocks now behave like the real TaskManager and TFHE-rs in more places. Tests that relied on the old mock behaviour may start failing, as they would on a real network.
+
+  - `FHE.asE*` (trivial encrypt) reverts with `InvalidInputForFunction` when the value does not fit the type (e.g. `FHE.asEuint8(256)`), and with `InvalidSecurityZone` for an out of range zone, instead of storing the value masked.
+  - `encryptInputs` against the mocks rejects out-of-range values with the same error as the production path, instead of passing them on to be masked (e.g. `Encryptable.uint8(256n)` became `0`).
+  - `FHE.not` on encrypted integers is a bitwise NOT (`not(euint8(2))` is 253, not 0), and `FHE.rol` / `FHE.ror` rotate within the type's width, with the amount taken modulo the width, instead of shifting.
+  - `FHE.rem(x, 0)` returns `x` instead of reverting.
+  - `FHE.random*` handles carry their type and security zone and can be allowed and computed on.
+  - `MockTaskManager.isPubliclyAllowed` returns whether a handle was made public with `FHE.allowGlobal` / `FHE.allowPublic`, instead of reverting with `NotImplemented`.
+  - Handles in a negative security zone go through the ACL like any other handle. Previously any contract could use them and `FHE.allow*` did nothing.
+  - `publishDecryptResultBatch` emits `DecryptionResult` with the caller as `requestor`, and the batch decrypt result functions revert with `LengthMismatch` when the arrays differ in length.
+  - `setSecurityZones` rejects an inverted range (`min > max`) with `InvalidSecurityZone`.
+
+- 5a192ee: Node storage now creates ~/.cofhesdk with mode 0700 and files with 0600, and tightens permissions on existing ones.
+- 757e448: Use the latest chain block timestamp for injected ACP revoker data while preserving explicit revoker configuration precedence.
+- 73d5297: `seal` and `unsealWithPrivateKey` now throw when the sealing key contains non-hex characters. Previously a 64-character key with invalid characters passed the length check and those characters decoded to zero bytes, so `seal` silently encrypted to the wrong key (an entirely invalid key became the all-zero key, which offers no confidentiality), and `unsealWithPrivateKey` failed later with `Failed to decrypt message`.
+- 8fad647: `unsealWithPrivateKey` throws a `CofheError` with code `SealOutputFailed` when a decrypt response can't be unsealed, instead of a plain `Error`. `useCofheDecrypt` no longer retries these failures.
+- a4fcea7: `verifyDecryptResult` now returns `false` when the chain's TaskManager has no `decryptResultSigner` set (zero address). It used to return `true` for any signature in that case. The on-chain `verifyDecryptResult` still skips the check when no signer is set.
+
 ## 0.8.0
 
 ### Minor Changes

package/acps/onchain-utils.ts

@@ -345,9 +345,9 @@ export const clearAclServedAddresses = () => aclServedAddressesCache.clear();
  * TaskManager -> acl() -> getters). Zero addresses and pre-upgrade ACLs (getters absent -> revert)
  * resolve to `undefined` — callers fall back to `acp.*` config.
  *
- * Resolutions are cached per chainId. A failure to reach the TaskManager (network
- * error, no CoFHE deployment) is NOT cached, so a transient outage does not pin
- * an empty result for the whole session.
+ * Resolutions are cached per chainId. A failure to reach the TaskManager or the ACL
+ * getters (network error, no CoFHE deployment) is NOT cached, so a transient outage
+ * does not pin an empty result for the whole session.
  */
 export const getAclServedAddresses = async (
   publicClient: PublicClient,
@@ -367,19 +367,24 @@ export const getAclServedAddresses = async (
     return {};
   }
 
+  // A revert means the getter is missing (pre-upgrade ACL) and is safe to cache. Any other
+  // error (rate limit, timeout) is transient: return what we have but don't cache it.
+  let transient = false;
+  const readServedAddress = (functionName: 'defaultRevokerContract' | 'shareRegistry') =>
+    publicClient.readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName }).catch((err) => {
+      if (revertErrorName(err, ACL_SERVED_ADDRESSES_ABI) === undefined) transient = true;
+      return undefined;
+    });
+
   const [defaultRevoker, shareRegistry] = await Promise.all([
-    publicClient
-      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'defaultRevokerContract' })
-      .catch(() => undefined),
-    publicClient
-      .readContract({ address: aclAddress, abi: ACL_SERVED_ADDRESSES_ABI, functionName: 'shareRegistry' })
-      .catch(() => undefined),
+    readServedAddress('defaultRevokerContract'),
+    readServedAddress('shareRegistry'),
   ]);
 
   const resolved: AclServedAddresses = {
     defaultRevoker: defaultRevoker != null && defaultRevoker !== zeroAddress ? defaultRevoker : undefined,
     shareRegistry: shareRegistry != null && shareRegistry !== zeroAddress ? shareRegistry : undefined,
   };
-  aclServedAddressesCache.set(chainId, resolved);
+  if (!transient) aclServedAddressesCache.set(chainId, resolved);
   return resolved;
 };

package/acps/sealing.ts

@@ -1,6 +1,7 @@
 import nacl from 'tweetnacl';
 import { type Hex } from 'viem';
 import { fromHexString, toBeArray, toBigInt, toHexString, isBigIntOrNumber, isString } from './utils.js';
+import { CofheError, CofheErrorCode } from '../core/error.js';
 
 /** 32-byte X25519 keys as bare hex (no 0x prefix) */
 const KEY_HEX_LENGTH = 64;
@@ -74,9 +75,28 @@ export const unsealWithPrivateKey = (privateKey: string, parsedData: EthEncrypte
     parsedData.public_key instanceof Uint8Array ? parsedData.public_key : new Uint8Array(parsedData.public_key);
   const dataToDecrypt = parsedData.data instanceof Uint8Array ? parsedData.data : new Uint8Array(parsedData.data);
 
-  const decryptedMessage = nacl.box.open(dataToDecrypt, nonce, ephemPublicKey, fromHexString(privateKey));
+  // nacl returns null for a wrong key or tampered payload and throws on malformed inputs. Either way it
+  // is a CofheError, so callers that stop retrying on those (e.g. `useCofheDecrypt`) do not re-request.
+  let decryptedMessage: Uint8Array | null;
+  let cause: Error | undefined;
+  try {
+    decryptedMessage = nacl.box.open(dataToDecrypt, nonce, ephemPublicKey, fromHexString(privateKey));
+  } catch (e) {
+    decryptedMessage = null;
+    cause = e instanceof Error ? e : undefined;
+  }
   if (!decryptedMessage) {
-    throw new Error('Failed to decrypt message');
+    // Lengths only: the context must not carry the private key or any sealing material.
+    throw new CofheError({
+      code: CofheErrorCode.SealOutputFailed,
+      message: 'Failed to unseal decrypt response',
+      cause,
+      context: {
+        dataLength: dataToDecrypt.length,
+        nonceLength: nonce.length,
+        publicKeyLength: ephemPublicKey.length,
+      },
+    });
   }
 
   return toBigInt(decryptedMessage);

package/acps/test/aclServedAddresses.test.ts

@@ -0,0 +1,65 @@
+import { ContractFunctionRevertedError, HttpRequestError, parseAbi } from 'viem';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearTaskManagerAddressCache } from '../../core/taskManager.js';
+import { clearAclServedAddresses, getAclServedAddresses } from '../onchain-utils.js';
+
+const CHAIN_ID = 421614;
+const TASK_MANAGER = '0x0000000000000000000000000000000000005000';
+const ACL = '0x00000000000000000000000000000000000000dd';
+const REVOKER = '0x00000000000000000000000000000000000000cc';
+const REGISTRY = '0x00000000000000000000000000000000000000ee';
+
+const GETTERS_ABI = parseAbi([
+  'function defaultRevokerContract() view returns (address)',
+  'function shareRegistry() view returns (address)',
+]);
+
+function clientWithGetters(getter: (functionName: string) => Promise<unknown>) {
+  return {
+    readContract: vi.fn(async ({ functionName }: { functionName: string }) => {
+      if (functionName === 'getTm') return TASK_MANAGER;
+      if (functionName === 'acl') return ACL;
+      return getter(functionName);
+    }),
+  } as any;
+}
+
+describe('getAclServedAddresses', () => {
+  beforeEach(() => {
+    clearAclServedAddresses();
+    clearTaskManagerAddressCache();
+  });
+
+  it('does not cache a transient failure of the ACL getters', async () => {
+    let down = true;
+    const publicClient = clientWithGetters(async (functionName) => {
+      if (down) throw new HttpRequestError({ url: 'http://rpc', status: 429 });
+      return functionName === 'defaultRevokerContract' ? REVOKER : REGISTRY;
+    });
+
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual({
+      defaultRevoker: undefined,
+      shareRegistry: undefined,
+    });
+
+    down = false;
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual({
+      defaultRevoker: REVOKER,
+      shareRegistry: REGISTRY,
+    });
+  });
+
+  it('caches a pre-upgrade ACL whose getters revert', async () => {
+    const publicClient = clientWithGetters(async (functionName) => {
+      throw new ContractFunctionRevertedError({ abi: GETTERS_ABI, functionName, data: '0x' });
+    });
+
+    const expected = { defaultRevoker: undefined, shareRegistry: undefined };
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual(expected);
+    const calls = publicClient.readContract.mock.calls.length;
+
+    expect(await getAclServedAddresses(publicClient, CHAIN_ID)).toEqual(expected);
+    expect(publicClient.readContract.mock.calls.length).toBe(calls);
+  });
+});

package/acps/test/sealing.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { GenerateSealingKey, seal, unsealWithPrivateKey } from '../index.js';
+import { CofheError, CofheErrorCode } from '../../core/error.js';
 
 describe('seal / unsealWithPrivateKey', () => {
   it('should seal data into EthEncryptedData shape', () => {
@@ -80,6 +81,56 @@ describe('seal / unsealWithPrivateKey', () => {
       seal('not a number', publicKey);
     }).toThrow('Value not a number is not a number or bigint: string');
   });
+
+  describe('unseal failures are CofheErrors', () => {
+    const expectUnsealFailed = (fn: () => unknown, secrets: string[] = []) => {
+      let thrown: unknown;
+      try {
+        fn();
+      } catch (e) {
+        thrown = e;
+      }
+      expect(thrown).toBeInstanceOf(CofheError);
+      expect((thrown as CofheError).code).toBe(CofheErrorCode.SealOutputFailed);
+      const serialized = (thrown as CofheError).serialize();
+      for (const secret of secrets) expect(serialized).not.toContain(secret.replace(/^0x/, ''));
+    };
+
+    it('throws SealOutputFailed when unsealing with the wrong private key', () => {
+      const pair = GenerateSealingKey();
+      const other = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+
+      expectUnsealFailed(() => unsealWithPrivateKey(other.privateKey, sealed), [other.privateKey, pair.privateKey]);
+    });
+
+    it('throws SealOutputFailed when the sealed payload is corrupted', () => {
+      const pair = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+      const corrupted = { ...sealed, data: Uint8Array.from(sealed.data) };
+      corrupted.data[0] ^= 0xff;
+
+      expectUnsealFailed(() => unsealWithPrivateKey(pair.privateKey, corrupted), [pair.privateKey]);
+    });
+
+    it('throws SealOutputFailed, keeping the cause, when nacl rejects malformed inputs', () => {
+      const pair = GenerateSealingKey();
+      const sealed = seal(BigInt(42), pair.publicKey);
+      const shortNonce = { ...sealed, nonce: sealed.nonce.slice(0, 4) };
+
+      expectUnsealFailed(() => unsealWithPrivateKey(pair.privateKey, shortNonce), [pair.privateKey]);
+      try {
+        unsealWithPrivateKey(pair.privateKey, shortNonce);
+      } catch (e) {
+        expect((e as CofheError).cause).toBeInstanceOf(Error);
+      }
+    });
+
+    it('still reports a malformed sealing key as a plain key error, not a seal failure', () => {
+      const sealed = seal(BigInt(1), GenerateSealingKey().publicKey);
+      expect(() => unsealWithPrivateKey('deadbeef', sealed)).toThrow('Private key must be of length 64');
+    });
+  });
 });
 
 describe('GenerateSealingKey', () => {

package/core/acps.ts

@@ -26,7 +26,7 @@ import {
   clearAclServedAddresses,
 } from '@/acps';
 
-import { type Hex, type PublicClient, type WalletClient, zeroAddress } from 'viem';
+import { type ContractFunctionParameters, type Hex, type PublicClient, type WalletClient, zeroAddress } from 'viem';
 
 // HELPERS
 
@@ -311,23 +311,39 @@ const getBlockRevokerData = async (publicClient: PublicClient): Promise<number>
  *
  * @returns the revocation transaction hash
  */
-const revokeACP = async (acp: ACP, walletClient: WalletClient): Promise<Hex> => {
+/**
+ * A registry or revoker write built but not sent: what a simulation or `writeContract` takes,
+ * minus the sender. For a caller that sends through its own path (simulate first, record the
+ * transaction) instead of the plain `writeContract` the senders below do.
+ */
+export type ShareRegistryWrite<functionName extends 'share' | 'removeShare'> = ContractFunctionParameters<
+  typeof ACP_SHARE_REGISTRY_ABI,
+  'nonpayable',
+  functionName
+>;
+export type RevokerWrite = ContractFunctionParameters<typeof ACP_REVOKER_ABI, 'nonpayable', 'revokeSingle'>;
+
+/** The revoker write that revokes one acp, built but not sent. Throws for an acp without a revoker. */
+const prepareRevokeACP = (acp: ACP): RevokerWrite => {
   if (acp.revokerContract === zeroAddress || acp.revokerData === 0) {
     throw new Error('ACP is not revocable: it has no revoker (revokerContract/revokerData unset)');
   }
+  return {
+    address: acp.revokerContract,
+    abi: ACP_REVOKER_ABI,
+    functionName: 'revokeSingle',
+    args: [BigInt(acp.revokerData)],
+  };
+};
+
+const revokeACP = async (acp: ACP, walletClient: WalletClient): Promise<Hex> => {
+  const write = prepareRevokeACP(acp);
   if (walletClient.account == null) throw new Error('Missing walletClient account');
   if (walletClient.account.address.toLowerCase() !== acp.issuer.toLowerCase()) {
     throw new Error('Only the acp issuer can revoke it');
   }
 
-  return walletClient.writeContract({
-    address: acp.revokerContract,
-    abi: ACP_REVOKER_ABI,
-    functionName: 'revokeSingle',
-    args: [BigInt(acp.revokerData)],
-    account: walletClient.account,
-    chain: walletClient.chain,
-  });
+  return walletClient.writeContract({ ...write, account: walletClient.account, chain: walletClient.chain });
 };
 
 /**
@@ -416,34 +432,51 @@ const metadataOf = (acp: ACP, { labels, metadata, appKey }: ShareOnChainOptions)
  * to discover and import — the on-chain alternative to `export()` — optionally
  * with the labels of its handles.
  */
-const shareOnChain = async (
+/**
+ * The registry `share` write for a signed sharing acp, built but not sent, with the share id it
+ * gets. Validates the acp, not the sender: the registry takes the write from the issuer only.
+ */
+const prepareShareOnChain = (
   acp: ACP,
-  walletClient: WalletClient,
   registry: Hex,
   options: ShareOnChainOptions = {}
-): Promise<{ txHash: Hex; shareId: Hex }> => {
+): { write: ShareRegistryWrite<'share'>; shareId: Hex } => {
   if (acp.type !== 'sharing') {
     throw new Error(`Cannot share a '${acp.type}' ACP on-chain — only 'sharing' ACPs are shareable.`);
   }
   if (acp.issuerSignature === '0x') {
     throw new Error('Cannot share an unsigned sharing ACP — sign it first.');
   }
+  return {
+    write: {
+      address: registry,
+      abi: ACP_SHARE_REGISTRY_ABI,
+      functionName: 'share',
+      args: [toChainShare(acp), metadataOf(acp, options)],
+    },
+    shareId: computeShareId(acp),
+  };
+};
+
+const shareOnChain = async (
+  acp: ACP,
+  walletClient: WalletClient,
+  registry: Hex,
+  options: ShareOnChainOptions = {}
+): Promise<{ txHash: Hex; shareId: Hex }> => {
+  const { write, shareId } = prepareShareOnChain(acp, registry, options);
   if (walletClient.account == null) throw new Error('Missing walletClient account');
   if (walletClient.account.address.toLowerCase() !== acp.issuer.toLowerCase()) {
     throw new Error('Only the ACP issuer can share it on-chain');
   }
-  const metadata = metadataOf(acp, options);
 
   const txHash = await walletClient.writeContract({
-    address: registry,
-    abi: ACP_SHARE_REGISTRY_ABI,
-    functionName: 'share',
-    args: [toChainShare(acp), metadata],
+    ...write,
     account: walletClient.account,
     chain: walletClient.chain ?? null,
   });
 
-  return { txHash, shareId: computeShareId(acp) };
+  return { txHash, shareId };
 };
 
 const toIncomingShare = ({ shareId, share: s, metadata }: PostedShare): IncomingShare => ({
@@ -514,14 +547,19 @@ const importFromChain = async (
   return importShared({ ...options, type: 'sharing' }, publicClient, walletClient, importOptions);
 };
 
+/** The registry `removeShare` write for one share id, built but not sent. */
+const prepareRemoveShare = (shareId: Hex, registry: Hex): ShareRegistryWrite<'removeShare'> => ({
+  address: registry,
+  abi: ACP_SHARE_REGISTRY_ABI,
+  functionName: 'removeShare',
+  args: [shareId],
+});
+
 /** Remove a share from the registry (issuer retracts / recipient dismisses). */
 const removeShareOnChain = async (shareId: Hex, walletClient: WalletClient, registry: Hex): Promise<Hex> => {
   if (walletClient.account == null) throw new Error('Missing walletClient account');
   return walletClient.writeContract({
-    address: registry,
-    abi: ACP_SHARE_REGISTRY_ABI,
-    functionName: 'removeShare',
-    args: [shareId],
+    ...prepareRemoveShare(shareId, registry),
     account: walletClient.account,
     chain: walletClient.chain ?? null,
   });
@@ -562,15 +600,18 @@ export const acps = {
   removeActiveACP,
 
   revokeACP,
+  prepareRevokeACP,
   revokeAllACPs,
   isACPRevoked,
   checkAccess,
 
   shareOnChain,
+  prepareShareOnChain,
   getIncomingShares,
   getShareFromChain,
   importFromChain,
   removeShareOnChain,
+  prepareRemoveShare,
   computeShareId,
 
   applyACPDefaultsFromChain,

package/core/client.ts

@@ -1,4 +1,4 @@
-import type { CreateSelfACPOptions, CreateSharingACPOptions, ImportSharedACPOptions } from '@/acps';
+import type { ACP, CreateSelfACPOptions, CreateSharingACPOptions, ImportSharedACPOptions } from '@/acps';
 import { decodeShareMetadata, shareAppKey, verifyShareLabels } from '@/acps';
 
 import { createStore } from 'zustand/vanilla';
@@ -90,6 +90,14 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     }
   };
 
+  /** The sharing writes the registry and the revoker take from the issuer only; say so before building one. */
+  const _requireIssuer = (acp: ACP, what: string) => {
+    const sender = connectStore.getState().walletClient?.account?.address;
+    if (sender == null || sender.toLowerCase() !== acp.issuer.toLowerCase()) {
+      throw new Error(`Only the acp issuer can ${what}`);
+    }
+  };
+
   // LIFECYCLE
 
   async function connect(publicClient: PublicClient, walletClient: WalletClient) {
@@ -306,6 +314,12 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       return acps.revokeACP(acp, walletClient!);
     },
 
+    prepareRevokeACP: (acp) => {
+      _requireConnected();
+      _requireIssuer(acp, 'revoke it');
+      return acps.prepareRevokeACP(acp);
+    },
+
     revokeAllACPs: async (revokerContract?: `0x${string}`) => {
       _requireConnected();
       const { publicClient, walletClient } = connectStore.getState();
@@ -333,6 +347,23 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
       return acps.shareOnChain(acp, walletClient!, sharingRegistry, { ...withAppKey(), ...options });
     },
 
+    prepareShareOnChain: async (acp, options) => {
+      _requireConnected();
+      _requireIssuer(acp, 'share it on-chain');
+      const { publicClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.prepareShareOnChain(acp, sharingRegistry, { ...withAppKey(), ...options });
+    },
+
+    prepareRemoveShare: async (shareId) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.prepareRemoveShare(shareId, sharingRegistry);
+    },
+
     getIncomingShares: async () => {
       _requireConnected();
       const { publicClient, walletClient } = connectStore.getState();

package/core/clientTypes.ts

@@ -6,7 +6,13 @@ import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js'
 import { type EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
-import { acps, type ImportSharedOptions, type ShareOnChainOptions } from './acps.js';
+import {
+  acps,
+  type ImportSharedOptions,
+  type RevokerWrite,
+  type ShareOnChainOptions,
+  type ShareRegistryWrite,
+} from './acps.js';
 import type { EncryptableItem, FheTypes, TfheInitializer } from './types.js';
 import type { ACPUtils } from 'acps/acp.js';
 import type {
@@ -114,6 +120,11 @@ export type CofheClientACPs = {
 
   // Revocation (on-chain, require connection)
   revokeACP: (acp: ACP) => Promise<`0x${string}`>;
+  /**
+   * The revoker write `revokeACP` sends, built but not sent — for an app that sends through its own
+   * path (a simulation first, a transaction store). Issuer only; throws for an acp without a revoker.
+   */
+  prepareRevokeACP: (acp: ACP) => RevokerWrite;
   revokeAllACPs: (revokerContract?: `0x${string}`) => Promise<`0x${string}`>;
   isACPRevoked: (acp: ACP) => Promise<boolean>;
   /**
@@ -129,6 +140,16 @@ export type CofheClientACPs = {
    * optionally with the labels of its handles (`options.labels`, one per handle) or an encoded blob.
    */
   shareOnChain: (acp: ACP, options?: ShareOnChainOptions) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
+  /**
+   * The registry write `shareOnChain` sends and the share id it gets, built but not sent — for an
+   * app that sends through its own path (a simulation first, a transaction store). Issuer only.
+   */
+  prepareShareOnChain: (
+    acp: ACP,
+    options?: ShareOnChainOptions
+  ) => Promise<{ write: ShareRegistryWrite<'share'>; shareId: `0x${string}` }>;
+  /** The registry write `dismissShare` / `cancelShare` sends, built but not sent. */
+  prepareRemoveShare: (shareId: `0x${string}`) => Promise<ShareRegistryWrite<'removeShare'>>;
   /** Importable shares addressed to the connected account (unexpired, not revoked), with their metadata. */
   getIncomingShares: () => Promise<IncomingShare[]>;
   /** One share by id, as posted; null when unknown or removed. */

package/core/test/acpsPrepare.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import type { Hex } from 'viem';
+import { ACP_REVOKER_ABI, ACP_SHARE_REGISTRY_ABI, computeShareId, encodeShareMetadata, toChainShare } from '@/acps';
+import { UNLABELLED } from '../../acps/share-metadata';
+import { createMockACP } from '../../acps/test-utils';
+import { acps } from '../acps';
+
+/**
+ * The sharing writes built but not sent: what a caller that sends through its own path
+ * (simulation, transaction store) gets, and what the plain senders send. No chain involved.
+ */
+
+const REGISTRY = '0x00000000000000000000000000000000000000A1';
+const REVOKER = '0x00000000000000000000000000000000000000B2';
+const ALICE = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8';
+const HANDLE: Hex = `0x${'1'.repeat(64)}`;
+
+const signedSharing = (overrides: Parameters<typeof createMockACP>[0] = {}) =>
+  createMockACP({ type: 'sharing', recipient: ALICE, issuerSignature: '0x1234', ...overrides });
+
+describe('prepareShareOnChain', () => {
+  it('a signed sharing acp: the registry share call with the acp and its metadata, and its share id', async () => {
+    const acp = await signedSharing();
+    const { write, shareId } = acps.prepareShareOnChain(acp, REGISTRY);
+    expect(write).toStrictEqual({
+      address: REGISTRY,
+      abi: ACP_SHARE_REGISTRY_ABI,
+      functionName: 'share',
+      args: [toChainShare(acp), '0x'],
+    });
+    expect(shareId).toBe(computeShareId(acp));
+  });
+
+  it('posts the labels it is given, else the metadata on the acp', async () => {
+    const acp = await signedSharing({ handles: [HANDLE] });
+    const labelled = acps.prepareShareOnChain(acp, REGISTRY, { labels: [UNLABELLED] });
+    expect(labelled.write.args[1]).toBe(encodeShareMetadata([UNLABELLED], { issuer: acp.issuer }));
+
+    const kept = acps.prepareShareOnChain({ ...acp, metadata: '0xdead' }, REGISTRY);
+    expect(kept.write.args[1]).toBe('0xdead');
+  });
+
+  it('refuses a self acp and an unsigned sharing acp', async () => {
+    const self = await createMockACP();
+    expect(() => acps.prepareShareOnChain(self, REGISTRY)).toThrow(/only 'sharing' ACPs/);
+    const unsigned = await createMockACP({ type: 'sharing', recipient: ALICE });
+    expect(() => acps.prepareShareOnChain(unsigned, REGISTRY)).toThrow(/sign it first/);
+  });
+});
+
+describe('prepareRemoveShare', () => {
+  it('the registry removeShare call for the share id', () => {
+    expect(acps.prepareRemoveShare(HANDLE, REGISTRY)).toStrictEqual({
+      address: REGISTRY,
+      abi: ACP_SHARE_REGISTRY_ABI,
+      functionName: 'removeShare',
+      args: [HANDLE],
+    });
+  });
+});
+
+describe('prepareRevokeACP', () => {
+  it('the revoker revokeSingle call for the acp revoker data', async () => {
+    const acp = await signedSharing({ revokerContract: REVOKER, revokerData: 42 });
+    expect(acps.prepareRevokeACP(acp)).toStrictEqual({
+      address: REVOKER,
+      abi: ACP_REVOKER_ABI,
+      functionName: 'revokeSingle',
+      args: [42n],
+    });
+  });
+
+  it('refuses an acp without a revoker', async () => {
+    const acp = await signedSharing();
+    expect(() => acps.prepareRevokeACP(acp)).toThrow(/not revocable/);
+  });
+});