build: integrate pre-commit hooks with upstream files filtering support

.github/CODEOWNERS

@@ -9,4 +9,3 @@
 * @ava-labs/platform-evm
 /.github/ @maru-ava @ava-labs/platform-evm
 /triedb/firewood/ @alarso16 @ava-labs/platform-evm
-

.github/CONTRIBUTING.md

@@ -1,53 +1,56 @@
 # Contributing
 
-Thank you for considering to help out with the source code! We welcome 
-contributions from anyone on the internet, and are grateful for even the 
+Thank you for considering to help out with the source code! We welcome
+contributions from anyone on the internet, and are grateful for even the
 smallest of fixes!
 
-If you'd like to contribute to coreth, please fork, fix, commit and send a 
+If you'd like to contribute to coreth, please fork, fix, commit and send a
 pull request for the maintainers to review and merge into the main code base. If
-you wish to submit more complex changes though, please check up with the core 
-devs first on [Discord](https://chat.avalabs.org) to 
-ensure those changes are in line with the general philosophy of the project 
+you wish to submit more complex changes though, please check up with the core
+devs first on [Discord](https://chat.avalabs.org) to
+ensure those changes are in line with the general philosophy of the project
 and/or get some early feedback which can make both your efforts much lighter as
 well as our review and merge procedures quick and simple.
 
 ## Coding guidelines
 
 Please make sure your contributions adhere to our coding guidelines:
 
- * Code must adhere to the official Go 
-[formatting](https://go.dev/doc/effective_go#formatting) guidelines 
-(i.e. uses [gofmt](https://pkg.go.dev/cmd/gofmt)).
- * Code must be documented adhering to the official Go 
-[commentary](https://go.dev/doc/effective_go#commentary) guidelines.
- * Pull requests need to be based on and opened against the `master` branch.
- * Pull reuqests should include a detailed description
- * Commits are required to be signed. See [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
- for information on signing commits.
- * Commit messages should be prefixed with the package(s) they modify.
-   * E.g. "eth, rpc: make trace configs optional"
+- Code must adhere to the official Go
+  [formatting](https://go.dev/doc/effective_go#formatting) guidelines
+  (i.e. uses [gofmt](https://pkg.go.dev/cmd/gofmt)).
+- Code must be documented adhering to the official Go
+  [commentary](https://go.dev/doc/effective_go#commentary) guidelines.
+- Pull requests need to be based on and opened against the `master` branch.
+- Pull reuqests should include a detailed description
+- Commits are required to be signed. See [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
+  for information on signing commits.
+- Commit messages should be prefixed with the package(s) they modify.
+  - E.g. "eth, rpc: make trace configs optional"
 
 ## Can I have feature X
 
-Before you submit a feature request, please check and make sure that it isn't 
+Before you submit a feature request, please check and make sure that it isn't
 possible through some other means.
 
 ## Mocks
 
 Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/mockgen) and `//go:generate` commands in the code.
 
-* To **re-generate all mocks**, use the command below from the root of the project:
+- To **re-generate all mocks**, use the command below from the root of the project:
 
-    ```sh
-    go generate -run "go.uber.org/mock/mockgen" ./...
-    ```
+  ```sh
+  go generate -run "go.uber.org/mock/mockgen" ./...
+  ```
+
+- To **add** an interface that needs a corresponding mock generated:
+
+  - if the file `mocks_generate_test.go` exists in the package where the interface is located, either:
+
+    - modify its `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface (preferred); or
+    - add another `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface according to specific mock generation settings
 
-* To **add** an interface that needs a corresponding mock generated:
-  * if the file `mocks_generate_test.go` exists in the package where the interface is located, either:
-    * modify its `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface (preferred); or
-    * add another `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface according to specific mock generation settings
-  * if the file `mocks_generate_test.go` does not exist in the package where the interface is located, create it with content (adapt as needed):
+  - if the file `mocks_generate_test.go` does not exist in the package where the interface is located, create it with content (adapt as needed):
 
     ```go
     // Copyright (C) 2025-2025, Ava Labs, Inc. All rights reserved.
@@ -59,10 +62,13 @@ Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/moc
     ```
 
     Notes:
+
     1. Ideally generate all mocks to `mocks_test.go` for the package you need to use the mocks for and do not export mocks to other packages. This reduces package dependencies, reduces production code pollution and forces to have locally defined narrow interfaces.
     1. Prefer using reflect mode to generate mocks than source mode, unless you need a mock for an unexported interface, which should be rare.
-* To **remove** an interface from having a corresponding mock generated:
+
+- To **remove** an interface from having a corresponding mock generated:
+
   1. Edit the `mocks_generate_test.go` file in the directory where the interface is defined
   1. If the `//go:generate` mockgen command line:
-      * generates a mock file for multiple interfaces, remove your interface from the line
-      * generates a mock file only for the interface, remove the entire line. If the file is empty, remove `mocks_generate_test.go` as well.
+     - generates a mock file for multiple interfaces, remove your interface from the line
+     - generates a mock file only for the interface, remove the entire line. If the file is empty, remove `mocks_generate_test.go` as well.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,7 +4,6 @@ about: Create a report to help us improve
 title: ''
 labels: bug
 assignees: ''
-
 ---
 
 **Describe the bug**

.github/ISSUE_TEMPLATE/feature_request.md

@@ -4,7 +4,6 @@ about: Suggest an idea for this project
 title: ''
 labels: ''
 assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**

.pre-commit-config.yaml

@@ -0,0 +1,98 @@
+# Usage:
+#   1) Install the hooks:
+#     pre-commit install && pre-commit install --hook-type pre-push
+#   2) [Optional] Run the hooks on demand before committing:
+#     pre-commit run --all-files
+#   3) [Optional] Run the hooks on demand before pushing changes:
+#     pre-commit run --hook-stage pre-push --all-files
+#
+# NOTE: 2) and 3) are only needed to run the hooks manually.
+# The hooks are automatically run by git when committing or pushing changes.
+#
+# If you want to temporarily disable the hooks without uninstalling them, you can use:
+#   git commit --no-verify
+#   git push --no-verify
+#
+# If you want to uninstall the hooks, you can use:
+#   pre-commit uninstall
+#
+# If you want to re-install the hooks, you can run 1) again.
+
+minimum_pre_commit_version: "3.6.0"
+
+repos:
+  # Fast feedback at commit time: baseline golangci-lint (v1)
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v1.63.4
+    hooks:
+      - id: golangci-lint
+        name: golangci-lint (baseline)
+        args: ["--config=.golangci.yml"]
+        stages: [pre-commit]
+
+  # Local utility scripts and full repo checks
+  - repo: local
+    hooks:
+      # Stricter extra lints (golangci-lint v2) on staged changes at pre-commit
+      - id: extra-golangci-lint
+        name: golangci-lint (extra via scripts/lint.sh)
+        entry: scripts/lint.sh
+        language: system
+        stages: [pre-commit]
+        pass_filenames: false
+        env:
+          TESTS: "avalanche_golangci_lint"
+
+      - id: actionlint
+        name: actionlint
+        entry: scripts/actionlint.sh
+        language: system
+        files: ^\.github/workflows/.*\.(yml|yaml)$
+        stages: [pre-commit]
+        pass_filenames: false
+
+      - id: shellcheck
+        name: shellcheck
+        entry: scripts/shellcheck.sh
+        language: system
+        files: \.sh$
+        stages: [pre-commit]
+        pass_filenames: false
+
+  # General purpose housekeeping hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        name: trailing-whitespace (filtered)
+        entry: scripts/filter_precommit_files.sh trailing-whitespace-fixer --
+        pass_filenames: true
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+        name: end-of-file-fixer (filtered)
+        entry: scripts/filter_precommit_files.sh end-of-file-fixer --
+        pass_filenames: true
+      - id: check-merge-conflict
+      - id: check-yaml
+        name: check-yaml (filtered)
+        entry: scripts/filter_precommit_files.sh check-yaml --
+        pass_filenames: true
+      - id: check-toml
+        name: check-toml (filtered)
+        entry: scripts/filter_precommit_files.sh check-toml --
+        pass_filenames: true
+      - id: check-json
+        name: check-json (filtered)
+        entry: scripts/filter_precommit_files.sh check-json --
+        pass_filenames: true
+        # Exclude intentionally invalid JSON fixtures used by tests
+        exclude: ^rpc/testdata/invalid-.*\.json$
+
+  # Markdown formatter
+  - repo: https://github.com/hukkin/mdformat
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-gfm==0.4.1
+          - mdformat-frontmatter==2.0.8

README.md

@@ -31,11 +31,11 @@ test run, require binary dependencies. One way of making these dependencies avai
 to use a nix shell which will give access to the dependencies expected by the test
 tooling:
 
- - Install [nix](https://nixos.org/). The [determinate systems
-   installer](https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#install-nix)
-   is recommended.
- - Use `./scripts/dev_shell.sh` to start a nix shell
- - Execute the dependency-requiring command (e.g. `./scripts/tests.e2e.sh --start-collectors`)
+- Install [nix](https://nixos.org/). The [determinate systems
+  installer](https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#install-nix)
+  is recommended.
+- Use `./scripts/dev_shell.sh` to start a nix shell
+- Execute the dependency-requiring command (e.g. `./scripts/tests.e2e.sh --start-collectors`)
 
 This repo also defines a `.envrc` file to configure [devenv](https://direnv.net/). With
 `devenv` and `nix` installed, a shell at the root of the repo will automatically start a nix
@@ -50,7 +50,7 @@ The C-Chain supports the following API namespaces:
 - `txpool`
 - `debug`
 
-Only the `eth` namespace is enabled by default. 
+Only the `eth` namespace is enabled by default.
 To enable the other namespaces see the instructions for passing the C-Chain config to AvalancheGo [here.](https://docs.avax.network/nodes/configure/chain-config-flags#enabling-evm-apis)
 Full documentation for the C-Chain's API can be found [here.](https://docs.avax.network/reference/avalanchego/c-chain/api)
 
@@ -82,16 +82,52 @@ To support these changes, there have been a number of changes to the C-Chain blo
 
 ### Block Body
 
-* `Version`: provides version of the `ExtData` in the block. Currently, this field is always 0.
-* `ExtData`: extra data field within the block body to store atomic transaction bytes.
+- `Version`: provides version of the `ExtData` in the block. Currently, this field is always 0.
+- `ExtData`: extra data field within the block body to store atomic transaction bytes.
 
 ### Block Header
 
-* `ExtDataHash`: the hash of the bytes in the `ExtDataHash` field
-* `BaseFee`: Added by EIP-1559 to represent the base fee of the block (present in Ethereum as of EIP-1559)
-* `ExtDataGasUsed`: amount of gas consumed by the atomic transactions in the block
-* `BlockGasCost`: surcharge for producing a block faster than the target rate
+- `ExtDataHash`: the hash of the bytes in the `ExtDataHash` field
+- `BaseFee`: Added by EIP-1559 to represent the base fee of the block (present in Ethereum as of EIP-1559)
+- `ExtDataGasUsed`: amount of gas consumed by the atomic transactions in the block
+- `BlockGasCost`: surcharge for producing a block faster than the target rate
 
 ## Releasing
 
 See [docs/releasing/README.md](docs/releasing/README.md) for the release process.
+
+## Local pre-commit hooks
+
+We use [pre-commit](https://pre-commit.com/) to provide fast local feedback and consistent formatting/linting in CI.
+
+1. Install the `pre-commit` tool locally. For instructions check [here](https://pre-commit.com/).
+
+1. Install hooks locally (done only once):
+
+   ```bash
+   pre-commit install
+   ```
+
+1. Just use `git commit` and `git push` as normal and the hooks will automatically run.
+
+Additional notes:
+
+- Run manually on the whole repo:
+
+  ```bash
+  pre-commit run --all-files
+  ```
+
+- Temporarily bypass hooks:
+
+  ```bash
+  git commit --no-verify
+  git push --no-verify
+  ```
+
+- For macOS developers:
+
+  - Some local scripts require GNU grep with PCRE support. Install via Homebrew:
+    `brew install grep`. If needed, add `$(brew --prefix grep)/libexec/gnubin` to your PATH.
+  - Our lint runner (`scripts/lint.sh`) will attempt to auto-detect and use Homebrew’s GNU grep
+    and Bash 4+ where available.

RELEASES.md

@@ -30,11 +30,15 @@
 ## [v0.15.0](https://github.com/ava-labs/coreth/releases/tag/v0.15.0)
 
 - Bump golang version to v1.23.6
+
 - Bump golangci-lint to v1.63 and add linters
+
 - Implement ACP-176
+
 - Add `GasTarget` to the chain config to allow modifying the chain's `GasTarget` based on the ACP-176 rules
 
 - Added `eth_suggestPriceOptions` API to suggest gas prices (slow, normal, fast) based on the current network conditions
+
 - Added `"price-options-slow-fee-percentage"`, `"price-options-fast-fee-percentage"`, `"price-options-max-base-fee"`, and `"price-options-max-tip"` config flags to configure the new `eth_suggestPriceOptions` API
 
 ## [v0.14.1](https://github.com/ava-labs/coreth/releases/tag/v0.14.1)

SECURITY.md

@@ -17,4 +17,3 @@ Please refer to the [Bug Bounty Page](https://hackenproof.com/avalanche) for the
 ## Supported Versions
 
 Please use the [most recently released version](https://github.com/ava-labs/coreth/releases/latest) to perform testing and to validate security issues.
-

Taskfile.yml

@@ -118,4 +118,4 @@ tasks:
 
   update-avalanchego-version:
     desc: Update AvalancheGo version in go.mod and sync GitHub Actions workflow custom action version
-    cmd: bash -x ./scripts/update_avalanchego_version.sh # ci.yml 
+    cmd: bash -x ./scripts/update_avalanchego_version.sh # ci.yml

cmd/abigen/namefilter.go

@@ -9,7 +9,6 @@
 //
 // Much love to the original authors for their work.
 // **********
-
 package main
 
 import (

cmd/abigen/namefilter_test.go

@@ -9,7 +9,6 @@
 //
 // Much love to the original authors for their work.
 // **********
-
 package main
 
 import (

cmd/simulator/README.md

@@ -43,7 +43,7 @@ WARNING:
 The `--sybil-protection-enabled=false` flag is only suitable for local testing. Disabling staking serves two functions explicitly for testing purposes:
 
 1. Ignore stake weight on the P-Chain and count each connected peer as having a stake weight of 1
-2. Automatically opts in to validate every Subnet
+1. Automatically opts in to validate every Subnet
 
 Once you have AvalancheGo running locally, it will be running an HTTP Server on the default port `9650`. This means that the RPC Endpoint for the C-Chain will be http://127.0.0.1:9650/ext/bc/C/rpc and ws://127.0.0.1:9650/ext/bc/C/ws for WebSocket connections.
 

core/blockchain_ext.go

@@ -1,5 +1,6 @@
 // Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE for licensing terms.
+
 package core
 
 import "github.com/ava-labs/libevm/metrics"