{"id":38543109,"url":"https://github.com/evmts/chop","last_synced_at":"2026-01-17T07:13:08.997Z","repository":{"id":319793891,"uuid":"1078502966","full_name":"evmts/chop","owner":"evmts","description":"The ultimate Evm SDK","archived":false,"fork":false,"pushed_at":"2025-12-21T09:02:57.000Z","size":1092,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-23T01:38:04.778Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evmts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T20:54:52.000Z","updated_at":"2025-12-21T09:03:01.000Z","dependencies_parsed_at":"2025-10-20T08:30:27.294Z","dependency_job_id":null,"html_url":"https://github.com/evmts/chop","commit_stats":null,"previous_names":["evmts/chop"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/evmts/chop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evmts%2Fchop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evmts%2Fchop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evmts%2Fchop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evmts%2Fchop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evmts","download_url":"https://codeload.github.com/evmts/chop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evmts%2Fchop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28503212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T07:13:08.225Z","updated_at":"2026-01-17T07:13:08.988Z","avatar_url":"https://github.com/evmts.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chop - Guillotine EVM CLI\n\n![CI](https://github.com/evmts/chop/workflows/CI/badge.svg)\n[![codecov](https://codecov.io/gh/evmts/chop/branch/main/graph/badge.svg)](https://codecov.io/gh/evmts/chop)\n[![Security](https://github.com/evmts/chop/workflows/Security/badge.svg)](https://github.com/evmts/chop/actions/workflows/security.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/evmts/chop)](https://goreportcard.com/report/github.com/evmts/chop)\n[![Release](https://img.shields.io/github/v/release/evmts/chop)](https://github.com/evmts/chop/releases)\n\nA hybrid Zig/Go project that uses the guillotine-mini EVM for Ethereum transaction processing with a Bubble Tea-based TUI.\n\n## Project Structure\n\n```\nchop/\n├── build.zig                        # Unified build system (orchestrates everything)\n├── src/                             # Zig source code\n│   ├── main.zig                     # Zig entry point\n│   └── root.zig                     # Zig module root\n├── main.go                          # Go application entry point\n├── internal/                        # Go source code\n│   ├── app/                         # Application logic\n│   │   ├── model.go                 # Bubble Tea model\n│   │   ├── init.go                  # Initialization logic\n│   │   ├── update.go                # Update function\n│   │   ├── view.go                  # View rendering\n│   │   ├── handlers.go              # Event handlers \u0026 navigation\n│   │   ├── parameters.go            # Call parameter management\n│   │   └── table_helpers.go         # Table update helpers\n│   ├── config/                      # Configuration \u0026 constants\n│   │   └── config.go                # App config, colors, keys\n│   ├── core/                        # Core business logic\n│   │   ├── logs.go                  # Log helpers\n│   │   ├── bytecode/                # Bytecode analysis (stubbed)\n│   │   │   └── bytecode.go\n│   │   ├── evm/                     # EVM execution (stubbed)\n│   │   │   └── evm.go\n│   │   ├── history/                 # Call history management\n│   │   │   └── history.go\n│   │   ├── state/                   # State persistence\n│   │   │   └── state.go\n│   │   └── utils/                   # Utility functions\n│   │       └── utils.go\n│   ├── types/                       # Type definitions\n│   │   └── types.go\n│   └── ui/                          # UI components \u0026 rendering\n│       └── ui.go\n├── lib/\n│   └── guillotine-mini/             # Git submodule - EVM implementation in Zig\n├── zig-out/                         # Build artifacts\n│   └── bin/\n│       ├── chop                     # Zig executable\n│       ├── chop-go                  # Go executable\n│       └── guillotine_mini.wasm     # EVM WASM library\n├── go.mod\n├── go.sum\n└── .gitmodules                      # Git submodule configuration\n```\n\n## Features\n\n### Current (Stubbed)\n\n- **Interactive TUI**: Full-featured Bubble Tea interface\n- **Call Parameter Configuration**: Configure EVM calls with validation\n- **Call History**: View past call executions\n- **Contract Management**: Track deployed contracts\n- **State Persistence**: Save and restore session state\n- **Bytecode Disassembly**: View disassembled contract bytecode (stubbed)\n\n### Application States\n\n1. **Main Menu**: Navigate between features\n2. **Call Parameter List**: Configure call parameters\n3. **Call Parameter Edit**: Edit individual parameters\n4. **Call Execution**: Execute EVM calls\n5. **Call Results**: View execution results\n6. **Call History**: Browse past executions\n7. **Contracts**: View deployed contracts\n8. **Contract Details**: Detailed contract view with disassembly\n\n### Keyboard Shortcuts\n\n- `↑/↓` or `k/j`: Navigate\n- `←/→` or `h/l`: Navigate blocks (in disassembly)\n- `Enter`: Select/Confirm\n- `Esc`: Back/Cancel\n- `e`: Execute call\n- `r`: Reset parameter\n- `R`: Reset all parameters\n- `c`: Copy to clipboard\n- `ctrl+v`: Paste from clipboard\n- `q` or `ctrl+c`: Quit\n\n## Prerequisites\n\n- **Zig**: 0.15.1 or later (for building from source)\n- **Go**: 1.21 or later (for building from source)\n- **Git**: For submodule management (for building from source)\n\n## Installation\n\n### Pre-built Binaries (Recommended)\n\nDownload pre-built binaries for your platform from the [GitHub Releases](https://github.com/evmts/chop/releases) page.\n\n#### macOS\n\n```bash\n# Intel Mac\ncurl -LO https://github.com/evmts/chop/releases/latest/download/chop_latest_darwin_amd64.tar.gz\ntar -xzf chop_latest_darwin_amd64.tar.gz\nchmod +x chop\nsudo mv chop /usr/local/bin/\n\n# Apple Silicon Mac\ncurl -LO https://github.com/evmts/chop/releases/latest/download/chop_latest_darwin_arm64.tar.gz\ntar -xzf chop_latest_darwin_arm64.tar.gz\nchmod +x chop\nsudo mv chop /usr/local/bin/\n```\n\n#### Linux\n\n```bash\n# AMD64\ncurl -LO https://github.com/evmts/chop/releases/latest/download/chop_latest_linux_amd64.tar.gz\ntar -xzf chop_latest_linux_amd64.tar.gz\nchmod +x chop\nsudo mv chop /usr/local/bin/\n\n# ARM64\ncurl -LO https://github.com/evmts/chop/releases/latest/download/chop_latest_linux_arm64.tar.gz\ntar -xzf chop_latest_linux_arm64.tar.gz\nchmod +x chop\nsudo mv chop /usr/local/bin/\n```\n\n#### Windows\n\nDownload the appropriate `.zip` file for your architecture from the [releases page](https://github.com/evmts/chop/releases), extract it, and add the executable to your PATH.\n\n### Building from Source\n\nIf you prefer to build from source, see the [Build System](#build-system) section below.\n\n## Setup\n\nInitialize the submodules:\n\n```bash\ngit submodule update --init --recursive\n```\n\n## Build System\n\nThe project uses Zig's build system as the primary orchestrator. All build commands go through `zig build`.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `zig build` | Build everything (default: stub EVM, WASM library) |\n| `zig build all` | Explicitly build everything |\n| `zig build go` | Build Go binary with stub EVM (CGo disabled) |\n| `zig build go-cgo` | **Build Go binary with real EVM (CGo enabled)** |\n| `zig build run` | Run the Go application (stub EVM) |\n| `zig build run-cgo` | **Run the Go application with real EVM** |\n| `zig build guillotine` | Build guillotine-mini WASM library |\n| `zig build guillotine-lib` | Build guillotine-mini native library for CGo |\n| `zig build test` | Run all tests |\n| `zig build go-test` | Run only Go tests |\n| `zig build clean` | Remove all build artifacts |\n\n### Quick Start\n\n#### Option 1: Stub EVM (Fast, No CGo)\n\n```bash\n# Build with stub EVM (no actual execution)\nzig build go\n\n# Run CLI (stub returns fake gas values)\n./zig-out/bin/chop-go call --bytecode 0x6001600101\n# Output: WARNING: CGo disabled - EVM execution stubbed\n```\n\n#### Option 2: Real EVM (CGo Enabled) ⭐ RECOMMENDED\n\n```bash\n# Build with real EVM execution\nzig build go-cgo\n\n# Run CLI with actual EVM\n./zig-out/bin/chop call --bytecode 0x6001600101\n# Output: ExecutionResult{Status: SUCCESS, GasUsed: 9, ...}\n\n# Or build and run directly\nzig build run-cgo -- call --bytecode 0x6000600055\n\n# Run tests\nzig build test\n```\n\n### CGo vs Stub Builds\n\nThe project supports two build modes:\n\n#### Stub Build (CGo Disabled)\n- **Command**: `zig build go`\n- **Output**: `zig-out/bin/chop-go`\n- **Pros**: Fast compilation, no C dependencies, portable\n- **Cons**: EVM execution is fake (returns mock values)\n- **Use for**: Development, testing UI/CLI without EVM\n\n#### CGo Build (Real EVM) ⭐\n- **Command**: `zig build go-cgo`\n- **Output**: `zig-out/bin/chop`\n- **Pros**: Actual EVM execution, real gas accounting, accurate results\n- **Cons**: Requires C compiler, longer build time (~10-20s)\n- **Use for**: Production, actual EVM testing, accurate gas measurements\n\n**Key Difference**: The CGo build links against the guillotine-mini native library (`libwasm.a`, `libblst.a`, `libc-kzg-4844.a`, `libbn254_wrapper.a`) and uses real Zig EVM implementation. The stub build has no external dependencies and returns fake execution results.\n\n## Components\n\n### Chop (Zig)\n\nThe Zig application component.\n\n**Source**: `src/`\n**Output**: `zig-out/bin/chop`\n\n### Chop Go (TUI Application)\n\nThe Go application with Bubble Tea TUI.\n\n**Source**: `internal/`, `main.go`\n**Output**: `zig-out/bin/chop-go`\n\n### Guillotine-mini\n\nThe EVM implementation, built as a WASM library.\n\n**Source**: `lib/guillotine-mini/` (submodule)\n**Output**: `lib/guillotine-mini/zig-out/bin/guillotine_mini.wasm`\n\n## Guillotine Integration Status\n\n### ✅ Completed\n\n1. **EVM Execution** (`evm/` package) - **WORKING**\n   - Full CGo bindings to guillotine-mini native library\n   - Real EVM execution with accurate gas accounting\n   - Support for all call types (CALL, STATICCALL, CREATE, etc.)\n   - Async execution with state injection\n   - Build system integration (`zig build go-cgo`)\n\n### 🚧 TODO\n\n1. **Bytecode Analysis** (`core/bytecode/bytecode.go`)\n   - Implement real EVM opcode disassembly\n   - Add control flow analysis\n   - Generate basic blocks\n\n2. **State Replay** (`core/state/state.go`)\n   - Implement state replay through VM\n\n3. **Clipboard Support** (`tui/ui.go`)\n   - Implement actual clipboard read/write operations\n\n4. **TUI Integration**\n   - Wire up TUI to use real EVM execution (currently uses stub)\n   - Update call results view to show real execution data\n\n## Development\n\nThe codebase is organized into clear layers:\n\n- **Presentation Layer**: `internal/ui/` and `internal/app/view.go`\n- **Application Layer**: `internal/app/` (handlers, navigation, state management)\n- **Domain Layer**: `internal/core/` (EVM, history, bytecode analysis)\n- **Infrastructure Layer**: `internal/core/state/` (persistence)\n\nAll EVM-related functionality is stubbed with clear TODO markers for easy integration with Guillotine.\n\n### Making Changes\n\n1. Edit your code in `src/` (Zig) or `internal/`, `main.go` (Go)\n2. Run `zig build` to rebuild\n3. Run `zig build test` to verify tests pass\n\n### Working with Guillotine-mini\n\nThe `guillotine-mini` submodule is a separate Zig project with its own build system.\n\n```bash\n# Build the WASM library through the main build system\nzig build guillotine\n\n# Or build it directly in the submodule\ncd lib/guillotine-mini\nzig build wasm\n```\n\nSee `lib/guillotine-mini/README.md` or `lib/guillotine-mini/CLAUDE.md` for detailed documentation on the EVM implementation.\n\n### Cleaning Build Artifacts\n\n```bash\nzig build clean\n```\n\nThis removes:\n- `zig-out/` (main project artifacts)\n- `zig-cache/` (Zig build cache)\n- `lib/guillotine-mini/zig-out/` (submodule artifacts)\n- `lib/guillotine-mini/zig-cache/` (submodule cache)\n\n## Go TUI Usage (Chop)\n\nBuild and run the Go TUI directly:\n\n```bash\nCGO_ENABLED=0 go build -o chop .\n./chop\n```\n\nTabs:\n- [1] Dashboard: Stats, recent blocks/txs (auto-refresh status shown)\n- [2] Accounts: Enter to view; 'p' to reveal private key\n- [3] Blocks: Enter to view block detail\n- [4] Transactions: Enter for transaction detail; in detail view press 'b' to open block\n- [5] Contracts: Enter to view details; 'c' copies address\n- [6] State Inspector: Type/paste address (ctrl+v), Enter to inspect\n- [7] Settings: 'r' reset blockchain, 'g' regenerate accounts (confirmation), 't' toggle auto-refresh\n\nGlobal:\n- Number keys 1–7 switch tabs; esc goes back; q or ctrl+c quits\n- 'c' in detail views copies the primary identifier (e.g., tx hash)\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all Go tests\ngo test ./...\n\n# Run tests with verbose output\ngo test ./... -v\n\n# Run tests with race detector (recommended for development)\ngo test ./... -race\n\n# Run tests with coverage report\ngo test ./... -cover\n\n# Generate detailed coverage report\ngo test ./... -coverprofile=coverage.txt -covermode=atomic\ngo tool cover -html=coverage.txt -o coverage.html\n```\n\n### Running Tests via Zig Build\n\n```bash\n# Run all tests (Zig and Go)\nzig build test\n\n# Run only Go tests\nzig build go-test\n```\n\n### Security Scanning\n\nThe project includes automated security scanning that runs on every push and pull request.\n\n#### Running Security Scans Locally\n\n```bash\n# Install gosec (security scanner)\ngo install github.com/securego/gosec/v2/cmd/gosec@latest\n\n# Run gosec security scan\ngosec ./...\n\n# Run gosec with detailed output\ngosec -fmt=json -out=results.json ./...\n\n# Install govulncheck (vulnerability scanner)\ngo install golang.org/x/vuln/cmd/govulncheck@latest\n\n# Run vulnerability check\ngovulncheck ./...\n```\n\n#### What Gets Scanned\n\n- **gosec**: Static security analysis checking for:\n  - Hardcoded credentials (G101)\n  - SQL injection vulnerabilities (G201-G202)\n  - File permission issues (G301-G304)\n  - Weak cryptography (G401-G404)\n  - Unsafe operations and more\n\n- **govulncheck**: Checks dependencies against the Go vulnerability database\n  - Scans both direct and indirect dependencies\n  - Reports known CVEs in your dependency tree\n\n- **Dependabot**: Automated dependency updates\n  - Weekly checks for Go module updates\n  - Weekly checks for GitHub Actions updates\n  - Automatic security patch PRs\n\nConfiguration files:\n- `.gosec.yml` - gosec scanner configuration\n- `.github/dependabot.yml` - Dependabot configuration\n- `.github/workflows/security.yml` - Security workflow\n\n### Code Quality and Linting\n\nThe project uses `golangci-lint` for comprehensive code quality checks and linting.\n\n#### Running Linters Locally\n\n```bash\n# Install golangci-lint (macOS)\nbrew install golangci-lint\n\n# Or install via go install\ngo install github.com/golangci/golangci-lint/cmd/golangci-lint@latest\n\n# Run all linters\ngolangci-lint run ./...\n\n# Run linters with timeout\ngolangci-lint run ./... --timeout=5m\n\n# Run linters and automatically fix issues (where possible)\ngolangci-lint run ./... --fix\n```\n\n#### Enabled Linters\n\nThe project uses `.golangci.yml` for configuration with the following categories of linters:\n\n**Code Correctness:**\n- `errcheck` - Check for unchecked errors\n- `govet` - Official Go static analyzer\n- `staticcheck` - Go static analysis\n- `typecheck` - Type-check Go code\n- `ineffassign` - Detect ineffectual assignments\n- `unused` - Check for unused code\n\n**Code Style:**\n- `gofmt` - Check code formatting\n- `goimports` - Check import formatting\n- `revive` - Fast, configurable linter\n- `gocritic` - Comprehensive Go source code linter\n\n**Code Quality:**\n- `gosimple` - Simplify code suggestions\n- `gocyclo` - Check cyclomatic complexity\n- `dupl` - Check for code duplication\n- `unconvert` - Remove unnecessary type conversions\n- `unparam` - Check for unused function parameters\n\n**Security:**\n- `gosec` - Inspect for security issues\n\n**Performance:**\n- `prealloc` - Find slice declarations that could be preallocated\n\n**Common Errors:**\n- `misspell` - Check for commonly misspelled words\n- `goconst` - Find repeated strings that could be constants\n- `nilerr` - Find code that returns nil incorrectly\n- `bodyclose` - Check HTTP response body is closed\n\n#### Current Linting Status\n\nAs of the last check, the codebase has approximately 89 linting issues across the following categories:\n- `gocritic` (34 issues) - Code style suggestions\n- `gofmt` (13 issues) - Formatting issues\n- `goimports` (11 issues) - Import organization\n- `gocyclo` (8 issues) - High cyclomatic complexity\n- `goconst` (7 issues) - Repeated strings\n- `gosec` (4 issues) - Security warnings\n- `errcheck` (4 issues) - Unchecked errors\n- `revive` (4 issues) - Style violations\n- Other minor issues (4 issues)\n\nMost issues are style-related and can be automatically fixed with `golangci-lint run --fix`. The linter is configured to be reasonable for existing code while maintaining good practices.\n\nConfiguration file: `.golangci.yml`\n\n### Continuous Integration\n\nAll pull requests and commits to `main` automatically run:\n- **Tests** on Go versions 1.22, 1.24 and platforms Ubuntu (Linux), macOS\n- **Linting** with golangci-lint for code quality checks\n- **Security scans** with gosec and govulncheck\n- **Dependency review** for known vulnerabilities\n- **Code coverage** reporting to Codecov\n\nYou can view the CI status in the [GitHub Actions](https://github.com/evmts/chop/actions) tab.\n\n## Why Zig Build?\n\nWe use Zig's build system as the orchestrator because:\n\n1. **Unified Interface**: Single command (`zig build`) for all components\n2. **Cross-Platform**: Works consistently across macOS, Linux, Windows\n3. **Dependency Management**: Properly tracks dependencies between components\n4. **Parallelization**: Automatically parallelizes independent build steps\n5. **Caching**: Only rebuilds what changed\n\n## Release Process (Maintainers)\n\nThe release process is fully automated using GitHub Actions and GoReleaser.\n\n### Creating a New Release\n\n1. **Ensure all changes are committed and pushed to `main`**\n   ```bash\n   git checkout main\n   git pull origin main\n   ```\n\n2. **Create and push a version tag** (following [Semantic Versioning](https://semver.org/))\n   ```bash\n   # For a new feature release\n   git tag -a v0.1.0 -m \"Release v0.1.0: Initial release with TUI\"\n\n   # For a bug fix release\n   git tag -a v0.1.1 -m \"Release v0.1.1: Fix state persistence bug\"\n\n   # For a major release with breaking changes\n   git tag -a v1.0.0 -m \"Release v1.0.0: First stable release\"\n\n   # Push the tag to trigger the release workflow\n   git push origin v0.1.0\n   ```\n\n3. **GitHub Actions will automatically**:\n   - Run all tests\n   - Build binaries for all platforms (Linux, macOS, Windows) and architectures (amd64, arm64)\n   - Generate checksums\n   - Create a GitHub Release with:\n     - Release notes from commit messages\n     - Downloadable binaries for all platforms\n     - Installation instructions\n\n4. **Monitor the release**:\n   - Visit the [Actions tab](https://github.com/evmts/chop/actions) to watch the release workflow\n   - Once complete, check the [Releases page](https://github.com/evmts/chop/releases)\n\n### Testing Releases Locally\n\nYou can test the release process locally without publishing:\n\n```bash\n# Install goreleaser (macOS)\nbrew install goreleaser\n\n# Or download from https://github.com/goreleaser/goreleaser/releases\n\n# Run goreleaser in snapshot mode (won't publish)\ngoreleaser release --snapshot --clean\n\n# Built artifacts will be in dist/\nls -la dist/\n```\n\n### Release Checklist\n\nBefore creating a release, ensure:\n- [ ] All tests pass: `go test ./...`\n- [ ] Code builds successfully: `CGO_ENABLED=0 go build -o chop .`\n- [ ] Documentation is up to date (README.md, DOCS.md)\n- [ ] CHANGELOG or commit messages clearly describe changes\n- [ ] Version follows [Semantic Versioning](https://semver.org/)\n- [ ] No breaking changes in minor/patch releases\n\n### Version Numbering Guide\n\n- **Major version (v1.0.0)**: Breaking changes, incompatible API changes\n- **Minor version (v0.1.0)**: New features, backwards-compatible\n- **Patch version (v0.0.1)**: Bug fixes, backwards-compatible\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevmts%2Fchop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevmts%2Fchop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevmts%2Fchop/lists"}