@cofhe/sdk 1.0.0-alpha.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @cofhe/sdk Changelog
 
+## 1.0.1
+
+### Patch Changes
+
+- fcc819c: **Breaking:** `encryptInputs(...).execute()` now binds the consuming contract into the ZK proof itself, and the CoFHE verifier requires it. Upgrade to 1.0.1: 1.0.0 is deprecated because of an issue in ZK verification, and once the verifier is updated a proof from 1.0.0 fails with `ZK_VERIFY_FAILED`. No code change is needed beyond the upgrade; `setConsumingContract(...)` was already required.
+
+  `execute()` now throws `CofheError` with code `CONSUMING_CONTRACT_INVALID` when `setConsumingContract(...)` was given something that is not an address, before TFHE is initialised or any proving starts. The check is byte-level, 20 bytes of hex in any case, and does not validate the EIP-55 checksum, so every address 1.0.0 accepted still passes. Previously the bad address reached the verifier and failed there, after the proof was generated. `CofheErrorCode` gains `ConsumingContractInvalid`; an exhaustive `switch` over the enum needs the new arm.
+
+## 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/encrypt/encryptInputsBuilder.ts

@@ -21,7 +21,7 @@ import { cofheMocksCheckEncryptableBits, cofheMocksZkVerifySign } from './cofheM
 import { hardhat } from 'viem/chains';
 import { fetchKeys, type FheKeyDeserializer } from '../fetchKeys.js';
 import { getZkVerifierUrlOrThrow } from '../config.js';
-import { type WalletClient } from 'viem';
+import { type WalletClient, isAddress } from 'viem';
 import { sleep } from '../utils.js';
 import { BaseBuilder, type BaseBuilderParams } from '../baseBuilder.js';
 import { type KeysStorage } from '../keyStore.js';
@@ -256,19 +256,37 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
   }
 
   /**
-   * Asserts that this.consumingContract is populated
-   * @throws {CofheError} If consumingContract is not set
+   * Asserts that this.consumingContract is populated and is an address.
+   * Runs before TFHE init, key fetching and proving, so a bad address costs
+   * nothing: the contract is bound into the proof, and a proof built for a
+   * non-address could only fail at the verifier, after the expensive step.
+   * @throws {CofheError} If consumingContract is not set or is not an address
    */
   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,
-      },
-    });
+    if (!this.consumingContract) {
+      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,
+        },
+      });
+    }
+    // strict: false — 20 bytes of hex in any case, no EIP-55 checksum check. The
+    // verifier decodes the address case-insensitively and the chain compares bytes,
+    // so a mixed-case address with a wrong checksum works end to end and a patch
+    // release must keep accepting it.
+    if (!isAddress(this.consumingContract, { strict: false })) {
+      throw new CofheError({
+        code: CofheErrorCode.ConsumingContractInvalid,
+        message: 'Consuming contract is not an address',
+        hint: 'setConsumingContract(...) takes the 20-byte address of the contract that will consume the encrypted inputs.',
+        context: {
+          consumingContract: this.consumingContract,
+        },
+      });
+    }
   }
 
   /**
@@ -567,7 +585,7 @@ export class EncryptInputsBuilder<T extends EncryptableItem[]> extends BaseBuild
     this.fireStepStart(EncryptStep.Prove);
 
     // Construct metadata once (used by both worker and main thread paths)
-    const metadata = constructZkPoKMetadata(this.account, this.securityZone, this.chainId);
+    const metadata = constructZkPoKMetadata(this.account, this.securityZone, this.chainId, this.consumingContract);
 
     let proof: Uint8Array | null = null;
     let usedWorker = false;

package/core/encrypt/zkPackProveVerify.ts

@@ -239,13 +239,24 @@ export const zkProve = async (
 };
 
 /**
- * Constructs the ZK Proof of Knowledge metadata for the proof
+ * Constructs the ZK Proof of Knowledge metadata for the proof:
+ * `securityZone (1) || account (20) || chainId (32, big-endian) || consumingContract (20)`.
+ *
+ * The verifier rebuilds the same bytes from the request fields before it checks the proof, so the
+ * proof is bound to the consuming contract itself, not only to the signature the verifier returns.
  * @internal - Used internally within the encrypt module
  */
-export const constructZkPoKMetadata = (accountAddr: string, securityZone: number, chainId: number): Uint8Array => {
-  // Decode the account address from hex
+export const constructZkPoKMetadata = (
+  accountAddr: string,
+  securityZone: number,
+  chainId: number,
+  consumingContract: string
+): Uint8Array => {
+  // Decode the account and contract addresses from hex
   const accountAddrNoPrefix = accountAddr.startsWith('0x') ? accountAddr.slice(2) : accountAddr;
   const accountBytes = hexToBytes(accountAddrNoPrefix);
+  const contractNoPrefix = consumingContract.startsWith('0x') ? consumingContract.slice(2) : consumingContract;
+  const contractBytes = hexToBytes(contractNoPrefix);
 
   // Encode chainId as 32 bytes (u256) in big-endian format
   const chainIdBytes = new Uint8Array(32);
@@ -259,10 +270,11 @@ export const constructZkPoKMetadata = (accountAddr: string, securityZone: number
     value = value >>> 8;
   }
 
-  const metadata = new Uint8Array(1 + accountBytes.length + 32);
+  const metadata = new Uint8Array(1 + accountBytes.length + 32 + contractBytes.length);
   metadata[0] = securityZone;
   metadata.set(accountBytes, 1);
   metadata.set(chainIdBytes, 1 + accountBytes.length);
+  metadata.set(contractBytes, 1 + accountBytes.length + 32);
 
   return metadata;
 };

package/core/error.ts

@@ -16,6 +16,7 @@ export enum CofheErrorCode {
   AccountUninitialized = 'ACCOUNT_UNINITIALIZED',
   ChainIdUninitialized = 'CHAIN_ID_UNINITIALIZED',
   ConsumingContractUninitialized = 'CONSUMING_CONTRACT_UNINITIALIZED',
+  ConsumingContractInvalid = 'CONSUMING_CONTRACT_INVALID',
   SealOutputFailed = 'SEAL_OUTPUT_FAILED',
   SealOutputReturnedNull = 'SEAL_OUTPUT_RETURNED_NULL',
   InvalidUtype = 'INVALID_UTYPE',

package/core/test/encryptInputsBuilder.test.ts

@@ -10,7 +10,7 @@ import {
 } from '../types.js';
 import { CofheError, CofheErrorCode } from '../error.js';
 import { fromHexString, toHexString } from '../utils.js';
-import { type PublicClient, createPublicClient, http, type WalletClient, createWalletClient } from 'viem';
+import { type PublicClient, createPublicClient, http, type WalletClient, createWalletClient, isAddress } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia } from 'viem/chains';
 import { type CofheConfig, createCofheConfigBase } from '../config.js';
@@ -53,9 +53,9 @@ const unpackMetadata = (metadata: string) => {
 
 export const deconstructZkPoKMetadata = (
   metadata: Uint8Array
-): { accountAddr: string; securityZone: number; chainId: number } => {
-  if (metadata.length < 53) {
-    // 1 + 20 + 32 = 53 bytes minimum
+): { accountAddr: string; securityZone: number; chainId: number; contractAddr: string } => {
+  if (metadata.length < 73) {
+    // 1 + 20 + 32 + 20 = 73 bytes minimum
     throw new CofheError({
       code: CofheErrorCode.InternalError,
       message: 'Invalid metadata: insufficient length',
@@ -78,10 +78,14 @@ export const deconstructZkPoKMetadata = (
     chainId = (chainId << 8) | chainIdBytes[i];
   }
 
+  // Extract the consuming contract (last 20 bytes)
+  const contractAddr = '0x' + toHexString(metadata.slice(53, 73));
+
   return {
     accountAddr,
     securityZone,
     chainId,
+    contractAddr,
   };
 };
 
@@ -445,6 +449,38 @@ describe('EncryptInputsBuilder', () => {
         expect((error as CofheError).code).toBe(CofheErrorCode.ConsumingContractUninitialized);
       }
     });
+
+    it('accepts a mixed-case consuming contract whose checksum is wrong', async () => {
+      // The verifier decodes the address case-insensitively and the chain compares
+      // 20 bytes, so a 1.0.0 dApp with such an address must keep working.
+      const wrongChecksum = '0xBEEFbeefBEEFbeefBEEFbeefBEEFbeefBEEFbeef';
+      expect(isAddress(wrongChecksum)).toBe(false);
+      expect(isAddress(wrongChecksum, { strict: false })).toBe(true);
+
+      const result = await new EncryptInputsBuilder(createDefaultParams())
+        .setConsumingContract(wrongChecksum)
+        .execute();
+
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it('rejects a consuming contract that is not an address before any encrypt step runs', async () => {
+      for (const notAnAddress of ['0x0', 'not-an-address', '0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbee']) {
+        const steps = vi.fn();
+        const invalid = new EncryptInputsBuilder(createDefaultParams())
+          .setConsumingContract(notAnAddress)
+          .onStep(steps);
+        try {
+          await invalid.execute();
+          expect.unreachable(`execute() should have thrown for ${notAnAddress}`);
+        } catch (error) {
+          expect(error, notAnAddress).toBeInstanceOf(CofheError);
+          expect((error as CofheError).code, notAnAddress).toBe(CofheErrorCode.ConsumingContractInvalid);
+        }
+        // Rejected before initTfhe, so no step (and no proving) ever started.
+        expect(steps, notAnAddress).not.toHaveBeenCalled();
+      }
+    });
   });
 
   describe('zkVerifierUrl', () => {
@@ -595,6 +631,22 @@ describe('EncryptInputsBuilder', () => {
       expect(encryptedMetadata.chainId).toBe(defaultChainId);
     });
 
+    it('binds the consuming contract into the proof metadata', async () => {
+      mockFetch.mockClear();
+
+      await builder.execute();
+
+      const verifyCall = mockFetch.mock.calls.find(([url]) => url === `${MockZkVerifierUrl}/verifyBatch`);
+      expect(verifyCall).toBeDefined();
+      const body = JSON.parse(verifyCall![1].body as string);
+      const { metadata } = parseWithBigInt(new TextDecoder().decode(fromHexString(body.packed_list)));
+      const embedded = deconstructZkPoKMetadata(Uint8Array.from(Object.values(metadata) as number[]));
+      expect(embedded.accountAddr).toBe(defaultSender);
+      expect(embedded.securityZone).toBe(0);
+      expect(embedded.chainId).toBe(defaultChainId);
+      expect(embedded.contractAddr).toBe(defaultConsumingContract);
+    });
+
     it('should use overridden account when set', async () => {
       const overriddenSender = '0x5555555555555555555555555555555555555555';
       builder.setAccount(overriddenSender);

package/core/test/zkPoKMetadata.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { constructZkPoKMetadata } from '../encrypt/zkPackProveVerify.js';
+import { toHexString } from '../utils.js';
+
+describe('constructZkPoKMetadata', () => {
+  const account = '0x1234567890123456789012345678901234567890';
+  const contract = '0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbeef';
+
+  it('lays out security zone, account, chain id and the consuming contract', () => {
+    const metadata = constructZkPoKMetadata(account, 3, 0x010203, contract);
+
+    expect(metadata.length).toBe(1 + 20 + 32 + 20);
+    expect(metadata[0]).toBe(3);
+    expect('0x' + toHexString(metadata.slice(1, 21))).toBe(account);
+    const chainId = metadata.slice(21, 53);
+    expect(Array.from(chainId.slice(0, 29))).toEqual(new Array(29).fill(0));
+    expect(Array.from(chainId.slice(29))).toEqual([1, 2, 3]);
+    expect('0x' + toHexString(metadata.slice(53))).toBe(contract);
+  });
+
+  it('accepts the consuming contract with or without the 0x prefix', () => {
+    const withPrefix = constructZkPoKMetadata(account, 0, 1, contract);
+    const withoutPrefix = constructZkPoKMetadata(account, 0, 1, contract.slice(2));
+
+    expect(Array.from(withoutPrefix)).toEqual(Array.from(withPrefix));
+  });
+});