@diamondslab/diamonds 1.3.2 → 1.4.0

package/README.md

@@ -1,115 +1,122 @@
 # Diamonds Module
 
-[![npm version](https://badge.fury.io/js/@geniusventures%2Fdiamonds.svg)](https://badge.fury.io/js/@geniusventures%2Fdiamonds)
+[![npm version](https://badge.fury.io/js/@diamondslab%2Fdiamonds.svg)](https://www.npmjs.com/package/@diamondslab/diamonds)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Hardhat](https://img.shields.io/badge/Hardhat-2.19+-orange.svg)](https://hardhat.org/)
 
-A comprehensive TypeScript framework for deploying, upgrading, and managing ERC-2535 Diamond Proxy contracts with enterprise-grade features including OpenZeppelin Defender integration, sophisticated version management, and flexible deployment strategies.
+`@diamondslab/diamonds` is a TypeScript framework for deploying, upgrading, and
+managing [ERC-2535 Diamond Proxy](https://eips.ethereum.org/EIPS/eip-2535)
+contracts. It provides a pluggable deployment-strategy system, automatic function
+selector management, configuration-driven facet versioning, and ABI tooling.
+
+> **Package manager:** this project uses **Yarn 4** (`packageManager: yarn@4.x`).
+> The examples below use `yarn`. npm/pnpm work for consuming the published package
+> but the repo scripts assume Yarn.
 
 ## ✨ Key Features
 
-### 🏗️ **Complete Diamond Implementation**
+### 🏗️ Complete Diamond Implementation
 
 - Full ERC-2535 Diamond Proxy Standard support
 - Modular facet architecture with automated function selector management
-- Smart collision detection and resolution
-- Comprehensive state management and validation
-
-### 🛡️ **Enterprise Security**
+- Selector collision detection and resolution
+- State management and validation
 
-- **OpenZeppelin Defender Integration**: Secure deployments through Defender's infrastructure
-- **Multi-signature Support**: Gnosis Safe and custom multisig workflows
-- **Automated Verification**: Contract verification on Etherscan and other explorers
-- **Access Control**: Role-based deployment permissions
+### 🔄 Deployment Management
 
-### 🔄 **Advanced Deployment Management**
+- **Strategy Pattern**: pluggable deployment strategies (Local, RPC, Base, Defender)
+- **Version Control**: configuration-driven versioning for facets and protocols
+- **Upgrade Automation**: `DiamondDeployer` detects an existing deployment and
+  performs an upgrade instead of a fresh deploy
+- **Post-deployment Callbacks**: run custom initialization after a cut
 
-- **Strategy Pattern**: Pluggable deployment strategies (Local, Defender, Custom)
-- **Version Control**: Sophisticated versioning for facets and protocols
-- **Upgrade Automation**: Intelligent upgrade detection and execution
-- **Rollback Support**: Safe rollback mechanisms
+### 🏭 Production Ready
 
-### 🏭 **Production Ready**
-
-- **Repository Pattern**: Flexible data persistence (File-based, Database-ready)
-- **Configuration Management**: JSON-based configuration with validation
-- **Comprehensive Testing**: Unit, integration, and end-to-end test suites
-- **CLI Tools**: Command-line interface for deployment operations
+- **Repository Pattern**: pluggable persistence (file-based out of the box)
+- **Configuration Management**: JSON configuration with Zod validation
+- **ABI Tooling**: combined Diamond ABI generation, preview, compare, and validate
+- **Comprehensive Testing**: unit and integration test suites
 
 ## 🚀 Quick Start
 
 ### Installation
 
 ```bash
-npm install @geniusventures/diamonds
+yarn add @diamondslab/diamonds
+# peer deps (if not already present)
+yarn add --dev hardhat @nomicfoundation/hardhat-ethers ethers
 ```
 
 ### Basic Usage
 
-```typescript
-import { Diamond, DiamondDeployer, FileDeploymentRepository } from '@geniusventures/diamonds';
-import { LocalDeploymentStrategy } from '@geniusventures/diamonds/strategies';
-import { ethers } from 'hardhat';
+Everything is exported from the package root (`@diamondslab/diamonds`):
 
-// Create diamond configuration
+```typescript
+import {
+  Diamond,
+  DiamondDeployer,
+  FileDeploymentRepository,
+  LocalDeploymentStrategy,
+} from "@diamondslab/diamonds";
+import { ethers } from "hardhat";
+
+// Diamond configuration
 const config = {
-  diamondName: 'MyDiamond',
-  networkName: 'localhost',
+  diamondName: "MyDiamond",
+  networkName: "localhost",
   chainId: 31337,
-  deploymentsPath: './diamonds',
-  contractsPath: './contracts'
+  deploymentsPath: "./diamonds",
+  contractsPath: "./contracts",
 };
 
-// Setup diamond and deployment components
+// Set up diamond + deployment components
 const repository = new FileDeploymentRepository(config);
 const diamond = new Diamond(config, repository);
 
-// Set provider and signer
+// Provide a provider and signer
 diamond.setProvider(ethers.provider);
-diamond.setSigner(await ethers.getSigners()[0]);
+const [signer] = await ethers.getSigners();
+diamond.setSigner(signer);
 
-// Deploy using local strategy
-const strategy = new LocalDeploymentStrategy(true); // verbose logging
+// Deploy using the local strategy (verbose logging on)
+const strategy = new LocalDeploymentStrategy(true);
 const deployer = new DiamondDeployer(diamond, strategy);
 
+// Deploys if new, upgrades if already deployed
 await deployer.deployDiamond();
 ```
 
 ## 📋 Project Structure
 
-```bash
-diamonds/
-├── src/                           # Source code
-│   ├── core/                      # Core classes
-│   │   ├── Diamond.ts             # Main diamond management
-│   │   ├── DiamondDeployer.ts     # Deployment orchestration
-│   │   ├── DeploymentManager.ts   # Deployment lifecycle
-│   │   └── CallbackManager.ts     # Post-deployment callbacks
-│   ├── strategies/                # Deployment strategies
-│   │   ├── BaseDeploymentStrategy.ts
-│   │   ├── LocalDeploymentStrategy.ts
-│   │   └── OZDefenderDeploymentStrategy.ts
-│   ├── repositories/              # Data persistence
-│   │   ├── DeploymentRepository.ts
-│   │   ├── FileDeploymentRepository.ts
-│   │   └── jsonFileHandler.ts
-│   ├── schemas/                   # Zod validation schemas
-│   │   └── DeploymentSchema.ts
-│   ├── types/                     # TypeScript definitions
-│   ├── utils/                     # Utility functions
-│   └── helpers/                   # Helper functions
-├── docs/                          # Documentation
-├── examples/                      # Usage examples
-├── test/                          # Test suites
-└── scripts/                       # CLI and utility scripts
+```text
+src/
+├── core/                      # Core classes
+│   ├── Diamond.ts             # Diamond state + selector registry
+│   ├── DiamondDeployer.ts     # Deploy/upgrade orchestration
+│   ├── DeploymentManager.ts   # Deployment lifecycle
+│   └── CallbackManager.ts     # Post-deployment callbacks
+├── strategies/                # Deployment strategies
+│   ├── DeploymentStrategy.ts  # Strategy interface
+│   ├── BaseDeploymentStrategy.ts
+│   ├── LocalDeploymentStrategy.ts
+│   ├── RPCDeploymentStrategy.ts
+│   └── OZDefenderDeploymentStrategy.ts   # legacy (see note below)
+├── repositories/              # Data persistence
+│   ├── DeploymentRepository.ts
+│   ├── FileDeploymentRepository.ts
+│   └── jsonFileHandler.ts
+├── schemas/                   # Zod validation schemas
+├── types/                     # TypeScript definitions
+├── utils/                     # Utilities (ABI generation, loupe, selectors, …)
+└── cli/                       # `diamond-abi` CLI
 ```
 
 ## 🔧 Configuration
 
 ### Diamond Configuration
 
-Create a diamond configuration file (`myDiamond.config.json`):
+Create a diamond configuration file (e.g. `myDiamond.config.json`):
 
 ```json
 {
@@ -118,15 +125,11 @@ Create a diamond configuration file (`myDiamond.config.json`):
   "facets": {
     "DiamondCutFacet": {
       "priority": 10,
-      "versions": {
-        "1.0": {}
-      }
+      "versions": { "1.0": {} }
     },
     "DiamondLoupeFacet": {
       "priority": 20,
-      "versions": {
-        "1.0": {}
-      }
+      "versions": { "1.0": {} }
     },
     "MyCustomFacet": {
       "priority": 30,
@@ -152,105 +155,87 @@ NETWORK_NAME=sepolia
 CHAIN_ID=11155111
 RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
 
-# OpenZeppelin Defender (Optional)
+# OpenZeppelin Defender (only for the legacy Defender strategy)
 DEFENDER_API_KEY=your_api_key
 DEFENDER_API_SECRET=your_api_secret
 DEFENDER_RELAYER_ADDRESS=0x...
 DEFENDER_SAFE_ADDRESS=0x...
 
 # Deployment Options
-AUTO_APPROVE_DEFENDER_PROPOSALS=false
 VERBOSE_DEPLOYMENT=true
 ```
 
-## 🛡️ OpenZeppelin Defender Integration
-
-The Diamonds module provides seamless integration with OpenZeppelin Defender for enterprise-grade deployments.
-
-### Setup Defender
-
-1. **Create Defender Account**: Visit [OpenZeppelin Defender](https://defender.openzeppelin.com/)
-2. **Generate API Credentials**: Create API keys with Deploy and Admin permissions
-3. **Configure Environment**: Set your API credentials in `.env`
-
-### Deploy with Defender
-
-```typescript
-import { OZDefenderDeploymentStrategy } from '@geniusventures/diamonds/strategies';
-
-const strategy = new OZDefenderDeploymentStrategy(
-  process.env.DEFENDER_API_KEY!,
-  process.env.DEFENDER_API_SECRET!,
-  process.env.DEFENDER_RELAYER_ADDRESS!,
-  false, // manual approval for production
-  process.env.DEFENDER_SAFE_ADDRESS!,
-  'Safe'
-);
-
-const deployer = new DiamondDeployer(diamond, strategy);
-await deployer.deployDiamond();
-```
-
-### Features
-
-- **Secure Deployments**: All deployments go through Defender's secure infrastructure
-- **Multi-signature Support**: Integrate with Gnosis Safe for production deployments
-- **Automated Monitoring**: Real-time deployment tracking and status updates
-- **Gas Optimization**: Automatic gas price optimization and retry logic
-
 ## 🔄 Deployment Strategies
 
+All strategies extend `BaseDeploymentStrategy` and accept an optional `verbose`
+flag. Pass a strategy instance to `DiamondDeployer`.
+
 ### Local Strategy
 
-For development and testing:
+For development and testing against a local/forked node:
 
 ```typescript
-import { LocalDeploymentStrategy } from '@geniusventures/diamonds/strategies';
+import { LocalDeploymentStrategy } from "@diamondslab/diamonds";
 
-const strategy = new LocalDeploymentStrategy(true); // verbose logging
+const strategy = new LocalDeploymentStrategy(true); // verbose
 ```
 
-### Defender Strategy
+### RPC Strategy
 
-For production deployments:
+For deploying through a configured RPC endpoint / signer:
 
 ```typescript
-import { OZDefenderDeploymentStrategy } from '@geniusventures/diamonds/strategies';
+import { RPCDeploymentStrategy } from "@diamondslab/diamonds";
 
-const strategy = new OZDefenderDeploymentStrategy(
-  apiKey,
-  apiSecret,
-  relayerAddress,
-  autoApprove,
-  viaAddress,
-  viaType,
-  verbose
-);
+const strategy =
+  new RPCDeploymentStrategy(/* see RPCDeploymentStrategy options */);
 ```
 
 ### Custom Strategy
 
-Implement your own deployment strategy:
+Implement your own by extending `BaseDeploymentStrategy` and overriding the
+protected task hooks:
 
 ```typescript
-import { BaseDeploymentStrategy } from '@geniusventures/diamonds/strategies';
+import { BaseDeploymentStrategy, Diamond } from "@diamondslab/diamonds";
 
 export class CustomDeploymentStrategy extends BaseDeploymentStrategy {
   protected async deployDiamondTasks(diamond: Diamond): Promise<void> {
     // Custom deployment logic
   }
-  
+
   protected async performDiamondCutTasks(diamond: Diamond): Promise<void> {
     // Custom diamond cut logic
   }
 }
 ```
 
+### OpenZeppelin Defender Strategy (legacy)
+
+> ⚠️ **Deprecated / legacy.** `OZDefenderDeploymentStrategy` is being phased out
+> and is not recommended for new work. It remains exported for backward
+> compatibility. Prefer `LocalDeploymentStrategy` / `RPCDeploymentStrategy` or a
+> custom strategy.
+
+```typescript
+import { OZDefenderDeploymentStrategy } from "@diamondslab/diamonds";
+
+const strategy = new OZDefenderDeploymentStrategy(
+  process.env.DEFENDER_API_KEY!,
+  process.env.DEFENDER_API_SECRET!,
+  process.env.DEFENDER_RELAYER_ADDRESS!,
+  false, // auto-approve
+  process.env.DEFENDER_SAFE_ADDRESS!,
+  "Safe",
+);
+```
+
 ## 📊 Advanced Features
 
 ### Version Management
 
-The Diamonds module provides sophisticated version management:
+Facets are versioned in the configuration; upgrades declare which prior versions
+they apply from:
 
 ```json
 {
@@ -258,10 +243,7 @@ The Diamonds module provides sophisticated version management:
     "MyFacet": {
       "priority": 100,
       "versions": {
-        "1.0": {
-          "deployInit": "initialize()",
-          "upgradeInit": "upgradeToV1()"
-        },
+        "1.0": { "deployInit": "initialize()", "upgradeInit": "upgradeToV1()" },
         "2.0": {
           "deployInit": "initialize()",
           "upgradeInit": "upgradeToV2()",
@@ -275,344 +257,207 @@ The Diamonds module provides sophisticated version management:
 
 ### Function Selector Management
 
-Automatic function selector management with collision detection:
+Automatic selector management with collision detection:
 
-- **Priority-based Resolution**: Higher priority facets take precedence
-- **Include/Exclude Lists**: Fine-grained control over function selectors
-- **Collision Detection**: Automatic detection and resolution of selector conflicts
-- **Orphaned Selector Prevention**: Validation to prevent deployment issues
+- **Priority-based resolution**: higher-priority facets take precedence
+- **Include/Exclude lists**: fine-grained selector control (`deployInclude` / `deployExclude`)
+- **Collision detection**: automatic detection and resolution of selector conflicts
+- **Orphaned selector prevention**: validation guards against bad cuts
 
 ### Post-Deployment Callbacks
 
-Execute custom logic after deployment:
-
 ```typescript
 // In your callbacks directory
 export async function postDeployCallback(args: CallbackArgs) {
   const { diamond } = args;
-  console.log(`Post-deployment callback executed for ${diamond.diamondName}`);
-  
+  console.log(`Post-deployment callback for ${diamond.diamondName}`);
   // Custom post-deployment logic
-  await customInitialization();
 }
 ```
 
-## 🧪 Testing
-
-### Running Tests
-
-```bash
-# Install dependencies
-npm install
-
-# Run all tests
-npm test
-
-# Run unit tests only
-npm run test:unit
-
-# Run integration tests
-npm run test:integration
-
-# Run with coverage
-npm run test:coverage
-
-# Test specific network
-TEST_NETWORK=sepolia npm test
-```
-
-### Test Categories
-
-- **Unit Tests**: Individual component testing
-- **Integration Tests**: Component interaction testing
-- **Defender Integration**: End-to-end Defender testing
-- **Performance Tests**: Deployment speed and resource usage
-
-### Example Test
-
-```typescript
-describe('Diamond Deployment', () => {
-  let diamond: Diamond;
-  let strategy: LocalDeploymentStrategy;
-
-  beforeEach(() => {
-    const config = {
-      diamondName: 'TestDiamond',
-      networkName: 'hardhat',
-      chainId: 31337,
-      deploymentsPath: './test-diamonds',
-      contractsPath: './contracts'
-    };
-    
-    const repository = new FileDeploymentRepository(config);
-    diamond = new Diamond(config, repository);
-    strategy = new LocalDeploymentStrategy();
-  });
-
-  it('should deploy diamond successfully', async () => {
-    const deployer = new DiamondDeployer(diamond, strategy);
-    await deployer.deployDiamond();
-    
-    const deployedData = diamond.getDeployedDiamondData();
-    expect(deployedData.DiamondAddress).to.not.be.undefined;
-  });
-});
-```
-
-## 🛠️ CLI Tools
+## 💎 Diamond ABI Tooling
 
-The Diamonds module includes a comprehensive CLI for deployment management:
+This package ships a `diamond-abi` CLI for working with the combined Diamond ABI.
 
 ```bash
-# Install CLI globally
-npm install -g @geniusventures/diamonds
-
-# Deploy a diamond
-diamonds deploy --diamond MyDiamond --network sepolia
-
-# Upgrade a diamond
-diamonds upgrade --diamond MyDiamond
+# Generate the combined ABI for a deployed diamond (requires a Hardhat project)
+npx diamond-abi generate --diamond MyDiamond --network localhost
 
-# Check deployment status
-diamonds status --diamond MyDiamond
+# Preview the ABI changes implied by planned cuts (requires a Hardhat project)
+npx diamond-abi preview --diamond MyDiamond --verbose
 
-# Verify contracts
-diamonds verify --diamond MyDiamond
+# Compare two ABI files (no chain / Hardhat needed)
+npx diamond-abi compare old-abi.json new-abi.json
 
-# Initialize new project
-diamonds init --diamond MyNewDiamond --network mainnet
+# Validate an ABI artifact file (no chain / Hardhat needed)
+npx diamond-abi validate diamond-abi.json
 ```
 
-### CLI Options
+> `generate` and `preview` connect to a chain and load your project's Hardhat
+> config (run them inside a Hardhat project). `compare` and `validate` operate on
+> ABI JSON files and run standalone. Run `npx diamond-abi <command> --help` for
+> all options.
 
-- `--diamond <name>`: Diamond name
-- `--network <name>`: Target network
-- `--config <path>`: Configuration file path
-- `--auto-approve`: Auto-approve Defender proposals
-- `--verbose`: Verbose output
-- `--batch <path>`: Batch deployment configuration
+The same combined ABI can also be produced programmatically via
+`generateDiamondAbi` / `previewDiamondAbi` from `@diamondslab/diamonds`.
 
 ## 📖 Examples
 
 ### Basic Diamond Deployment
 
 ```typescript
-import { Diamond, DiamondDeployer, FileDeploymentRepository } from '@geniusventures/diamonds';
-import { LocalDeploymentStrategy } from '@geniusventures/diamonds/strategies';
+import {
+  Diamond,
+  DiamondDeployer,
+  FileDeploymentRepository,
+  LocalDeploymentStrategy,
+} from "@diamondslab/diamonds";
+import { ethers } from "hardhat";
 
 async function deployBasicDiamond() {
   const config = {
-    diamondName: 'BasicDiamond',
-    networkName: 'localhost',
+    diamondName: "BasicDiamond",
+    networkName: "localhost",
     chainId: 31337,
-    deploymentsPath: './diamonds',
-    contractsPath: './contracts'
+    deploymentsPath: "./diamonds",
+    contractsPath: "./contracts",
   };
 
   const repository = new FileDeploymentRepository(config);
   const diamond = new Diamond(config, repository);
-  
+
   diamond.setProvider(ethers.provider);
-  diamond.setSigner(await ethers.getSigners()[0]);
+  const [signer] = await ethers.getSigners();
+  diamond.setSigner(signer);
 
   const strategy = new LocalDeploymentStrategy();
   const deployer = new DiamondDeployer(diamond, strategy);
 
   await deployer.deployDiamond();
-  console.log('Diamond deployed successfully!');
-}
-```
-
-### Production Deployment with Defender
-
-```typescript
-import { OZDefenderDeploymentStrategy } from '@geniusventures/diamonds/strategies';
-
-async function deployProductionDiamond() {
-  const config = {
-    diamondName: 'ProductionDiamond',
-    networkName: 'mainnet',
-    chainId: 1,
-    deploymentsPath: './diamonds',
-    contractsPath: './contracts'
-  };
-
-  const repository = new FileDeploymentRepository(config);
-  const diamond = new Diamond(config, repository);
-  
-  // Setup provider and signer for mainnet
-  diamond.setProvider(mainnetProvider);
-  diamond.setSigner(productionSigner);
-
-  const strategy = new OZDefenderDeploymentStrategy(
-    process.env.DEFENDER_API_KEY!,
-    process.env.DEFENDER_API_SECRET!,
-    process.env.DEFENDER_RELAYER_ADDRESS!,
-    false, // manual approval for production
-    process.env.DEFENDER_SAFE_ADDRESS!,
-    'Safe'
-  );
-
-  const deployer = new DiamondDeployer(diamond, strategy);
-  await deployer.deployDiamond();
+  console.log("Diamond deployed successfully!");
 }
 ```
 
-### Complex Multi-Facet Upgrade
+### Multi-Facet Upgrade
 
 ```typescript
-async function performComplexUpgrade() {
-  // Load existing diamond
-  const diamond = await loadExistingDiamond('MyDiamond');
-  
-  // Update configuration for new version
+async function performUpgrade(diamond: Diamond) {
+  // Update configuration for the new version
   const config = diamond.repository.loadDeployConfig();
   config.protocolVersion = 2.0;
-  
-  // Add new facet
+
+  // Add a new facet
   config.facets.NewFeatureFacet = {
     priority: 150,
     versions: {
-      "2.0": {
-        deployInit: "initialize()",
-        callbacks: ["setupNewFeature"]
-      }
-    }
+      "2.0": { deployInit: "initialize()", callbacks: ["setupNewFeature"] },
+    },
   };
-  
-  // Upgrade existing facet
+
+  // Upgrade an existing facet
   config.facets.ExistingFacet.versions["2.0"] = {
     upgradeInit: "upgradeToV2()",
-    fromVersions: [1.0]
+    fromVersions: [1.0],
   };
-  
-  await diamond.repository.saveDeployConfig(config);
-  
-  // Execute upgrade
-  const strategy = new OZDefenderDeploymentStrategy(/* config */);
-  const deployer = new DiamondDeployer(diamond, strategy);
+
+  diamond.repository.saveDeployConfig(config);
+
+  // DiamondDeployer detects the existing deployment and performs the upgrade
+  const deployer = new DiamondDeployer(diamond, new LocalDeploymentStrategy());
   await deployer.deployDiamond();
 }
 ```
 
 ## 🔍 Monitoring and Debugging
 
-### Enable Verbose Logging
-
-```typescript
-const strategy = new LocalDeploymentStrategy(true); // Enable verbose mode
-```
-
-### Debug Function Selectors
+### Inspect Function Selectors
 
 ```typescript
-import { getSighash } from '@geniusventures/diamonds/utils';
+import { getSighash } from "@diamondslab/diamonds";
 
-// Get function selector
-const selector = getSighash('transfer(address,uint256)');
-console.log('Selector:', selector);
+const selector = getSighash("transfer(address,uint256)");
+console.log("Selector:", selector);
 
-// Check if selector is registered
-const isRegistered = diamond.isFunctionSelectorRegistered(selector);
-console.log('Is registered:', isRegistered);
+console.log("Registered:", diamond.isFunctionSelectorRegistered(selector));
 ```
 
-### Monitor Deployment State
+### Compare On-Chain vs. Local State
 
 ```typescript
-// Check deployment status
-const deployedData = diamond.getDeployedDiamondData();
-console.log('Diamond address:', deployedData.DiamondAddress);
-console.log('Deployed facets:', Object.keys(deployedData.DeployedFacets || {}));
+import { diffDeployedFacets } from "@diamondslab/diamonds";
+import { ethers } from "hardhat";
 
-// Validate on-chain state
-import { diffDeployedFacets } from '@geniusventures/diamonds/utils';
-const isConsistent = await diffDeployedFacets(deployedData, ethers.provider, true);
+const deployedData = diamond.getDeployedDiamondData();
+console.log("Diamond address:", deployedData.DiamondAddress);
+console.log("Deployed facets:", Object.keys(deployedData.DeployedFacets ?? {}));
+
+// Returns true when on-chain facets match the local deployment record
+const isConsistent = await diffDeployedFacets(
+  deployedData,
+  ethers.provider,
+  true,
+);
 ```
 
-## 🔐 Security Considerations
-
-### Production Best Practices
+## 🧪 Testing & Development
 
-1. **Use Multi-signature Wallets**: Always use multi-sig for mainnet deployments
-2. **Test Thoroughly**: Test all upgrades on testnets first
-3. **Verify Contracts**: Ensure all contracts are verified on Etherscan
-4. **Monitor Deployments**: Use Defender monitoring for production systems
-5. **Access Control**: Implement proper role-based access controls
+Run from the package directory:
 
-### Secure Configuration
+```bash
+yarn install          # install dependencies (Yarn 4)
+yarn build            # compile TypeScript to dist/
+yarn test             # run the Hardhat test suite
+yarn test:unit        # unit tests only
+yarn test:integration # integration tests only
+yarn test:coverage    # tests with coverage
+yarn lint             # lint
+```
 
-```typescript
-// Production configuration example
-const productionConfig = {
-  diamondName: 'ProductionDiamond',
-  networkName: 'mainnet',
-  chainId: 1,
-  deploymentsPath: './production-diamonds',
-  contractsPath: './contracts',
-  writeDeployedDiamondData: true
-};
+## 🔐 Security Considerations
 
-const strategy = new OZDefenderDeploymentStrategy(
-  process.env.PROD_DEFENDER_API_KEY!,
-  process.env.PROD_DEFENDER_API_SECRET!,
-  process.env.PROD_RELAYER_ADDRESS!,
-  false, // Never auto-approve in production
-  process.env.PROD_SAFE_ADDRESS!,
-  'Safe'
-);
-```
+1. **Use multi-signature wallets** for mainnet deployments.
+2. **Test upgrades on a testnet/fork first.**
+3. **Verify contracts** on the relevant block explorer.
+4. **Apply role-based access control** to privileged diamond functions.
+5. **Never commit secrets** — deployment records may contain addresses/keys and are gitignored.
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Setup
+Contributions are welcome. Please open an issue or pull request on
+[GitHub](https://github.com/DiamondsLab/diamonds).
 
 ```bash
-# Clone the repository
-git clone https://github.com/geniusventures/diamonds.git
+git clone https://github.com/DiamondsLab/diamonds.git
 cd diamonds
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build the project
-npm run build
-
-# Run linting
-npm run lint
+yarn install
+yarn test
+yarn build
+yarn lint
 ```
 
 ### Coding Standards
 
-- Follow TypeScript best practices
-- Maintain 90%+ test coverage
-- Use conventional commit messages
+- Follow the existing TypeScript style
+- Use Conventional Commits
+- Add tests for new functionality
 - Update documentation for new features
-- Add comprehensive tests for new functionality
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT — see the [LICENSE](LICENSE) file.
 
 ## 🙏 Acknowledgments
 
-- [OpenZeppelin](https://openzeppelin.com/) for Defender platform and security tools
 - [ERC-2535 Diamond Standard](https://eips.ethereum.org/EIPS/eip-2535) authors
 - [Hardhat](https://hardhat.org/) development framework
-- The Ethereum community for continuous innovation
+- [OpenZeppelin](https://openzeppelin.com/) for security tooling
+- The Ethereum community
 
 ## 📞 Support
 
-- **Documentation**: [Full Documentation](https://docs.geniusventures.com/diamonds)
-- **GitHub Issues**: [Report Issues](https://github.com/geniusventures/diamonds/issues)
-- **Discord**: [Join our Community](https://discord.gg/geniusventures)
-- **Email**: <support@geniusventures.com>
+- **Documentation**: see the [`docs/`](docs/) directory
+- **Issues**: [github.com/DiamondsLab/diamonds/issues](https://github.com/DiamondsLab/diamonds/issues)
 
 ---
 
-**Built with ❤️ for the Ethereum ecosystem by [Genius Ventures](https://geniusventures.com)**
+**Built with ❤️ for the Ethereum ecosystem by [DiamondsLab](https://github.com/DiamondsLab)**