graphprotocol · RembrandtK · Aug 13, 2025 · Aug 13, 2025 · Aug 14, 2025 · Aug 14, 2025
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -47,6 +47,9 @@ RUN npm install -g [email protected]
 # Install cloc for code analysis
 RUN npm install -g cloc
 
+# Install Claude Code
+RUN npm install -g @anthropic-ai/claude-code
+
 # Install Foundry for Anvil (as root for global installation)
 RUN curl -L https://foundry.paradigm.xyz | bash && \
     /root/.foundry/bin/foundryup && \

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -16,9 +16,12 @@
   },
   "postCreateCommand": ".devcontainer/project-setup.sh",
   "remoteUser": "vscode",
-  "workspaceFolder": "${localWorkspaceFolder}",
+  "workspaceFolder": "/work",
   "customizations": {
     "vscode": {
+      "settings": {
+        "terminal.integrated.cwd": "/work"
+      },
       "extensions": [
         "rust-lang.rust-analyzer",
         "tamasfe.even-better-toml",
@@ -35,7 +38,8 @@
         "streetsidesoftware.code-spell-checker",
         "Augment.vscode-augment",
         "NomicFoundation.hardhat-solidity",
-        "foundry-rs.foundry-vscode"
+        "foundry-rs.foundry-vscode",
+        "BlueGlassBlock.better-json5"
       ]
     }
   }

diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
@@ -3,6 +3,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+    user: vscode
+    working_dir: /work
     env_file:
       - /opt/configs/graphprotocol/contracts.env
     environment:
@@ -31,6 +33,8 @@ services:
       # Note: NPM, Foundry, and Solidity caches are intentionally not set
       # to avoid cross-branch contamination. Tools will use their default locations.
     volumes:
+      - ..:/work
+
       # Git repo root
       - /git:/git
 

diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml
@@ -47,4 +47,4 @@ jobs:
           files: ${{ steps.coverage_files.outputs.files }}
           flags: unittests
           name: graphprotocol-contracts
-          fail_ci_if_error: true
+          fail_ci_if_error: false
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -167,15 +167,6 @@ jobs:
             echo "sol_prettier_exit_code=0" >> $GITHUB_OUTPUT
           fi
 
-      - name: Lint Solidity files (Natspec Documentation)
-        id: lint_sol_natspec
-        continue-on-error: true
-        run: |
-          echo "Checking Solidity documentation with natspec-smells..."
-          # Run natspec-smells from root to check all configured packages
-          npx natspec-smells
-          echo "sol_natspec_exit_code=$?" >> $GITHUB_OUTPUT
-
       - name: Lint Markdown files (Markdownlint)
         id: lint_md_markdownlint
         continue-on-error: true
@@ -320,15 +311,6 @@ jobs:
             WARNINGS=$((WARNINGS+1))
           fi
 
-          # Solidity - Natspec Documentation
-          if [ "$SOL_NATSPEC_EXIT_CODE" = "1" ]; then
-            echo "::error::natspec-smells found documentation issues in Solidity files"
-            ERRORS=$((ERRORS+1))
-          elif [ "$SOL_NATSPEC_EXIT_CODE" != "0" ]; then
-            echo "::warning::natspec-smells found warnings in Solidity files"
-            WARNINGS=$((WARNINGS+1))
-          fi
-
           # Markdown - Markdownlint
           if [ "$MD_MARKDOWNLINT_EXIT_CODE" = "1" ]; then
             echo "::error::Markdownlint found errors in Markdown files"

diff --git a/.gitignore b/.gitignore
@@ -5,8 +5,7 @@ node.log
 
 # Dependency directories
 node_modules/
-forge-std/
-**/lib/forge-std/
+.pnpm-store/
 
 # Yarn
 .yarn/*
@@ -29,8 +28,12 @@ packages/*/.eslintcache
 # Build artifacts
 dist/
 build/
+typechain/
+typechain-types/
 types/
 deployments/hardhat/
+*.js.map
+*.d.ts.map
 
 # TypeScript incremental compilation cache
 **/tsconfig.tsbuildinfo
@@ -51,13 +54,12 @@ lcov.info
 hardhat-dependency-compiler/
 
 # Local test files
-addresses-local.json
+addresses-local*.json
 localNetwork.json
 arbitrum-addresses-local.json
 tx-*.log
 addresses-fork.json
 addresses-hardhat.json
-addresses-local-network.json
 
 # Keys
 .keystore
@@ -66,7 +68,6 @@ addresses-local-network.json
 cache_forge
 forge-artifacts/
 out/
-packages/issuance/lib/forge-std/
 
 # Graph client
 .graphclient

diff --git a/.markdownlint.json b/.markdownlint.json
@@ -1,9 +1,14 @@
 {
   "default": true,
+  "MD004": { "style": "dash" },
+  "MD007": { "indent": 2 },
   "MD013": false,
+  "MD022": false,
   "MD024": { "siblings_only": true },
-  "MD033": false,
   "MD029": { "style": "ordered" },
-  "MD007": { "indent": 2 },
-  "MD004": { "style": "dash" }
+  "MD031": false,
+  "MD032": false,
+  "MD033": false,
+  "MD040": false,
+  "MD047": false
 }
diff --git a/.markdownlintignore b/.markdownlintignore
@@ -0,0 +1,37 @@
+# Autogenerated GraphClient files (committed but should not be linted)
+**/.graphclient-extracted/
+**/.graphclient/
+
+# Dependencies (from .gitignore patterns)
+node_modules/
+lib/
+
+# Build outputs that might contain markdown
+**/build/
+**/dist/
+**/artifacts/
+**/typechain-types/
+**/types/
+**/cache/
+**/cached/
+cache
+typechain/
+bin/
+forge-artifacts/
+out/
+
+# Coverage and reports
+coverage/
+reports/
+coverage.json
+lcov.info
+.nyc_output/
+
+# Other generated files
+.eslintcache
+packages/*/.eslintcache
+deployments/hardhat/
+.graphclient
+**/chain-*/
+**/*-localhost/
+**/*-hardhat/
diff --git a/.prettierignore b/.prettierignore
@@ -5,7 +5,9 @@ yarn.lock
 
 # Dependencies (from .gitignore)
 node_modules/
-forge-std/
+
+# Third-party libraries in lib directories
+**/lib/
 
 # Build outputs (from .gitignore)
 **/build/
@@ -33,6 +35,7 @@ lcov.info
 packages/*/.eslintcache
 deployments/hardhat/
 .graphclient
+**/.graphclient-extracted/
 **/chain-31337/
 **/chain-1377/
 **/horizon-localhost/

diff --git a/README.md b/README.md
@@ -35,13 +35,13 @@ This repository is a pnpm workspaces monorepo containing the following packages:
 
 | Package                                             | Latest version                                                                                                                                   | Description                                                                                       |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| [common](./packages/common)                         | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fcommon.svg)](https://badge.fury.io/js/@graphprotocol%2Fcommon)                         | Common utilities and configuration for Graph Protocol packages                                    |
 | [contracts](./packages/contracts)                   | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fcontracts.svg)](https://badge.fury.io/js/@graphprotocol%2Fcontracts)                   | Contracts enabling the open and permissionless decentralized network known as The Graph protocol. |
+| [data-edge](./packages/data-edge)                   | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fdata-edge.svg)](https://badge.fury.io/js/@graphprotocol%2Fdata-edge)                   | Data edge testing and utilities for The Graph protocol                                            |
 | [horizon](./packages/horizon)                       | -                                                                                                                                                | Contracts for Graph Horizon, the next iteration of The Graph protocol.                            |
-| [token-distribution](./packages/token-distribution) | [![npm version](https://badge.fury.io/js/@graphprotocol%2Ftoken-distribution.svg)](https://badge.fury.io/js/@graphprotocol%2Ftoken-distribution) | Contracts managing token locks for network participants                                           |
-| [sdk](./packages/sdk)                               | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fsdk.svg)](https://badge.fury.io/js/@graphprotocol%2Fsdk)                               | TypeScript based SDK to interact with the protocol contracts                                      |
 | [issuance](./packages/issuance)                     | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fissuance.svg)](https://badge.fury.io/js/@graphprotocol%2Fissuance)                     | Smart contracts for The Graph's token issuance functionality                                      |
-| [data-edge](./packages/data-edge)                   | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fdata-edge.svg)](https://badge.fury.io/js/@graphprotocol%2Fdata-edge)                   | Data edge testing and utilities for The Graph protocol                                            |
-| [common](./packages/common)                         | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fcommon.svg)](https://badge.fury.io/js/@graphprotocol%2Fcommon)                         | Common utilities and configuration for Graph Protocol packages                                    |
+| [sdk](./packages/sdk)                               | [![npm version](https://badge.fury.io/js/@graphprotocol%2Fsdk.svg)](https://badge.fury.io/js/@graphprotocol%2Fsdk)                               | TypeScript based SDK to interact with the protocol contracts                                      |
+| [token-distribution](./packages/token-distribution) | [![npm version](https://badge.fury.io/js/@graphprotocol%2Ftoken-distribution.svg)](https://badge.fury.io/js/@graphprotocol%2Ftoken-distribution) | Contracts managing token locks for network participants                                           |
 
 ## Development
 
@@ -117,6 +117,161 @@ pnpm publish --recursive
 
 Alternatively, there is a GitHub action that can be manually triggered to publish a package.
 
+## Linting Configuration
+
+This monorepo uses a comprehensive linting setup with multiple tools to ensure code quality and consistency across all packages.
+
+### Linting Tools Overview
+
+- **ESLint**: JavaScript/TypeScript code quality and style enforcement
+- **Prettier**: Code formatting for JavaScript, TypeScript, JSON, Markdown, YAML, and Solidity
+- **Solhint**: Solidity-specific linting for smart contracts
+- **Markdownlint**: Markdown formatting and style consistency
+- **YAML Lint**: YAML file validation and formatting
+- **NatSpec Smells**: Documentation quality checks for Solidity contracts
+
+### Configuration Architecture
+
+The linting configuration follows a hierarchical structure where packages inherit from root-level configurations:
+
+#### ESLint Configuration
+
+- **Root Configuration**: `eslint.config.mjs` - Modern flat config format
+- **Direct Command**: `npx eslint '**/*.{js,ts,cjs,mjs,jsx,tsx}' --fix`
+- **Behavior**: ESLint automatically searches up parent directories to find configuration files
+- **Package Inheritance**: Packages automatically inherit the root ESLint configuration without needing local config files
+- **Global Ignores**: Configured to exclude autogenerated files (`.graphclient-extracted/`, `lib/`) and build outputs
+
+#### Prettier Configuration
+
+- **Root Configuration**: `prettier.config.cjs` - Base formatting rules for all file types
+- **Direct Command**: `npx prettier -w --cache '**/*.{js,ts,cjs,mjs,jsx,tsx,json,md,sol,yml,yaml}'`
+- **Package Inheritance**: Packages that need Prettier must have a `prettier.config.cjs` file that inherits from the shared config
+- **Example Package Config**:
+
+  ```javascript
+  const baseConfig = require('../../prettier.config.cjs')
+  module.exports = { ...baseConfig }
+  ```
+
+- **Ignore Files**: `.prettierignore` excludes lock files, build outputs, and third-party dependencies
+
+#### Solidity Linting (Solhint)
+
+- **Root Configuration**: `.solhint.json` - Base Solidity linting rules extending `solhint:recommended`
+- **Direct Command**: `npx solhint 'contracts/**/*.sol'` (add `--fix` for auto-fixing)
+- **List Applied Rules**: `npx solhint list-rules`
+- **TODO Comment Checking**: `scripts/check-todos.sh` - Blocks commits and linting if TODO/FIXME/XXX/HACK comments are found in changed Solidity files
+- **Package Inheritance**: Packages can extend the root config with package-specific rules
+- **Configuration Inheritance Limitation**: Solhint has a limitation where nested `extends` don't work properly. When a local config extends a parent config that itself extends `solhint:recommended`, the built-in ruleset is ignored.
+- **Recommended Package Extension Pattern**:
+
+  ```json
+  {
+    "extends": ["solhint:recommended", "./../../.solhint.json"],
+    "rules": {
+      "no-console": "off",
+      "import-path-check": "off"
+    }
+  }
+  ```
+
+#### Markdown Linting (Markdownlint)
+
+- **Root Configuration**: `.markdownlint.json` - Markdown formatting and style rules
+- **Direct Command**: `npx markdownlint '**/*.md' --fix`
+- **Ignore Files**: `.markdownlintignore` automatically picked up by markdownlint CLI
+- **Global Application**: Applied to all markdown files across the monorepo
+
+### Linting Scripts
+
+#### Root Level Scripts
+
+```bash
+# Run all linting tools
+pnpm lint
+
+# Individual linting commands
+pnpm lint:ts      # ESLint + Prettier for TypeScript/JavaScript
+pnpm lint:sol     # TODO check + Solhint + Prettier for Solidity (runs recursively)
+pnpm lint:md      # Markdownlint + Prettier for Markdown
+pnpm lint:json    # Prettier for JSON files
+pnpm lint:yaml    # YAML linting + Prettier
+
+# Lint only staged files (useful for manual pre-commit checks)
+pnpm lint:staged  # Run linting on git-staged files only
+```
+
+#### Package Level Scripts
+
+Each package can define its own linting scripts that work with the inherited configurations:
+
+```bash
+# Example from packages/contracts
+pnpm lint:sol   # Solhint for contracts in this package only
+pnpm lint:ts    # ESLint for TypeScript files in this package
+```
+
+### Pre-commit Hooks (lint-staged)
+
+The repository uses `lint-staged` with Husky to run linting on staged files before commits:
+
+- **Automatic**: Runs automatically on `git commit` via Husky pre-commit hook
+- **Manual**: Run `pnpm lint:staged` to manually check staged files before committing
+- **Configuration**: Root `package.json` contains lint-staged configuration
+- **Custom Script**: `scripts/lint-staged-run.sh` filters out generated files that shouldn't be linted
+- **File Type Handling**:
+  - `.{js,ts,cjs,mjs,jsx,tsx}`: ESLint + Prettier
+  - `.sol`: TODO check + Solhint + Prettier
+  - `.md`: Markdownlint + Prettier
+  - `.json`: Prettier only
+  - `.{yml,yaml}`: YAML lint + Prettier
+
+**Usage**: `pnpm lint:staged` is particularly useful when you want to check what linting changes will be applied to your staged files before actually committing.
+
+### TODO Comment Enforcement
+
+The repository enforces TODO comment resolution to maintain code quality:
+
+- **Scope**: Applies only to Solidity (`.sol`) files
+- **Detection**: Finds TODO, FIXME, XXX, and HACK comments (case-insensitive)
+- **Triggers**:
+  - **Pre-commit**: Blocks commits if TODO comments exist in files being committed
+  - **Regular linting**: Flags TODO comments in locally changed, staged, or untracked Solidity files
+- **Script**: `scripts/check-todos.sh` (must be run from repository root)
+- **Bypass**: Use `git commit --no-verify` to bypass (not recommended for production)
+
+### Key Design Principles
+
+1. **Hierarchical Configuration**: Root configurations provide base rules, packages can extend as needed
+2. **Tool-Specific Inheritance**: ESLint searches up automatically, Prettier requires explicit inheritance
+3. **Generated File Exclusion**: Multiple layers of exclusion for autogenerated content
+4. **Consistent Formatting**: Prettier ensures consistent code formatting across all file types
+5. **Fail-Fast Linting**: Pre-commit hooks catch issues before they enter the repository
+
+### Configuration Files Reference
+
+| Tool         | Root Config           | Package Config                   | Ignore Files                 |
+| ------------ | --------------------- | -------------------------------- | ---------------------------- |
+| ESLint       | `eslint.config.mjs`   | Auto-inherited                   | Built into config            |
+| Prettier     | `prettier.config.cjs` | `prettier.config.cjs` (inherits) | `.prettierignore`            |
+| Solhint      | `.solhint.json`       | `.solhint.json` (array extends)  | N/A                          |
+| NatSpec      | No config required    | No config required               | N/A                          |
+| Markdownlint | `.markdownlint.json`  | Auto-inherited                   | `.markdownlintignore`        |
+| Lint-staged  | `package.json`        | N/A                              | `scripts/lint-staged-run.sh` |
+
+### Troubleshooting
+
+- **ESLint not finding config**: ESLint searches up parent directories automatically - no local config needed
+- **Prettier not working**: Packages need a `prettier.config.cjs` that inherits from root config
+- **Solhint missing rules**: If extending a parent config, use array format: `["solhint:recommended", "./../../.solhint.json"]` to ensure all rules are loaded
+- **Solhint inheritance not working**: Nested extends don't work - parent config's `solhint:recommended` won't be inherited with simple string extends
+- **Solhint rule reference**: Use `npx solhint list-rules` to see all available rules and their descriptions
+- **NatSpec linting failing**: Ensure package dependencies are properly declared in `package.json` and installed. The linting runs in each package's context and resolves imports through the package dependency system
+- **Generated files being linted**: Check ignore patterns in `.prettierignore`, `.markdownlintignore`, and ESLint config
+- **Preview lint changes before commit**: Use `pnpm lint:staged` to see what changes will be applied to staged files
+- **Commit blocked by linting**: Fix the linting issues or use `git commit --no-verify` to bypass (not recommended)
+
 ## Documentation
 
 > Coming soon