@cofhe/sdk 0.6.0 → 0.7.0

package/core/encrypt/encryptInputsBuilder.ts

@@ -1,10 +1,11 @@
 import {
   type ZkBuilderAndCrsGenerator,
   type ZkProveWorkerFunction,
+  type VerifyBatchResult,
   zkPack,
   zkProve,
   zkProveWithWorker,
-  zkVerify,
+  zkVerifyBatch,
   constructZkPoKMetadata,
 } from './zkPackProveVerify.js';
 import { CofheError, CofheErrorCode } from '../error.js';
@@ -12,8 +13,6 @@ import {
   type EncryptStepCallbackFunction,
   EncryptStep,
   type EncryptableItem,
-  type EncryptedItemInput,
-  type EncryptedItemInputs,
   type TfheInitializer,
   type EncryptStepCallbackContext,
   type HashPlusProofResult,
@@ -48,11 +47,20 @@ type EncryptInputsBuilderParams<T extends EncryptableItem[]> = BaseBuilderParams
  * config, tfhePublicKeyDeserializer, compactPkeCrsDeserializer, and zkBuilderAndCrsGenerator are required to be set in the builder.
  */
 
-export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boolean = false> extends BaseBuilder {
+/**
+ * The builder as returned by `client.encryptInputs(...)`, before a consuming contract has been set.
+ *
+ * `execute()` is intentionally absent: the verifier binds the consuming contract into the signed
+ * digest, so no batch can be produced until the caller commits to the contract that will consume it.
+ * `setConsumingContract(...)` returns the full {@link EncryptInputsBuilder}, unlocking `execute()`.
+ */
+export type EncryptInputsBuilderUnset<T extends EncryptableItem[]> = Omit<EncryptInputsBuilder<T>, 'execute'>;
+
+export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuilder {
   private securityZone: number;
+  protected consumingContract: string | undefined;
   private stepCallback?: EncryptStepCallbackFunction;
   private inputItems: [...T];
-  private hpp: boolean = false;
 
   private zkvWalletClient: WalletClient | undefined;
 
@@ -156,7 +164,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The chainable EncryptInputsBuilder instance.
    */
-  setAccount(account: string): EncryptInputsBuilder<T, HPP> {
+  setAccount(this: EncryptInputsBuilder<T>, account: string): EncryptInputsBuilder<T>;
+  setAccount(this: EncryptInputsBuilderUnset<T>, account: string): EncryptInputsBuilderUnset<T>;
+  setAccount(account: string): EncryptInputsBuilder<T> {
     this.account = account;
     return this;
   }
@@ -179,7 +189,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The chainable EncryptInputsBuilder instance.
    */
-  setChainId(chainId: number): EncryptInputsBuilder<T, HPP> {
+  setChainId(this: EncryptInputsBuilder<T>, chainId: number): EncryptInputsBuilder<T>;
+  setChainId(this: EncryptInputsBuilderUnset<T>, chainId: number): EncryptInputsBuilderUnset<T>;
+  setChainId(chainId: number): EncryptInputsBuilder<T> {
     this.chainId = chainId;
     return this;
   }
@@ -202,7 +214,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The chainable EncryptInputsBuilder instance.
    */
-  setSecurityZone(securityZone: number): EncryptInputsBuilder<T, HPP> {
+  setSecurityZone(this: EncryptInputsBuilder<T>, securityZone: number): EncryptInputsBuilder<T>;
+  setSecurityZone(this: EncryptInputsBuilderUnset<T>, securityZone: number): EncryptInputsBuilderUnset<T>;
+  setSecurityZone(securityZone: number): EncryptInputsBuilder<T> {
     this.securityZone = securityZone;
     return this;
   }
@@ -212,18 +226,44 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
   }
 
   /**
+   * @param address - The contract that will consume the resulting hashes+signature (i.e. the
+   * contract that will call `FHE.asEuint*`/`FHE.asEuint*s` with them).
+   *
+   * Required before `execute()` - the verifier binds this address into the signed digest, so a
+   * batch signed for one contract cannot be replayed into another.
+   *
    * Example:
    * ```typescript
    * const encrypted = await encryptInputs([Encryptable.uint128(10n)])
-   *   .asHashPlusProof()
+   *   .setConsumingContract("0x123...890")
    *   .execute();
    * ```
    *
-   * @returns Chainable EncryptInputsBuilder instance that will return a HashPlusProofResult instead of an array of EncryptedItemInputs.
+   * @returns The chainable EncryptInputsBuilder instance.
    */
-  asHashPlusProof(): EncryptInputsBuilder<T, true> {
-    this.hpp = true;
-    return this as unknown as EncryptInputsBuilder<T, true>;
+  setConsumingContract(address: string): EncryptInputsBuilder<T> {
+    this.consumingContract = address;
+    return this;
+  }
+
+  getConsumingContract(): string | undefined {
+    return this.consumingContract;
+  }
+
+  /**
+   * Asserts that this.consumingContract is populated
+   * @throws {CofheError} If consumingContract is not set
+   */
+  private assertConsumingContract(): asserts this is this & { consumingContract: string } {
+    if (this.consumingContract) return;
+    throw new CofheError({
+      code: CofheErrorCode.ConsumingContractUninitialized,
+      message: 'Consuming contract is not set',
+      hint: 'Use setConsumingContract(...) to set the contract that will consume the encrypted inputs.',
+      context: {
+        consumingContract: this.consumingContract,
+      },
+    });
   }
 
   /**
@@ -240,7 +280,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The chainable EncryptInputsBuilder instance.
    */
-  setUseWorker(useWorker: boolean): EncryptInputsBuilder<T, HPP> {
+  setUseWorker(this: EncryptInputsBuilder<T>, useWorker: boolean): EncryptInputsBuilder<T>;
+  setUseWorker(this: EncryptInputsBuilderUnset<T>, useWorker: boolean): EncryptInputsBuilderUnset<T>;
+  setUseWorker(useWorker: boolean): EncryptInputsBuilder<T> {
     this.useWorker = useWorker;
     return this;
   }
@@ -277,7 +319,9 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The EncryptInputsBuilder instance.
    */
-  onStep(callback: EncryptStepCallbackFunction): EncryptInputsBuilder<T, HPP> {
+  onStep(this: EncryptInputsBuilder<T>, callback: EncryptStepCallbackFunction): EncryptInputsBuilder<T>;
+  onStep(this: EncryptInputsBuilderUnset<T>, callback: EncryptStepCallbackFunction): EncryptInputsBuilderUnset<T>;
+  onStep(callback: EncryptStepCallbackFunction): EncryptInputsBuilder<T> {
     this.stepCallback = callback;
     return this;
   }
@@ -433,10 +477,11 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    * cofheMocksInsertPackedHashes - stores the ctHashes and their plaintext values for on-chain mocking of FHE operations.
    * cofheMocksZkCreateProofSignatures - creates signatures to be included in the encrypted inputs. The signers address is known and verified in the mock contracts.
    */
-  private async mocksExecute(): Promise<[...EncryptedItemInputs<T>]> {
+  private async mocksExecute(): Promise<VerifyBatchResult> {
     this.assertAccount();
     this.assertPublicClient();
     this.assertWalletClient();
+    this.assertConsumingContract();
 
     const [initTfheDelay, fetchKeysDelay, packDelay, proveDelay, verifyDelay] = this.resolveEncryptDelays();
 
@@ -468,31 +513,27 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
 
     this.fireStepStart(EncryptStep.Verify);
     await sleep(verifyDelay);
-    const signedResults = await cofheMocksZkVerifySign(
+    const result = await cofheMocksZkVerifySign(
       this.inputItems,
       this.account,
       this.securityZone,
+      this.consumingContract,
       this.publicClient,
       this.walletClient,
       this.zkvWalletClient
     );
-    const encryptedInputs: EncryptedItemInput[] = signedResults.map(({ ct_hash, signature }, index) => ({
-      ctHash: BigInt(ct_hash),
-      securityZone: this.securityZone,
-      utype: this.inputItems[index].utype,
-      signature,
-    }));
     this.fireStepEnd(EncryptStep.Verify, { isMocks: true, mockSleep: verifyDelay });
 
-    return encryptedInputs as [...EncryptedItemInputs<T>];
+    return result;
   }
 
   /**
    * In the production context, perform a true encryption with the CoFHE coprocessor.
    */
-  private async productionExecute(): Promise<[...EncryptedItemInputs<T>]> {
+  private async productionExecute(): Promise<VerifyBatchResult> {
     this.assertAccount();
     this.assertChainId();
+    this.assertConsumingContract();
 
     this.fireStepStart(EncryptStep.InitTfhe);
 
@@ -555,32 +596,28 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
 
     const zkVerifierUrl = await this.getZkVerifierUrl();
 
-    const verifyResults = await zkVerify(zkVerifierUrl, proof, this.account, this.securityZone, this.chainId);
-    // Add securityZone and utype to the verify results
-    const encryptedInputs: EncryptedItemInput[] = verifyResults.map(
-      ({ ct_hash, signature }: { ct_hash: string; signature: `0x${string}` }, index: number) => ({
-        ctHash: BigInt(ct_hash),
-        securityZone: this.securityZone,
-        utype: this.inputItems[index].utype,
-        signature,
-      })
+    const result = await zkVerifyBatch(
+      zkVerifierUrl,
+      proof,
+      this.account,
+      this.securityZone,
+      this.chainId,
+      this.consumingContract
     );
 
     this.fireStepEnd(EncryptStep.Verify);
 
-    return encryptedInputs as [...EncryptedItemInputs<T>];
+    return result;
   }
 
-  private structsToHashPlusProof(inItems: [...EncryptedItemInputs<T>]): HashPlusProofResult<T> {
-    let hashes: string[] = [];
-    let proof: string = '';
-
-    for (const item of inItems) {
-      hashes.push('0x' + item.ctHash.toString(16).padStart(64, '0'));
-      proof += item.signature;
-    }
+  /**
+   * Converts a batch-verified result (per-item ctHash/ctType + one shared signature) into the
+   * tuple returned by `execute()`: per-item hashes in input order, followed by the single signature.
+   */
+  private buildBatchResult(result: VerifyBatchResult): HashPlusProofResult<T> {
+    const hashes = result.outputs.map((output) => '0x' + BigInt(output.ct_hash).toString(16).padStart(64, '0'));
 
-    return [...hashes, proof] as unknown as HashPlusProofResult<T>;
+    return [...hashes, result.signature] as unknown as HashPlusProofResult<T>;
   }
 
   /**
@@ -602,17 +639,14 @@ export class EncryptInputsBuilder<T extends EncryptableItem[], HPP extends boole
    *
    * @returns The encrypted inputs.
    */
-  async execute(): Promise<HPP extends true ? HashPlusProofResult<T> : [...EncryptedItemInputs<T>]> {
-    type Result = HPP extends true ? HashPlusProofResult<T> : [...EncryptedItemInputs<T>];
-
-    let items: [...EncryptedItemInputs<T>];
+  async execute(): Promise<HashPlusProofResult<T>> {
+    let result: VerifyBatchResult;
 
     // On hardhat chain, interact with MockZkVerifier contract instead of CoFHE
-    if (this.chainId === hardhat.id) items = await this.mocksExecute();
+    if (this.chainId === hardhat.id) result = await this.mocksExecute();
     // On other chains, interact with CoFHE coprocessor
-    else items = await this.productionExecute();
+    else result = await this.productionExecute();
 
-    if (this.hpp) return this.structsToHashPlusProof(items) as unknown as Result;
-    return items as unknown as Result;
+    return this.buildBatchResult(result);
   }
 }

package/core/encrypt/zkPackProveVerify.ts

@@ -41,14 +41,19 @@ export interface ZkProveWorkerResponse {
   error?: string;
 }
 
-export type VerifyResultRaw = {
+export type VerifyBatchOutputRaw = {
   ct_hash: string;
+  ct_type: number;
+};
+
+export type VerifyBatchResultRaw = {
+  ciphertexts: VerifyBatchOutputRaw[];
   signature: string;
   recid: number;
 };
 
-export type VerifyResult = {
-  ct_hash: string;
+export type VerifyBatchResult = {
+  outputs: VerifyBatchOutputRaw[];
   signature: `0x${string}`;
 };
 
@@ -256,13 +261,14 @@ export const constructZkPoKMetadata = (accountAddr: string, securityZone: number
   return metadata;
 };
 
-export const zkVerify = async (
+export const zkVerifyBatch = async (
   verifierUrl: string,
   serializedBytes: Uint8Array,
   address: string,
   securityZone: number,
-  chainId: number
-): Promise<VerifyResult[]> => {
+  chainId: number,
+  consumingContract: string
+): Promise<VerifyBatchResult> => {
   // Convert bytearray to hex string
   const packed_list = toHexString(serializedBytes);
 
@@ -274,13 +280,14 @@ export const zkVerify = async (
     account_addr: address,
     security_zone: sz_byte[0],
     chain_id: chainId,
+    contract_address: consumingContract,
   };
 
   const body = JSON.stringify(payload);
 
   // Send request to verification server
   try {
-    const response = await fetch(`${verifierUrl}/verify`, {
+    const response = await fetch(`${verifierUrl}/verifyBatch`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -293,34 +300,34 @@ export const zkVerify = async (
       const errorBody = await response.text();
       throw new CofheError({
         code: CofheErrorCode.ZkVerifyFailed,
-        message: `HTTP error! ZK proof verification failed - ${errorBody}`,
+        message: `HTTP error! ZK batch proof verification failed - ${errorBody}`,
       });
     }
 
-    const json = (await response.json()) as { status: string; data: VerifyResultRaw[]; error: string };
+    const json = (await response.json()) as { status: string; data: VerifyBatchResultRaw; error: string };
 
     if (json.status !== 'success') {
       throw new CofheError({
         code: CofheErrorCode.ZkVerifyFailed,
-        message: `ZK proof verification response malformed - ${json.error}`,
+        message: `ZK batch proof verification response malformed - ${json.error}`,
       });
     }
 
-    return json.data.map(({ ct_hash, signature, recid }) => {
-      return {
-        ct_hash,
-        signature: concatSigRecid(signature, recid),
-      };
-    });
+    const { ciphertexts, signature, recid } = json.data;
+
+    return {
+      outputs: ciphertexts,
+      signature: concatSigRecid(signature, recid),
+    };
   } catch (e) {
     throw new CofheError({
       code: CofheErrorCode.ZkVerifyFailed,
-      message: `ZK proof verification failed`,
+      message: `ZK batch proof verification failed`,
       cause: e instanceof Error ? e : undefined,
     });
   }
 };
 
-const concatSigRecid = (signature: string, recid: number): `0x${string}` => {
+export const concatSigRecid = (signature: string, recid: number): `0x${string}` => {
   return `${signature}${(recid + 27).toString(16).padStart(2, '0')}` as `0x${string}`;
 };

package/core/error.ts

@@ -9,12 +9,13 @@ export enum CofheErrorCode {
   MissingWalletClient = 'MISSING_WALLET_CLIENT',
   MissingProviderParam = 'MISSING_PROVIDER_PARAM',
   EmptySecurityZonesParam = 'EMPTY_SECURITY_ZONES_PARAM',
-  InvalidPermitData = 'INVALID_PERMIT_DATA',
-  InvalidPermitDomain = 'INVALID_PERMIT_DOMAIN',
-  PermitNotFound = 'PERMIT_NOT_FOUND',
-  CannotRemoveLastPermit = 'CANNOT_REMOVE_LAST_PERMIT',
+  InvalidACPData = 'INVALID_ACP_DATA',
+  InvalidACPDomain = 'INVALID_ACP_DOMAIN',
+  ACPNotFound = 'ACP_NOT_FOUND',
+  CannotRemoveLastACP = 'CANNOT_REMOVE_LAST_ACP',
   AccountUninitialized = 'ACCOUNT_UNINITIALIZED',
   ChainIdUninitialized = 'CHAIN_ID_UNINITIALIZED',
+  ConsumingContractUninitialized = 'CONSUMING_CONTRACT_UNINITIALIZED',
   SealOutputFailed = 'SEAL_OUTPUT_FAILED',
   SealOutputReturnedNull = 'SEAL_OUTPUT_RETURNED_NULL',
   InvalidUtype = 'INVALID_UTYPE',
@@ -42,6 +43,26 @@ export enum CofheErrorCode {
   PublicWalletGetChainIdFailed = 'PUBLIC_WALLET_GET_CHAIN_ID_FAILED',
   PublicWalletGetAddressesFailed = 'PUBLIC_WALLET_GET_ADDRESSES_FAILED',
   RehydrateKeysStoreFailed = 'REHYDRATE_KEYS_STORE_FAILED',
+
+  // Threshold-network stable error codes (decrypt/sealoutput), see API-RESPONSES.md
+  BadRequest = 'BAD_REQUEST',
+  UnknownChain = 'UNKNOWN_CHAIN',
+  ACPMalformed = 'ACP_MALFORMED',
+  ACPDenied = 'ACP_DENIED',
+  ACPExpired = 'ACP_EXPIRED',
+  ACPInvalid = 'ACP_INVALID',
+  ACPRevoked = 'ACP_REVOKED',
+  NotPubliclyAllowed = 'NOT_PUBLICLY_ALLOWED',
+  CtNotFound = 'CT_NOT_FOUND',
+  UnsupportedSecurityZone = 'UNSUPPORTED_SECURITY_ZONE',
+  UnsupportedType = 'UNSUPPORTED_TYPE',
+  SigningFailed = 'SIGNING_FAILED',
+  CtSourceError = 'CT_SOURCE_ERROR',
+  ACPVerifierError = 'ACP_VERIFIER_ERROR',
+  CtSourceTimeout = 'CT_SOURCE_TIMEOUT',
+  ACPVerifierTimeout = 'ACP_VERIFIER_TIMEOUT',
+  ACPRequired = 'ACP_REQUIRED',
+  SealFailed = 'SEAL_FAILED',
 }
 
 export type CofheErrorParams = {
@@ -50,6 +71,8 @@ export type CofheErrorParams = {
   cause?: Error;
   hint?: string;
   context?: Record<string, unknown>;
+  /** Raw backend `error` string, when this error originated from a threshold-network response. */
+  apiErrorCode?: string;
 };
 
 /**
@@ -68,8 +91,9 @@ export class CofheError extends Error {
   public readonly cause?: Error;
   public readonly hint?: string;
   public readonly context?: Record<string, unknown>;
+  public readonly apiErrorCode?: string;
 
-  constructor({ code, message, cause, hint, context }: CofheErrorParams) {
+  constructor({ code, message, cause, hint, context, apiErrorCode }: CofheErrorParams) {
     // If there's a cause, append its message to provide full context
     const fullMessage = cause ? `${message} | Caused by: ${cause.message}` : message;
 
@@ -79,6 +103,7 @@ export class CofheError extends Error {
     this.cause = cause;
     this.hint = hint;
     this.context = context;
+    this.apiErrorCode = apiErrorCode;
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
     if (Error.captureStackTrace) {
@@ -101,6 +126,7 @@ export class CofheError extends Error {
       message: wrapperError?.message ?? 'An internal error occurred',
       hint: wrapperError?.hint,
       context: wrapperError?.context,
+      apiErrorCode: wrapperError?.apiErrorCode,
       cause: cause,
     });
   }
@@ -115,6 +141,7 @@ export class CofheError extends Error {
       message: this.message,
       hint: this.hint,
       context: this.context,
+      apiErrorCode: this.apiErrorCode,
       cause: this.cause
         ? {
             name: this.cause.name,
@@ -130,7 +157,8 @@ export class CofheError extends Error {
    * Returns a human-readable string representation of the error
    */
   toString(): string {
-    const parts = [`${this.name} [${this.code}]: ${this.message}`];
+    const codeSuffix = this.apiErrorCode ? ` (api: ${this.apiErrorCode})` : '';
+    const parts = [`${this.name} [${this.code}]${codeSuffix}: ${this.message}`];
 
     if (this.hint) {
       parts.push(`Hint: ${this.hint}`);

package/core/index.ts

@@ -1,8 +1,18 @@
 // Client (base implementations)
 export { createCofheClientBase, InitialConnectStore as CONNECT_STORE_DEFAULTS } from './client.js';
 
+// Debug interceptors (neutral, opt-in network hooks for fault injection / logging)
+export { setCofheDebugInterceptors, getCofheDebugInterceptors, cofheFetch } from './debug.js';
+export type {
+  CofheDebugInterceptors,
+  CofheOnRequest,
+  CofheOnResponse,
+  CofheRequestContext,
+  CofheRequestOverride,
+} from './debug.js';
+
 // Configuration (base implementations)
-export { createCofheConfigBase, getCofheConfigItem } from './config.js';
+export { createCofheConfigBase, getCofheConfigItem, assertNoRenamedConfigKeys } from './config.js';
 export type { CofheConfig, CofheInputConfig, CofheInternalConfig } from './config.js';
 
 // Types
@@ -11,7 +21,7 @@ export type {
   CofheClient as CofheClient,
   CofheClientParams as CofheClientParams,
   CofheClientConnectionState as CofheClientConnectionState,
-  CofheClientPermits as CofheClientPermits,
+  CofheClientACPs as CofheClientACPs,
 } from './clientTypes.js';
 
 export type {
@@ -30,18 +40,8 @@ export type {
   EncryptableAddress,
   // Encrypted types
   EncryptedNumber,
-  EncryptedItemInput,
-  EncryptedBoolInput,
-  EncryptedUint8Input,
-  EncryptedUint16Input,
-  EncryptedUint32Input,
-  EncryptedUint64Input,
-  EncryptedUint128Input,
-  EncryptedAddressInput,
-  EncryptedItemInputs,
-  EncryptableToEncryptedItemInputMap,
   FheTypeValue,
-  // Hash-plus-proof external types
+  // Batch-verified external hash + signature types
   ExternalBoolHash,
   ExternalUint8Hash,
   ExternalUint16Hash,
@@ -71,7 +71,6 @@ export {
   isEncryptableItem,
   EncryptStep,
   isLastEncryptionStep,
-  assertCorrectEncryptedItemInput,
 } from './types.js';
 
 // Error handling
@@ -88,6 +87,7 @@ export type { KeysStorage, KeysStore } from './keyStore.js';
 
 // Builders (exported via client, but can be imported directly for typing)
 export { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+export type { EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 export { DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
 export { DecryptForTxBuilder } from './decrypt/decryptForTxBuilder.js';
 export type { DecryptForTxResult } from './decrypt/decryptForTxBuilder.js';

package/core/test/acpDefaults.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { acps } from '../acps.js';
+
+type ScopeOpts = {
+  revokerData?: number;
+  revokerContract?: string;
+  scope?: number;
+  contracts?: string[];
+  handles?: bigint[];
+};
+const opts = (o: ScopeOpts): ScopeOpts => o;
+
+const CHAIN = 31337;
+const REVOKER = '0x00000000000000000000000000000000000000aa' as `0x${string}`;
+const CONTRACT_A = '0x00000000000000000000000000000000000000bb' as `0x${string}`;
+
+const acpConfig = {
+  defaultRevoker: { [CHAIN]: REVOKER },
+  defaultContractScopes: { [CHAIN]: [CONTRACT_A] },
+};
+
+describe('applyACPDefaults', () => {
+  it('injects default revoker (contract + creation timestamp) when no revoker options given', () => {
+    const before = Math.round(Date.now() / 1000);
+    const result = acps.applyACPDefaults(opts({}), acpConfig, CHAIN);
+    expect(result.revokerContract).toBe(REVOKER);
+    expect(result.revokerData).toBeGreaterThanOrEqual(before - 60); // 60s clock-skew backdating
+    expect(result.revokerData).toBeLessThanOrEqual(Math.round(Date.now() / 1000) - 59);
+  });
+
+  it('does not override an explicit revoker pair', () => {
+    const result = acps.applyACPDefaults({ revokerData: 42, revokerContract: CONTRACT_A }, acpConfig, CHAIN);
+    expect(result.revokerData).toBe(42);
+    expect(result.revokerContract).toBe(CONTRACT_A);
+  });
+
+  it('injects default contract scopes when no scope options given', () => {
+    const result = acps.applyACPDefaults(opts({}), acpConfig, CHAIN);
+    expect(result.contracts).toEqual([CONTRACT_A]);
+  });
+
+  it('does not inject scopes when the caller provides any scope option (incl. explicit scope)', () => {
+    expect(acps.applyACPDefaults(opts({ scope: 0 }), acpConfig, CHAIN).contracts).toBeUndefined();
+    expect(acps.applyACPDefaults(opts({ handles: [1n] }), acpConfig, CHAIN).contracts).toBeUndefined();
+    expect(acps.applyACPDefaults(opts({ contracts: [] }), acpConfig, CHAIN).contracts).toEqual([]);
+  });
+
+  it('no-op for chains without defaults and for missing config', () => {
+    expect(acps.applyACPDefaults(opts({}), acpConfig, 999)).toEqual({});
+    expect(acps.applyACPDefaults(opts({}), undefined, CHAIN)).toEqual({});
+  });
+});