@cofhe/mock-contracts 0.0.0-alpha-20260409113701

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# @cofhe/mock-contracts Changelog
+
+## 0.0.0-alpha-20260409113701
+
+## 0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- d4e86ea: Aligns with CTA encrypted variables bytes32 representation.
+
+  - **@cofhe/hardhat-plugin**: `hre.cofhe.mocks.getTestBed()`, `getMockTaskManager()`, `getMockACL()`, `getMockThresholdNetwork()`, and `getMockZkVerifier()` now return typed contracts (typechain interfaces) instead of untyped `Contract`. `getPlaintext(ctHash)` and `expectPlaintext(ctHash, value)` now accept bytes32 ctHashes as `string` support cofhe-contracts 0.1.0 CTA changes.
+  - **@cofhe/mock-contracts**: Export typechain-generated contract types (`TestBed`, `MockACL`, `MockTaskManager`, `MockZkVerifier`, `MockThresholdNetwork`) for use with the hardhat plugin. Typechain is run from artifact ABIs only; factory files are not generated.
+  - **@cofhe/abi**: CTA-related types use `bytes32` (string) instead of `uint256`. Decryption and return-type helpers aligned with cofhe-contracts 0.1.0.
+  - **@cofhe/sdk**: Decryption APIs (`decryptForTx`, `decryptForView`, and related builders) now also accept `string` for ciphertext hashes (bytes32) as well as `bigint`.
+
+## 0.3.1
+
+### Patch Changes
+
+- 370f0c7: no-op
+
+## 0.3.0
+
+### Minor Changes
+
+- 35024b6: Remove `sdk` from function names and exported types. Rename:
+
+  - `createCofhesdkConfig` -> `createCofheConfig`
+  - `createCofhesdkClient` -> `createCofheClient`
+  - `hre.cofhesdk.*` -> `hre.cofhe.*`
+  - `hre.cofhesdk.createCofheConfig()` → `hre.cofhe.createConfig()`
+  - `hre.cofhesdk.createCofheClient()` → `hre.cofhe.createClient()`
+  - `hre.cofhesdk.createBatteriesIncludedCofheClient()` → `hre.cofhe.createClientWithBatteries()`
+
+- 29c2401: implement decrypt-with-proof flows and related tests:
+
+  - Implement production `decryptForTx` backed by Threshold Network `POST /decrypt`, with explicit permit vs global-allowance selection.
+  - Rename mocks “Query Decrypter” -> “Threshold Network” and update SDK constants/contracts/artifacts accordingly.
+  - Extend mock contracts + hardhat plugin to publish & verify decryption results on-chain, and add end-to-end integration tests.
+
+## 0.2.1
+
+### Patch Changes
+
+- ac47e2f: Add `PermitUtils.checkValidityOnChain` to validate permits against the on-chain deployed ACL (source of truth).
+- 0000d5e: Mock contracts deployed to alternate fixed addresses to avoid collision with hardhat pre-compiles.
+
+## 0.2.0
+
+### Minor Changes
+
+- 8fda09a: Removes `Promise<boolean>` return type from `client.connect(...)`, instead throws an error if the connection fails.
+- e0caeca: Adds `environment: 'node' | 'web' | 'hardhat' | 'react'` option to config. Exposed via `client.config.enviroment`. Automatically populated appropriately within the various `createCofhesdkConfig` functions.
+
+### Patch Changes
+
+- e121108: Fix ACL permission invalid issue. MockACL needs real deployment since etching doesn't call the constructor, so the EIP712 is uninitialized. Also adds additional utility functions to hardhat-plugin:
+
+  - `hre.cofhesdk.connectWithHardhatSigner(client, signer)` - Connect to client with hardhat ethers signer.
+  - `hre.cofhesdk.createBatteriesIncludedCofhesdkClient()` - Creates a batteries included client with signer connected.
+  - `hre.cofhesdk.mocks.getMockTaskManager()` - Gets deployed Mock Taskmanager
+  - `hre.cofhesdk.mocks.getMockACL()` - Gets deployed Mock ACL
+
+## 0.1.1
+
+### Patch Changes
+
+- a1d1323: Add repository info to package.json of public packages to fix npm publish provenance issue.
+- d232d11: Ensure publish includes correct src and dist files
+- b6521fb: Update publish workflow to create versioning PR upon merge with changeset.
+
+## 0.1.0
+
+### Minor Changes
+
+- 8d41cf2: Combine existing packages into more reasonable defaults. New package layout is @cofhe/sdk (includes all the core logic for configuring and creating a @cofhe/sdk client, encrypting values, and decrypting handles), mock-contracts, hardhat-plugin, and react.
+- a83facb: Prepare for initial release. Rename scope from `@cofhesdk` to `@cofhe` and rename `cofhesdk` package to `@cofhe/sdk`. Create `publish.yml` to publish `beta` packages on merged PR, and `latest` on changeset PR.
+- 58e93a8: Migrate cofhe-mock-contracts and cofhe-hardhat-plugin into @cofhe/sdk.
+
+This changelog is maintained by Changesets and will be populated on each release.
+
+- Do not edit this file by hand.
+- Upcoming changes can be previewed with `pnpm changeset status --verbose`.
+- Entries are generated when the Changesets "Version Packages" PR is created/merged.

package/README.md

@@ -0,0 +1,180 @@
+# cofhe/mock-contracts [![NPM Package][npm-badge]][npm] [![License: MIT][license-badge]][license]
+
+[npm]: https://www.npmjs.com/package/@fhenixprotocol/cofhe-mock-contracts
+[npm-badge]: https://img.shields.io/npm/v/@fhenixprotocol/cofhe-mock-contracts.svg
+[license]: https://opensource.org/licenses/MIT
+[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
+
+A mock smart contract library for testing CoFHE (Confidential Computing Framework for Homomorphic Encryption) with FHE primitives. This package provides mock implementations of core CoFHE contracts for development and testing purposes.
+
+## Features
+
+- Mock implementations of core CoFHE contracts:
+  - MockTaskManager
+  - MockThresholdNetwork
+  - MockZkVerifier
+  - ACL (Access Control List)
+- Synchronous operation simulation with mock delays
+- On-chain access to unencrypted values for testing
+- Compatible with the main `@fhenixprotocol/cofhe-contracts` package
+
+## Installation
+
+npm
+
+```bash
+npm install @fhenixprotocol/cofhe-mock-contracts
+```
+
+foundry
+
+```bash
+forge install fhenixprotocol/cofhe-mock-contracts
+```
+
+## Usages and Integrations
+
+### Who is this for?
+
+This package is intended for **developers building and testing CoFHE-enabled applications and smart contracts**.
+
+Use these mocks when you want to:
+
+- Run **local tests** without depending on the real CoFHE coprocessor infrastructure.
+- Debug flows end-to-end (encrypt → submit → operate → decrypt) with fast iteration.
+- Assert on results deterministically in CI.
+
+Do **not** use these mocks for production deployments: they intentionally make testing convenient (e.g. storing plaintext on-chain for inspection) and therefore **do not provide real confidentiality guarantees**.
+
+### Hardhat integration vs Foundry integration
+
+Both integrations use the same underlying mock contracts, but they differ in **how mocks get deployed** and **how you interact with them**.
+
+#### Hardhat (recommended for TS/SDK + Solidity tests)
+
+Use this when you are already using **Hardhat** and/or want to run the **TypeScript SDK (`@cofhe/sdk`)** against a local chain.
+
+- The `cofhesdk/hardhat-plugin` watches Hardhat `node` and `test` tasks.
+- It automatically deploys the mocks to the Hardhat network at fixed addresses.
+- The `cofheClient` (created with `createCofheClient(...)`) detects the mocks and routes CoFHE actions to them.
+
+Minimal setup:
+
+```ts
+// hardhat.config.ts
+import 'cofhe-hardhat-plugin';
+
+export default {
+  cofhe: {
+    logMocks: true, // optional
+  },
+};
+```
+
+Run:
+
+```bash
+npx hardhat test
+# or
+npx hardhat node
+```
+
+If you want to assert on plaintext values in Hardhat tests, the plugin exposes helpers like `mock_expectPlaintext(...)` (see the hardhat-plugin README).
+
+#### Foundry (recommended for Solidity-only tests)
+
+Use this when you are writing tests in **Solidity** and running them with `forge test`.
+
+- You typically inherit from the abstract `CoFheTest` helper to deploy/setup the necessary FHE mock environment.
+- You use helper methods to create encrypted inputs and assert their underlying values.
+
+> **Important**: You must set `isolate = true` in your `foundry.toml`. Without this setting, some variables may be used without proper permission checks, which will cause failures on production chains.
+
+`@cofhe/sdk` is designed to work with mock contracts in a testing / hardhat environment. `cofhesdk/hardhat-plugin` deploys the mock contracts in this repo, and the `cofheClient` detects a testnet chain and interacts correctly using the mocks rather than the true CoFHE coprocessor.
+
+When installed and imported in the `hardhat.config.ts`, `cofhesdk/hardhat-plugin` will watch for Hardhat `node` and `test` tasks, and will deploy the mocks to the hardhat testnet chain at fixed addresses.
+
+Once deployed, interaction with the mock contracts is handled by the `cofheClient` (created with `createCofheClient(...)`). The client checks for the existence of mock contracts at known addresses, and if they exist, marks the current connection as a testnet.
+
+## Logging
+
+By default the mock CoFHE contracts log the internal "FHE" operations using `hardhat/console.sol`. Logs can be enabled or disabled using the `setLogOps()` function in `MockTaskManager.sol`.
+
+## Differences between Cofhe and Mocks
+
+### Symbolic Execution
+
+The CoFHE coprocessor uses symbolic execution when performing operations on chain. Each ciphertext exists off-chain, and is represented by an on-chain ciphertext hash (`ctHash`).
+
+FHE operations between one or more `ctHash`es returns a resultant `ctHash`, which is symbolically linked to the true `ciphertext` which includes the encrypted values.
+
+In `cofhe-mock-contracts` the symbolic execution is preserved. In the case of the mocks, the `ciphertext` is not encrypted to be used in the FHE scheme, but is stored as a plaintext value. In this case, the `ctHash` associated with the `ciphertext` is pointing directly at the plaintext value instead.
+
+During the execution of a mock FHE operation, say `FHE.add(euint8 ctHashA, euint8 ctHashB) -> euint8 ctHashC`, rather than being performed off-chain by the FHE computation engine, the input `ctHashes` are mapped to their plaintext value, and the operation performed as plaintext math on-chain. The result is inserted into the symbolic value position of `ctHashC`.
+
+### On-chain Decryption
+
+CoFHE coprocessor handles on-chain decryption requests asynchronously. Once the decryption is requested with `FHE.decrypt(...)` the decryption will be performed off-chain by CoFHE, and the result posted on-chain in the `PlaintextStorage` module of `TaskManager`. The decryption result can then checked using either `FHE.getDecryptResult(...)` or `FHE.getDecryptResultSafe(...)`.
+
+When a mock decryption is requested, a random number between 1 and 10 is generated to determine how many seconds the mock decryption async duration. Though the decryption result is available immediately within the mock contracts, the async duration is added to mimic the off-chain decryption and posting time.
+
+### ZkVerifying
+
+A key component of CoFHE is the ability to pre-encrypt inputs in a secure and verifiable way. `cofhesdk` prepares these inputs automatically, and requests a verification signature from the coprocessor `ZkVerifier` module. The zkVerifier returns a signature indicating that the encrypted ciphertext is valid, and has been stored on the Fhenix L2 blockchain.
+
+The mocks are then responsible for mocking two actions:
+
+1. Creating the signature.
+2. Storing the plaintext value on-chain.
+
+The `MockZkVerifier` contract handles the on-chain storage of encrypted inputs. The signature creation is handled automatically within `cofheClient.encryptInputs` when executing against a testnet.
+
+### Off-chain Decryption / Sealing
+
+Off-chain decryption is performed by calling the `cofheClient.decryptHandle` function with a valid `ctHash` and a valid `permit` [todo link].
+
+When interacting with CoFHE this request is routed to the Threshold Network, which will perform the decryption operation, ultimately returning a decrypted result.
+
+When working with the mocks, the `cofheClient` will instead query the `MockThresholdNetwork` contract, which will verify the request `permit`, and return the decrypted result.
+
+### Using Foundry
+
+Use abstract CoFheTest contract to automatically deploy all necessary FHE contracts for testing.
+
+CoFheTest also exposes useful test methods such as
+
+- `assertHashValue(euint, uint)` - asserting an encrypted value is equal to an expected plaintext value
+- `createInEuint..(number, user)` - for creating encrypted inputs (8-256bits) for a given user
+
+see `contracts/TestBed.sol` for the original contract
+
+```solidity
+import {Test} from "forge-std/Test.sol";
+import {CoFheTest} from "@fhenixprotocol/cofhe-contracts/FHE.sol";
+...
+contract TestBed is Test, CoFheTest {
+
+  TestBed private testbed;
+
+  address private user = makeAddr("user");
+
+  function setUp() public {
+    // optional ... enable verbose logging for fhe mocks
+    // setLog(true);
+
+    testbed = new TestBed();
+  }
+
+  function testSetNumber() public {
+    uint32 n = 10;
+    InEuint32 memory number = createInEuint32(n, user);
+
+    //must be the user who sends transaction
+    //or else invalid permissions from fhe allow
+    vm.prank(user);
+    testbed.setNumber(number);
+
+    assertHashValue(testbed.eNumber(), n);
+  }
+}
+```

package/contracts/ABITest.sol

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.13;
+
+import '@fhenixprotocol/cofhe-contracts/FHE.sol';
+
+contract ABITest {
+  euint32 public eNumber;
+  uint256 public numberHash;
+
+  euint8 public eUint8;
+  euint16 public eUint16;
+  euint32 public eUint32;
+  euint64 public eUint64;
+  euint128 public eUint128;
+  ebool public eBool;
+  eaddress public eAddress;
+
+  constructor() {
+    eUint8 = FHE.asEuint8(1);
+    eUint16 = FHE.asEuint16(1);
+    eUint32 = FHE.asEuint32(1);
+    eUint64 = FHE.asEuint64(1);
+    eUint128 = FHE.asEuint128(1);
+    eBool = FHE.asEbool(true);
+    eAddress = FHE.asEaddress(address(0));
+  }
+
+  struct ContainsEncryptedInput {
+    uint256 value;
+    InEuint32 encryptedInput;
+  }
+
+  struct ContainsEncryptedResult {
+    uint256 value;
+    euint32 encryptedResult;
+  }
+
+  // INPUTS
+
+  function fnNoEncryptedInputs(uint8 value) public {}
+
+  function fnEncryptedInput(InEuint32 memory inNumber) public {}
+
+  function fnBlendedInputsIncludingEncryptedInput(uint256 value, InEuint32 memory inNumber) public {}
+
+  function fnAllEncryptedInputs(
+    InEuint8 memory inEuint8,
+    InEuint16 memory inEuint16,
+    InEuint32 memory inEuint32,
+    InEuint64 memory inEuint64,
+    InEuint128 memory inEuint128,
+    InEbool memory inEbool,
+    InEaddress memory inEaddress
+  ) public {}
+
+  function fnStructContainsEncryptedInput(ContainsEncryptedInput memory containsEncryptedInput) public {}
+
+  function fnArrayContainsEncryptedInput(InEuint32[] memory inEuint32Array) public {}
+
+  function fnTupleContainsEncryptedInput(InEuint32[2] memory inEuint32Array) public {}
+
+  // OUTPUTS
+
+  function fnReturnNoEncrypted() public pure returns (uint256) {
+    return 1;
+  }
+
+  function fnReturnEncrypted() public view returns (euint32) {
+    return eUint32;
+  }
+
+  function fnReturnBlendedIncludingEncrypted() public view returns (uint256, euint32) {
+    return (1, eUint32);
+  }
+
+  function fnReturnEncryptedArray() public view returns (euint32[] memory) {
+    euint32[] memory encryptedArray = new euint32[](1);
+    encryptedArray[0] = eUint32;
+    return encryptedArray;
+  }
+
+  function fnReturnEncryptedStruct() public view returns (ContainsEncryptedResult memory) {
+    ContainsEncryptedResult memory encryptedResult = ContainsEncryptedResult({ value: 1, encryptedResult: eUint32 });
+    return encryptedResult;
+  }
+
+  function fnReturnAllEncrypted() public view returns (euint8, euint16, euint32, euint64, euint128, ebool, eaddress) {
+    return (eUint8, eUint16, eUint32, eUint64, eUint128, eBool, eAddress);
+  }
+
+  // EVENTS
+
+  event EventNoEncryptedInputs(uint8 value);
+  event EncryptedValue(euint32 value);
+  event BlendedValue(uint256 value, euint32 encryptedValue);
+  event EncryptedArray(euint32[] value);
+  event EncryptedStruct(ContainsEncryptedResult value);
+  event AllEncrypted(euint8, euint16, euint32, euint64, euint128, ebool, eaddress);
+}