cowprotocol · squadgazzz · Oct 2, 2025 · Oct 2, 2025 · Oct 2, 2025 · Oct 2, 2025
@@ -0,0 +1,138 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+  id-token: write
+  actions: read
+
+jobs:
+  claude-review:
+    if: github.event.pull_request.user.login == 'squadgazzz'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude Code Review
+        uses: anthropics/claude-code-action@v1
+        env:
+          GH_TOKEN: ${{ github.token }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPOSITORY: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+            PR AUTHOR: ${{ github.event.pull_request.user.login }}
+            PR TITLE: ${{ github.event.pull_request.title }}
+
+            You are a Rust code reviewer for the CoW Protocol services codebase.
+
+            TASK:
+            1. Generate a PR description if the PR body is empty
+            2. Review the PR diff and leave inline comments on problematic code
+
+            PART 1 - PR DESCRIPTION (only if PR body is empty):
+            Use `gh pr view ${{ github.event.pull_request.number }} --json body` to check if PR has a description.
+            If body is empty, generate and update PR description using:
+            ```
+            gh pr edit ${{ github.event.pull_request.number }} --body-file /dev/stdin <<'EOF'
+            ## Description
+            [High-level description of changes, background, and motivation]
+
+            ## Changes
+            - [List of specific changes made]
+            - [Each bullet should be a concrete change]
+
+            ## How to test
+            [How these changes should be tested. If no new tests were added, write "Existing tests"]
+
+            ## Related issues
+            <!-- Link related issues here, e.g., Fixes #123 -->
+            EOF
+            ```
+
+            PART 2 - CODE REVIEW:
+
+            REVIEW FOCUS (issues only, no positive feedback):
+            1. **Bugs & Logic Errors**: Race conditions, off-by-one errors, incorrect error handling, panic risks
+            2. **Non-Idiomatic Rust**: Unnecessary clones, missing iterators, improper lifetimes, unwrap() abuse
+            3. **Style Deviations**: Check CLAUDE.md for project conventions (alloy vs ethcontract patterns, RPC batching, quote system)
+            4. **Test Coverage**: Missing tests for new functionality, edge cases not covered
+            5. **Performance Issues**: Unnecessary allocations, blocking operations in async code
+            6. **Security Concerns**: Input validation, authorization checks, data exposure
+
+            REVIEW PROCESS:
+            1. Use `gh pr diff ${{ github.event.pull_request.number }}` to get the full diff
+            2. Analyze each changed file carefully for the issues above
+            3. Post a high-level summary comment first using:
+               ```
+               gh pr comment ${{ github.event.pull_request.number }} \
+                 --body-file /dev/stdin <<'EOF'
+               ## 🤖 Claude Code Review
+
+               **Summary**: [1-2 sentence overview of what this PR does]
+
+               **Files Changed**: [Count and brief categorization]
+
+               **Issues Found**: [Number of issues, or "None" if clean]
+               EOF
+               ```
+            4. For each problem found, leave an inline issue comment using:
+               ```
+               gh pr comment ${{ github.event.pull_request.number }} \
+                 --body-file /dev/stdin <<'EOF'
+               **[Issue Type]** Brief description
+
+               **File**: `path/to/file.rs:LINE`
+
+               **Problem**: Clear explanation of the issue
+
+               **Suggested Fix**:
+               ```rust
+               // Corrected code here
+               ```
+
+               **Why**: Explanation of why this is better
+               EOF
+               ```
+
+            CRITICAL RULES:
+            - DO NOT mention positive aspects or praise in issue comments
+            - DO include a high-level summary comment describing what the PR does
+            - DO NOT modify any repository files
+            - BE CONCISE: Issue comments should be 3-5 lines maximum
+            - ONLY comment on actual problems, not style preferences unless they deviate from CLAUDE.md
+            - For Rust-specific issues, suggest idiomatic alternatives
+            - Check that new features have corresponding tests
+
+            EXAMPLE COMMENT FORMAT:
+            ```
+            **[Bug]** Potential panic on empty vector
+
+            **File**: `crates/shared/src/foo.rs:42`
+
+            **Problem**: `quotes.first().unwrap()` will panic if quotes is empty
+
+            **Fix**:
+            ```rust
+            let quote = quotes.first().ok_or(Error::NoQuotes)?;
+            ```
+
+            **Why**: Graceful error handling instead of panic
+            ```
+
+            Start by fetching the PR diff and analyzing it systematically.
+
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --allowedTools Read,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr edit:*),Bash(gh pr comment:*)
@@ -0,0 +1,97 @@
+name: Claude Code Assistant
+
+# Triggers when @claude is mentioned in comments, issues, or PR reviews
+# Provides code analysis, answers questions, and helps with debugging
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+  actions: read
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude Code Assistant
+        uses: anthropics/claude-code-action@v1
+        env:
+          GH_TOKEN: ${{ github.token }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          additional_permissions: |
+            actions: read
+
+          prompt: |
+            You are a helpful code assistant for the CoW Protocol services codebase.
+
+            CONTEXT:
+            - Repository: ${{ github.repository }}
+            - Event: ${{ github.event_name }}
+            - Triggered by: @claude mention
+
+            YOUR TASK:
+            Respond to the user's request mentioned in their comment/issue. The user tagged you with @claude followed by their question or request.
+
+            CAPABILITIES:
+            1. **Code Analysis**: Examine code, explain logic, identify patterns
+            2. **Bug Investigation**: Help debug issues, suggest fixes
+            3. **Architecture Questions**: Explain system design, data flow, component interactions
+            4. **Best Practices**: Suggest Rust idioms, performance improvements
+            5. **Documentation**: Explain how things work based on CLAUDE.md and codebase
+
+            GUIDELINES:
+            - DO NOT modify PR/issue descriptions unless explicitly asked
+            - DO post comments with your analysis/answers
+            - Use CLAUDE.md for project conventions
+            - Reference specific files and line numbers when relevant (e.g., `path/to/file.rs:42`)
+            - For PRs: Can use `gh pr diff` to examine changes
+            - For issues: Can use `gh issue view` to get context
+            - Be concise but thorough
+            - Focus on being helpful and accurate
+
+            RESPONSE FORMAT:
+            Post your response as a comment using:
+            ```bash
+            gh pr comment <number> --body "your response"
+            # OR
+            gh issue comment <number> --body "your response"
+            ```
+
+            IMPORTANT RULES:
+            - DO NOT change any repository files
+            - DO NOT update PR/issue descriptions
+            - DO provide clear, actionable answers
+            - DO reference codebase patterns and conventions
+            - DO use code blocks for examples
+
+            Start by identifying what the user is asking for and respond appropriately.
+
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --allowedTools Read,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr comment:*),Bash(gh issue view:*),Bash(gh issue comment:*),Bash(gh run view:*)
+
@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- Use `cargo nextest run` instead of `cargo test` (CI uses nextest and handles global state differently)
+- Run specific test suites:
+  - Unit tests: `cargo nextest run`
+  - Database tests: `cargo nextest run postgres -p orderbook -p database -p autopilot --test-threads 1 --run-ignored ignored-only`
+  - E2E local tests: `cargo nextest run -p e2e local_node --test-threads 1 --failure-output final --run-ignored ignored-only`
+  - E2E forked tests: `cargo nextest run -p e2e forked_node --test-threads 1 --run-ignored ignored-only --failure-output final`
+  - Driver tests: `RUST_MIN_STACK=3145728 cargo nextest run -p driver --test-threads 1 --run-ignored ignored-only`
+
+### Linting and Formatting
+- Format: `cargo +nightly fmt --all`
+- Lint: `cargo clippy --locked --workspace --all-features --all-targets -- -D warnings`
+- Check format: `cargo +nightly fmt --all -- --check`
+
+### Local Development Environment
+- Start local PostgreSQL: `docker-compose up`
+- Full playground environment: `docker compose -f playground/docker-compose.fork.yml up -d`
+- For forked network tests, set environment variables: `FORK_MAINNET_URL` and `FORK_GNOSIS_URL`
+- Reset playground: `docker-compose -f playground/docker-compose.fork.yml down --remove-orphans --volumes`
+
+## Architecture Overview
+
+### Core Services
+- **orderbook** - HTTP API for order management, user interactions, and solver queries. Uses PostgreSQL backend. Multiple instances can run concurrently for horizontal scaling.
+- **autopilot** - Protocol driver responsible for auction creation, order inclusion decisions, and settlement competition management. Single instance per deployment.
+- **driver** - In-development replacement for `solver` with improved design for co-location with external solvers.
+- **solvers** - External solver implementations and solver-related functionality.
+
+### Key Library Crates
+- **database** - Shared PostgreSQL database layer and storage logic for orderbook and autopilot
+- **shared** - Common functionality between services including utilities, types, and business logic
+- **contracts** - Smart contract bindings (migrating from ethcontract to alloy). See `crates/contracts/src/alloy.rs` for alloy bindings, `crates/contracts/build.rs` for legacy ethcontract
+- **model** - Serialization models for the orderbook API
+- **ethrpc** - Extended Ethereum RPC client with batching layer (`crates/ethrpc/src/alloy/buffering.rs`)
+- **chain** - Blockchain interaction utilities
+- **number** - Numerical type extensions and conversions for 256-bit integers
+- **app-data** - Order metadata validation with 8KB default size limit
+- **alerter** - Monitors orderbook metrics for orders that should be solved but aren't
+- **testlib** - Shared helpers for writing unit and end-to-end tests
+- **observe** - Initialization and helper functions for logging and metrics
+
+### Testing Requirements
+- PostgreSQL tests require local database: Run `docker-compose up` first
+- Forked network tests require `anvil` (from Foundry) and RPC URLs
+- Use `--test-threads 1` for database and E2E tests to avoid conflicts
+- CI runs doc-tests, unit tests, DB tests, E2E tests (local and forked), and driver tests
+
+### Workspace Configuration
+- Rust Edition 2024
+- Uses workspace dependencies for consistency
+- Tokio-console support enabled (set `TOKIO_CONSOLE=true` to activate)
+- Runtime log filter changes via UNIX socket at `/tmp/log_filter_override_<program_name>_<pid>.sock`
+
+### Development Notes
+- Binaries support `--help` for comprehensive command documentation
+- OpenAPI documentation available for orderbook, driver, and solver APIs
+- Performance profiling available via tokio-console
+- Memory allocator: Uses mimalloc for performance
+
+### Playground Environment
+- Access full local development stack with CoW Swap UI at http://localhost:8000
+- CoW Explorer available at http://localhost:8001
+- Orderbook API at http://localhost:8080
+- Database admin (Adminer) at http://localhost:8082
+- Uses test mnemonic: "test test test test test test test test test test test junk"
+- First 10 accounts have 10000 ETH balance by default
+
+## Important Implementation Details
+
+### Contract Bindings Migration
+- **New pattern (alloy)**: Use `crates/contracts/src/alloy.rs` with the `bindings!` macro and `deployments!` macro
+- **Legacy pattern (ethcontract)**: `crates/contracts/build.rs` - being phased out
+- Follow existing style in `alloy.rs` when adding new contract bindings
+
+### Quote System
+- **Fast quotes**: Unverified, not stored, immediate expiration (for UI price display)
+- **Optimal quotes**: Verified per config, stored in DB, 60s expiration (standard) or 600s (onchain)
+- Quote verification modes: `Unverified`, `Prefer`, `EnforceWhenPossible`
+- App data size limit: 8KB default (configurable via `--app-data-size-limit`)
+- See `quote-competition-analysis.md` and `quote-verification-analysis.md` for details
+
+### RPC Client Architecture
+- Batching layer in `crates/ethrpc/src/alloy/buffering.rs` auto-batches individual calls
+- Request IDs: Random u32 converted to u64, then incremented per request
+- Uses Tower middleware layers: LabelingLayer, InstrumentationLayer, BatchCallLayer