@cofhe/sdk 1.0.0 → 1.1.0-alpha.0

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