@diamondslab/diamonds 1.0.0

package/docs/README-DEFENDER.md

@@ -0,0 +1,394 @@
+# Diamonds Module - OpenZeppelin Defender Integration
+
+## Project Overview
+
+This project provides a comprehensive implementation of the ERC-2535 Diamond Proxy Standard with full OpenZeppelin Defender integration for enterprise-grade smart contract deployment and management.
+
+## ✨ Key Features
+
+### Core Functionality
+
+- **ERC-2535 Diamond Proxy**: Full implementation of the Diamond standard
+- **Modular Facet System**: Add, replace, and remove functionality without changing the main contract
+- **Version Management**: Sophisticated versioning system for facets and protocols
+- **Strategy Pattern**: Pluggable deployment strategies (Local, Defender, Custom)
+- **Repository Pattern**: Flexible data persistence (File-based, Database-ready)
+
+### OpenZeppelin Defender Integration
+
+- **Secure Deployments**: Deploy contracts through Defender's secure infrastructure
+- **Multi-signature Support**: Integrate with Gnosis Safe and other multi-sig wallets
+- **Automated Execution**: Optional auto-approval for streamlined deployments
+- **Transaction Monitoring**: Real-time deployment tracking and status updates
+- **Contract Verification**: Automatic contract verification through Defender
+- **Robust Error Handling**: Comprehensive retry logic and error recovery
+
+### Enterprise Features
+
+- **TypeScript**: Full type safety with strict TypeScript configuration
+- **Comprehensive Testing**: Unit, integration, and end-to-end test suites
+- **Documentation**: Extensive documentation and examples
+- **CI/CD Ready**: GitHub Actions integration and automated testing
+- **Security Focused**: Best practices for production deployments
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Node.js 18+ and npm
+node --version  # v18.0.0 or higher
+npm --version   # 8.0.0 or higher
+
+# Git
+git --version
+```
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/diamonds.git
+cd diamonds
+
+# Install dependencies
+npm install
+
+# Setup environment
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+### Basic Usage
+
+```typescript
+import { Diamond, DiamondDeployer, FileDeploymentRepository } from '@diamonds/core';
+import { OZDefenderDeploymentStrategy } from '@diamonds/strategies';
+
+// Create diamond configuration
+const config = {
+  diamondName: 'MyDiamond',
+  networkName: 'sepolia',
+  chainId: 11155111,
+  deploymentsPath: './deployments',
+  contractsPath: './contracts'
+  // ... other configuration
+};
+
+// Setup diamond and strategy
+const repository = new FileDeploymentRepository(config);
+const diamond = new Diamond(config, repository);
+const strategy = new OZDefenderDeploymentStrategy(
+  process.env.DEFENDER_API_KEY!,
+  process.env.DEFENDER_API_SECRET!,
+  process.env.DEFENDER_RELAYER_ADDRESS!,
+  false, // manual approval
+  process.env.DEFENDER_SAFE_ADDRESS!,
+  'Safe'
+);
+
+// Deploy diamond
+const deployer = new DiamondDeployer(diamond, strategy);
+await deployer.deployDiamond();
+```
+
+## 📁 Project Structure
+
+```bash
+diamonds/
+├── src/                           # Source code
+│   ├── core/                      # Core classes (Diamond, DiamondDeployer, etc.)
+│   ├── strategies/                # Deployment strategies
+│   ├── repositories/              # Data persistence layer
+│   ├── schemas/                   # Zod validation schemas
+│   ├── types/                     # TypeScript type definitions
+│   └── utils/                     # Utility functions
+├── test/                          # Test suites
+│   ├── unit/                      # Unit tests
+│   ├── integration/               # Integration tests
+│   └── helpers/                   # Test utilities
+├── examples/                      # Complete examples
+│   └── defender-deployment/       # Defender integration example
+├── docs/                          # Documentation
+│   ├── defender-integration.md    # Defender setup guide
+│   └── testing-guide.md          # Testing documentation
+└── artifacts/                     # Compiled contracts
+```
+
+## 🛡️ OpenZeppelin Defender Setup
+
+### 1. Create Defender Account
+
+1. Visit [OpenZeppelin Defender](https://defender.openzeppelin.com/)
+2. Sign up or log in
+3. Generate API credentials with Deploy and Admin permissions
+
+### 2. Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit with your credentials
+DEFENDER_API_KEY=your_api_key_here
+DEFENDER_API_SECRET=your_api_secret_here
+DEFENDER_RELAYER_ADDRESS=0x1234567890123456789012345678901234567890
+DEFENDER_SAFE_ADDRESS=0x0987654321098765432109876543210987654321
+```
+
+### 3. Deploy with Defender
+
+```bash
+# Run the complete example
+cd examples/defender-deployment
+npm install
+npm run deploy:sepolia
+```
+
+## 🧪 Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+
+# Run with coverage
+npm run test:coverage
+
+# Test specific environment
+TEST_NETWORK=sepolia npm test
+```
+
+### Test Categories
+
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: Component interaction testing
+- **Defender Integration**: End-to-end Defender testing
+- **Network Fork Tests**: Real network state testing
+- **Performance Tests**: Deployment speed and resource usage
+- **Error Handling Tests**: Failure scenario testing
+
+## 📖 Documentation
+
+### Core Documentation
+
+- [Defender Integration Guide](docs/defender-integration.md) - Complete setup and usage guide
+- [Testing Guide](docs/testing-guide.md) - Comprehensive testing documentation
+
+### Examples
+
+- [Defender Deployment Example](examples/defender-deployment/) - Complete working example
+- [Local Deployment Example](examples/local-deployment/) - Local development setup
+
+### API Reference
+
+- [Core Classes](src/core/) - Diamond, DiamondDeployer, DeploymentManager
+- [Strategies](src/strategies/) - Deployment strategy implementations
+- [Repositories](src/repositories/) - Data persistence implementations
+- [Utilities](src/utils/) - Helper functions and utilities
+
+## 🔧 Configuration
+
+### Diamond Configuration
+
+```json
+{
+  "protocolVersion": 1.0,
+  "protocolInitFacet": "MyProtocolFacet",
+  "facets": {
+    "DiamondCutFacet": {
+      "priority": 10,
+      "versions": { "1.0": {} }
+    },
+    "DiamondLoupeFacet": {
+      "priority": 20,
+      "versions": { "1.0": {} }
+    },
+    "MyFacet": {
+      "priority": 30,
+      "versions": {
+        "1.0": {
+          "deployInit": "initialize()",
+          "upgradeInit": "upgradeToV1()",
+          "callbacks": ["postDeployCallback"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Deployment Strategies
+
+```typescript
+// Local deployment
+const localStrategy = new LocalDeploymentStrategy(true);
+
+// Defender deployment with auto-approval
+const defenderStrategy = new OZDefenderDeploymentStrategy(
+  apiKey,
+  apiSecret,
+  relayerAddress,
+  true, // auto-approve
+  safeAddress,
+  'Safe'
+);
+
+// Defender deployment with manual approval
+const manualDefenderStrategy = new OZDefenderDeploymentStrategy(
+  apiKey,
+  apiSecret,
+  relayerAddress,
+  false, // manual approval required
+  safeAddress,
+  'Safe'
+);
+```
+
+## 🚀 Deployment Workflows
+
+### Initial Deployment
+
+1. Deploy DiamondCutFacet through Defender
+2. Deploy main Diamond contract
+3. Deploy all configured facets
+4. Create Defender proposal for diamond cut
+5. Execute proposal (auto or manual approval)
+6. Run post-deployment callbacks
+
+### Upgrade Process
+
+1. Update diamond configuration with new versions
+2. Deploy only modified/new facets
+3. Create diamond cut proposal with changes
+4. Execute upgrade proposal
+5. Run upgrade callbacks and validation
+
+### Monitoring and Management
+
+- Real-time status tracking through Defender dashboard
+- Automated transaction monitoring
+- Gas optimization recommendations
+- Error logging and alerting
+
+## 🔒 Security Features
+
+### Access Control
+
+- Multi-signature support for critical operations
+- Role-based deployment permissions
+- API key security and rotation
+- Network-specific configurations
+
+### Best Practices
+
+- Comprehensive input validation
+- State corruption protection
+- Transaction replay protection
+- Gas optimization and limits
+
+### Audit Trail
+
+- Complete deployment history
+- Transaction logging and monitoring
+- Error tracking and recovery
+- Verification and compliance reporting
+
+## 🤝 Contributing
+
+### Development Setup
+
+```bash
+# Clone and setup
+git clone https://github.com/geniusventures/diamonds.git
+cd diamonds
+npm install
+
+# Run tests
+npm test
+
+# Build project
+npm run build
+
+# Lint code
+npm run lint
+```
+
+### Contribution Guidelines
+
+1. Follow TypeScript best practices
+2. Maintain 90%+ test coverage
+3. Update documentation for new features
+4. Follow conventional commit messages
+5. Add comprehensive tests for new functionality
+
+## 📋 Roadmap
+
+### Current Version (1.0)
+
+- ✅ Core Diamond implementation
+- ✅ OpenZeppelin Defender integration
+- ✅ Comprehensive testing suite
+- ✅ Documentation and examples
+
+### Upcoming Features (1.1)
+
+- 🔄 Defender Autotasks integration
+- 🔄 Defender Sentinel monitoring
+- 🔄 Multi-network deployment support
+- 🔄 Advanced upgrade patterns
+
+### Future Enhancements (2.0)
+
+- 📅 Database repository implementation
+- 📅 GraphQL API for deployment data
+- 📅 Web dashboard for deployment management
+- 📅 Advanced analytics and reporting
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **API Authentication Errors**
+   - Verify Defender API credentials
+   - Check API key permissions
+   - Ensure network connectivity
+
+2. **Deployment Failures**
+   - Check gas prices and limits
+   - Verify contract compilation
+   - Review Defender dashboard logs
+
+3. **Network Issues**
+   - Validate RPC endpoints
+   - Check network connectivity
+   - Verify chain ID configuration
+
+### Getting Help
+
+- Check [Documentation](docs/)
+- Review [Examples](examples/)
+- Open [GitHub Issue](https://github.com/genius/diamonds/issues)
+- Join [Telegram Community](https://t.me/geniustokens)
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [OpenZeppelin](https://openzeppelin.com/) for Defender platform
+- [ERC-2535 Standard](https://eips.ethereum.org/EIPS/eip-2535) authors
+- [Hardhat](https://hardhat.org/) development framework
+- Diamond standard community and contributors
+
+---
+
+Built with ❤️ for the Ethereum ecosystem

package/docs/README_DIAMOND_ABI_GENERATOR.md

@@ -0,0 +1,303 @@
+# Diamond ABI Generator Documentation
+
+## Overview
+
+The Diamond ABI Generator is a comprehensive tool for generating unified Application Binary Interface (ABI) files for ERC-2535 Diamond Proxy contracts. This documentation provides everything you need to implement and utilize the Diamond ABI Generator in your projects.
+
+## 📚 Documentation Structure
+
+### 1. [Implementation Guide](./DIAMOND_ABI_GENERATOR_IMPLEMENTATION.md)
+
+Complete implementation guide covering all aspects of the Diamond ABI Generator
+
+- ✅ Installation and setup
+- ✅ Command-line interface usage
+- ✅ Programmatic API integration
+- ✅ TypeChain integration for type generation
+- ✅ Viem integration for modern Ethereum development
+- ✅ AbityPe integration for type-safe ABI handling
+- ✅ Configuration options and advanced features
+- ✅ Best practices and troubleshooting
+
+### 2. [Practical Examples](./DIAMOND_ABI_GENERATOR_EXAMPLES.md)
+
+Real-world examples and patterns for common use cases
+
+- ✅ Integration patterns for different project types
+- ✅ Frontend framework integration (React, Next.js, Vue.js)
+- ✅ Testing strategies and patterns
+- ✅ CI/CD pipeline integration
+- ✅ Performance optimization techniques
+- ✅ Custom tooling and extensions
+- ✅ Migration strategies
+
+### 3. [Quick Reference](./DIAMOND_ABI_GENERATOR_QUICK_REFERENCE.md)
+
+Cheat sheet for common operations and configurations
+
+- ✅ Command reference
+- ✅ API quick reference
+- ✅ Configuration options
+- ✅ Common patterns
+- ✅ Troubleshooting guide
+- ✅ Best practices checklist
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js 16+ and npm/yarn
+- Hardhat project with compiled contracts  
+- Diamonds module setup with deployment configuration
+
+### Basic Usage
+
+```bash
+# Generate ABI for your diamond
+npm run diamond-abi generate --diamond YourDiamond --network localhost
+
+# Generate with TypeChain types
+npm run diamond-abi generate --diamond YourDiamond
+npx typechain --target ethers-v5 --out-dir typechain-types artifacts/diamond-abi/*.json
+
+# Preview ABI changes before deployment
+npm run diamond-abi preview --diamond YourDiamond --verbose
+```
+
+## 🔧 Key Features
+
+### Core Functionality
+
+- **Unified ABI Generation**: Combine all facet ABIs into a single, cohesive interface
+- **Function Selector Registry**: Seamless integration with diamond deployment system
+- **Preview Mode**: Preview ABI changes before applying diamond cuts
+- **Source Information**: Optional inclusion of source code metadata
+- **Validation**: Function selector uniqueness validation
+
+### Development Integration
+
+- **TypeChain Support**: Generate type-safe TypeScript interfaces
+- **Viem Integration**: Modern Ethereum development with type safety
+- **AbityPe Support**: Type-safe ABI handling and validation
+- **CLI Tools**: Professional command-line interface
+- **Watch Mode**: Automatic regeneration during development
+
+### Production Features
+
+- **Performance Optimization**: Efficient processing of large diamond deployments
+- **Caching**: Intelligent caching for improved performance
+- **Error Handling**: Comprehensive error handling and recovery
+- **CI/CD Integration**: Automated workflows for deployment pipelines
+- **Multi-Network Support**: Support for different networks and chain IDs
+
+## 🏗️ Architecture
+
+### Core Components
+
+```typescript
+// Core ABI Generation
+import { generateDiamondAbi, Diamond } from 'diamonds';
+
+// Setup
+const diamond = new Diamond(config, repository);
+const result = await generateDiamondAbi(diamond, options);
+
+// Advanced Usage
+const generator = new DiamondAbiGenerator(options);
+const result = await generator.generateAbi();
+```
+
+### Output Structure
+
+```text
+artifacts/diamond-abi/
+├── YourDiamond.json          # Complete diamond artifact
+├── YourDiamond.d.ts          # TypeScript interface
+└── metadata.json             # Generation metadata
+```
+
+## 🛠️ Integration Examples
+
+### Frontend Integration
+
+```typescript
+// React Hook
+import { useDiamond } from './hooks/useDiamond';
+import DiamondABI from './artifacts/diamond-abi/GameDiamond.json';
+
+function GameComponent() {
+  const { contract } = useDiamond(diamondAddress, provider);
+  // Use contract with full ABI
+}
+```
+
+### Viem Integration
+
+```typescript
+import { createPublicClient, http } from 'viem';
+import DiamondABI from './artifacts/diamond-abi/GameDiamond.json';
+
+const client = createPublicClient({
+  chain: mainnet,
+  transport: http()
+});
+
+const result = await client.readContract({
+  address: diamondAddress,
+  abi: DiamondABI.abi,
+  functionName: 'someFunction'
+});
+```
+
+### Testing Integration
+
+```typescript
+describe('Diamond ABI', () => {
+  it('should generate valid ABI', async () => {
+    const result = await generateDiamondAbi(diamond);
+    expect(result.abi).to.be.an('array');
+    expect(result.stats.totalFunctions).to.be.greaterThan(0);
+  });
+});
+```
+
+## 📋 Configuration
+
+### Basic Configuration
+
+```typescript
+const options = {
+  outputDir: './artifacts/diamond-abi',
+  includeSourceInfo: true,
+  validateSelectors: true,
+  verbose: true
+};
+```
+
+### CLI Configuration
+
+```bash
+npm run diamond-abi generate \
+  --diamond YourDiamond \
+  --network localhost \
+  --output ./artifacts/diamond-abi \
+  --include-source \
+  --validate-selectors \
+  --verbose
+```
+
+## 🧪 Testing
+
+### Unit Tests
+
+```bash
+# Run ABI generation tests
+npm run test:unit -- --grep "Diamond ABI"
+
+# Run integration tests
+npm run test:integration -- --grep "diamondAbiGeneration"
+```
+
+### Validation
+
+```bash
+# Validate generated ABI
+npm run diamond-abi validate artifacts/diamond-abi/YourDiamond.json
+
+# Compare ABIs
+npm run diamond-abi compare old-abi.json new-abi.json
+```
+
+## 🚦 CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Generate Diamond ABI
+  run: |
+    npm run diamond-abi generate --diamond ${{ matrix.diamond }} --network ${{ matrix.network }}
+    npx typechain --target ethers-v5 --out-dir typechain-types artifacts/diamond-abi/*.json
+
+- name: Upload artifacts
+  uses: actions/upload-artifact@v3
+  with:
+    name: diamond-abi
+    path: artifacts/diamond-abi/
+```
+
+## 📦 Package.json Scripts
+
+Recommended scripts for your project:
+
+```json
+{
+  "scripts": {
+    "diamond:abi": "npm run diamond-abi generate",
+    "diamond:types": "npm run diamond:abi && npx typechain --target ethers-v5 --out-dir typechain-types artifacts/diamond-abi/*.json",
+    "diamond:preview": "npm run diamond-abi preview --verbose",
+    "diamond:validate": "npm run diamond-abi validate artifacts/diamond-abi/*.json",
+    "diamond:clean": "rimraf artifacts/diamond-abi typechain-types"
+  }
+}
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "No artifacts found" | Run `npm run compile` first |
+| "Function selector collision" | Enable `validateSelectors: true` |
+| "Missing deployment data" | Check `diamonds/` directory exists |
+| "TypeChain generation fails" | Validate ABI first |
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+npm run diamond-abi generate --verbose
+
+# Or programmatically
+const result = await generateDiamondAbi(diamond, { verbose: true });
+```
+
+## 📈 Performance
+
+### Optimization Tips
+
+1. **Use caching** for repeated operations
+2. **Enable parallel processing** for multiple diamonds
+3. **Filter facets** to include only necessary ones
+4. **Use preview mode** to validate changes before generation
+
+### Benchmarks
+
+- **Small diamonds (1-5 facets)**: ~50-200ms
+- **Medium diamonds (10-20 facets)**: ~100-300ms  
+- **Large diamonds (50+ facets)**: ~500-1000ms
+
+## 🤝 Best Practices
+
+1. **Always validate selectors** in production
+2. **Include in CI/CD pipeline** for automated testing
+3. **Version control generated ABIs** for tracking changes
+4. **Use TypeScript types** for better development experience
+5. **Test integration** with actual contracts
+6. **Monitor performance** for large diamonds
+
+## 🔗 Related Documentation
+
+- [Main Implementation Summary](./DIAMOND_ABI_GENERATION.md)
+- [ERC-2535 Diamond Standard](https://eips.ethereum.org/EIPS/eip-2535)
+- [TypeChain Documentation](https://github.com/dethcrypto/TypeChain)
+- [Viem Documentation](https://viem.sh/)
+- [AbityPe Documentation](https://abitype.dev/)
+
+## 📄 License
+
+This documentation is part of the diamonds module and is licensed under the MIT License.
+
+---
+
+**Need help?** Check the [troubleshooting section](./DIAMOND_ABI_GENERATOR_QUICK_REFERENCE.md#troubleshooting) or open an issue in the repository.