feat(ai): Add docs

.cursor/rules/code_standards.mdc

@@ -0,0 +1,105 @@
+---
+description: Ethereum Package Code Standards - Starlark and configuration standards
+globs:
+  - "**/*.star"
+  - "**/*.yaml"
+  - "**/*.yml"
+  - "**/Dockerfile"
+alwaysApply: false
+---
+
+# Ethereum Package Code Standards
+
+## Starlark Coding Conventions
+
+### File Organization
+- Use `.star` extension for all Starlark files
+- Import modules at the top of files using `import_module()`
+- Order imports: constants, then utilities, then specific modules
+- Group related imports together
+
+### Naming Conventions
+- **Functions**: Use `snake_case` (e.g., `launch_participant`, `get_network_params`)
+- **Variables**: Use `snake_case` for all variables
+- **Constants**: Use `UPPER_SNAKE_CASE` (e.g., `DEFAULT_MNEMONIC`, `HTTP_PORT_ID`)
+- **Module Names**: Use `snake_case` for module names
+- **Struct Fields**: Use `snake_case` for struct field names
+
+### Function Design
+- Return structs for complex data (using `struct()`)
+- Use keyword arguments for functions with many parameters
+- Provide sensible defaults where appropriate
+- Document complex functions with docstrings
+
+### Error Handling
+- Use `fail()` for critical errors that should stop execution
+- Validate inputs early in functions
+- Provide clear error messages
+
+### Common Patterns
+```starlark
+# Module imports
+constants = import_module("../package_io/constants.star")
+
+# Launcher pattern
+def new_launcher(config_data, jwt_file):
+    return struct(
+        config=config_data,
+        jwt=jwt_file,
+    )
+
+# Service launch pattern  
+def launch(plan, launcher, service_name, **kwargs):
+    config = launcher.config
+    # Launch implementation
+    return service_context
+```
+
+## YAML/Configuration Standards
+
+### Structure
+- Use 2-space indentation
+- Group related parameters together
+- Provide comments for complex configurations
+- Use meaningful defaults
+
+### Naming
+- Use `snake_case` for all configuration keys
+- Be consistent with naming across different services
+- Prefix service-specific configs appropriately
+
+### Documentation
+- Include inline comments for non-obvious parameters
+- Document valid values for enum-type parameters
+- Provide examples for complex configurations
+
+## Template Standards
+
+### Template Files
+- Store in `static_files/` directory
+- Use `.tmpl` extension for template files
+- Use clear placeholder syntax: `{{.VARIABLE_NAME}}`
+- Group related templates in subdirectories
+
+### Docker Standards
+- Prefer official images where available
+- Pin versions for production stability
+- Use descriptive image tags
+- Document any custom images in comments
+
+## Service Naming
+- Use descriptive service names: `<client>-<type>-<index>`
+- Examples: `geth-el-1`, `lighthouse-beacon-2`, `teku-validator-1`
+- Maintain consistency across the codebase
+
+## Port Management
+- Define port constants in constants.star
+- Use sequential port allocation
+- Document port usage in service definitions
+- Avoid hardcoded port numbers
+
+## Resource Limits
+- Always make CPU/memory limits configurable
+- Use 0 as "no limit" convention
+- Express CPU in millicores, memory in MB
+- Provide reasonable defaults based on client requirements

.cursor/rules/development_workflow.mdc

@@ -0,0 +1,116 @@
+---
+description: Ethereum Package Development Workflow - Git, testing, and deployment practices
+globs:
+  - "**/*.star"
+  - ".github/**/*"
+  - "network_params.yaml"
+alwaysApply: false
+---
+
+# Ethereum Package Development Workflow
+
+## Git Workflow
+
+### Branch Strategy
+- **main**: Production-ready code, protected branch
+- **feature/***: New features and enhancements
+- **fix/***: Bug fixes
+- **test/***: Testing and experimental changes
+
+### Commit Standards
+- Use conventional commit format: `type(scope): description`
+- Types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`
+- Keep commits atomic and focused
+- Write clear, descriptive commit messages
+
+### Pull Request Process
+1. Create feature branch from main
+2. Make changes following code standards
+3. Test locally with various network configurations
+4. Open PR with descriptive title (checked by CI)
+5. Ensure all CI checks pass
+6. Request review from maintainers
+7. Address review feedback
+8. Merge via squash and merge
+
+## Testing Requirements
+
+### Local Testing
+```bash
+# Basic network test
+kurtosis run . --args-file network_params.yaml
+
+# Test with specific configuration
+kurtosis run . --args-file .github/tests/minimal.yaml
+
+# Clean up after testing
+kurtosis enclave rm -f <enclave-name>
+```
+
+### CI Pipeline
+- **Per-PR Tests**: Run on every pull request
+  - Starlark validation
+  - Multiple configuration tests
+  - Docker image availability checks
+- **Nightly Tests**: Extended test suite
+- **Release Tests**: Full validation before release
+
+### Test Coverage
+- Test different client combinations
+- Validate MEV configurations
+- Check persistence features
+- Verify public network syncing
+- Test additional services integration
+
+## Release Process
+
+### Versioning
+- Uses semantic versioning (MAJOR.MINOR.PATCH)
+- Managed by release-please automation
+- Version tracked in version.txt
+
+### Release Checklist
+1. Ensure all tests pass
+2. Update CHANGELOG.md
+3. Verify documentation is current
+4. Test with latest client versions
+5. Create release via release-please PR
+
+## Development Best Practices
+
+### Before Starting Work
+1. Pull latest changes from main
+2. Check existing issues and PRs
+3. Discuss major changes in issues first
+
+### During Development
+1. Test incrementally
+2. Keep changes focused
+3. Update documentation as needed
+4. Add tests for new features
+
+### Code Review Guidelines
+- Review for correctness and standards compliance
+- Check for security implications
+- Verify resource usage is reasonable
+- Ensure backward compatibility
+- Test the changes locally
+
+### Debugging Tips
+- Use `--verbosity detailed` for verbose output
+- Check service logs: `kurtosis service logs <enclave> <service>`
+- Access service shell: `kurtosis service shell <enclave> <service>`
+- Download artifacts: `kurtosis files download <enclave> <file>`
+
+## Dependency Management
+- Pin critical dependencies versions
+- Update client images regularly
+- Test with new versions before updating defaults
+- Document breaking changes
+
+## Security Considerations
+- Never commit secrets or private keys
+- Use JWT authentication for all EL-CL communication
+- Validate all user inputs
+- Follow least privilege principle for permissions
+- Regular security audits of configurations

.cursor/rules/project_architecture.mdc

@@ -0,0 +1,67 @@
+---
+description: Ethereum Package Architecture - Kurtosis-based multi-client Ethereum network orchestration
+globs:
+  - "**/*.star"
+  - "**/*.yaml"
+  - "**/*.yml"
+alwaysApply: false
+---
+
+# Ethereum Package Architecture
+
+This package orchestrates the deployment and management of private Ethereum testnets and public devnets using Kurtosis. It supports multi-client configurations for both execution and consensus layers.
+
+## Core Architecture Principles
+
+### 1. Participant-Based Design
+- Each participant represents a complete Ethereum node (EL + CL + optional VC + optional signer)
+- Participants can be configured individually or through matrices for multi-client testing
+- Service discovery and coordination happens through the Kurtosis plan API
+
+### 2. Modular Component Structure
+- **Execution Layer (EL)**: Supports geth, nethermind, erigon, besu, reth, ethereumjs, nimbus-eth1
+- **Consensus Layer (CL)**: Supports lighthouse, teku, nimbus, prysm, lodestar, grandine
+- **Validator Clients (VC)**: Can run separately or integrated with CL clients
+- **Additional Services**: MEV infrastructure, monitoring, testing tools, explorers
+
+### 3. Network Types
+- **Devnet**: Private development networks with custom genesis
+- **Public Networks**: Mainnet, sepolia, holesky, and other public testnets
+- **Shadowforks**: Fork existing networks at specific blocks
+- **Ephemery**: Short-lived testnets with automatic reset
+
+### 4. Key Technical Patterns
+- **Starlark-based Configuration**: All orchestration logic in `.star` files
+- **Template-driven Generation**: Static configuration templates in `static_files/`
+- **Service Isolation**: Each component runs in isolated containers
+- **Dynamic Port Management**: Automatic port allocation with optional public exposure
+- **Persistent Storage**: Optional persistent volumes for stateful services
+
+## Directory Structure
+
+```
+src/
+├── cl/                     # Consensus layer client launchers
+├── el/                     # Execution layer client launchers
+├── vc/                     # Validator client configurations
+├── mev/                    # MEV infrastructure (boost, relay, builder)
+├── network_launcher/       # Network initialization strategies
+├── package_io/             # Input parsing and validation
+├── prelaunch_data_generator/ # Genesis and keystore generation
+├── shared_utils/           # Common utilities
+└── [additional_services]/  # Monitoring, testing, exploration tools
+```
+
+## Service Lifecycle
+
+1. **Input Validation**: Parse and validate network parameters
+2. **Genesis Generation**: Create genesis data for both EL and CL
+3. **Network Launch**: Deploy nodes according to participant configuration
+4. **Service Discovery**: Establish peer connections and API endpoints
+5. **Additional Services**: Deploy optional monitoring, testing, and tooling
+
+## Resource Management
+- CPU/Memory limits configurable per service
+- Volume sizes adjustable for different network types
+- Kubernetes tolerations and node selectors for cluster scheduling
+- Docker cache support for optimized image pulling

.cursor/rules/src/assertoor/assertoor.mdc

@@ -0,0 +1 @@
+../../../../src/assertoor/CURSOR.mdc

.cursor/rules/src/blobscan/blobscan.mdc

@@ -0,0 +1 @@
+../../../../src/blobscan/CURSOR.mdc

.cursor/rules/src/blockscout/blockscout.mdc

@@ -0,0 +1 @@
+../../../../src/blockscout/CURSOR.mdc

.cursor/rules/src/cl/cl.mdc

@@ -0,0 +1 @@
+../../../../src/cl/CURSOR.mdc

.cursor/rules/src/cl/grandine/grandine.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/grandine/CURSOR.mdc

.cursor/rules/src/cl/lighthouse/lighthouse.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/lighthouse/CURSOR.mdc

.cursor/rules/src/cl/lodestar/lodestar.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/lodestar/CURSOR.mdc

.cursor/rules/src/cl/nimbus/nimbus.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/nimbus/CURSOR.mdc

.cursor/rules/src/cl/prysm/prysm.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/prysm/CURSOR.mdc

.cursor/rules/src/cl/teku/teku.mdc

@@ -0,0 +1 @@
+../../../../../src/cl/teku/CURSOR.mdc

.cursor/rules/src/el/el.mdc

@@ -0,0 +1 @@
+../../../../src/el/CURSOR.mdc

.cursor/rules/src/el/geth/geth.mdc

@@ -0,0 +1 @@
+../../../../../src/el/geth/CURSOR.mdc

.cursor/rules/src/full_beaconchain/full_beaconchain.mdc

@@ -0,0 +1 @@
+../../../../src/full_beaconchain/CURSOR.mdc

.cursor/rules/src/grafana/grafana.mdc

@@ -0,0 +1 @@
+../../../../src/grafana/CURSOR.mdc

.cursor/rules/src/network_launcher/network_launcher.mdc

@@ -0,0 +1 @@
+../../../../src/network_launcher/CURSOR.mdc

.cursor/rules/src/package_io/package_io.mdc

@@ -0,0 +1 @@
+../../../../src/package_io/CURSOR.mdc

.cursor/rules/src/prelaunch_data_generator/validator_keystores/validator_keystores.mdc

@@ -0,0 +1 @@
+../../../../../src/prelaunch_data_generator/validator_keystores/CURSOR.mdc

.cursor/rules/src/prometheus/prometheus.mdc

@@ -0,0 +1 @@
+../../../../src/prometheus/CURSOR.mdc

.cursor/rules/src/shared_utils/shared_utils.mdc

@@ -0,0 +1 @@
+../../../../src/shared_utils/CURSOR.mdc

.cursor/rules/src/src.mdc

@@ -0,0 +1 @@
+../../../src/CURSOR.mdc

.cursor/rules/src/vc/vc.mdc

@@ -0,0 +1 @@
+../../../../src/vc/CURSOR.mdc

.roo

@@ -0,0 +1 @@
+.cursor

CLAUDE.md

@@ -0,0 +1,38 @@
+# Ethereum Package
+
+A Kurtosis package for orchestrating multi-client Ethereum network deployments, supporting private testnets, public networks, shadowforks, and comprehensive testing infrastructure.
+
+## Project Structure
+Claude MUST read the `.cursor/rules/project_architecture.mdc` file before making any structural changes to the project.
+
+## Code Standards  
+Claude MUST read the `.cursor/rules/code_standards.mdc` file before writing any code in this project.
+
+## Development Workflow
+Claude MUST read the `.cursor/rules/development_workflow.mdc` file before making changes to build, test, or deployment configurations.
+
+## Component Documentation
+Individual components have their own CLAUDE.md files with component-specific rules. Always check for and read component-level documentation when working on specific parts of the codebase.
+
+## Key Capabilities
+- Multi-client support for both execution (Geth, Nethermind, Besu, Erigon, Reth) and consensus layers (Lighthouse, Teku, Nimbus, Prysm, Lodestar, Grandine)
+- MEV infrastructure integration (mev-boost, builders, relays)
+- Comprehensive monitoring and observability (Prometheus, Grafana)
+- Testing tools (Assertoor, tx-fuzz, spamoor)
+- Block explorers and analysis tools (Dora, Blockscout, Blobscan)
+- Support for various network types including shadowforks and ephemery
+
+## Quick Start
+```bash
+# Run with default configuration
+kurtosis run github.com/ethpandaops/ethereum-package
+
+# Run with custom parameters
+kurtosis run . --args-file network_params.yaml
+```
+
+## Important Notes
+- All orchestration logic is written in Starlark (.star files)
+- Configuration templates are stored in static_files/
+- Each service runs in isolated containers managed by Kurtosis
+- Resource limits and network parameters are highly configurable