@diamondslab/diamonds-hardhat-foundry 1.0.3 → 2.2.0

package/src/framework/DeploymentManager.ts

@@ -1,59 +1,38 @@
-import { Diamond } from "@diamondslab/diamonds";
+import { Diamond } from "@diamondslab/diamonds/core";
+import {
+  LocalDiamondDeployer,
+  LocalDiamondDeployerConfig,
+} from "@diamondslab/hardhat-diamonds/dist/lib";
+import "@nomicfoundation/hardhat-ethers";
 import { existsSync } from "fs";
-import { HardhatRuntimeEnvironment } from "hardhat/types";
+import type { HardhatRuntimeEnvironment } from "hardhat/types";
 import { join } from "path";
 import { Logger } from "../utils/logger";
 
-// Type for LocalDiamondDeployer (avoiding import issues)
-type LocalDiamondDeployerConfig = {
-  diamondName: string;
-  networkName: string;
-  provider: any;
-  chainId: number;
-  writeDeployedDiamondData: boolean;
-};
-
 /**
  * DeploymentManager - Manages Diamond deployment lifecycle for Forge testing
  * 
- * Note: This class dynamically requires LocalDiamondDeployer from the workspace
- * to avoid module resolution issues in the published package.
+ * Uses LocalDiamondDeployer from @diamondslab/hardhat-diamonds peer dependency
+ * for portable, dependency-managed Diamond deployments.
  */
 export class DeploymentManager {
-  constructor(private hre: HardhatRuntimeEnvironment) {}
+  // In-memory cache for ephemeral deployments (when writeDeployedDiamondData: false)
+  private deploymentCache: Map<string, Diamond> = new Map();
 
-  /**
-   * Get LocalDiamondDeployer class
-   * @private
-   */
-  private async getDeployerClass(): Promise<any> {
-    // LocalDiamondDeployer is in the workspace scripts, not exported from the module
-    // This will need to be available in user projects
-    const localDeployerPath = join(
-      this.hre.config.paths.root,
-      "scripts/setup/LocalDiamondDeployer"
-    );
-    
-    try {
-      const deployer = await import(localDeployerPath);
-      return deployer.LocalDiamondDeployer;
-    } catch {
-      throw new Error(
-        "LocalDiamondDeployer not found. Make sure your project has scripts/setup/LocalDiamondDeployer.ts"
-      );
-    }
-  }
+  constructor(private hre: HardhatRuntimeEnvironment) {}
 
   /**
    * Deploy a Diamond using LocalDiamondDeployer
    * @param diamondName - Name of the Diamond to deploy
    * @param networkName - Target network (hardhat, localhost, anvil)
    * @param force - Force redeployment even if exists
+   * @param writeDeployedDiamondData - Whether to write deployment record to file
    */
   async deploy(
     diamondName: string = "ExampleDiamond",
     networkName: string = "hardhat",
-    force: boolean = false
+    force: boolean = false,
+    writeDeployedDiamondData: boolean = false
   ): Promise<Diamond> {
     Logger.section(`Deploying ${diamondName} to ${networkName}`);
 
@@ -67,42 +46,60 @@ export class DeploymentManager {
       Logger.info("Deployment record exists, using existing deployment");
       Logger.info("Use --force to redeploy");
       
-      const LocalDiamondDeployer = await this.getDeployerClass();
-      const deployer = await LocalDiamondDeployer.getInstance({
+      try {
+        const deployer = await LocalDiamondDeployer.getInstance(this.hre, {
+          diamondName,
+          networkName,
+          provider,
+          chainId,
+          writeDeployedDiamondData,
+        } as LocalDiamondDeployerConfig);
+        
+        return await deployer.getDiamond();
+      } catch (error) {
+        throw new Error(
+          `Failed to load deployment. Ensure @diamondslab/hardhat-diamonds is installed.\n` +
+          `Error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+
+    Logger.step("Initializing LocalDiamondDeployer...");
+    
+    try {
+      const deployer = await LocalDiamondDeployer.getInstance(this.hre as any, {
         diamondName,
         networkName,
         provider,
         chainId,
-        writeDeployedDiamondData: true,
+        writeDeployedDiamondData,
       } as LocalDiamondDeployerConfig);
-      
-      return await deployer.getDiamond();
-    }
-
-    Logger.step("Initializing LocalDiamondDeployer...");
-    
-    const LocalDiamondDeployer = await this.getDeployerClass();
-    
-    const deployer = await LocalDiamondDeployer.getInstance({
-      diamondName,
-      networkName,
-      provider,
-      chainId,
-      writeDeployedDiamondData: true,
-    } as LocalDiamondDeployerConfig);
 
-    await deployer.setVerbose(false); // Reduce noise, use our logger instead
+      await deployer.setVerbose(false); // Reduce noise, use our logger instead
 
-    Logger.step("Deploying Diamond contract...");
-    const diamond = await deployer.getDiamondDeployed();
-    
-    const deployedData = diamond.getDeployedDiamondData();
-    
-    Logger.success(`Diamond deployed at: ${deployedData.DiamondAddress}`);
-    Logger.info(`Deployer: ${deployedData.DeployerAddress}`);
-    Logger.info(`Facets deployed: ${Object.keys(deployedData.DeployedFacets || {}).length}`);
+      Logger.step("Deploying Diamond contract...");
+      const diamond = await deployer.getDiamondDeployed();
+      
+      const deployedData = diamond.getDeployedDiamondData();
+      
+      Logger.success(`Diamond deployed at: ${deployedData.DiamondAddress}`);
+      Logger.info(`Deployer: ${deployedData.DeployerAddress}`);
+      Logger.info(`Facets deployed: ${Object.keys(deployedData.DeployedFacets || {}).length}`);
+
+      // Cache deployment if not writing to file
+      if (!writeDeployedDiamondData) {
+        const cacheKey = `${diamondName}-${networkName}-${chainId}`;
+        this.deploymentCache.set(cacheKey, diamond);
+        Logger.info("Deployment cached in memory (not persisted to file)");
+      }
 
-    return diamond;
+      return diamond;
+    } catch (error) {
+      throw new Error(
+        `Failed to deploy diamond. Ensure @diamondslab/hardhat-diamonds is installed.\n` +
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
 
   /**
@@ -121,13 +118,19 @@ export class DeploymentManager {
       const network = await provider.getNetwork();
       const actualChainId = chainId ?? Number(network.chainId);
 
+      // Check in-memory cache first (for ephemeral deployments)
+      const cacheKey = `${diamondName}-${networkName}-${actualChainId}`;
+      if (this.deploymentCache.has(cacheKey)) {
+        Logger.info("Using cached deployment (ephemeral)");
+        return this.deploymentCache.get(cacheKey)!;
+      }
+
       if (!this.hasDeploymentRecord(diamondName, networkName, actualChainId)) {
         Logger.warn("No deployment record found");
         return null;
       }
 
-      const LocalDiamondDeployer = await this.getDeployerClass();
-      const deployer = await LocalDiamondDeployer.getInstance({
+      const deployer = await LocalDiamondDeployer.getInstance(this.hre as any, {
         diamondName,
         networkName,
         provider,
@@ -137,7 +140,7 @@ export class DeploymentManager {
 
       return await deployer.getDiamond();
     } catch (error) {
-      Logger.error(`Failed to get deployment: ${error}`);
+      Logger.error(`Failed to get deployment. Ensure @diamondslab/hardhat-diamonds is installed: ${error}`);
       return null;
     }
   }
@@ -147,11 +150,13 @@ export class DeploymentManager {
    * @param diamondName - Name of the Diamond
    * @param networkName - Network name
    * @param force - Force redeployment
+   * @param writeDeployedDiamondData - Whether to write deployment record to file
    */
   async ensureDeployment(
     diamondName: string = "ExampleDiamond",
     networkName: string = "hardhat",
-    force: boolean = false
+    force: boolean = false,
+    writeDeployedDiamondData: boolean = false
   ): Promise<Diamond> {
     const provider = this.hre.ethers.provider;
     const network = await provider.getNetwork();
@@ -166,7 +171,7 @@ export class DeploymentManager {
     }
 
     // Deploy if not exists or force is true
-    return await this.deploy(diamondName, networkName, force);
+    return await this.deploy(diamondName, networkName, force, writeDeployedDiamondData);
   }
 
   /**

package/src/framework/ForgeFuzzingFramework.ts

@@ -23,6 +23,10 @@ export interface ForgeTestOptions {
   skipHelpers?: boolean;
   /** Skip deployment (use existing) */
   skipDeployment?: boolean;
+  /** Write deployment data to file (default: false for ephemeral) */
+  writeDeployedDiamondData?: boolean;
+  /** Use EVM snapshots for test isolation */
+  useSnapshot?: boolean;
 }
 
 /**
@@ -58,6 +62,8 @@ export class ForgeFuzzingFramework {
     const {
       diamondName = "ExampleDiamond",
       networkName = "hardhat",
+      writeDeployedDiamondData = false,
+      useSnapshot = false,
       force = false,
       matchTest,
       matchContract,
@@ -82,7 +88,8 @@ export class ForgeFuzzingFramework {
         await this.deploymentManager.ensureDeployment(
           diamondName,
           networkName,
-          force
+          force,
+          writeDeployedDiamondData
         );
       } else {
         Logger.info("Skipping deployment (using existing)");
@@ -131,11 +138,26 @@ export class ForgeFuzzingFramework {
 
       // Step 5: Run tests
       Logger.section("Step 4/4: Running Forge Tests");
+      
+      // Only fork when using persistent networks (localhost, sepolia, mainnet, etc.)
+      // The ephemeral "hardhat" network cannot be forked from
+      let forkUrl: string | undefined;
+      if (networkName !== "hardhat") {
+        const provider = this.hre.ethers.provider;
+        forkUrl = (provider as any)._hardhatProvider?._wrapped?.url || "http://127.0.0.1:8545";
+        Logger.info(`Forking from ${networkName}: ${forkUrl}`);
+      } else {
+        Logger.warn(`⚠️  Using ephemeral "${networkName}" network - tests requiring deployed Diamond will fail`);
+        Logger.warn(`💡 For deployed Diamond testing, use: npx hardhat diamonds-forge:test --network localhost`);
+        Logger.warn(`💡 Make sure to start Hardhat node first: npx hardhat node`);
+      }
+      
       const testResult = await runForgeTest({
         matchTest,
         matchContract,
         verbosity,
         gasReport,
+        forkUrl, // Only set for persistent networks
         cwd: this.hre.config.paths.root,
       });
 

package/src/framework/HelperGenerator.ts

@@ -184,6 +184,11 @@ export class HelperGenerator {
     source += `    /// @dev This is the main Diamond proxy address\n`;
     source += `    address constant DIAMOND_ADDRESS = ${deploymentData.DiamondAddress};\n\n`;
 
+    // Deployer address
+    source += `    /// @notice Address of the deployer account\n`;
+    source += `    /// @dev Account that deployed the Diamond\n`;
+    source += `    address constant DEPLOYER_ADDRESS = ${deploymentData.DeployerAddress};\n\n`;
+
     // Facet addresses
     source += "    // ========================================\n";
     source += "    // Facet Addresses\n";
@@ -215,6 +220,14 @@ export class HelperGenerator {
     source += "        return DIAMOND_ADDRESS;\n";
     source += "    }\n\n";
 
+    source += "    /**\n";
+    source += "     * @notice Get the deployer address\n";
+    source += "     * @return The address of the deployer account\n";
+    source += "     */\n";
+    source += "    function getDeployerAddress() internal pure returns (address) {\n";
+    source += "        return DEPLOYER_ADDRESS;\n";
+    source += "    }\n\n";
+
     source += "    /**\n";
     source += "     * @notice Get facet implementation address by name\n";
     source += "     * @param facetName The name of the facet\n";

package/src/index.ts

@@ -21,11 +21,6 @@ import {
 } from "./foundry";
 import { validateConfig } from "./utils/validation";
 
-// Export framework classes for programmatic use
-export { DeploymentManager } from "./framework/DeploymentManager";
-export { ForgeFuzzingFramework } from "./framework/ForgeFuzzingFramework";
-export { HelperGenerator } from "./framework/HelperGenerator";
-
 // Export types
 export * from "./types/config";
 

package/src/tasks/deploy.ts

@@ -1,6 +1,5 @@
 import { task, types } from "hardhat/config";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
-import { DeploymentManager } from "../framework/DeploymentManager";
 import { Logger } from "../utils/logger";
 import { validateFoundryInstallation } from "../utils/validation";
 
@@ -24,6 +23,7 @@ task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
   )
   .addFlag("reuse", "Reuse existing deployment if available")
   .addFlag("force", "Force redeployment even if deployment exists")
+  .addFlag("saveDeployment", "Write deployment data to file (default: true for localhost/testnet)")
   .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
     Logger.section("Deploying Diamond for Forge Testing");
 
@@ -32,6 +32,11 @@ task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
     const diamondName = taskArgs.diamondName;
     const reuse = taskArgs.reuse;
     const force = taskArgs.force;
+    
+    // Default to saving deployment for persistent networks (localhost, sepolia, etc.)
+    // but not for ephemeral hardhat network. 
+    // Flags default to false when not provided, so we check if explicitly passed
+    const saveDeployment = taskArgs.saveDeployment || networkName !== "hardhat";
 
     // Validate flags
     if (reuse && force) {
@@ -42,6 +47,7 @@ task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
     Logger.info(`Diamond: ${diamondName}`);
     Logger.info(`Network: ${networkName}`);
     Logger.info(`Mode: ${force ? "force deploy" : reuse ? "reuse if exists" : "deploy new"}`);
+    Logger.info(`Save Deployment: ${saveDeployment}`);
 
     // Step 1: Validate Foundry (optional for deployment, but recommended)
     Logger.step("Checking Foundry installation...");
@@ -56,6 +62,9 @@ task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
 
     // Step 2: Deploy or reuse Diamond
     Logger.step("Deploying Diamond contract...");
+    
+    // Lazy-load DeploymentManager to avoid circular dependency
+    const { DeploymentManager } = await import("../framework/DeploymentManager.js");
     const deploymentManager = new DeploymentManager(hre);
 
     try {
@@ -66,14 +75,16 @@ task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
         diamond = await deploymentManager.ensureDeployment(
           diamondName,
           networkName,
-          false
+          false,
+          saveDeployment
         );
       } else {
         // Deploy (force if flag is set)
         diamond = await deploymentManager.deploy(
           diamondName,
           networkName,
-          force
+          force,
+          saveDeployment
         );
       }
 

package/src/tasks/generate-helpers.ts

@@ -1,7 +1,5 @@
 import { task, types } from "hardhat/config";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
-import { DeploymentManager } from "../framework/DeploymentManager";
-import { HelperGenerator } from "../framework/HelperGenerator";
 import { Logger } from "../utils/logger";
 
 /**
@@ -39,6 +37,9 @@ task("diamonds-forge:generate-helpers", "Generate Solidity helpers from Diamond
     Logger.info(`Network: ${networkName}`);
     Logger.info(`Output: ${outputDir}`);
 
+    // Lazy-load framework to avoid circular dependency during config loading
+    const { DeploymentManager } = await import("../framework/DeploymentManager.js");
+
     // Step 1: Get deployment
     Logger.step("Loading deployment data...");
     const deploymentManager = new DeploymentManager(hre);
@@ -62,6 +63,9 @@ task("diamonds-forge:generate-helpers", "Generate Solidity helpers from Diamond
       const network = await provider.getNetwork();
       const chainId = Number(network.chainId);
 
+      // Lazy-load HelperGenerator
+      const { HelperGenerator } = await import("../framework/HelperGenerator.js");
+
       // Step 3: Generate helpers
       Logger.step("Generating Solidity helpers...");
       const generator = new HelperGenerator(hre);

package/src/tasks/init.ts

@@ -1,6 +1,5 @@
 import { task, types } from "hardhat/config";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
-import { HelperGenerator } from "../framework/HelperGenerator";
 import { Logger } from "../utils/logger";
 import { validateConfig, validateFoundryInstallation } from "../utils/validation";
 
@@ -50,6 +49,9 @@ task("diamonds-forge:init", "Initialize Forge testing structure for Diamond cont
 
     // Step 3: Scaffold project structure
     Logger.step("Creating test directory structure...");
+    
+    // Lazy-load framework classes to avoid circular dependency
+    const { HelperGenerator } = await import("../framework/HelperGenerator.js");
     const generator = new HelperGenerator(hre);
     
     try {

package/src/tasks/test.ts

@@ -1,6 +1,5 @@
 import { task, types } from "hardhat/config";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
-import { ForgeFuzzingFramework, ForgeTestOptions } from "../framework/ForgeFuzzingFramework";
 import { Logger } from "../utils/logger";
 
 /**
@@ -43,6 +42,8 @@ task("diamonds-forge:test", "Run Forge tests with Diamond deployment")
   .addFlag("skipDeployment", "Skip Diamond deployment step")
   .addFlag("skipHelpers", "Skip helper generation step")
   .addFlag("force", "Force redeployment of Diamond")
+  .addFlag("saveDeployment", "Write deployment data to file for reuse")
+  .addFlag("useSnapshot", "Use EVM snapshots for test isolation")
   .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
     Logger.section("Running Forge Tests with Diamond");
 
@@ -56,6 +57,8 @@ task("diamonds-forge:test", "Run Forge tests with Diamond deployment")
     const skipDeployment = taskArgs.skipDeployment;
     const skipHelpers = taskArgs.skipHelpers;
     const force = taskArgs.force;
+    const saveDeployment = taskArgs.saveDeployment;
+    const useSnapshot = taskArgs.useSnapshot;
 
     Logger.info(`Diamond: ${diamondName}`);
     Logger.info(`Network: ${networkName}`);
@@ -65,6 +68,12 @@ task("diamonds-forge:test", "Run Forge tests with Diamond deployment")
     if (gasReport) Logger.info("Gas Report: enabled");
     if (skipDeployment) Logger.info("Skip Deployment: true");
     if (skipHelpers) Logger.info("Skip Helpers: true");
+    if (saveDeployment) Logger.info("Save Deployment: true");
+    if (useSnapshot) Logger.info("Use Snapshot: true");
+
+    // Lazy-load framework to avoid circular dependency during config loading
+    const { ForgeFuzzingFramework } = await import("../framework/ForgeFuzzingFramework.js");
+    type ForgeTestOptions = Parameters<InstanceType<typeof ForgeFuzzingFramework>["runTests"]>[0];
 
     // Create test options
     const options: ForgeTestOptions = {
@@ -77,6 +86,8 @@ task("diamonds-forge:test", "Run Forge tests with Diamond deployment")
       gasReport,
       skipHelpers,
       skipDeployment,
+      writeDeployedDiamondData: saveDeployment,
+      useSnapshot,
     };
 
     // Run tests using the framework

package/src/templates/ExampleFuzzTest.t.sol.template

@@ -3,8 +3,9 @@ pragma solidity ^0.8.0;
 
 import "forge-std/Test.sol";
 import "forge-std/console.sol";
-import "../../contracts/DiamondFuzzBase.sol";
-import "../../helpers/DiamondDeployment.sol";
+import "@diamondslab/diamonds-hardhat-foundry/contracts/DiamondFuzzBase.sol";
+import "@diamondslab/diamonds-hardhat-foundry/contracts/DiamondForgeHelpers.sol";
+import "../helpers/DiamondDeployment.sol";
 
 /**
  * @title ExampleFuzzTest
@@ -12,17 +13,19 @@ import "../../helpers/DiamondDeployment.sol";
  * @dev Uses DiamondFuzzBase for common fuzz testing utilities
  */
 contract ExampleFuzzTest is DiamondFuzzBase {
+    using DiamondForgeHelpers for address;
+
+    /// @notice Override to load Diamond from deployment
+    function _loadDiamondAddress() internal view override returns (address) {
+        return DiamondDeployment.diamond();
+    }
+
     function setUp() public override {
         super.setUp();
         
-        // Load Diamond deployment
-        setDiamondAddress(DiamondDeployment.diamond());
-        
-        // Register facets (customize for your Diamond)
-        // registerFacet("FacetName", DiamondDeployment.facetName());
-        
         console.log("Fuzz test setup complete");
         console.log("Diamond:", diamond);
+        console.log("Functions loaded:", diamondSelectors.length);
     }
 
     /**
@@ -31,11 +34,14 @@ contract ExampleFuzzTest is DiamondFuzzBase {
      */
     function testFuzz_AddressInput(address randomAddress) public {
         // Filter invalid addresses
-        assumeValidAddress(randomAddress);
+        vm.assume(DiamondForgeHelpers.isValidTestAddress(randomAddress));
         
         // TODO: Test your Diamond function with fuzzed address
         // Example:
-        // MyDiamond(diamond).someFunction(randomAddress);
+        // bytes4 selector = bytes4(keccak256("someFunction(address)"));
+        // bytes memory data = abi.encode(randomAddress);
+        // (bool success,) = _callDiamond(selector, data);
+        // assertTrue(success);
         
         assertTrue(true, "Replace with actual fuzz test");
     }
@@ -46,11 +52,13 @@ contract ExampleFuzzTest is DiamondFuzzBase {
      */
     function testFuzz_AmountInput(uint256 amount) public {
         // Bound the amount to valid range
-        assumeValidAmount(amount);
+        vm.assume(DiamondForgeHelpers.isValidTestAmount(amount));
         
         // TODO: Test your Diamond function with fuzzed amount
         // Example:
-        // MyDiamond(diamond).transfer(user1, amount);
+        // bytes4 selector = bytes4(keccak256("transfer(address,uint256)"));
+        // bytes memory data = abi.encode(user1, amount);
+        // (bool success,) = _callDiamond(selector, data);
         
         assertTrue(true, "Replace with actual fuzz test");
     }
@@ -67,8 +75,8 @@ contract ExampleFuzzTest is DiamondFuzzBase {
         bytes memory data
     ) public {
         // Filter inputs
-        assumeValidAddress(addr);
-        assumeValidAmount(value);
+        vm.assume(DiamondForgeHelpers.isValidTestAddress(addr));
+        vm.assume(DiamondForgeHelpers.isValidTestAmount(value));
         vm.assume(data.length > 0);
         vm.assume(data.length < 1024); // Reasonable size limit
         
@@ -86,8 +94,9 @@ contract ExampleFuzzTest is DiamondFuzzBase {
         vm.assume(badValue > type(uint128).max);
         
         // TODO: Test that function reverts with invalid input
-        // expectRevertWithMessage("Invalid amount");
-        // MyDiamond(diamond).someFunction(badValue);
+        // bytes4 selector = bytes4(keccak256("someFunction(uint256)"));
+        // bytes memory data = abi.encode(badValue);
+        // _expectDiamondRevert(selector, data, bytes(""));
         
         assertTrue(true, "Replace with actual revert fuzz test");
     }
@@ -98,7 +107,7 @@ contract ExampleFuzzTest is DiamondFuzzBase {
      */
     function testFuzz_BoundedValue(uint256 rawValue) public {
         // Bound value to specific range (e.g., 1 to 1000)
-        uint256 boundedValue = boundValue(rawValue, 1, 1000);
+        uint256 boundedValue = bound(rawValue, 1, 1000);
         
         // TODO: Test with bounded value
         assertGe(boundedValue, 1, "Value should be >= 1");

package/src/templates/ExampleIntegrationTest.t.sol.template

@@ -3,7 +3,9 @@ pragma solidity ^0.8.0;
 
 import "forge-std/Test.sol";
 import "forge-std/console.sol";
-import "../../helpers/DiamondDeployment.sol";
+import "@diamondslab/diamonds-hardhat-foundry/contracts/DiamondForgeHelpers.sol";
+import "@diamondslab/diamonds-hardhat-foundry/contracts/DiamondABILoader.sol";
+import "../helpers/DiamondDeployment.sol";
 
 /**
  * @title ExampleIntegrationTest
@@ -11,6 +13,9 @@ import "../../helpers/DiamondDeployment.sol";
  * @dev Tests interactions between multiple facets and Diamond functionality
  */
 contract ExampleIntegrationTest is Test {
+    using DiamondForgeHelpers for address;
+    using DiamondABILoader for string;
+
     address diamond;
     address deployer;
     
@@ -23,6 +28,9 @@ contract ExampleIntegrationTest is Test {
         diamond = DiamondDeployment.diamond();
         deployer = DiamondDeployment.deployer();
 
+        // Validate Diamond
+        DiamondForgeHelpers.assertValidDiamond(diamond);
+
         // Set up test users
         user1 = makeAddr("user1");
         user2 = makeAddr("user2");

package/src/templates/ExampleUnitTest.t.sol.template

@@ -3,7 +3,8 @@ pragma solidity ^0.8.0;
 
 import "forge-std/Test.sol";
 import "forge-std/console.sol";
-import "../../helpers/DiamondDeployment.sol";
+import "@diamondslab/diamonds-hardhat-foundry/contracts/DiamondForgeHelpers.sol";
+import "../helpers/DiamondDeployment.sol";
 
 /**
  * @title ExampleUnitTest
@@ -11,6 +12,8 @@ import "../../helpers/DiamondDeployment.sol";
  * @dev This is a template - customize for your specific Diamond implementation
  */
 contract ExampleUnitTest is Test {
+    using DiamondForgeHelpers for address;
+
     address diamond;
     address deployer;
 
@@ -21,6 +24,9 @@ contract ExampleUnitTest is Test {
 
         console.log("Diamond deployed at:", diamond);
         console.log("Deployed by:", deployer);
+        
+        // Validate Diamond deployment
+        DiamondForgeHelpers.assertValidDiamond(diamond);
     }
 
     /**

package/src/types/hardhat.ts

@@ -2,6 +2,7 @@
  * Type extensions for Hardhat Runtime Environment
  */
 
+import "@nomicfoundation/hardhat-ethers";
 import "hardhat/types/config";
 import "hardhat/types/runtime";
 import { DiamondsFoundryConfig } from "../types/config";
@@ -19,6 +20,5 @@ declare module "hardhat/types/config" {
 declare module "hardhat/types/runtime" {
   export interface HardhatRuntimeEnvironment {
     diamondsFoundry: Required<DiamondsFoundryConfig>;
-    ethers: any; // Will be provided by @nomicfoundation/hardhat-ethers
   }
 }

package/src/utils/foundry.ts

@@ -89,6 +89,7 @@ export async function runForgeTest(options: {
   matchContract?: string;
   verbosity?: number;
   gasReport?: boolean;
+  forkUrl?: string;
   cwd?: string;
   env?: Record<string, string>;
 }): Promise<{ success: boolean; output: string }> {
@@ -110,6 +111,10 @@ export async function runForgeTest(options: {
     args.push("--gas-report");
   }
 
+  if (options.forkUrl) {
+    args.push("--fork-url", options.forkUrl);
+  }
+
   try {
     const result = await execForgeAsync("forge", args, {
       cwd: options.cwd,