-
Notifications
You must be signed in to change notification settings - Fork 253
chore: add agents.md, link claude.md to it #3173
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
julienrbrt
wants to merge
2
commits into
main
Choose a base branch
from
julien/agents
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,173 @@ | ||
| # CLAUDE.md | ||
|
|
||
| This file provides guidance to LLM agents when working with code in this repository. | ||
|
|
||
| ## Project Overview | ||
|
|
||
| ev-node is a sovereign rollup framework built in Go that allows developers to build rollups on any DA layer. It provides a modular architecture where components like the data availability layer, executor, and sequencer can be plugged in. | ||
|
|
||
| ## Build and Development Commands | ||
|
|
||
| Uses [just](https://github.com/casey/just) as the command runner. Run `just help` to list all recipes. | ||
|
|
||
| ### Building | ||
|
|
||
| - `just build` - Builds the Testapp CLI to `./build/testapp` | ||
| - `just install` - Installs Testapp CLI to your Go bin directory | ||
| - `just build-all` - Builds all ev-node binaries | ||
| - `just docker-build` - Builds Docker image tagged as `evstack:local-dev` | ||
|
|
||
| ### Testing | ||
|
|
||
| - `just test` - Runs unit tests for all go.mod files | ||
| - `just test-integration` - Runs integration tests (15m timeout) | ||
| - `just test-e2e` - Runs end-to-end tests (requires building binaries first) | ||
| - `just test-cover` - Generates code coverage report | ||
| - `just test-all` - Runs all tests including Docker E2E tests | ||
|
|
||
| ### Linting and Code Quality | ||
|
|
||
| - `just lint` - Runs all linters (golangci-lint, markdownlint, hadolint, yamllint, goreleaser check, actionlint) | ||
| - `just lint-fix` - Auto-fixes linting issues where possible | ||
| - `just vet` - Runs go vet | ||
|
|
||
| ### Development Utilities | ||
|
|
||
| - `just deps` - Downloads dependencies and runs go mod tidy for all modules | ||
| - `just proto-gen` - Generates protobuf files (requires Docker) | ||
| - `just mock-gen` - Generates mocks using mockery | ||
| - `just run-n 3` - Run multiple nodes locally (default: 1) | ||
|
|
||
| ## Code Architecture | ||
|
|
||
| ### Core Package Structure | ||
|
|
||
| The project uses a zero-dependency core package pattern: | ||
|
|
||
| - **core/** - Contains only interfaces and types, no external dependencies | ||
| - **block/** - Block management, creation, validation, and synchronization | ||
| - **pkg/p2p/** - Networking layer built on libp2p | ||
| - **pkg/sequencers/** - Modular sequencer implementations | ||
| - **apps/testapp/** - Reference implementation for testing | ||
|
|
||
| ### Key Interfaces | ||
|
|
||
| - **Executor** (`core/executor.go`) - Handles state transitions | ||
| - **Sequencer** (`core/sequencer.go`) - Orders transactions | ||
| - **DA** (`pkg/da/types`) - Data availability layer abstraction | ||
|
|
||
| ### Modular Design | ||
|
|
||
| - Each component has an interface in the core package | ||
| - Implementations are in separate packages | ||
| - Components are wired together via dependency injection | ||
| - Multiple go.mod files enable modular builds | ||
|
|
||
| ### P2P Architecture | ||
|
|
||
| - Built on libp2p with GossipSub and Kademlia DHT | ||
| - Nodes advertise capabilities (full/light, DA layers) | ||
| - Automatic peer discovery with rendezvous points | ||
|
|
||
| ## Testing Patterns | ||
|
|
||
| ### Test Organization | ||
|
|
||
| - Unit tests: `*_test.go` files alongside code | ||
| - Integration tests: `test/integration/` | ||
| - E2E tests: `test/e2e/` | ||
|
|
||
| ### Running Specific Tests | ||
|
|
||
| ```bash | ||
| # Run a single test | ||
| go test -run TestSpecificFunction ./package/... | ||
|
|
||
| # Run with verbose output | ||
| go test -v ./package/... | ||
|
|
||
| # Run with race detection | ||
| go test -race ./package/... | ||
| ``` | ||
|
|
||
| ### Mock Generation | ||
|
|
||
| - Mocks are defined in `.mockery.yaml` | ||
| - Generate with `just mock-gen` | ||
| - Mocks are placed in `mocks/` directories | ||
|
|
||
| ## Code Style Guidelines | ||
|
|
||
| ### Go Conventions | ||
|
|
||
| - Follow standard Go formatting (enforced by golangci-lint) | ||
| - Use meaningful variable names | ||
| - Keep functions small and focused | ||
| - Document exported types and functions | ||
| - Use context.Context for cancellation | ||
|
|
||
| ### Error Handling | ||
|
|
||
| - Wrap errors with context using `fmt.Errorf` | ||
| - Return errors early | ||
| - Use custom error types for domain-specific errors | ||
|
|
||
| ### Logging | ||
|
|
||
| - Use structured logging (look for existing patterns) | ||
| - Include relevant context in log messages | ||
| - Use appropriate log levels | ||
|
|
||
| ## Common Development Tasks | ||
|
|
||
| ### Adding a New DA Layer | ||
|
|
||
| 1. Implement the `DA` interface from `pkg/da/types` | ||
| 2. Add configuration in the appropriate config package | ||
| 3. Wire it up in the initialization code | ||
| 4. Add tests following existing patterns | ||
|
|
||
| ### Modifying Protobuf Definitions | ||
|
|
||
| 1. Edit `.proto` files in `types/pb/` | ||
| 2. Run `just proto-gen` to regenerate Go code | ||
| 3. Update any affected code | ||
| 4. Run tests to ensure compatibility | ||
|
|
||
| ### Adding New Tests | ||
|
|
||
| 1. Place unit tests next to the code being tested | ||
| 2. Use table-driven tests where appropriate | ||
| 3. Mock external dependencies using mockery | ||
| 4. Ensure tests are deterministic | ||
|
|
||
| ## Security Considerations | ||
|
|
||
| - Never expose private keys in logs or errors | ||
| - Validate all inputs from external sources | ||
| - Use secure random number generation | ||
| - Follow the principle of least privilege | ||
| - Be careful with concurrent access to shared state | ||
|
|
||
| ## Performance Considerations | ||
|
|
||
| - The project uses concurrent processing extensively | ||
| - Be mindful of goroutine leaks | ||
| - Use buffered channels appropriately | ||
| - Profile before optimizing | ||
| - Consider memory allocation in hot paths | ||
|
|
||
| ## Debugging Tips | ||
|
|
||
| - Use `just run-n 2` to test multi-node scenarios locally | ||
| - Check logs for error messages and stack traces | ||
| - Use Go's built-in profiling tools for performance issues | ||
| - The testapp provides a simple way to test changes | ||
|
|
||
| ## Contributing Guidelines | ||
|
|
||
| - All code must pass linting (`just lint`) | ||
| - All tests must pass (`just test-all`) | ||
| - Follow the existing code patterns | ||
| - Update tests when changing functionality | ||
| - Keep commits focused and atomic | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,173 +1 @@ | ||
| # CLAUDE.md | ||
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| ## Project Overview | ||
|
|
||
| ev-node is a sovereign rollup framework built in Go that allows developers to build rollups on any DA layer. It provides a modular architecture where components like the data availability layer, executor, and sequencer can be plugged in. | ||
|
|
||
| ## Build and Development Commands | ||
|
|
||
| Uses [just](https://github.com/casey/just) as the command runner. Run `just help` to list all recipes. | ||
|
|
||
| ### Building | ||
|
|
||
| - `just build` - Builds the Testapp CLI to `./build/testapp` | ||
| - `just install` - Installs Testapp CLI to your Go bin directory | ||
| - `just build-all` - Builds all ev-node binaries | ||
| - `just docker-build` - Builds Docker image tagged as `evstack:local-dev` | ||
|
|
||
| ### Testing | ||
|
|
||
| - `just test` - Runs unit tests for all go.mod files | ||
| - `just test-integration` - Runs integration tests (15m timeout) | ||
| - `just test-e2e` - Runs end-to-end tests (requires building binaries first) | ||
| - `just test-cover` - Generates code coverage report | ||
| - `just test-all` - Runs all tests including Docker E2E tests | ||
|
|
||
| ### Linting and Code Quality | ||
|
|
||
| - `just lint` - Runs all linters (golangci-lint, markdownlint, hadolint, yamllint, goreleaser check, actionlint) | ||
| - `just lint-fix` - Auto-fixes linting issues where possible | ||
| - `just vet` - Runs go vet | ||
|
|
||
| ### Development Utilities | ||
|
|
||
| - `just deps` - Downloads dependencies and runs go mod tidy for all modules | ||
| - `just proto-gen` - Generates protobuf files (requires Docker) | ||
| - `just mock-gen` - Generates mocks using mockery | ||
| - `just run-n 3` - Run multiple nodes locally (default: 1) | ||
|
|
||
| ## Code Architecture | ||
|
|
||
| ### Core Package Structure | ||
|
|
||
| The project uses a zero-dependency core package pattern: | ||
|
|
||
| - **core/** - Contains only interfaces and types, no external dependencies | ||
| - **block/** - Block management, creation, validation, and synchronization | ||
| - **pkg/p2p/** - Networking layer built on libp2p | ||
| - **pkg/sequencers/** - Modular sequencer implementations | ||
| - **apps/testapp/** - Reference implementation for testing | ||
|
|
||
| ### Key Interfaces | ||
|
|
||
| - **Executor** (`core/executor.go`) - Handles state transitions | ||
| - **Sequencer** (`core/sequencer.go`) - Orders transactions | ||
| - **DA** (`pkg/da/types`) - Data availability layer abstraction | ||
|
|
||
| ### Modular Design | ||
|
|
||
| - Each component has an interface in the core package | ||
| - Implementations are in separate packages | ||
| - Components are wired together via dependency injection | ||
| - Multiple go.mod files enable modular builds | ||
|
|
||
| ### P2P Architecture | ||
|
|
||
| - Built on libp2p with GossipSub and Kademlia DHT | ||
| - Nodes advertise capabilities (full/light, DA layers) | ||
| - Automatic peer discovery with rendezvous points | ||
|
|
||
| ## Testing Patterns | ||
|
|
||
| ### Test Organization | ||
|
|
||
| - Unit tests: `*_test.go` files alongside code | ||
| - Integration tests: `test/integration/` | ||
| - E2E tests: `test/e2e/` | ||
|
|
||
| ### Running Specific Tests | ||
|
|
||
| ```bash | ||
| # Run a single test | ||
| go test -run TestSpecificFunction ./package/... | ||
|
|
||
| # Run with verbose output | ||
| go test -v ./package/... | ||
|
|
||
| # Run with race detection | ||
| go test -race ./package/... | ||
| ``` | ||
|
|
||
| ### Mock Generation | ||
|
|
||
| - Mocks are defined in `.mockery.yaml` | ||
| - Generate with `just mock-gen` | ||
| - Mocks are placed in `mocks/` directories | ||
|
|
||
| ## Code Style Guidelines | ||
|
|
||
| ### Go Conventions | ||
|
|
||
| - Follow standard Go formatting (enforced by golangci-lint) | ||
| - Use meaningful variable names | ||
| - Keep functions small and focused | ||
| - Document exported types and functions | ||
| - Use context.Context for cancellation | ||
|
|
||
| ### Error Handling | ||
|
|
||
| - Wrap errors with context using `fmt.Errorf` | ||
| - Return errors early | ||
| - Use custom error types for domain-specific errors | ||
|
|
||
| ### Logging | ||
|
|
||
| - Use structured logging (look for existing patterns) | ||
| - Include relevant context in log messages | ||
| - Use appropriate log levels | ||
|
|
||
| ## Common Development Tasks | ||
|
|
||
| ### Adding a New DA Layer | ||
|
|
||
| 1. Implement the `DA` interface from `pkg/da/types` | ||
| 2. Add configuration in the appropriate config package | ||
| 3. Wire it up in the initialization code | ||
| 4. Add tests following existing patterns | ||
|
|
||
| ### Modifying Protobuf Definitions | ||
|
|
||
| 1. Edit `.proto` files in `types/pb/` | ||
| 2. Run `just proto-gen` to regenerate Go code | ||
| 3. Update any affected code | ||
| 4. Run tests to ensure compatibility | ||
|
|
||
| ### Adding New Tests | ||
|
|
||
| 1. Place unit tests next to the code being tested | ||
| 2. Use table-driven tests where appropriate | ||
| 3. Mock external dependencies using mockery | ||
| 4. Ensure tests are deterministic | ||
|
|
||
| ## Security Considerations | ||
|
|
||
| - Never expose private keys in logs or errors | ||
| - Validate all inputs from external sources | ||
| - Use secure random number generation | ||
| - Follow the principle of least privilege | ||
| - Be careful with concurrent access to shared state | ||
|
|
||
| ## Performance Considerations | ||
|
|
||
| - The project uses concurrent processing extensively | ||
| - Be mindful of goroutine leaks | ||
| - Use buffered channels appropriately | ||
| - Profile before optimizing | ||
| - Consider memory allocation in hot paths | ||
|
|
||
| ## Debugging Tips | ||
|
|
||
| - Use `just run-n 2` to test multi-node scenarios locally | ||
| - Check logs for error messages and stack traces | ||
| - Use Go's built-in profiling tools for performance issues | ||
| - The testapp provides a simple way to test changes | ||
|
|
||
| ## Contributing Guidelines | ||
|
|
||
| - All code must pass linting (`just lint`) | ||
| - All tests must pass (`just test-all`) | ||
| - Follow the existing code patterns | ||
| - Update tests when changing functionality | ||
| - Keep commits focused and atomic | ||
| See [AGENTS.md](./AGENTS.md) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correct the heading to match the filename.
The heading says "# CLAUDE.md" but this file is named AGENTS.md. This creates confusion about which file is being read.
📝 Proposed fix
📝 Committable suggestion
🤖 Prompt for AI Agents