@cofhe/hardhat-plugin 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# @cofhe/hardhat-plugin Changelog
+
+## 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.
+- Updated dependencies [a1d1323]
+- Updated dependencies [d232d11]
+- Updated dependencies [b6521fb]
+  - @cofhe/mock-contracts@0.1.1
+  - @cofhe/sdk@0.1.1
+
+## 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.
+
+### Patch Changes
+
+- Updated dependencies [cba73fd]
+- Updated dependencies [87fc8a0]
+- Updated dependencies [8d41cf2]
+- Updated dependencies [738b9f5]
+- Updated dependencies [a83facb]
+- Updated dependencies [9a7c98e]
+- Updated dependencies [58e93a8]
+- Updated dependencies [fdf26d4]
+- Updated dependencies [f5b8e25]
+- Updated dependencies [3b135a8]
+- Updated dependencies [5b7c43b]
+- Updated dependencies [4bc8182]
+  - @cofhe/sdk@0.1.0
+  - @cofhe/mock-contracts@0.1.0
+
+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/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@cofhe/hardhat-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FhenixProtocol/cofhesdk.git",
+    "directory": "packages/hardhat-plugin"
+  },
   "files": [
-    "dist/**"
+    "dist/**",
+    "src/**",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "@fhenixprotocol/cofhe-contracts": "0.0.13",
@@ -17,8 +24,8 @@
     "fast-glob": "^3.3.2",
     "viem": "^2.0.0",
     "chai": "^4.2.0",
-    "@cofhe/sdk": "0.1.0",
-    "@cofhe/mock-contracts": "0.1.0"
+    "@cofhe/sdk": "0.1.1",
+    "@cofhe/mock-contracts": "0.1.1"
   },
   "devDependencies": {
     "@nomicfoundation/hardhat-ethers": "^3.0.5",
@@ -36,7 +43,7 @@
     "tsup": "^8.0.2",
     "typescript": "5.5.4",
     "@cofhe/tsconfig": "0.1.0",
-    "@cofhe/eslint-config": "0.1.0"
+    "@cofhe/eslint-config": "0.1.1"
   },
   "peerDependencies": {
     "hardhat": "^2.0.0",

package/src/consts.ts

@@ -0,0 +1,10 @@
+export const TASK_COFHE_USE_FAUCET = 'task:cofhe:usefaucet';
+export const TASK_COFHE_MOCKS_SET_LOG_OPS = 'task:cofhe-mocks:setlogops';
+export const TASK_COFHE_MOCKS_DEPLOY = 'task:cofhe-mocks:deploy';
+
+export const TASK_MANAGER_ADDRESS = '0xeA30c4B8b44078Bbf8a6ef5b9f1eC1626C7848D9';
+export const MOCKS_ACL_ADDRESS = '0x0000000000000000000000000000000000000400';
+export const MOCKS_ZK_VERIFIER_ADDRESS = '0x0000000000000000000000000000000000000100';
+export const MOCKS_QUERY_DECRYPTER_ADDRESS = '0x0000000000000000000000000000000000000200';
+export const TEST_BED_ADDRESS = '0x0000000000000000000000000000000000000300';
+export const MOCKS_ZK_VERIFIER_SIGNER_ADDRESS = '0x6E12D8C87503D4287c294f2Fdef96ACd9DFf6bd2';

package/src/deploy.ts

@@ -0,0 +1,242 @@
+import { type HardhatRuntimeEnvironment } from 'hardhat/types';
+import chalk from 'chalk';
+import { Contract } from 'ethers';
+
+import {
+  TASK_MANAGER_ADDRESS,
+  MOCKS_ZK_VERIFIER_ADDRESS,
+  MOCKS_QUERY_DECRYPTER_ADDRESS,
+  TEST_BED_ADDRESS,
+  MOCKS_ZK_VERIFIER_SIGNER_ADDRESS,
+  MOCKS_ACL_ADDRESS,
+} from './consts.js';
+
+import {
+  MockTaskManagerArtifact,
+  MockACLArtifact,
+  MockZkVerifierArtifact,
+  MockQueryDecrypterArtifact,
+  TestBedArtifact,
+} from '@cofhe/mock-contracts';
+
+// Deploy
+
+const deployMockTaskManager = async (hre: HardhatRuntimeEnvironment) => {
+  const [signer] = await hre.ethers.getSigners();
+
+  // Deploy MockTaskManager
+  await hardhatSetCode(hre, TASK_MANAGER_ADDRESS, MockTaskManagerArtifact.deployedBytecode);
+  const taskManager = await hre.ethers.getContractAt(MockTaskManagerArtifact.abi, TASK_MANAGER_ADDRESS);
+
+  // Initialize MockTaskManager
+  const initTx = await taskManager.initialize(signer.address);
+  await initTx.wait();
+
+  // Check if MockTaskManager exists
+  const tmExists = await taskManager.exists();
+  if (!tmExists) {
+    throw new Error('MockTaskManager does not exist');
+  }
+
+  return taskManager;
+};
+
+const deployMockACL = async (hre: HardhatRuntimeEnvironment): Promise<Contract> => {
+  // Deploy MockACL
+  await hardhatSetCode(hre, MOCKS_ACL_ADDRESS, MockACLArtifact.deployedBytecode);
+  const acl = await hre.ethers.getContractAt(MockACLArtifact.abi, MOCKS_ACL_ADDRESS);
+
+  // Check if ACL exists
+  const exists = await acl.exists();
+  if (!exists) {
+    logError('MockACL does not exist', 2);
+    throw new Error('MockACL does not exist');
+  }
+
+  return acl;
+};
+
+const deployMockZkVerifier = async (hre: HardhatRuntimeEnvironment) => {
+  await hardhatSetCode(hre, MOCKS_ZK_VERIFIER_ADDRESS, MockZkVerifierArtifact.deployedBytecode);
+  const zkVerifier = await hre.ethers.getContractAt(MockZkVerifierArtifact.abi, MOCKS_ZK_VERIFIER_ADDRESS);
+
+  const zkVerifierExists = await zkVerifier.exists();
+  if (!zkVerifierExists) {
+    logError('MockZkVerifier does not exist', 2);
+    throw new Error('MockZkVerifier does not exist');
+  }
+
+  return zkVerifier;
+};
+
+const deployMockQueryDecrypter = async (hre: HardhatRuntimeEnvironment, acl: Contract) => {
+  await hardhatSetCode(hre, MOCKS_QUERY_DECRYPTER_ADDRESS, MockQueryDecrypterArtifact.deployedBytecode);
+  const queryDecrypter = await hre.ethers.getContractAt(MockQueryDecrypterArtifact.abi, MOCKS_QUERY_DECRYPTER_ADDRESS);
+
+  // Initialize MockQueryDecrypter
+  const initTx = await queryDecrypter.initialize(TASK_MANAGER_ADDRESS, await acl.getAddress());
+  await initTx.wait();
+
+  // Check if MockQueryDecrypter exists
+  const queryDecrypterExists = await queryDecrypter.exists();
+  if (!queryDecrypterExists) {
+    logError('MockQueryDecrypter does not exist', 2);
+    throw new Error('MockQueryDecrypter does not exist');
+  }
+
+  return queryDecrypter;
+};
+
+const deployTestBedContract = async (hre: HardhatRuntimeEnvironment) => {
+  await hardhatSetCode(hre, TEST_BED_ADDRESS, TestBedArtifact.deployedBytecode);
+  const testBed = await hre.ethers.getContractAt(TestBedArtifact.abi, TEST_BED_ADDRESS);
+  await testBed.waitForDeployment();
+  return testBed;
+};
+
+// Funding
+
+const fundZkVerifierSigner = async (hre: HardhatRuntimeEnvironment) => {
+  const zkVerifierSigner = await hre.ethers.getSigner(MOCKS_ZK_VERIFIER_SIGNER_ADDRESS);
+  await hre.network.provider.send('hardhat_setBalance', [
+    zkVerifierSigner.address,
+    '0x' + hre.ethers.parseEther('10').toString(16),
+  ]);
+};
+
+// Initializations
+
+const setTaskManagerACL = async (taskManager: Contract, acl: Contract) => {
+  const setAclTx = await taskManager.setACLContract(await acl.getAddress());
+  await setAclTx.wait();
+};
+
+export type DeployMocksArgs = {
+  deployTestBed?: boolean;
+  gasWarning?: boolean;
+  silent?: boolean;
+};
+
+export const deployMocks = async (
+  hre: HardhatRuntimeEnvironment,
+  options: DeployMocksArgs = {
+    deployTestBed: true,
+    gasWarning: true,
+    silent: false,
+  }
+) => {
+  // Check if network is Hardhat, if not log skip message and return
+  const isHardhat = await checkNetworkAndSkip(hre);
+  if (!isHardhat) return;
+
+  const logEmptyIfNoisy = () => {
+    if (!options.silent) {
+      logEmpty();
+    }
+  };
+  const logSuccessIfNoisy = (message: string, indent = 0) => {
+    if (!options.silent) {
+      logSuccess(message, indent);
+    }
+  };
+  const logDeploymentIfNoisy = (contractName: string, address: string) => {
+    if (!options.silent) {
+      logDeployment(contractName, address);
+    }
+  };
+  const logWarningIfNoisy = (message: string, indent = 0) => {
+    if (!options.silent) {
+      logWarning(message, indent);
+    }
+  };
+
+  // Log start message
+  logEmptyIfNoisy();
+  logSuccessIfNoisy(chalk.bold('cofhe-hardhat-plugin :: deploy mocks'), 0);
+  logEmptyIfNoisy();
+
+  // Compile mock contracts
+  logEmptyIfNoisy();
+  logSuccessIfNoisy('Mock contracts compiled', 1);
+
+  // Deploy mock contracts
+  const taskManager = await deployMockTaskManager(hre);
+  logDeploymentIfNoisy('MockTaskManager', await taskManager.getAddress());
+
+  const acl = await deployMockACL(hre);
+  logDeploymentIfNoisy('MockACL', await acl.getAddress());
+
+  await setTaskManagerACL(taskManager, acl);
+  logSuccessIfNoisy('ACL address set in TaskManager', 2);
+
+  await fundZkVerifierSigner(hre);
+  logSuccessIfNoisy(`ZkVerifier signer (${MOCKS_ZK_VERIFIER_SIGNER_ADDRESS}) funded`, 1);
+
+  const zkVerifierSignerBalance = await hre.ethers.provider.getBalance(MOCKS_ZK_VERIFIER_SIGNER_ADDRESS);
+  logSuccessIfNoisy(`ETH balance: ${zkVerifierSignerBalance.toString()}`, 2);
+
+  const zkVerifier = await deployMockZkVerifier(hre);
+  logDeploymentIfNoisy('MockZkVerifier', await zkVerifier.getAddress());
+
+  const queryDecrypter = await deployMockQueryDecrypter(hre, acl);
+  logDeploymentIfNoisy('MockQueryDecrypter', await queryDecrypter.getAddress());
+
+  if (options.deployTestBed) {
+    logSuccessIfNoisy('TestBed deployment enabled', 2);
+    const testBed = await deployTestBedContract(hre);
+    logDeploymentIfNoisy('TestBed', await testBed.getAddress());
+  }
+
+  // Log success message
+  logEmptyIfNoisy();
+  logSuccessIfNoisy(chalk.bold('cofhe-hardhat-plugin :: mocks deployed successfully'), 0);
+
+  // Log warning about mocks increased gas costs
+  if (options.gasWarning) {
+    logEmptyIfNoisy();
+    logWarningIfNoisy(
+      "When using mocks, FHE operations (eg FHE.add / FHE.mul) report a higher gas price due to additional on-chain mocking logic. Deploy your contracts on a testnet chain to check the true gas costs.\n(Disable this warning by setting '@cofhe/sdk.gasWarning' to false in your hardhat config",
+      0
+    );
+  }
+
+  logEmptyIfNoisy();
+};
+
+// Utils
+
+const hardhatSetCode = async (hre: HardhatRuntimeEnvironment, address: string, bytecode: string) => {
+  await hre.network.provider.send('hardhat_setCode', [address, bytecode]);
+};
+
+// Network
+
+const checkNetworkAndSkip = async (hre: HardhatRuntimeEnvironment) => {
+  const network = hre.network.name;
+  const isHardhat = network === 'hardhat';
+  if (!isHardhat) logSuccess(`cofhe-hardhat-plugin - deploy mocks - skipped on non-hardhat network ${network}`, 0);
+  return isHardhat;
+};
+
+// Logging
+
+const logEmpty = () => {
+  console.log('');
+};
+
+const logSuccess = (message: string, indent = 1) => {
+  console.log(chalk.green(`${'  '.repeat(indent)}✓ ${message}`));
+};
+
+const logWarning = (message: string, indent = 1) => {
+  console.log(chalk.bold(chalk.yellow(`${'  '.repeat(indent)}⚠ NOTE:`)), message);
+};
+
+const logError = (message: string, indent = 1) => {
+  console.log(chalk.red(`${'  '.repeat(indent)}✗ ${message}`));
+};
+
+const logDeployment = (contractName: string, address: string) => {
+  const paddedName = `${contractName} deployed`.padEnd(36);
+  logSuccess(`${paddedName} ${chalk.bold(address)}`);
+};

package/src/expectResultUtils.ts

@@ -0,0 +1,24 @@
+import { type Result } from '@cofhe/sdk';
+import { expect } from 'chai';
+
+export const expectResultError = <T>(result: Result<T>, errorPartial: string) => {
+  expect(result.success).to.eq(false, 'Result should be an error');
+  expect(result.error).to.include(errorPartial, `Error should contain error partial: ${errorPartial}`);
+};
+
+export const expectResultSuccess = <T>(result: Result<T>): T => {
+  expect(result.success).to.eq(true, 'Result should be a success');
+  return result.data!;
+};
+
+export const expectResultValue = <T>(result: Result<T>, value: T): T => {
+  expect(result.success).to.eq(true, 'Result should be a success');
+  expect(result.data).to.eq(value, `Result should have the expected value ${value}`);
+  return result.data!;
+};
+
+export const expectResultPartialValue = <T>(result: Result<T>, partial: Partial<T>): T => {
+  expect(result.success).to.eq(true, 'Result should be a success');
+  expect(result.data).to.include(partial, `Result should have the expected partial ${partial}`);
+  return result.data!;
+};

package/src/fund.ts

@@ -0,0 +1,82 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+import { type HardhatRuntimeEnvironment } from 'hardhat/types';
+import '@nomicfoundation/hardhat-ethers';
+
+/**
+ * Sends funds to the specified address
+ * @param hre Hardhat Runtime Environment
+ * @param toAddress Address to send funds to
+ * @param amount Amount to send in ETH (default: 10)
+ * @returns Transaction receipt or null if failed
+ */
+export async function localcofheFundAccount(hre: HardhatRuntimeEnvironment, toAddress: string, amount: string = '10') {
+  // Load private key from environment
+  const privateKey =
+    process.env.FUNDER_PRIVATE_KEY ?? '0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659';
+  if (!privateKey) {
+    console.error('Error: FUNDER_PRIVATE_KEY environment variable not set');
+    return null;
+  }
+
+  try {
+    // Create wallet from private key
+    const wallet = new hre.ethers.Wallet(privateKey, hre.ethers.provider);
+
+    // Get wallet balance
+    const balance = await hre.ethers.provider.getBalance(wallet.address);
+    console.log(`Funder wallet address: ${wallet.address}`);
+    console.log(`Funder wallet balance: ${hre.ethers.formatEther(balance)} ETH`);
+
+    // Check if wallet has enough funds
+    const amountToSend = hre.ethers.parseEther(amount);
+    if (balance < amountToSend) {
+      console.error(
+        `Error: Funder wallet doesn't have enough funds. Current balance: ${hre.ethers.formatEther(balance)} ETH`
+      );
+      return null;
+    }
+
+    // Send transaction
+    console.log(`Sending ${amount} ETH to ${toAddress}...`);
+    const tx = await wallet.sendTransaction({
+      to: toAddress,
+      value: amountToSend,
+    });
+
+    console.log(`Transaction sent! Hash: ${tx.hash}`);
+    console.log('Waiting for confirmation...');
+
+    // Wait for transaction to be mined
+    const receipt = await tx.wait();
+    console.log(`Transaction confirmed in block ${receipt?.blockNumber}`);
+    console.log(`Successfully sent ${amount} ETH to ${toAddress}`);
+
+    return receipt;
+  } catch (error) {
+    console.error('Error sending funds:', error);
+    return null;
+  }
+}
+
+/**
+ * Checks a wallet's balance and funds it if below 1 ETH
+ * @param hre Hardhat Runtime Environment
+ * @param walletAddress Address of the wallet to check and potentially fund
+ * @returns Promise that resolves when the funding operation completes (if needed)
+ */
+export async function localcofheFundWalletIfNeeded(hre: HardhatRuntimeEnvironment, walletAddress: string) {
+  // Check wallet balance and fund if needed
+  const walletBalance = await hre.ethers.provider.getBalance(walletAddress);
+  console.log(`Wallet balance: ${hre.ethers.formatEther(walletBalance)} ETH`);
+
+  if (walletBalance < hre.ethers.parseEther('1')) {
+    console.log(`Wallet balance is less than 1 ETH. Funding ${walletAddress}...`);
+    const receipt = await localcofheFundAccount(hre, walletAddress);
+    if (receipt) {
+      const newBalance = await hre.ethers.provider.getBalance(walletAddress);
+      console.log(`Wallet new balance: ${hre.ethers.formatEther(newBalance)} ETH`);
+    } else {
+      console.error(`Failed to fund ${walletAddress}`);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,390 @@
+/* eslint-disable no-empty-pattern */
+/* eslint-disable turbo/no-undeclared-env-vars */
+/* eslint-disable no-unused-vars */
+import chalk from 'chalk';
+import { type PublicClient, type WalletClient } from 'viem';
+import { extendConfig, extendEnvironment, task, types } from 'hardhat/config';
+import { TASK_TEST, TASK_NODE } from 'hardhat/builtin-tasks/task-names';
+import { HardhatEthersSigner } from '@nomicfoundation/hardhat-ethers/signers';
+import { type CofhesdkClient, type CofhesdkConfig, type CofhesdkInputConfig, type Result } from '@cofhe/sdk';
+import { createCofhesdkClient, createCofhesdkConfig } from '@cofhe/sdk/node';
+import { HardhatSignerAdapter } from '@cofhe/sdk/adapters';
+
+import { localcofheFundAccount } from './fund.js';
+import {
+  MOCKS_ZK_VERIFIER_SIGNER_ADDRESS,
+  TASK_COFHE_MOCKS_DEPLOY,
+  TASK_COFHE_MOCKS_SET_LOG_OPS,
+  TASK_COFHE_USE_FAUCET,
+} from './consts.js';
+import { deployMocks, type DeployMocksArgs } from './deploy.js';
+import { mock_setLoggingEnabled, mock_withLogs } from './logging.js';
+import { mock_expectPlaintext } from './utils.js';
+import { mock_getPlaintext } from './utils.js';
+import {
+  expectResultError,
+  expectResultPartialValue,
+  expectResultSuccess,
+  expectResultValue,
+} from './expectResultUtils.js';
+export {
+  MockACLArtifact,
+  MockQueryDecrypterArtifact,
+  MockTaskManagerArtifact,
+  MockZkVerifierArtifact,
+  TestBedArtifact,
+} from '@cofhe/mock-contracts';
+
+/**
+ * Configuration interface for the CoFHE Hardhat plugin.
+ * Allows users to configure mock logging and gas warning settings.
+ */
+declare module 'hardhat/types/config' {
+  interface HardhatUserConfig {
+    cofhesdk?: {
+      /** Whether to log mock operations (default: true) */
+      logMocks?: boolean;
+      /** Whether to show gas usage warnings for mock operations (default: true) */
+      gasWarning?: boolean;
+    };
+  }
+
+  interface HardhatConfig {
+    cofhesdk: {
+      /** Whether to log mock operations (default: true) */
+      logMocks: boolean;
+      /** Whether to show gas usage warnings for mock operations (default: true) */
+      gasWarning: boolean;
+    };
+  }
+}
+
+extendConfig((config, userConfig) => {
+  // Allow users to override the localcofhe network config
+  if (userConfig.networks && userConfig.networks.localcofhe) {
+    return;
+  }
+
+  // Default config
+  config.networks.localcofhe = {
+    gas: 'auto',
+    gasMultiplier: 1.2,
+    gasPrice: 'auto',
+    timeout: 10_000,
+    httpHeaders: {},
+    url: 'http://127.0.0.1:42069',
+    accounts: [
+      '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+      '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d',
+      '0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a',
+      '0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6',
+    ],
+  };
+
+  // Only add Sepolia config if user hasn't defined it
+  if (!userConfig.networks?.['eth-sepolia']) {
+    config.networks['eth-sepolia'] = {
+      url: process.env.SEPOLIA_RPC_URL ?? 'https://ethereum-sepolia.publicnode.com',
+      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
+      chainId: 11155111,
+      gas: 'auto',
+      gasMultiplier: 1.2,
+      gasPrice: 'auto',
+      timeout: 60_000,
+      httpHeaders: {},
+    };
+  }
+
+  // Only add Arbitrum Sepolia config if user hasn't defined it
+  if (!userConfig.networks?.['arb-sepolia']) {
+    config.networks['arb-sepolia'] = {
+      url: process.env.ARBITRUM_SEPOLIA_RPC_URL ?? 'https://sepolia-rollup.arbitrum.io/rpc',
+      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
+      chainId: 421614,
+      gas: 'auto',
+      gasMultiplier: 1.2,
+      gasPrice: 'auto',
+      timeout: 60_000,
+      httpHeaders: {},
+    };
+  }
+
+  // Add cofhe config
+  config.cofhesdk = {
+    logMocks: userConfig.cofhesdk?.logMocks ?? true,
+    gasWarning: userConfig.cofhesdk?.gasWarning ?? true,
+  };
+});
+
+type UseFaucetArgs = {
+  address?: string;
+};
+
+task(TASK_COFHE_USE_FAUCET, 'Fund an account from the funder')
+  .addOptionalParam('address', 'Address to fund', undefined, types.string)
+  .setAction(async ({ address }: UseFaucetArgs, hre) => {
+    const { network } = hre;
+    const { name: networkName } = network;
+
+    if (networkName !== 'localcofhe') {
+      console.info(chalk.yellow(`Programmatic faucet only supported for localcofhe`));
+      return;
+    }
+
+    if (!address) {
+      console.info(chalk.red(`Failed to get address to fund`));
+      return;
+    }
+
+    console.info(chalk.green(`Getting funds from faucet for ${address}`));
+
+    try {
+      await localcofheFundAccount(hre, address);
+    } catch (e) {
+      console.info(chalk.red(`failed to get funds from localcofhe for ${address}: ${e}`));
+    }
+  });
+
+// DEPLOY TASKS
+
+task(TASK_COFHE_MOCKS_DEPLOY, 'Deploys the mock contracts on the Hardhat network')
+  .addOptionalParam('deployTestBed', 'Whether to deploy the test bed', true, types.boolean)
+  .addOptionalParam('silent', 'Whether to suppress output', false, types.boolean)
+  .setAction(async ({ deployTestBed, silent }: DeployMocksArgs, hre) => {
+    await deployMocks(hre, {
+      deployTestBed: deployTestBed ?? true,
+      gasWarning: hre.config.cofhesdk.gasWarning ?? true,
+      silent: silent ?? false,
+    });
+  });
+
+task(TASK_TEST, 'Deploy mock contracts on hardhat').setAction(async ({}, hre, runSuper) => {
+  await deployMocks(hre, {
+    deployTestBed: true,
+    gasWarning: hre.config.cofhesdk.gasWarning ?? true,
+  });
+  return runSuper();
+});
+
+task(TASK_NODE, 'Deploy mock contracts on hardhat').setAction(async ({}, hre, runSuper) => {
+  await deployMocks(hre, {
+    deployTestBed: true,
+    gasWarning: hre.config.cofhesdk.gasWarning ?? true,
+  });
+  return runSuper();
+});
+
+// SET LOG OPS
+
+task(TASK_COFHE_MOCKS_SET_LOG_OPS, 'Set logging for the Mock CoFHE contracts')
+  .addParam('enable', 'Whether to enable logging', false, types.boolean)
+  .setAction(async ({ enable }, hre) => {
+    await mock_setLoggingEnabled(hre, enable);
+  });
+
+// MOCK UTILS
+
+export * from './utils.js';
+export * from './expectResultUtils.js';
+export * from './fund.js';
+export * from './logging.js';
+export * from './deploy.js';
+
+/**
+ * Runtime environment extensions for the CoFHE Hardhat plugin.
+ * Provides access to CoFHE initialization, environment checks, and mock utilities.
+ */
+declare module 'hardhat/types/runtime' {
+  export interface HardhatRuntimeEnvironment {
+    cofhesdk: {
+      /**
+       * Create a CoFHE SDK configuration for use with cofhesdk.createCofhesdkClient(...)
+       * @param {CofhesdkInputConfig} config - The CoFHE SDK input configuration
+       * @returns {CofhesdkConfig} The CoFHE SDK configuration
+       */
+      createCofhesdkConfig: (config: CofhesdkInputConfig) => Promise<CofhesdkConfig>;
+      /**
+       * Create a CoFHE SDK client instance
+       * @param {CofhesdkConfig} config - The CoFHE SDK configuration (use createCofhesdkConfig to create with Node.js defaults)
+       * @returns {Promise<CofhesdkClient>} The CoFHE SDK client instance
+       */
+      createCofhesdkClient: (config: CofhesdkConfig) => CofhesdkClient;
+      /**
+       * Create viem clients from a Hardhat ethers signer, to be used with `cofhesdkClient.connect(...)`
+       * @param {HardhatEthersSigner} signer - The Hardhat ethers signer to use
+       * @returns {Promise<{ publicClient: PublicClient; walletClient: WalletClient }>} The viem clients
+       */
+      hardhatSignerAdapter: (
+        signer: HardhatEthersSigner
+      ) => Promise<{ publicClient: PublicClient; walletClient: WalletClient }>;
+
+      /**
+       * Assert that a Result type returned from a function is successful and return its value (result.success === true)
+       * @param {Result<T>} result - The Result to check
+       * @returns {T} The inner data of the Result (non null)
+       */
+      expectResultSuccess: <T>(result: Result<T> | Promise<Result<T>>) => Promise<T>;
+
+      /**
+       * Assert that a Result type contains an error matching the partial string (result.success === false && result.error.includes(errorPartial))
+       * @param {Result<T>} result - The Result to check
+       * @param {string} errorPartial - The partial error string to match
+       */
+      expectResultError: <T>(result: Result<T> | Promise<Result<T>>, errorPartial: string) => Promise<void>;
+
+      /**
+       * Assert that a Result type contains a specific value (result.success === true && result.data === value)
+       * @param {Result<T>} result - The Result to check
+       * @param {T} value - The inner data of the Result (non null)
+       */
+      expectResultValue: <T>(result: Result<T> | Promise<Result<T>>, value: T) => Promise<T>;
+
+      /**
+       * Assert that a Result type contains a value matching the partial object (result.success === true && result.data.includes(partial))
+       * @param {Result<T>} result - The Result to check
+       * @param {Partial<T>} partial - The partial object to match against
+       * @returns {T} The inner data of the Result (non null)
+       */
+      expectResultPartialValue: <T>(result: Result<T> | Promise<Result<T>>, partial: Partial<T>) => Promise<T>;
+
+      mocks: {
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Execute a block of code with cofhe mock contracts logging enabled.
+         *
+         * _(If logging only a function, we recommend passing the function name as the closureName (ex "counter.increment()"))_
+         *
+         * Example usage:
+         *
+         * ```ts
+         * await hre.cofhesdk.mocks.withLogs("counter.increment()", async () => {
+         *   await counter.increment();
+         * });
+         * ```
+         *
+         * Expected output:
+         * ```
+         * ┌──────────────────┬──────────────────────────────────────────────────
+         * │ [COFHE-MOCKS]    │ "counter.increment()" logs:
+         * ├──────────────────┴──────────────────────────────────────────────────
+         * ├ FHE.add          | euint32(4473..3424)[0] + euint32(1157..3648)[1]  =>  euint32(1106..1872)[1]
+         * ├ FHE.allowThis    | euint32(1106..1872)[1] -> 0x663f..6602
+         * ├ FHE.allow        | euint32(1106..1872)[1] -> 0x3c44..93bc
+         * └─────────────────────────────────────────────────────────────────────
+         * ```
+         * @param {string} closureName - Name of the code block to log within
+         * @param {() => Promise<void>} closure - The async function to execute
+         */
+        withLogs: (closureName: string, closure: () => Promise<void>) => Promise<void>;
+
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Enable logging from cofhe mock contracts
+         * @param {string} closureName - Optional name of the code block to enable logging for
+         */
+        enableLogs: (closureName?: string) => Promise<void>;
+
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Disable logging from cofhe mock contracts
+         */
+        disableLogs: () => Promise<void>;
+
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Deploy the cofhe mock contracts (normally this is done automatically)
+         * @param {DeployMocksArgs} options - Deployment options
+         */
+        deployMocks: (options: DeployMocksArgs) => Promise<void>;
+
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Get the plaintext value for a ciphertext hash
+         * @param {bigint} ctHash - The ciphertext hash to look up
+         * @returns {Promise<bigint>} The plaintext value
+         */
+        getPlaintext: (ctHash: bigint) => Promise<bigint>;
+
+        /**
+         * **[MOCKS ONLY]**
+         *
+         * Assert that a ciphertext hash represents an expected plaintext value
+         * @param {bigint} ctHash - The ciphertext hash to check
+         * @param {bigint} expectedValue - The expected plaintext value
+         */
+        expectPlaintext: (ctHash: bigint, expectedValue: bigint) => Promise<void>;
+      };
+    };
+  }
+}
+
+extendEnvironment((hre) => {
+  hre.cofhesdk = {
+    createCofhesdkConfig: async (config: CofhesdkInputConfig) => {
+      // Create zkv wallet client
+      // This wallet interacts with the MockZkVerifier contract so that the user's connected wallet doesn't have to
+      const zkvHhSigner = await hre.ethers.getImpersonatedSigner(MOCKS_ZK_VERIFIER_SIGNER_ADDRESS);
+      const { walletClient: zkvWalletClient } = await HardhatSignerAdapter(zkvHhSigner);
+
+      // Inject zkv wallet client into config
+      const configWithZkvWalletClient = {
+        ...config,
+        _internal: {
+          ...config._internal,
+          zkvWalletClient,
+        },
+      };
+
+      return createCofhesdkConfig(configWithZkvWalletClient);
+    },
+    createCofhesdkClient: (config: CofhesdkConfig) => {
+      return createCofhesdkClient(config);
+    },
+    hardhatSignerAdapter: async (signer: HardhatEthersSigner) => {
+      return HardhatSignerAdapter(signer);
+    },
+    expectResultSuccess: async <T>(result: Result<T> | Promise<Result<T>>) => {
+      const awaitedResult = await result;
+      return expectResultSuccess(awaitedResult);
+    },
+    expectResultError: async <T>(result: Result<T> | Promise<Result<T>>, errorPartial: string) => {
+      const awaitedResult = await result;
+      return expectResultError(awaitedResult, errorPartial);
+    },
+    expectResultValue: async <T>(result: Result<T> | Promise<Result<T>>, value: T) => {
+      const awaitedResult = await result;
+      return expectResultValue(awaitedResult, value);
+    },
+    expectResultPartialValue: async <T>(result: Result<T> | Promise<Result<T>>, partial: Partial<T>) => {
+      const awaitedResult = await result;
+      return expectResultPartialValue(awaitedResult, partial);
+    },
+    mocks: {
+      withLogs: async (closureName: string, closure: () => Promise<void>) => {
+        return mock_withLogs(hre, closureName, closure);
+      },
+      enableLogs: async (closureName?: string) => {
+        return mock_setLoggingEnabled(hre, true, closureName);
+      },
+      disableLogs: async () => {
+        return mock_setLoggingEnabled(hre, false);
+      },
+      deployMocks: async (options: DeployMocksArgs) => {
+        return deployMocks(hre, options);
+      },
+      getPlaintext: async (ctHash: bigint) => {
+        const [signer] = await hre.ethers.getSigners();
+        return mock_getPlaintext(signer.provider, ctHash);
+      },
+      expectPlaintext: async (ctHash: bigint, expectedValue: bigint) => {
+        const [signer] = await hre.ethers.getSigners();
+        return mock_expectPlaintext(signer.provider, ctHash, expectedValue);
+      },
+    },
+  };
+});

package/src/logging.ts

@@ -0,0 +1,75 @@
+import chalk from 'chalk';
+import { type HardhatRuntimeEnvironment } from 'hardhat/types';
+import { TASK_MANAGER_ADDRESS } from './consts';
+import { MockTaskManagerArtifact } from '@cofhe/mock-contracts';
+
+const getDeployedMockTaskManager = async (hre: HardhatRuntimeEnvironment) => {
+  // Fetch the deployed MockTaskManager
+  const taskManager = await hre.ethers.getContractAt(MockTaskManagerArtifact.abi, TASK_MANAGER_ADDRESS);
+
+  return taskManager;
+};
+
+const getLoggingEnabled = async (hre: HardhatRuntimeEnvironment) => {
+  const taskManager = await getDeployedMockTaskManager(hre);
+  return await taskManager.logOps();
+};
+
+const setLoggingEnabled = async (hre: HardhatRuntimeEnvironment, enabled: boolean) => {
+  const taskManager = await getDeployedMockTaskManager(hre);
+  await taskManager.setLogOps(enabled);
+};
+
+// prettier-ignore
+const printLogsEnabledMessage = (closureMessage: string) => {
+  console.log("┌──────────────────┬──────────────────────────────────────────────────");
+  console.log(`│ [COFHE-MOCKS]    │ ${closureMessage}`);
+  console.log("├──────────────────┴──────────────────────────────────────────────────");
+};
+
+// prettier-ignore
+const printLogsBlockEnd = () => {
+  console.log("└─────────────────────────────────────────────────────────────────────");
+};
+
+export const mock_setLoggingEnabled = async (
+  hre: HardhatRuntimeEnvironment,
+  enabled: boolean,
+  closureName?: string
+) => {
+  try {
+    const initiallyEnabled = await getLoggingEnabled(hre);
+
+    await setLoggingEnabled(hre, enabled);
+
+    // Only print if enabling logs
+    if (enabled) {
+      printLogsEnabledMessage(`${closureName ? `"${chalk.bold(closureName)}" logs:` : 'Logs:'}`);
+    }
+
+    // Only print if disabling logs AND logs currently enabled
+    if (!enabled && initiallyEnabled) {
+      printLogsBlockEnd();
+    }
+  } catch (error) {
+    console.log(chalk.red('mock_setLoggingEnabled error'), error);
+  }
+};
+
+export const mock_withLogs = async (
+  hre: HardhatRuntimeEnvironment,
+  closureName: string,
+  closure: () => Promise<void>
+) => {
+  const initiallyEnabled = await getLoggingEnabled(hre);
+
+  await setLoggingEnabled(hre, true);
+  printLogsEnabledMessage(`"${chalk.bold(closureName)}" logs:`);
+  await closure();
+  printLogsBlockEnd();
+
+  // If logs were disabled, disable them again
+  if (!initiallyEnabled) {
+    await setLoggingEnabled(hre, false);
+  }
+};

package/src/utils.ts

@@ -0,0 +1,75 @@
+import { TASK_MANAGER_ADDRESS, MOCKS_ZK_VERIFIER_ADDRESS } from './consts.js';
+import { expect } from 'chai';
+import { ethers } from 'ethers';
+import { type HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/internal/hardhat-ethers-provider';
+
+const mock_checkIsTestnet = async (fnName: string, provider: HardhatEthersProvider | ethers.JsonRpcProvider) => {
+  // Testnet is checked by testing if MockZkVerifier is deployed
+
+  // Get bytecode at ZK_VERIFIER_ADDRESS
+  const bytecode = await provider.getCode(MOCKS_ZK_VERIFIER_ADDRESS);
+
+  // If bytecode is empty, we are on a testnet
+  const isTestnet = bytecode.length === 0;
+
+  // Log if we are on a testnet
+  if (isTestnet) {
+    console.log(`${fnName} - skipped on non-testnet chain`);
+  }
+
+  return isTestnet;
+};
+
+export const mock_getPlaintext = async (provider: HardhatEthersProvider | ethers.JsonRpcProvider, ctHash: bigint) => {
+  // Skip with log if called on a non-testnet chain
+  if (await mock_checkIsTestnet(mock_getPlaintext.name, provider)) return;
+
+  // Connect to MockTaskManager
+  const taskManager = new ethers.Contract(
+    TASK_MANAGER_ADDRESS,
+    ['function mockStorage(uint256) view returns (uint256)'],
+    provider
+  );
+
+  // Fetch the plaintext
+  const plaintext = await taskManager.mockStorage(ctHash);
+
+  return plaintext;
+};
+
+export const mock_getPlaintextExists = async (
+  provider: HardhatEthersProvider | ethers.JsonRpcProvider,
+  ctHash: bigint
+) => {
+  // Skip with log if called on a non-testnet chain
+  if (await mock_checkIsTestnet(mock_getPlaintextExists.name, provider)) return;
+
+  // Connect to MockTaskManager
+  const taskManager = new ethers.Contract(
+    TASK_MANAGER_ADDRESS,
+    ['function inMockStorage(uint256) view returns (bool)'],
+    provider
+  );
+
+  // Fetch the plaintext exists
+  const plaintextExists = await taskManager.inMockStorage(ctHash);
+
+  return plaintextExists;
+};
+
+export const mock_expectPlaintext = async (
+  provider: HardhatEthersProvider | ethers.JsonRpcProvider,
+  ctHash: bigint,
+  expectedValue: bigint
+) => {
+  // Skip with log if called on a non-testnet chain
+  if (await mock_checkIsTestnet(mock_expectPlaintext.name, provider)) return;
+
+  // Expect the plaintext to exist
+  const plaintextExists = await mock_getPlaintextExists(provider, ctHash);
+  expect(plaintextExists).equal(true, 'Plaintext does not exist');
+
+  // Expect the plaintext to have the expected value
+  const plaintext = await mock_getPlaintext(provider, ctHash);
+  expect(plaintext).equal(expectedValue, 'Plaintext value is incorrect');
+};