@diamondslab/diamonds-hardhat-foundry 1.0.0

package/src/tasks/deploy.ts

@@ -0,0 +1,110 @@
+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";
+
+/**
+ * Task: diamonds-forge:deploy
+ * 
+ * Deploys a Diamond contract for Forge testing.
+ * - Validates Foundry installation
+ * - Deploys Diamond using LocalDiamondDeployer
+ * - Saves deployment record
+ * - Optionally reuses existing deployment
+ */
+task("diamonds-forge:deploy", "Deploy Diamond contract for Forge testing")
+  .addOptionalParam(
+    "network",
+    "Target network for deployment",
+    "hardhat",
+    types.string
+  )
+  .addOptionalParam(
+    "diamondName",
+    "Name of the Diamond to deploy",
+    "ExampleDiamond",
+    types.string
+  )
+  .addFlag("reuse", "Reuse existing deployment if available")
+  .addFlag("force", "Force redeployment even if deployment exists")
+  .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
+    Logger.section("Deploying Diamond for Forge Testing");
+
+    const networkName = taskArgs.network;
+    const diamondName = taskArgs.diamondName;
+    const reuse = taskArgs.reuse;
+    const force = taskArgs.force;
+
+    // Validate flags
+    if (reuse && force) {
+      Logger.error("Cannot use both --reuse and --force flags");
+      throw new Error("Conflicting flags: --reuse and --force");
+    }
+
+    Logger.info(`Diamond: ${diamondName}`);
+    Logger.info(`Network: ${networkName}`);
+    Logger.info(`Mode: ${force ? "force deploy" : reuse ? "reuse if exists" : "deploy new"}`);
+
+    // Step 1: Validate Foundry (optional for deployment, but recommended)
+    Logger.step("Checking Foundry installation...");
+    const foundryInstalled = validateFoundryInstallation();
+    
+    if (!foundryInstalled) {
+      Logger.warn("Foundry is not installed");
+      Logger.warn("You'll need it to run tests later");
+    } else {
+      Logger.success("Foundry is installed");
+    }
+
+    // Step 2: Deploy or reuse Diamond
+    Logger.step("Deploying Diamond contract...");
+    const deploymentManager = new DeploymentManager(hre);
+
+    try {
+      let diamond;
+      
+      if (reuse) {
+        // Try to reuse, deploy if not exists
+        diamond = await deploymentManager.ensureDeployment(
+          diamondName,
+          networkName,
+          false
+        );
+      } else {
+        // Deploy (force if flag is set)
+        diamond = await deploymentManager.deploy(
+          diamondName,
+          networkName,
+          force
+        );
+      }
+
+      // Step 3: Display deployment info
+      const deploymentData = diamond.getDeployedDiamondData();
+      
+      Logger.section("Deployment Summary");
+      Logger.success(`Diamond Address: ${deploymentData.DiamondAddress}`);
+      Logger.info(`Deployer Address: ${deploymentData.DeployerAddress}`);
+      
+      const facetCount = Object.keys(deploymentData.DeployedFacets || {}).length;
+      Logger.info(`Facets Deployed: ${facetCount}`);
+      
+      if (facetCount > 0) {
+        Logger.info("\nDeployed Facets:");
+        for (const [name, facet] of Object.entries(deploymentData.DeployedFacets || {})) {
+          Logger.info(`  - ${name}: ${facet.address}`);
+        }
+      }
+
+      Logger.section("Next Steps");
+      Logger.info("Generate helpers: npx hardhat diamonds-forge:generate-helpers");
+      Logger.info("Run tests: npx hardhat diamonds-forge:test");
+
+    } catch (error: any) {
+      Logger.error(`Deployment failed: ${error.message}`);
+      throw error;
+    }
+  });
+
+

package/src/tasks/generate-helpers.ts

@@ -0,0 +1,101 @@
+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";
+
+/**
+ * Task: diamonds-forge:generate-helpers
+ * 
+ * Generates Solidity helper files from Diamond deployment data.
+ * - Reads deployment record
+ * - Generates DiamondDeployment.sol library
+ * - Creates constants for addresses and facets
+ */
+task("diamonds-forge:generate-helpers", "Generate Solidity helpers from Diamond deployment")
+  .addOptionalParam(
+    "diamondName",
+    "Name of the deployed Diamond",
+    "ExampleDiamond",
+    types.string
+  )
+  .addOptionalParam(
+    "network",
+    "Network where Diamond is deployed",
+    "hardhat",
+    types.string
+  )
+  .addOptionalParam(
+    "outputDir",
+    "Directory for generated helper files",
+    undefined,
+    types.string
+  )
+  .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
+    Logger.section("Generating Diamond Deployment Helpers");
+
+    const diamondName = taskArgs.diamondName;
+    const networkName = taskArgs.network;
+    const outputDir = taskArgs.outputDir || hre.diamondsFoundry.helpersDir;
+
+    Logger.info(`Diamond: ${diamondName}`);
+    Logger.info(`Network: ${networkName}`);
+    Logger.info(`Output: ${outputDir}`);
+
+    // Step 1: Get deployment
+    Logger.step("Loading deployment data...");
+    const deploymentManager = new DeploymentManager(hre);
+    
+    try {
+      const diamond = await deploymentManager.getDeployment(
+        diamondName,
+        networkName
+      );
+
+      if (!diamond) {
+        Logger.error("No deployment found");
+        Logger.info(`Deploy first: npx hardhat diamonds-forge:deploy --diamond-name ${diamondName} --network ${networkName}`);
+        throw new Error("Deployment not found");
+      }
+
+      Logger.success("Deployment loaded");
+
+      // Step 2: Get network info for chainId
+      const provider = hre.ethers.provider;
+      const network = await provider.getNetwork();
+      const chainId = Number(network.chainId);
+
+      // Step 3: Generate helpers
+      Logger.step("Generating Solidity helpers...");
+      const generator = new HelperGenerator(hre);
+      
+      const deploymentData = diamond.getDeployedDiamondData();
+      
+      const helperPath = await generator.generateDeploymentHelpers(
+        diamondName,
+        networkName,
+        chainId,
+        deploymentData
+      );
+
+      // Step 4: Summary
+      Logger.section("Helper Generation Complete");
+      Logger.success(`Generated: ${helperPath}`);
+      
+      const facetCount = Object.keys(deploymentData.DeployedFacets || {}).length;
+      Logger.info(`Diamond Address: ${deploymentData.DiamondAddress}`);
+      Logger.info(`Facets Included: ${facetCount}`);
+
+      Logger.section("Next Steps");
+      Logger.info("Import in your test files:");
+      Logger.info(`  import "../../helpers/DiamondDeployment.sol";`);
+      Logger.info("\nRun tests:");
+      Logger.info(`  npx hardhat diamonds-forge:test`);
+
+    } catch (error: any) {
+      Logger.error(`Helper generation failed: ${error.message}`);
+      throw error;
+    }
+  });
+
+

package/src/tasks/init.ts

@@ -0,0 +1,90 @@
+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";
+
+/**
+ * Task: diamonds-forge:init
+ * 
+ * Initializes the project for Forge testing with Diamond contracts.
+ * - Validates configuration
+ * - Checks Foundry installation
+ * - Scaffolds test directory structure
+ * - Optionally generates example tests
+ */
+task("diamonds-forge:init", "Initialize Forge testing structure for Diamond contracts")
+  .addOptionalParam(
+    "helpersDir",
+    "Directory for generated helper files",
+    undefined,
+    types.string
+  )
+  .addFlag("examples", "Generate example test files")
+  .addFlag("force", "Overwrite existing files")
+  .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
+    Logger.section("Initializing Diamonds-Forge Testing");
+
+    // Step 1: Validate configuration
+    Logger.step("Validating configuration...");
+    const config = validateConfig(hre.diamondsFoundry);
+    
+    // Override with task args if provided
+    const helpersDir = taskArgs.helpersDir || config.helpersDir;
+    const generateExamples = taskArgs.examples || config.generateExamples;
+
+    Logger.info(`Helpers directory: ${helpersDir}`);
+    Logger.info(`Generate examples: ${generateExamples}`);
+
+    // Step 2: Check Foundry installation
+    Logger.step("Checking Foundry installation...");
+    const foundryInstalled = validateFoundryInstallation();
+    
+    if (!foundryInstalled) {
+      Logger.warn("Foundry is not installed or not in PATH");
+      Logger.warn("Install from: https://book.getfoundry.sh/getting-started/installation");
+      Logger.warn("Continuing anyway...");
+    } else {
+      Logger.success("Foundry is installed");
+    }
+
+    // Step 3: Scaffold project structure
+    Logger.step("Creating test directory structure...");
+    const generator = new HelperGenerator(hre);
+    
+    try {
+      await generator.scaffoldProject(helpersDir);
+      Logger.success("Directory structure created");
+    } catch (error: any) {
+      Logger.error(`Failed to scaffold project: ${error.message}`);
+      throw error;
+    }
+
+    // Step 4: Generate example tests if requested
+    if (generateExamples) {
+      Logger.step("Generating example test files...");
+      try {
+        const examplePaths = await generator.generateExampleTests();
+        
+        if (examplePaths.length > 0) {
+          Logger.success(`Generated ${examplePaths.length} example test(s)`);
+          examplePaths.forEach((path) => Logger.info(`  - ${path}`));
+        } else {
+          Logger.info("No example tests generated (implementation pending)");
+        }
+      } catch (error: any) {
+        Logger.error(`Failed to generate examples: ${error.message}`);
+        throw error;
+      }
+    }
+
+    // Step 5: Summary
+    Logger.section("Initialization Complete");
+    Logger.success("Your project is ready for Forge testing!");
+    Logger.info("\nNext steps:");
+    Logger.info("  1. Deploy your Diamond: npx hardhat diamonds-forge:deploy");
+    Logger.info("  2. Generate helpers: npx hardhat diamonds-forge:generate-helpers");
+    Logger.info("  3. Run tests: npx hardhat diamonds-forge:test");
+  });
+
+

package/src/tasks/test.ts

@@ -0,0 +1,108 @@
+import { task, types } from "hardhat/config";
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { ForgeFuzzingFramework, ForgeTestOptions } from "../framework/ForgeFuzzingFramework";
+import { Logger } from "../utils/logger";
+
+/**
+ * Task: diamonds-forge:test
+ * 
+ * Runs Forge tests with Diamond deployment.
+ * - Ensures Diamond deployment exists
+ * - Generates Solidity helpers
+ * - Compiles Forge contracts
+ * - Runs forge test with specified options
+ */
+task("diamonds-forge:test", "Run Forge tests with Diamond deployment")
+  .addOptionalParam(
+    "diamondName",
+    "Name of the Diamond to test",
+    "ExampleDiamond",
+    types.string
+  )
+  .addOptionalParam(
+    "network",
+    "Network for deployment",
+    "hardhat",
+    types.string
+  )
+  .addOptionalParam(
+    "matchTest",
+    "Run tests matching pattern (--match-test)",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "matchContract",
+    "Run tests in contracts matching pattern (--match-contract)",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "verbosity",
+    "Verbosity level (1-5, more v's = more verbose)",
+    2,
+    types.int
+  )
+  .addFlag("gasReport", "Show gas report")
+  .addFlag("skipDeployment", "Skip Diamond deployment step")
+  .addFlag("skipHelpers", "Skip helper generation step")
+  .addFlag("force", "Force redeployment of Diamond")
+  .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
+    Logger.section("Running Forge Tests with Diamond");
+
+    const diamondName = taskArgs.diamondName;
+    const networkName = taskArgs.network;
+    const matchTest = taskArgs.matchTest;
+    const matchContract = taskArgs.matchContract;
+    const verbosity = taskArgs.verbosity;
+    const gasReport = taskArgs.gasReport;
+    const skipDeployment = taskArgs.skipDeployment;
+    const skipHelpers = taskArgs.skipHelpers;
+    const force = taskArgs.force;
+
+    Logger.info(`Diamond: ${diamondName}`);
+    Logger.info(`Network: ${networkName}`);
+    
+    if (matchTest) Logger.info(`Match Test: ${matchTest}`);
+    if (matchContract) Logger.info(`Match Contract: ${matchContract}`);
+    if (gasReport) Logger.info("Gas Report: enabled");
+    if (skipDeployment) Logger.info("Skip Deployment: true");
+    if (skipHelpers) Logger.info("Skip Helpers: true");
+
+    // Create test options
+    const options: ForgeTestOptions = {
+      diamondName,
+      networkName,
+      force,
+      matchTest,
+      matchContract,
+      verbosity,
+      gasReport,
+      skipHelpers,
+      skipDeployment,
+    };
+
+    // Run tests using the framework
+    const framework = new ForgeFuzzingFramework(hre);
+    
+    try {
+      const success = await framework.runTests(options);
+
+      if (success) {
+        Logger.section("Test Execution Complete");
+        Logger.success("All tests passed!");
+        process.exitCode = 0;
+      } else {
+        Logger.section("Test Execution Complete");
+        Logger.error("Some tests failed");
+        process.exitCode = 1;
+      }
+
+    } catch (error: any) {
+      Logger.error(`Test execution failed: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  });
+
+

package/src/templates/DiamondDeployment.sol.template

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/**
+ * @title DiamondDeployment
+ * @notice Deployment data for {{DIAMOND_NAME}} on {{NETWORK_NAME}} (Chain ID: {{CHAIN_ID}})
+ * @dev Auto-generated by diamonds-hardhat-foundry
+ * 
+ * Generated: {{TIMESTAMP}}
+ */
+library DiamondDeployment {
+    // Diamond Contract Address
+    address constant DIAMOND_ADDRESS = {{DIAMOND_ADDRESS}};
+    
+    // Deployer Address
+    address constant DEPLOYER_ADDRESS = {{DEPLOYER_ADDRESS}};
+
+    // Facet Addresses
+{{FACET_ADDRESSES}}
+
+    /**
+     * @notice Get the Diamond contract address
+     * @return The address of the Diamond contract
+     */
+    function diamond() internal pure returns (address) {
+        return DIAMOND_ADDRESS;
+    }
+
+    /**
+     * @notice Get the deployer address
+     * @return The address that deployed the Diamond
+     */
+    function deployer() internal pure returns (address) {
+        return DEPLOYER_ADDRESS;
+    }
+
+{{FACET_GETTERS}}
+}

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "forge-std/Test.sol";
+import "forge-std/console.sol";
+import "../../contracts/DiamondFuzzBase.sol";
+import "../../helpers/DiamondDeployment.sol";
+
+/**
+ * @title ExampleFuzzTest
+ * @notice Example fuzz test for Diamond contract
+ * @dev Uses DiamondFuzzBase for common fuzz testing utilities
+ */
+contract ExampleFuzzTest is DiamondFuzzBase {
+    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);
+    }
+
+    /**
+     * @notice Fuzz test with random address input
+     * @param randomAddress Fuzzed address parameter
+     */
+    function testFuzz_AddressInput(address randomAddress) public {
+        // Filter invalid addresses
+        assumeValidAddress(randomAddress);
+        
+        // TODO: Test your Diamond function with fuzzed address
+        // Example:
+        // MyDiamond(diamond).someFunction(randomAddress);
+        
+        assertTrue(true, "Replace with actual fuzz test");
+    }
+
+    /**
+     * @notice Fuzz test with random amount input
+     * @param amount Fuzzed amount parameter
+     */
+    function testFuzz_AmountInput(uint256 amount) public {
+        // Bound the amount to valid range
+        assumeValidAmount(amount);
+        
+        // TODO: Test your Diamond function with fuzzed amount
+        // Example:
+        // MyDiamond(diamond).transfer(user1, amount);
+        
+        assertTrue(true, "Replace with actual fuzz test");
+    }
+
+    /**
+     * @notice Fuzz test with multiple parameters
+     * @param addr Fuzzed address
+     * @param value Fuzzed value
+     * @param data Fuzzed bytes data
+     */
+    function testFuzz_MultipleParams(
+        address addr,
+        uint256 value,
+        bytes memory data
+    ) public {
+        // Filter inputs
+        assumeValidAddress(addr);
+        assumeValidAmount(value);
+        vm.assume(data.length > 0);
+        vm.assume(data.length < 1024); // Reasonable size limit
+        
+        // TODO: Test with multiple fuzzed parameters
+        
+        assertTrue(true, "Replace with actual multi-param fuzz test");
+    }
+
+    /**
+     * @notice Fuzz test for failure conditions
+     * @param badValue Value that should cause revert
+     */
+    function testFuzz_ExpectedRevert(uint256 badValue) public {
+        // Set up conditions for expected revert
+        vm.assume(badValue > type(uint128).max);
+        
+        // TODO: Test that function reverts with invalid input
+        // expectRevertWithMessage("Invalid amount");
+        // MyDiamond(diamond).someFunction(badValue);
+        
+        assertTrue(true, "Replace with actual revert fuzz test");
+    }
+
+    /**
+     * @notice Fuzz test with bounded values
+     * @param rawValue Raw fuzzed value
+     */
+    function testFuzz_BoundedValue(uint256 rawValue) public {
+        // Bound value to specific range (e.g., 1 to 1000)
+        uint256 boundedValue = boundValue(rawValue, 1, 1000);
+        
+        // TODO: Test with bounded value
+        assertGe(boundedValue, 1, "Value should be >= 1");
+        assertLe(boundedValue, 1000, "Value should be <= 1000");
+        
+        assertTrue(true, "Replace with actual bounded fuzz test");
+    }
+}

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

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "forge-std/Test.sol";
+import "forge-std/console.sol";
+import "../../helpers/DiamondDeployment.sol";
+
+/**
+ * @title ExampleIntegrationTest
+ * @notice Example integration test for Diamond contract
+ * @dev Tests interactions between multiple facets and Diamond functionality
+ */
+contract ExampleIntegrationTest is Test {
+    address diamond;
+    address deployer;
+    
+    // Test users
+    address user1;
+    address user2;
+
+    function setUp() public {
+        // Load Diamond deployment data
+        diamond = DiamondDeployment.diamond();
+        deployer = DiamondDeployment.deployer();
+
+        // Set up test users
+        user1 = makeAddr("user1");
+        user2 = makeAddr("user2");
+        
+        // Fund test users
+        vm.deal(user1, 100 ether);
+        vm.deal(user2, 100 ether);
+
+        console.log("Diamond:", diamond);
+        console.log("User1:", user1);
+        console.log("User2:", user2);
+    }
+
+    /**
+     * @notice Test multi-facet interaction workflow
+     */
+    function test_MultiFacetWorkflow() public {
+        // TODO: Implement your multi-facet workflow test
+        // Example:
+        // 1. User1 calls function on Facet A
+        // 2. Verify state change
+        // 3. User2 calls function on Facet B
+        // 4. Verify combined state
+        
+        vm.startPrank(user1);
+        // Your test logic here
+        vm.stopPrank();
+        
+        assertTrue(true, "Replace with actual integration test");
+    }
+
+    /**
+     * @notice Test cross-facet state management
+     */
+    function test_CrossFacetState() public {
+        // TODO: Test that state is properly shared/isolated between facets
+        
+        assertTrue(true, "Replace with actual state test");
+    }
+
+    /**
+     * @notice Test Diamond upgrade scenario (if applicable)
+     */
+    function test_DiamondUpgrade() public {
+        // TODO: Test facet addition/replacement/removal
+        // This requires diamondCut functionality
+        
+        vm.startPrank(deployer);
+        // Your upgrade logic here
+        vm.stopPrank();
+        
+        assertTrue(true, "Replace with actual upgrade test");
+    }
+}

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

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "forge-std/Test.sol";
+import "forge-std/console.sol";
+import "../../helpers/DiamondDeployment.sol";
+
+/**
+ * @title ExampleUnitTest
+ * @notice Example unit test for Diamond contract
+ * @dev This is a template - customize for your specific Diamond implementation
+ */
+contract ExampleUnitTest is Test {
+    address diamond;
+    address deployer;
+
+    function setUp() public {
+        // Load Diamond deployment data
+        diamond = DiamondDeployment.diamond();
+        deployer = DiamondDeployment.deployer();
+
+        console.log("Diamond deployed at:", diamond);
+        console.log("Deployed by:", deployer);
+    }
+
+    /**
+     * @notice Test that Diamond was deployed successfully
+     */
+    function test_DiamondDeployed() public view {
+        // Check that Diamond address is not zero
+        assertNotEq(diamond, address(0), "Diamond address should not be zero");
+        
+        // Check that Diamond has code
+        uint256 codeSize;
+        assembly {
+            codeSize := extcodesize(diamond)
+        }
+        assertGt(codeSize, 0, "Diamond should have code deployed");
+    }
+
+    /**
+     * @notice Test that deployer address is set correctly
+     */
+    function test_DeployerSet() public view {
+        assertNotEq(deployer, address(0), "Deployer address should not be zero");
+    }
+
+    /**
+     * @notice Example test - customize for your Diamond's functionality
+     */
+    function test_ExampleFunctionality() public {
+        // TODO: Add your Diamond-specific tests here
+        // Example:
+        // MyDiamond(diamond).someFunction();
+        // assertEq(result, expectedValue);
+        
+        assertTrue(true, "Replace this with actual test");
+    }
+}