@diamondslab/diamonds 1.0.0

package/examples/defender-deployment/contracts/UpgradeFacet.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.17;
+
+contract UpgradeFacet {
+    bytes32 constant STORAGE_POSITION = keccak256("upgrade.facet.storage");
+    
+    struct FacetStorage {
+        uint256 upgradeCount;
+        mapping(uint256 => uint256) upgradeTimestamps;
+        bool initialized;
+        string[] upgradeLog;
+    }
+    
+    function facetStorage() internal pure returns (FacetStorage storage fs) {
+        bytes32 position = STORAGE_POSITION;
+        assembly {
+            fs.slot := position
+        }
+    }
+    
+    event Initialized(uint256 timestamp);
+    event UpgradeLogged(uint256 indexed upgradeId, string description, uint256 timestamp);
+    event SystemUpgraded(string version, uint256 timestamp);
+    
+    function initialize() external {
+        FacetStorage storage fs = facetStorage();
+        require(!fs.initialized, "Already initialized");
+        
+        fs.initialized = true;
+        fs.upgradeCount = 0;
+        
+        emit Initialized(block.timestamp);
+    }
+    
+    function logUpgrade(string memory description) external {
+        FacetStorage storage fs = facetStorage();
+        require(fs.initialized, "Not initialized");
+        
+        uint256 upgradeId = fs.upgradeCount++;
+        fs.upgradeTimestamps[upgradeId] = block.timestamp;
+        fs.upgradeLog.push(description);
+        
+        emit UpgradeLogged(upgradeId, description, block.timestamp);
+    }
+    
+    function getUpgradeCount() external view returns (uint256) {
+        FacetStorage storage fs = facetStorage();
+        return fs.upgradeCount;
+    }
+    
+    function getUpgradeTimestamp(uint256 upgradeId) external view returns (uint256) {
+        FacetStorage storage fs = facetStorage();
+        require(upgradeId < fs.upgradeCount, "Invalid upgrade ID");
+        return fs.upgradeTimestamps[upgradeId];
+    }
+    
+    function getUpgradeLog() external view returns (string[] memory) {
+        FacetStorage storage fs = facetStorage();
+        return fs.upgradeLog;
+    }
+    
+    function getLatestUpgrade() external view returns (string memory, uint256) {
+        FacetStorage storage fs = facetStorage();
+        require(fs.upgradeCount > 0, "No upgrades logged");
+        
+        uint256 latestId = fs.upgradeCount - 1;
+        return (fs.upgradeLog[latestId], fs.upgradeTimestamps[latestId]);
+    }
+    
+    function markSystemUpgrade(string memory _version) external {
+        FacetStorage storage fs = facetStorage();
+        require(fs.initialized, "Not initialized");
+        
+        string memory description = string(abi.encodePacked("System upgrade to version ", _version));
+        
+        uint256 upgradeId = fs.upgradeCount++;
+        fs.upgradeTimestamps[upgradeId] = block.timestamp;
+        fs.upgradeLog.push(description);
+        
+        emit UpgradeLogged(upgradeId, description, block.timestamp);
+        emit SystemUpgraded(_version, block.timestamp);
+    }
+    
+    function isInitialized() external view returns (bool) {
+        FacetStorage storage fs = facetStorage();
+        return fs.initialized;
+    }
+    
+    function version() external pure returns (string memory) {
+        return "1.0.0";
+    }
+}

package/examples/defender-deployment/deploy-script.ts

@@ -0,0 +1,170 @@
+import { ethers } from 'hardhat';
+import { Diamond } from '../../src/core/Diamond';
+import { DiamondDeployer } from '../../src/core/DiamondDeployer';
+import { FileDeploymentRepository } from '../../src/repositories/FileDeploymentRepository';
+import { OZDefenderDeploymentStrategy } from '../../src/strategies/OZDefenderDeploymentStrategy';
+import * as path from 'path';
+import * as fs from 'fs-extra';
+
+async function main() {
+  console.log('🚀 Starting Defender deployment...');
+
+  // Get network information
+  const network = await ethers.provider.getNetwork();
+  const signers = await ethers.getSigners();
+  const deployer = signers[0];
+
+  console.log(`📍 Network: ${network.name} (${network.chainId})`);
+  console.log(`👤 Deployer: ${deployer.address}`);
+
+  // Load configuration
+  const configPath = path.join(__dirname, 'diamond-config.json');
+  const exampleConfig = {
+    diamondName: 'ExampleDiamond',
+    networkName: network.name,
+    chainId: network.chainId,
+    deploymentsPath: path.join(__dirname, 'deployments'),
+    contractsPath: path.join(__dirname, 'contracts'),
+    callbacksPath: path.join(__dirname, 'callbacks'),
+    configFilePath: configPath,
+    deployedDiamondDataFilePath: path.join(__dirname, 'deployments', `examplediamond-${network.name}-${network.chainId}.json`)
+  };
+
+  // Ensure directories exist
+  await fs.ensureDir(exampleConfig.deploymentsPath);
+  await fs.ensureDir(exampleConfig.callbacksPath);
+
+  // Create diamond instance
+  const repository = new FileDeploymentRepository(exampleConfig);
+  const diamond = new Diamond(exampleConfig, repository);
+
+  // Setup provider and signer
+  diamond.setProvider(ethers.provider);
+  diamond.setSigner(deployer);
+
+  // Validate environment variables
+  const requiredEnvVars = [
+    'DEFENDER_API_KEY',
+    'DEFENDER_API_SECRET',
+    'DEFENDER_RELAYER_ADDRESS',
+    'DEFENDER_SAFE_ADDRESS'
+  ];
+
+  for (const envVar of requiredEnvVars) {
+    if (!process.env[envVar]) {
+      console.error(`❌ Missing required environment variable: ${envVar}`);
+      console.log('Please check your .env file and ensure all Defender credentials are set.');
+      process.exit(1);
+    }
+  }
+
+  // Create Defender strategy
+  const strategy = new OZDefenderDeploymentStrategy(
+    process.env.DEFENDER_API_KEY!,
+    process.env.DEFENDER_API_SECRET!,
+    process.env.DEFENDER_RELAYER_ADDRESS!,
+    process.env.AUTO_APPROVE === 'true',
+    process.env.DEFENDER_SAFE_ADDRESS!,
+    'Safe',
+    true // verbose logging
+  );
+
+  console.log('🛡️ Defender strategy configured');
+  console.log(`⚙️ Auto-approve: ${process.env.AUTO_APPROVE === 'true' ? 'enabled' : 'disabled'}`);
+
+  // Execute deployment
+  const diamondDeployer = new DiamondDeployer(diamond, strategy);
+
+  try {
+    await diamondDeployer.deployDiamond();
+
+    console.log('\n✅ Deployment completed successfully!');
+
+    // Output deployment information
+    const deployedData = diamond.getDeployedDiamondData();
+    console.log('\n📊 Deployment Summary:');
+    console.log(`Diamond Address: ${deployedData.DiamondAddress}`);
+    console.log(`Deployer Address: ${deployedData.DeployerAddress}`);
+    console.log(`Network: ${network.name} (Chain ID: ${network.chainId})`);
+
+    console.log('\n📋 Deployed Facets:');
+    if (deployedData.DeployedFacets) {
+      Object.entries(deployedData.DeployedFacets).forEach(([name, facet]) => {
+        console.log(`  ${name}:`);
+        console.log(`    Address: ${facet.address}`);
+        console.log(`    Version: ${facet.version}`);
+        console.log(`    Selectors: ${facet.funcSelectors?.length || 0}`);
+        if (facet.tx_hash) {
+          console.log(`    TX Hash: ${facet.tx_hash}`);
+        }
+      });
+    }
+
+    // Save deployment summary
+    const summary = {
+      timestamp: new Date().toISOString(),
+      network: network.name,
+      chainId: network.chainId,
+      deployerAddress: deployer.address,
+      diamondAddress: deployedData.DiamondAddress,
+      facets: deployedData.DeployedFacets,
+      deploymentMethod: 'OpenZeppelin Defender'
+    };
+
+    const summaryPath = path.join(exampleConfig.deploymentsPath, 'deployment-summary.json');
+    await fs.writeJson(summaryPath, summary, { spaces: 2 });
+
+    console.log(`\n📄 Deployment summary saved to: ${summaryPath}`);
+
+    // Display next steps
+    console.log('\n🎯 Next Steps:');
+    console.log('1. Verify contracts on block explorer');
+    console.log('2. Test diamond functionality');
+    console.log('3. Set up monitoring and alerts');
+    console.log('4. Prepare upgrade scenarios');
+
+    if (process.env.AUTO_APPROVE !== 'true') {
+      console.log('\n⚠️ Note: Auto-approval is disabled. Check your Defender dashboard for pending proposals.');
+    }
+
+  } catch (error) {
+    console.error('\n❌ Deployment failed:', error);
+
+    // Save error information for debugging
+    const errorInfo = {
+      timestamp: new Date().toISOString(),
+      error: error instanceof Error ? {
+        message: error.message,
+        stack: error.stack,
+        name: error.name
+      } : String(error),
+      network: network.name,
+      chainId: network.chainId,
+      deployerAddress: deployer.address
+    };
+
+    const errorPath = path.join(exampleConfig.deploymentsPath, 'deployment-error.json');
+    await fs.writeJson(errorPath, errorInfo, { spaces: 2 });
+
+    console.log(`\n🔍 Error details saved to: ${errorPath}`);
+    console.log('\nTroubleshooting tips:');
+    console.log('1. Check your Defender API credentials');
+    console.log('2. Ensure sufficient balance for gas fees');
+    console.log('3. Verify network connectivity');
+    console.log('4. Check Defender dashboard for detailed logs');
+
+    process.exit(1);
+  }
+}
+
+// Handle script execution
+if (require.main === module) {
+  main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+      console.error('Unhandled error:', error);
+      process.exit(1);
+    });
+}
+
+export { main as deployWithDefender };

package/examples/defender-deployment/diamond-config.json

@@ -0,0 +1,36 @@
+{
+  "protocolVersion": 0.0,
+  "protocolInitFacet": "ExampleFacet1",
+  "facets": {
+    "DiamondCutFacet": {
+      "priority": 10,
+      "versions": {
+        "0.0": {}
+      }
+    },
+    "DiamondLoupeFacet": {
+      "priority": 20,
+      "versions": {
+        "0.0": {}
+      }
+    },
+    "ExampleFacet1": {
+      "priority": 30,
+      "versions": {
+        "0.0": {
+          "deployInit": "initialize()",
+          "callbacks": ["logDeployment"]
+        }
+      }
+    },
+    "ExampleFacet2": {
+      "priority": 40,
+      "versions": {
+        "0.0": {
+          "deployInit": "setup()",
+          "callbacks": ["validateSetup"]
+        }
+      }
+    }
+  }
+}

package/examples/defender-deployment/upgrade-script.ts

@@ -0,0 +1,237 @@
+import { ethers } from 'hardhat';
+import { Diamond } from '../../src/core/Diamond';
+import { DiamondDeployer } from '../../src/core/DiamondDeployer';
+import { FileDeploymentRepository } from '../../src/repositories/FileDeploymentRepository';
+import { OZDefenderDeploymentStrategy } from '../../src/strategies/OZDefenderDeploymentStrategy';
+import * as path from 'path';
+import * as fs from 'fs-extra';
+
+async function main() {
+  console.log('♻️ Starting upgrade process...');
+
+  // Get network information
+  const network = await ethers.provider.getNetwork();
+  const signers = await ethers.getSigners();
+  const deployer = signers[0];
+
+  console.log(`📍 Network: ${network.name} (${network.chainId})`);
+  console.log(`👤 Deployer: ${deployer.address}`);
+
+  // Load and update configuration
+  const configPath = path.join(__dirname, 'diamond-config.json');
+  const deploymentDataPath = path.join(__dirname, 'deployments', `examplediamond-${network.name}-${network.chainId}.json`);
+
+  // Check if initial deployment exists
+  if (!await fs.pathExists(deploymentDataPath)) {
+    console.error('❌ No existing deployment found. Please run deploy-script.ts first.');
+    process.exit(1);
+  }
+
+  console.log('📄 Loading existing deployment data...');
+
+  // Load current configuration
+  const config = await fs.readJson(configPath);
+  const originalVersion = config.protocolVersion;
+
+  console.log(`📊 Current protocol version: ${originalVersion}`);
+
+  // Update configuration for upgrade
+  config.protocolVersion = 1.0;
+
+  // Add new UpgradeFacet
+  config.facets['UpgradeFacet'] = {
+    priority: 50,
+    versions: {
+      "1.0": {
+        deployInit: "initialize()",
+        callbacks: ["logUpgrade"]
+      }
+    }
+  };
+
+  // Upgrade existing ExampleFacet1 to version 1.0
+  if (!config.facets['ExampleFacet1'].versions) {
+    config.facets['ExampleFacet1'].versions = {};
+  }
+  config.facets['ExampleFacet1'].versions["1.0"] = {
+    upgradeInit: "upgradeToV1()",
+    callbacks: ["validateUpgrade"]
+  };
+
+  console.log('📝 Updated configuration:');
+  console.log(`  - Protocol version: ${originalVersion} → ${config.protocolVersion}`);
+  console.log('  - Added UpgradeFacet v1.0');
+  console.log('  - Upgraded ExampleFacet1 to v1.0');
+
+  // Save updated configuration
+  await fs.writeJson(configPath, config, { spaces: 2 });
+
+  // Setup diamond configuration
+  const diamondConfig = {
+    diamondName: 'ExampleDiamond',
+    networkName: network.name,
+    chainId: network.chainId,
+    deploymentsPath: path.join(__dirname, 'deployments'),
+    contractsPath: path.join(__dirname, 'contracts'),
+    callbacksPath: path.join(__dirname, 'callbacks'),
+    configFilePath: configPath,
+    deployedDiamondDataFilePath: deploymentDataPath
+  };
+
+  // Create diamond instance
+  const repository = new FileDeploymentRepository(diamondConfig);
+  const diamond = new Diamond(diamondConfig, repository);
+
+  diamond.setProvider(ethers.provider);
+  diamond.setSigner(deployer);
+
+  // Validate environment variables
+  const requiredEnvVars = [
+    'DEFENDER_API_KEY',
+    'DEFENDER_API_SECRET',
+    'DEFENDER_RELAYER_ADDRESS',
+    'DEFENDER_SAFE_ADDRESS'
+  ];
+
+  for (const envVar of requiredEnvVars) {
+    if (!process.env[envVar]) {
+      console.error(`❌ Missing required environment variable: ${envVar}`);
+      process.exit(1);
+    }
+  }
+
+  // Create Defender strategy
+  const strategy = new OZDefenderDeploymentStrategy(
+    process.env.DEFENDER_API_KEY!,
+    process.env.DEFENDER_API_SECRET!,
+    process.env.DEFENDER_RELAYER_ADDRESS!,
+    process.env.AUTO_APPROVE === 'true',
+    process.env.DEFENDER_SAFE_ADDRESS!,
+    'Safe',
+    true // verbose logging
+  );
+
+  console.log('🛡️ Defender strategy configured for upgrade');
+
+  // Load existing deployment data to show before state
+  const existingData = diamond.getDeployedDiamondData();
+  console.log('\n📊 Pre-upgrade State:');
+  console.log(`Diamond Address: ${existingData.DiamondAddress}`);
+  if (existingData.DeployedFacets) {
+    console.log('Current Facets:');
+    Object.entries(existingData.DeployedFacets).forEach(([name, facet]) => {
+      console.log(`  ${name}: v${facet.version} at ${facet.address}`);
+    });
+  }
+
+  // Execute upgrade
+  const diamondDeployer = new DiamondDeployer(diamond, strategy);
+
+  try {
+    console.log('\n🚀 Starting upgrade deployment...');
+    await diamondDeployer.deployDiamond(); // Automatically detects upgrade scenario
+
+    console.log('\n✅ Upgrade completed successfully!');
+
+    // Output upgrade information
+    const upgradedData = diamond.getDeployedDiamondData();
+    console.log('\n📊 Post-upgrade State:');
+    console.log(`Diamond Address: ${upgradedData.DiamondAddress}`);
+
+    if (upgradedData.DeployedFacets) {
+      console.log('Updated Facets:');
+      Object.entries(upgradedData.DeployedFacets).forEach(([name, facet]) => {
+        const isNew = !existingData.DeployedFacets?.[name];
+        const isUpgraded = existingData.DeployedFacets?.[name]?.version !== facet.version;
+
+        let status = '';
+        if (isNew) status = ' [NEW]';
+        else if (isUpgraded) status = ' [UPGRADED]';
+
+        console.log(`  ${name}: v${facet.version} at ${facet.address}${status}`);
+      });
+    }
+
+    // Create upgrade summary
+    const upgradeSummary = {
+      timestamp: new Date().toISOString(),
+      network: network.name,
+      chainId: network.chainId,
+      deployerAddress: deployer.address,
+      diamondAddress: upgradedData.DiamondAddress,
+      upgrade: {
+        fromVersion: originalVersion,
+        toVersion: config.protocolVersion,
+        newFacets: ['UpgradeFacet'],
+        upgradedFacets: ['ExampleFacet1'],
+        deploymentMethod: 'OpenZeppelin Defender'
+      },
+      facets: upgradedData.DeployedFacets
+    };
+
+    const summaryPath = path.join(diamondConfig.deploymentsPath, 'upgrade-summary.json');
+    await fs.writeJson(summaryPath, upgradeSummary, { spaces: 2 });
+
+    console.log(`\n📄 Upgrade summary saved to: ${summaryPath}`);
+
+    // Display next steps
+    console.log('\n🎯 Next Steps:');
+    console.log('1. Test new functionality');
+    console.log('2. Verify upgrade initialization');
+    console.log('3. Update documentation');
+    console.log('4. Notify stakeholders');
+
+    if (process.env.AUTO_APPROVE !== 'true') {
+      console.log('\n⚠️ Note: Auto-approval is disabled. Check your Defender dashboard for pending proposals.');
+    }
+
+  } catch (error) {
+    console.error('\n❌ Upgrade failed:', error);
+
+    // Restore original configuration
+    config.protocolVersion = originalVersion;
+    delete config.facets['UpgradeFacet'];
+    if (config.facets['ExampleFacet1'].versions && config.facets['ExampleFacet1'].versions["1.0"]) {
+      delete config.facets['ExampleFacet1'].versions["1.0"];
+    }
+    await fs.writeJson(configPath, config, { spaces: 2 });
+
+    console.log('🔄 Configuration restored to pre-upgrade state');
+
+    // Save error information
+    const errorInfo = {
+      timestamp: new Date().toISOString(),
+      error: error instanceof Error ? {
+        message: error.message,
+        stack: error.stack,
+        name: error.name
+      } : String(error),
+      network: network.name,
+      chainId: network.chainId,
+      deployerAddress: deployer.address,
+      attemptedUpgrade: {
+        fromVersion: originalVersion,
+        toVersion: 1.0
+      }
+    };
+
+    const errorPath = path.join(diamondConfig.deploymentsPath, 'upgrade-error.json');
+    await fs.writeJson(errorPath, errorInfo, { spaces: 2 });
+
+    console.log(`\n🔍 Error details saved to: ${errorPath}`);
+
+    process.exit(1);
+  }
+}
+
+// Handle script execution
+if (require.main === module) {
+  main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+      console.error('Unhandled error:', error);
+      process.exit(1);
+    });
+}
+
+export { main as upgradeWithDefender };

package/examples/hardhat-diamonds-config.example.ts

@@ -0,0 +1,41 @@
+// Example hardhat.config.ts extension for hardhat-diamonds integration
+// This would be used when the hardhat-diamonds plugin is available
+
+import { HardhatUserConfig } from "hardhat/config";
+import "@nomiclabs/hardhat-waffle";
+import "@nomiclabs/hardhat-ethers";
+// import "@gnus.ai/hardhat-diamonds"; // When available
+
+const config: HardhatUserConfig = {
+  solidity: "0.8.17",
+
+  // Extended configuration for hardhat-diamonds plugin
+  diamonds: {
+    // Multiple diamond configurations can be defined
+    ProxyDiamond: {
+      deploymentsPath: "./diamonds",
+      contractsPath: "./contracts",
+      callbacksPath: "./diamonds/ProxyDiamond/callbacks",
+      configFilePath: "./diamonds/ProxyDiamond/proxydiamond.config.json",
+      // Network-specific deployment file paths will be auto-generated
+    },
+
+    TestDiamond: {
+      deploymentsPath: "./test-diamonds",
+      contractsPath: "./test/mocks/contracts",
+      callbacksPath: "./test-diamonds/TestDiamond/callbacks",
+      configFilePath: "./test-diamonds/TestDiamond/testdiamond.config.json",
+    },
+
+    // More diamonds can be configured...
+  },
+
+  networks: {
+    hardhat: {
+      chainId: 31337,
+    },
+    // Other networks...
+  },
+};
+
+export default config;