Skip to content

CLAUDE.md

Latest commit

 

History

History
126 lines (94 loc) · 3.6 KB

CLAUDE.md

File metadata and controls

126 lines (94 loc) · 3.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

polygon-cli is a Swiss Army knife of blockchain tools for building, testing, and running blockchain applications. It's a collection of utilities primarily focused on Polygon/Ethereum ecosystems.

Architecture Overview

The project follows a command-based architecture using Cobra framework:

  • Main Entry: main.go simply calls cmd.Execute()
  • Command Structure: Each command is organized in its own package under cmd/ (e.g., cmd/loadtest/, cmd/monitor/)
  • Bindings: Go bindings for smart contracts are in bindings/ (generated from Solidity contracts in contracts/)
  • Utilities: Common utilities are in util/ package

Key architectural patterns:

  • Commands are self-contained with their own usage documentation (.md files)
  • Heavy use of code generation for documentation, protobuf, contract bindings, and RPC types
  • Docker-based generation workflows to ensure consistency

Common Development Commands

Building and Installation

# Build the binary
make build

# Install to ~/go/bin/
make install

# Cross-compile for different platforms
make cross        # With CGO
make simplecross  # Without CGO

Testing

# Run all tests with coverage
make test

# Run specific test
go test -v ./cmd/loadtest/...

# Run load test against local node
make geth          # Start local geth node
make geth-loadtest # Fund account and run load test

Code Quality

# Run all linters (includes tidy, vet, golangci-lint)
make lint

# Individual linter commands
make tidy          # Clean up go.mod
make fmt           # Format code
make vet           # Run go vet and shadow
make golangci-lint # Run golangci-lint

Code Generation

# Generate everything (docs, proto, bindings, etc.)
make gen

# Individual generation commands
make gen-doc              # Generate CLI documentation
make gen-proto            # Generate protobuf stubs
make gen-go-bindings      # Generate contract bindings
make gen-load-test-modes  # Generate loadtest mode strings
make gen-json-rpc-types   # Generate JSON RPC types

Contract Development

# Work with smart contracts
cd contracts/
make build            # Build contracts with Foundry
make gen-go-bindings  # Generate Go bindings

Adding New Features

When adding a new command:

  1. Create a new package under cmd/your-command/
  2. Add the command to cmd/root.go in the NewPolycliCommand() function
  3. Create a usage documentation file (e.g., yourCommandUsage.md)
  4. Run make gen-doc to update the main documentation
  5. If adding a new loadtest mode, run make gen-load-test-modes after using stringer

CI/CD Considerations

The CI pipeline (/.github/workflows/ci.yml) runs:

  • Linting (golangci-lint, shadow)
  • Tests
  • Generation checks (ensures all generated files are up-to-date)
  • Load tests against both geth and anvil

Always run make gen before committing if you've changed anything that affects code generation.

Key Dependencies

  • Go 1.23+ required
  • Foundry (for smart contract compilation)
  • Docker (for generation tasks)
  • Additional tools: jq, bc, protoc (for development)

Environment Configuration

The tool supports configuration via:

  • CLI flags (highest priority)
  • Environment variables
  • Config file (~/.polygon-cli.yaml)
  • Viper is used for configuration management

Logging

  • Use zerolog for structured, performant logging throughout the project

Development Guidelines

  • Use conventional commit messages

Development Memories

  • Use make build to build polycli