@cofhe/hardhat-plugin 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# CoFHE Hardhat Plugin
+
+A Hardhat plugin for Fully Homomorphic Encryption (FHE) development with CoFHE.
+
+## Installation
+
+```bash
+npm install cofhe-hardhat-plugin
+# or
+yarn add cofhe-hardhat-plugin
+# or
+pnpm add cofhe-hardhat-plugin
+```
+
+## Configuration
+
+Add the plugin to your Hardhat config:
+
+```javascript
+// hardhat.config.js or hardhat.config.ts
+require("cofhe-hardhat-plugin");
+// or if using TypeScript
+import "cofhe-hardhat-plugin";
+
+module.exports = {
+  // ... other config
+  cofhe: {
+    logMocks: true, // Optional: Set to true to log mock operations
+  },
+  // Network configuration is automatically added by the plugin
+};
+```
+
+The plugin automatically adds network configurations for:
+
+- Hardhat network with deployed mock contracts
+- Ethereum Sepolia testnet
+- Arbitrum Sepolia testnet
+
+## Features
+
+### Mock Contracts
+
+This plugin uses [cofhe-mock-contracts](https://github.com/FhenixProtocol/cofhe-mock-contracts) to provide on-chain simulations of the CoFHE system. These mock contracts enable development and testing without requiring the actual off-chain FHE computation engine.
+
+The mock contracts include:
+
+- MockTaskManager: Manages FHE operations and stores plaintext values
+- MockQueryDecrypter: Handles decryption requests
+- MockZkVerifier: Simulates verification of encrypted inputs
+- ACL: Handles access control
+
+Key differences from the real CoFHE system:
+
+- Operations are performed on-chain instead of off-chain
+- Plaintext values are stored on-chain for testing and verification
+- Decryption operations are simulated with mock delays
+- Operations are logged using hardhat/console.sol
+
+### Mock Contracts Deployment
+
+Mock contracts are automatically deployed when using the Hardhat network:
+
+- Running tests: `npx hardhat test`
+- Starting a local node: `npx hardhat node`
+
+You can also manually deploy mock contracts:
+
+```bash
+npx hardhat deploy-mocks [--deploy-test-bed true|false] [--log-mocks true|false]
+```
+
+Options:
+
+- `--deploy-test-bed`: Deploy the TestBed contract (default: true)
+- `--log-mocks`: Log mock operations (default: true)
+
+### Utility Functions
+
+The plugin exports several utility functions for working with mock contracts:
+
+#### Mock Utilities
+
+```typescript
+// Get plaintext value from a ciphertext hash
+import { mock_getPlaintext } from "cofhe-hardhat-plugin";
+const plaintext = await mock_getPlaintext(provider, ctHash);
+
+// Check if a plaintext exists for a ciphertext hash
+import { mock_getPlaintextExists } from "cofhe-hardhat-plugin";
+const exists = await mock_getPlaintextExists(provider, ctHash);
+
+// Test assertion for plaintext values
+import { mock_expectPlaintext } from "cofhe-hardhat-plugin";
+await mock_expectPlaintext(provider, ctHash, expectedValue);
+```
+
+#### Network Utilities
+
+```typescript
+// Get the CoFHE environment based on network name
+import { getCofheEnvironmentFromNetwork } from "cofhe-hardhat-plugin";
+const environment = getCofheEnvironmentFromNetwork(networkName);
+
+// Check if a CoFHE environment is permitted for a given network
+import { isPermittedCofheEnvironment } from "cofhe-hardhat-plugin";
+const isPermitted = isPermittedCofheEnvironment(hre, environmentName);
+
+// Initialize CoFHEjs with a Hardhat signer
+import { cofhejs_initializeWithHardhatSigner } from "cofhe-hardhat-plugin";
+await cofhejs_initializeWithHardhatSigner(signer, options);
+```
+
+## Usage in Tests
+
+The plugin automatically deploys mock contracts when running tests:
+
+```typescript
+import { expect } from "chai";
+import { mock_expectPlaintext } from "cofhe-hardhat-plugin";
+
+describe("My FHE Contract", function() {
+  it("should store encrypted value correctly", async function() {
+    const [signer] = await ethers.getSigners();
+    const myContract = await ethers.deployContract("MyFHEContract");
+
+    // Interact with your contract
+    const tx = await myContract.storeEncrypted(123);
+    await tx.wait();
+
+    // Get the ciphertext hash from event logs
+    const ctHash = /* extract from logs */;
+
+    // Verify plaintext value (only works on hardhat network)
+    await mock_expectPlaintext(signer.provider, ctHash, 123n);
+  });
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,192 @@
+import { PublicClient, WalletClient } from 'viem';
+import { HardhatEthersSigner } from '@nomicfoundation/hardhat-ethers/signers';
+import { Result, CofhesdkInputConfig, CofhesdkConfig, CofhesdkClient } from '@cofhe/sdk';
+import { HardhatRuntimeEnvironment } from 'hardhat/types';
+export { MockACLArtifact, MockQueryDecrypterArtifact, MockTaskManagerArtifact, MockZkVerifierArtifact, TestBedArtifact } from '@cofhe/mock-contracts';
+import * as ethers from 'ethers';
+import { ethers as ethers$1 } from 'ethers';
+import { HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/internal/hardhat-ethers-provider';
+
+type DeployMocksArgs = {
+    deployTestBed?: boolean;
+    gasWarning?: boolean;
+    silent?: boolean;
+};
+declare const deployMocks: (hre: HardhatRuntimeEnvironment, options?: DeployMocksArgs) => Promise<void>;
+
+declare const mock_getPlaintext: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint) => Promise<any>;
+declare const mock_getPlaintextExists: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint) => Promise<any>;
+declare const mock_expectPlaintext: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint, expectedValue: bigint) => Promise<void>;
+
+declare const expectResultError: <T>(result: Result<T>, errorPartial: string) => void;
+declare const expectResultSuccess: <T>(result: Result<T>) => T;
+declare const expectResultValue: <T>(result: Result<T>, value: T) => T;
+declare const expectResultPartialValue: <T>(result: Result<T>, partial: Partial<T>) => T;
+
+/**
+ * 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
+ */
+declare function localcofheFundAccount(hre: HardhatRuntimeEnvironment, toAddress: string, amount?: string): Promise<ethers.TransactionReceipt | 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)
+ */
+declare function localcofheFundWalletIfNeeded(hre: HardhatRuntimeEnvironment, walletAddress: string): Promise<void>;
+
+declare const mock_setLoggingEnabled: (hre: HardhatRuntimeEnvironment, enabled: boolean, closureName?: string) => Promise<void>;
+declare const mock_withLogs: (hre: HardhatRuntimeEnvironment, closureName: string, closure: () => Promise<void>) => Promise<void>;
+
+/**
+ * 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;
+        };
+    }
+}
+
+/**
+ * Runtime environment extensions for the CoFHE Hardhat plugin.
+ * Provides access to CoFHE initialization, environment checks, and mock utilities.
+ */
+declare module 'hardhat/types/runtime' {
+    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>;
+            };
+        };
+    }
+}
+
+export { type DeployMocksArgs, deployMocks, expectResultError, expectResultPartialValue, expectResultSuccess, expectResultValue, localcofheFundAccount, localcofheFundWalletIfNeeded, mock_expectPlaintext, mock_getPlaintext, mock_getPlaintextExists, mock_setLoggingEnabled, mock_withLogs };

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import { PublicClient, WalletClient } from 'viem';
+import { HardhatEthersSigner } from '@nomicfoundation/hardhat-ethers/signers';
+import { Result, CofhesdkInputConfig, CofhesdkConfig, CofhesdkClient } from '@cofhe/sdk';
+import { HardhatRuntimeEnvironment } from 'hardhat/types';
+export { MockACLArtifact, MockQueryDecrypterArtifact, MockTaskManagerArtifact, MockZkVerifierArtifact, TestBedArtifact } from '@cofhe/mock-contracts';
+import * as ethers from 'ethers';
+import { ethers as ethers$1 } from 'ethers';
+import { HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/internal/hardhat-ethers-provider';
+
+type DeployMocksArgs = {
+    deployTestBed?: boolean;
+    gasWarning?: boolean;
+    silent?: boolean;
+};
+declare const deployMocks: (hre: HardhatRuntimeEnvironment, options?: DeployMocksArgs) => Promise<void>;
+
+declare const mock_getPlaintext: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint) => Promise<any>;
+declare const mock_getPlaintextExists: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint) => Promise<any>;
+declare const mock_expectPlaintext: (provider: HardhatEthersProvider | ethers$1.JsonRpcProvider, ctHash: bigint, expectedValue: bigint) => Promise<void>;
+
+declare const expectResultError: <T>(result: Result<T>, errorPartial: string) => void;
+declare const expectResultSuccess: <T>(result: Result<T>) => T;
+declare const expectResultValue: <T>(result: Result<T>, value: T) => T;
+declare const expectResultPartialValue: <T>(result: Result<T>, partial: Partial<T>) => T;
+
+/**
+ * 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
+ */
+declare function localcofheFundAccount(hre: HardhatRuntimeEnvironment, toAddress: string, amount?: string): Promise<ethers.TransactionReceipt | 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)
+ */
+declare function localcofheFundWalletIfNeeded(hre: HardhatRuntimeEnvironment, walletAddress: string): Promise<void>;
+
+declare const mock_setLoggingEnabled: (hre: HardhatRuntimeEnvironment, enabled: boolean, closureName?: string) => Promise<void>;
+declare const mock_withLogs: (hre: HardhatRuntimeEnvironment, closureName: string, closure: () => Promise<void>) => Promise<void>;
+
+/**
+ * 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;
+        };
+    }
+}
+
+/**
+ * Runtime environment extensions for the CoFHE Hardhat plugin.
+ * Provides access to CoFHE initialization, environment checks, and mock utilities.
+ */
+declare module 'hardhat/types/runtime' {
+    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>;
+            };
+        };
+    }
+}
+
+export { type DeployMocksArgs, deployMocks, expectResultError, expectResultPartialValue, expectResultSuccess, expectResultValue, localcofheFundAccount, localcofheFundWalletIfNeeded, mock_expectPlaintext, mock_getPlaintext, mock_getPlaintextExists, mock_setLoggingEnabled, mock_withLogs };