chore: update .shared subtree from shared-hardhat-tools

[Git-on-my-level]

Updates the .shared subtree with latest changes from shared-hardhat-tools:

• Add multicall support for role scanning (batch operations)
• Add grant-default-admin and transfer-ownership scripts
• Update role scanning with improved batch operations
• Improve role manifest management
• Remove deprecated transfer-roles script and runner module

This brings ronin-solidity-contracts in sync with katana-solidity-contracts for role management tooling.

[claude]

Claude finished @Git-on-my-level's task —— View job

---

PR Review: Update .shared subtree from shared-hardhat-tools

Review Checklist

• Read repository guidelines (CLAUDE.md)
• Analyze new multicall functionality
• Review new grant-default-admin script
• Review new transfer-ownership script
• Examine role scanning improvements
• Check manifest management changes
• Verify removal of deprecated code is safe
• Assess overall code quality and security
• Provide comprehensive feedback

---

Overall Assessment ✅

This PR represents a well-designed refactoring that improves the role management tooling significantly. The changes align with the documented refactor plan and follow solid engineering practices.

Key Improvements

🚀 Performance Enhancements

• Multicall Integration: New multicall.ts (.shared/lib/roles/multicall.ts:1-102) provides efficient batch RPC operations using Multicall3
• Batched Role Scanning: Enhanced scan.ts now batches role constant lookups and hasRole checks, reducing RPC calls significantly
• Chunked Processing: Configurable batch sizes (default 50) with progress callbacks for large deployments

🔧 Improved Architecture

• Single Responsibility: Split monolithic functionality into focused scripts:
  • grant-default-admin.ts - Direct DEFAULT_ADMIN_ROLE grants
  • transfer-ownership.ts - Ownable contract transfers
  • revoke-roles.ts - Safe batch revocations (enhanced)
• Removed Complexity: Eliminated the 624-line runner.ts module and deprecated transfer-roles.ts

🛡️ Enhanced Safety & UX

• Explicit Opt-out Tracking: All scripts now clearly report manifest exclusions
• Comprehensive Summaries: Detailed execution reports with success/failure/skip counts
• Dry-run Support: All scripts support --dry-run with clear simulation logging
• JSON Output: Machine-readable reports for CI/automation integration

---

Code Quality Analysis

✅ Strengths

1. Error Handling: Robust error handling with graceful fallbacks

   // .shared/lib/roles/multicall.ts:58-62
   } catch (error) {
     options?.logger?.(
       `Multicall unavailable at ${address}: ${error instanceof Error ? error.message : String(error)}. Falling back to individual calls.`,
     );
     return null;
   }

2. Type Safety: Strong TypeScript typing throughout with proper interfaces

   // .shared/scripts/roles/grant-default-admin.ts:15-22
   interface GrantTarget {
     readonly deployment: string;
     readonly contractName: string;
     readonly address: string;
     readonly manifestSource: ManifestSource;
     readonly defaultAdminRoleHash: string;
     readonly rolesInfo: ScanResult["rolesContracts"][number];
   }

3. Security Best Practices:

   • Address validation using @ethersproject/address
   • Explicit transaction confirmation prompts
   • Dry-run capabilities for all operations
   • Clear separation of direct vs Safe execution modes

4. Logging & Observability: Comprehensive progress tracking and summary reporting

⚠️ Areas for Attention

1. Multicall Address Hardcoding:

   // .shared/lib/roles/multicall.ts:3
   export const DEFAULT_MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";

   Impact: Low - This is the canonical Multicall3 address deployed on most chains, but could be made configurable for non-standard deployments.

2. Dynamic Require Usage:

   // .shared/scripts/roles/grant-default-admin.ts:79
   const hre = require("hardhat");

   Impact: Low - Standard pattern for Hardhat scripts, but could benefit from proper import typing.

3. File System Operations: Direct fs.writeFileSync usage without explicit error handling in JSON output functions.

---

Security Assessment 🔒

✅ Security Strengths

• Address Validation: Proper checksumming via @ethersproject/address
• Permission Verification: Scripts verify deployer permissions before execution
• Transaction Confirmation: User prompts prevent accidental execution
• Manifest-Driven: Configuration-based approach reduces hardcoded values
• Safe Integration: Proper Safe transaction batching for role revocations

✅ No Security Concerns Found

• No hardcoded private keys or secrets
• No unsafe external calls or dynamic imports
• Proper input validation and error handling
• Read-only operations for scanning, write operations properly gated

---

Performance Considerations 📈

✅ Excellent Improvements

1. RPC Optimization: Multicall batching reduces network calls by ~50-90%
2. Chunked Processing: Configurable batch sizes prevent RPC timeouts
3. Fallback Strategy: Graceful degradation when Multicall3 unavailable
4. Progress Tracking: User feedback during long-running operations

📊 Measurement Suggestion

Consider adding RPC call metrics to quantify the performance improvement:

// Example enhancement for scan.ts
const rpcMetrics = {
  multicallRequests: 0,
  directCalls: 0,
  timesSaved: 0
};

---

Testing & Compatibility 🧪

✅ Backward Compatibility

• CLI interfaces remain consistent
• Existing manifest format supported
• Network configuration compatibility maintained

⚠️ Testing Recommendations

1. Integration Tests: Verify multicall functionality across different networks
2. Fallback Testing: Test behavior when Multicall3 is unavailable
3. Large Dataset Testing: Validate performance with 100+ contracts
4. Safe Integration: Test transaction batching with actual Safe deployments

---

Documentation Quality 📚

✅ Excellent Documentation

• Comprehensive RolesScriptRefactorPlan.md explains the design rationale
• Updated README with new workflow examples
• Clear CLI help text and option descriptions
• Manifest schema documentation

---

Recommendation 🎯

✅ APPROVE - This is a high-quality refactoring that significantly improves the tooling while maintaining backward compatibility. The code demonstrates solid engineering practices with proper error handling, type safety, and security considerations.

Minor Suggestions for Future PRs:

1. Add RPC metrics tracking for performance measurement
2. Consider making Multicall3 address configurable via environment variable
3. Add integration tests for the new multicall functionality
4. Consider adding timeout configuration for large batch operations

Ready to merge - No blocking issues identified.

---

[claude]

Claude finished @Git-on-my-level's task —— View job

---

PR Review: Update .shared subtree from shared-hardhat-tools

Review Checklist

• Read repository guidelines (CLAUDE.md)
• Analyze new multicall functionality
• Review new grant-default-admin script
• Review new transfer-ownership script
• Examine role scanning improvements
• Check manifest management changes
• Verify removal of deprecated code is safe
• Assess overall code quality and security
• Provide comprehensive feedback

---

Overall Assessment ✅

This PR represents a well-designed refactoring that improves the role management tooling significantly. The changes align with the documented refactor plan and follow solid engineering practices.

Key Improvements

🚀 Performance Enhancements

• Multicall Integration: New multicall.ts (.shared/lib/roles/multicall.ts:1-102) provides efficient batch RPC operations using Multicall3
• Batched Role Scanning: Enhanced scan.ts now batches role constant lookups and hasRole checks, reducing RPC calls significantly
• Chunked Processing: Configurable batch sizes (default 50) with progress callbacks for large deployments

🔧 Improved Architecture

• Single Responsibility: Split monolithic functionality into focused scripts:
  • grant-default-admin.ts - Direct DEFAULT_ADMIN_ROLE grants
  • transfer-ownership.ts - Ownable contract transfers
  • revoke-roles.ts - Safe batch revocations (enhanced)
• Removed Complexity: Eliminated the 624-line runner.ts module and deprecated transfer-roles.ts

🛡️ Enhanced Safety & UX

• Explicit Opt-out Tracking: All scripts now clearly report manifest exclusions
• Comprehensive Summaries: Detailed execution reports with success/failure/skip counts
• Dry-run Support: All scripts support --dry-run with clear simulation logging
• JSON Output: Machine-readable reports for CI/automation integration

---

Code Quality Analysis

✅ Strengths

1. Error Handling: Robust error handling with graceful fallbacks

   // .shared/lib/roles/multicall.ts:58-62
   } catch (error) {
     options?.logger?.(
       `Multicall unavailable at ${address}: ${error instanceof Error ? error.message : String(error)}. Falling back to individual calls.`,
     );
     return null;
   }

2. Type Safety: Strong TypeScript typing throughout with proper interfaces

   // .shared/scripts/roles/grant-default-admin.ts:15-22
   interface GrantTarget {
     readonly deployment: string;
     readonly contractName: string;
     readonly address: string;
     readonly manifestSource: ManifestSource;
     readonly defaultAdminRoleHash: string;
     readonly rolesInfo: ScanResult["rolesContracts"][number];
   }

3. Security Best Practices:

   • Address validation using @ethersproject/address
   • Explicit transaction confirmation prompts
   • Dry-run capabilities for all operations
   • Clear separation of direct vs Safe execution modes

4. Logging & Observability: Comprehensive progress tracking and summary reporting

⚠️ Areas for Attention

1. Multicall Address Hardcoding:

   // .shared/lib/roles/multicall.ts:3
   export const DEFAULT_MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";

   Impact: Low - This is the canonical Multicall3 address deployed on most chains, but could be made configurable for non-standard deployments.

2. Dynamic Require Usage:

   // .shared/scripts/roles/grant-default-admin.ts:79
   const hre = require("hardhat");

   Impact: Low - Standard pattern for Hardhat scripts, but could benefit from proper import typing.

3. File System Operations: Direct fs.writeFileSync usage without explicit error handling in JSON output functions.

---

Security Assessment 🔒

✅ Security Strengths

• Address Validation: Proper checksumming via @ethersproject/address
• Permission Verification: Scripts verify deployer permissions before execution
• Transaction Confirmation: User prompts prevent accidental execution
• Manifest-Driven: Configuration-based approach reduces hardcoded values
• Safe Integration: Proper Safe transaction batching for role revocations

✅ No Security Concerns Found

• No hardcoded private keys or secrets
• No unsafe external calls or dynamic imports
• Proper input validation and error handling
• Read-only operations for scanning, write operations properly gated

---

Performance Considerations 📈

✅ Excellent Improvements

1. RPC Optimization: Multicall batching reduces network calls by ~50-90%
2. Chunked Processing: Configurable batch sizes prevent RPC timeouts
3. Fallback Strategy: Graceful degradation when Multicall3 unavailable
4. Progress Tracking: User feedback during long-running operations

📊 Measurement Suggestion

Consider adding RPC call metrics to quantify the performance improvement:

// Example enhancement for scan.ts
const rpcMetrics = {
  multicallRequests: 0,
  directCalls: 0,
  timesSaved: 0
};

---

Testing & Compatibility 🧪

✅ Backward Compatibility

• CLI interfaces remain consistent
• Existing manifest format supported
• Network configuration compatibility maintained

⚠️ Testing Recommendations

1. Integration Tests: Verify multicall functionality across different networks
2. Fallback Testing: Test behavior when Multicall3 is unavailable
3. Large Dataset Testing: Validate performance with 100+ contracts
4. Safe Integration: Test transaction batching with actual Safe deployments

---

Documentation Quality 📚

✅ Excellent Documentation

• Comprehensive RolesScriptRefactorPlan.md explains the design rationale
• Updated README with new workflow examples
• Clear CLI help text and option descriptions
• Manifest schema documentation

---

Recommendation 🎯

✅ APPROVE - This is a high-quality refactoring that significantly improves the tooling while maintaining backward compatibility. The code demonstrates solid engineering practices with proper error handling, type safety, and security considerations.

Minor Suggestions for Future PRs:

1. Add RPC metrics tracking for performance measurement
2. Consider making Multicall3 address configurable via environment variable
3. Add integration tests for the new multicall functionality
4. Consider adding timeout configuration for large batch operations

Ready to merge - No blocking issues identified.

---

[claude]

Claude finished @Git-on-my-level's task —— View job

---

PR Review: Update .shared subtree from shared-hardhat-tools

Review Checklist

• Read repository guidelines (CLAUDE.md)
• Analyze the refactor plan and documentation
• Review multicall implementation for performance and security
• Examine new grant-default-admin script
• Review new transfer-ownership script
• Analyze role scanning improvements
• Check manifest management changes
• Verify removal of deprecated code is safe
• Assess overall code quality and best practices
• Check for potential security vulnerabilities
• Evaluate error handling and edge cases
• Provide comprehensive feedback

---

Overall Assessment ✅

This PR represents a high-quality refactoring that significantly improves the role management tooling with excellent performance optimizations, security considerations, and maintainability improvements. The changes follow solid engineering practices and are well-documented.

Code Quality Analysis

✅ Major Strengths

🚀 Performance Improvements

• Multicall Integration: New .shared/lib/roles/multicall.ts provides efficient batch RPC operations using Multicall3
• Dramatic Speed Improvement: Documented 5x speed improvement (29s → 6s for Katana mainnet scan)
• Optimized Batching: Configurable chunk sizes (default 50) with graceful fallback to individual calls
• RPC Reduction: From 400+ individual calls to 5 aggregate batches covering 204 calls

🏗️ Excellent Architecture

• Single Responsibility: Well-structured separation of concerns:
  • grant-default-admin.ts - Direct DEFAULT_ADMIN_ROLE grants
  • transfer-ownership.ts - Ownable contract transfers
  • revoke-roles.ts - Safe batch revocations
• Removed Complexity: Eliminated 624-line runner.ts module and deprecated transfer-roles.ts
• Type Safety: Strong TypeScript interfaces throughout with proper error handling

🛡️ Security Best Practices

• Address Validation: Proper checksumming via @ethersproject/address
• Permission Verification: Scripts verify deployer permissions before execution
• Safe Integration: Proper Safe transaction batching for role revocations
• Dry-run Support: All scripts support --dry-run with clear simulation logging
• No Hardcoded Secrets: Clean of any exposed credentials or keys

✅ Code Quality Highlights

1. Robust Error Handling:

   // .shared/lib/roles/multicall.ts:57-62
   } catch (error) {
     options?.logger?.(
       `Multicall unavailable at ${address}: ${error instanceof Error ? error.message : String(error)}. Falling back to individual calls.`,
     );
     return null;
   }

2. Clean Type Definitions:

   // .shared/scripts/roles/grant-default-admin.ts:15-22
   interface GrantTarget {
     readonly deployment: string;
     readonly contractName: string;
     readonly address: string;
     readonly manifestSource: ManifestSource;
     readonly defaultAdminRoleHash: string;
     readonly rolesInfo: ScanResult["rolesContracts"][number];
   }

3. Comprehensive Logging: Progress tracking and detailed summaries across all scripts

Security Assessment 🔒

✅ No Security Concerns Found

• Input Validation: Proper address validation and type checking
• Transaction Safety: User confirmation prompts prevent accidental execution
• Manifest-Driven Configuration: Reduces hardcoded values and improves auditability
• Read-Only Scanning: Scanning operations properly isolated from write operations
• Safe Transaction Batching: Proper integration with Safe multisig workflows

⚠️ Minor Technical Considerations

1. Multicall Address: Uses canonical Multicall3 address 0xcA11bde05977b3631167028862bE2a173976CA11

   • Impact: Very low - This is the standard address deployed on most chains
   • Suggestion: Consider making configurable for non-standard deployments

2. Dynamic Require Usage: const hre = require("hardhat"); in scripts

   • Impact: Low - Standard Hardhat pattern, but could benefit from proper import typing

Performance Analysis 📈

✅ Outstanding Improvements

• 5x Speed Improvement: 29s → 6s for real-world deployments
• RPC Optimization: ~95% reduction in network calls via multicall batching
• Chunked Processing: Prevents RPC timeouts on large deployments
• Progress Feedback: Clear user feedback during long operations

Testing & Compatibility 🧪

✅ Backward Compatibility Maintained

• CLI interfaces remain consistent
• Existing manifest format fully supported
• Network configuration compatibility preserved

📋 Testing Evidence

• Real-World Validation: Tested against Katana mainnet (50+ contracts)
• Comprehensive Dry-Runs: All scripts tested with --dry-run flag
• Fallback Testing: Multicall fallback behavior validated

Documentation Quality 📚

✅ Excellent Documentation

• Comprehensive Plan: RolesScriptRefactorPlan.md provides clear design rationale
• Updated Workflows: README updated with new four-script workflow
• CLI Documentation: Clear help text and option descriptions
• Real Performance Data: Includes actual before/after metrics

Removed Code Safety ✅

✅ Safe Deprecation

• transfer-roles.ts: Properly replaced by focused grant-default-admin.ts and transfer-ownership.ts
• runner.ts: 624-line module replaced by cleaner, focused scripts
• Manifest Cleanup: Removed deprecated roles.renounce configuration cleanly

Final Recommendation 🎯

✅ STRONGLY APPROVE - This is exemplary refactoring work that:

1. Delivers Significant Value: 5x performance improvement with measurable impact
2. Follows Best Practices: Clean architecture, type safety, comprehensive error handling
3. Maintains Compatibility: Zero breaking changes to existing workflows
4. Includes Excellent Documentation: Clear explanations and real-world validation data
5. Demonstrates Security Awareness: Proper input validation, Safe integration, dry-run capabilities

Minor Future Enhancements:

• Consider making Multicall3 address configurable via environment variable
• Add integration tests for the multicall functionality
• Consider adding RPC metrics collection for performance monitoring

Ready to merge immediately - No blocking issues identified. This represents high-quality engineering work that meaningfully improves the developer experience.

---