feat(credits): add local development setup and fix entitlements script

[vutuanlinh2k2]

Summary

• Add local credits development tooling including setup script and documentation
• Update indexer config with local Credits contract address
• Fix GraphQL type mismatch in timeWindowedEntitlements (BigInt! → numeric!)
• Add tsx dependency for running TypeScript scripts

Test plan

• Run setup-local-credits.sh to verify local environment setup
• Execute timeWindowedEntitlements script to confirm GraphQL query works
• Verify indexer runs with updated local config

🤖 Generated with Claude Code

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

PR Review Complete ✅

Summary: This PR adds comprehensive local development tooling for the credits system, including a complete setup script and improved documentation. The changes are well-structured and address a real development need.

📝 Overall Assessment

Strengths:

• ✅ Comprehensive tooling: Complete end-to-end local development setup
• ✅ Good documentation: Detailed setup guide with troubleshooting
• ✅ Error handling: Robust error checking in shell script
• ✅ GraphQL fix: Correct type change from BigInt! to numeric!
• ✅ Clean dependency management: Appropriate tsx addition

Areas for attention:

• ⚠️ Security: Hardcoded private keys and addresses (acceptable for local dev)
• ⚠️ Complexity: Large shell script with many moving parts
• ⚠️ Dependencies: Docker and foundry requirements

🔍 Detailed Review

1. Code Quality & Best Practices

✅ setup-local-credits.sh (lines 1-716):

• Good error handling with set -euo pipefail
• Proper cleanup with trap handlers
• Clear function organization and logging
• Robust prerequisite checking

✅ timeWindowedEntitlements.ts (line 56):

• Correct fix changing BigInt! → numeric! for GraphQL compatibility
• Follows established patterns in the codebase

2. Security Considerations

✅ Acceptable for local development:

• Private keys are hardcoded Anvil test keys (lines 27, 32)
• Addresses are deterministic test accounts
• No production secrets exposed

3. Performance & Resource Usage

⚠️ Resource intensive setup:

• Starts multiple services: Anvil, PostgreSQL, Hasura, Indexer
• 30GB+ gas limit configuration (line 23)
• May consume significant system resources

✅ Efficient implementation:

• Proper pagination in GraphQL queries
• Cleanup handlers prevent resource leaks

4. Documentation Quality

✅ Excellent documentation (LOCAL_GUIDE.md):

• Clear step-by-step instructions
• Good troubleshooting section
• Proper prerequisite listing
• Real-world usage examples

5. Potential Issues

Minor concerns:

1. Package management complexity (lines 463-471):

   # Fix pnpm symlink issue - brittle workaround
   local PNPM_GENERATED
   PNPM_GENERATED=$(find node_modules/.pnpm -type d -name "generated@file*" 2>/dev/null | head -1)

2. Docker startup logic (lines 176-196):

   • macOS-specific Docker Desktop handling
   • May not work on all platforms

3. Time dependencies (lines 218-219):

   • Relies on wall-clock time calculations
   • Could be fragile in CI/test environments

6. Dependency Analysis

✅ tsx addition (package.json line 20):

• Legitimate need for TypeScript execution in scripts
• Widely used and maintained package
• Appropriate for development tooling

🎯 Recommendations

1. Consider adding validation for contract deployment success:

   # After contract deployment, verify they're functional
   cast call "$CREDITS_ADDRESS" "epochId()" --rpc-url "$RPC_URL" || exit 1

2. Environment variable documentation: Consider adding a .env.example file for the script

3. Cross-platform support: Add Linux alternatives for Docker startup logic

✅ Final Verdict

APPROVE - This is a well-implemented feature that significantly improves the local development experience. The code quality is high, security considerations are appropriate for development tooling, and the documentation is comprehensive.

The changes follow repository conventions and provide genuine value for developers working with the credits system.

---

[vutuanlinh2k2]

warnings here are not critical, can ignore them

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

PR Review Complete ✅

This PR adds comprehensive local development tooling for the credits system with excellent documentation and robust implementation. Here's my detailed analysis:

Todo List:

• Analyze the main setup script (setup-local-credits.sh)
• Review the documentation (LOCAL_GUIDE.md)
• Check package.json changes and dependency additions
• Examine the GraphQL type fix in timeWindowedEntitlements.ts
• Review indexer config changes
• Provide comprehensive review feedback and recommendations

---

📋 Overall Assessment

✅ APPROVE - This is a well-implemented feature that significantly improves the local development experience for the credits system.

Strengths:

• ✅ Comprehensive tooling: Complete end-to-end local development setup
• ✅ Excellent documentation: Clear step-by-step guide with troubleshooting
• ✅ Robust error handling: Proper cleanup, validation, and prerequisite checking
• ✅ Correct GraphQL fix: Proper type change from BigInt! to numeric!
• ✅ Clean dependency management: Appropriate tsx addition for TypeScript execution

---

🔍 Detailed Code Review

1. setup-local-credits.sh (716 lines)

Excellent implementation with strong practices:

✅ Error Handling & Safety:

• Proper set -euo pipefail configuration (line 2)
• Comprehensive cleanup with trap handlers (lines 143-154)
• Thorough prerequisite checking (lines 156-206)
• Input validation for private keys (lines 133-136)

✅ Well-Structured Code:

• Clear function organization and separation of concerns
• Informative logging throughout
• Proper argument parsing with usage documentation
• Good use of configuration variables

✅ Robust Implementation:

• Deterministic contract addresses through fresh Anvil start
• Docker startup handling with retry logic
• Indexer sync verification with timeout
• Multicall3 deployment with validation

Minor observations:

• Hardcoded private keys are acceptable for local development (ANVIL_KEY, test accounts)
• Complex pnpm symlink workaround (lines 463-471) may be brittle but necessary
• Docker Desktop auto-start logic is macOS-specific but gracefully handled

2. LOCAL_GUIDE.md (155 lines)

Outstanding documentation quality:

✅ Comprehensive Coverage:

• Clear step-by-step instructions from setup to verification
• Excellent troubleshooting section with common issues
• Real-world usage examples with actual commands
• Proper environment variable documentation

✅ User-Friendly:

• Well-organized sections with clear headings
• Prerequisites clearly listed upfront
• Multiple verification steps to confirm success
• Helpful port conflict resolution

3. Package Changes

✅ tsx Addition (package.json line 20):

• Legitimate need for reliable TypeScript execution in scripts
• Version 4.21.0 is current and well-maintained
• Properly added as devDependency, not production
• Used correctly in setup script for npx tsx runEpoch.ts (line 617)

✅ Package Lock Updates:

• Standard npm lock file updates for tsx and its dependencies
• No suspicious or unnecessary additions
• All changes align with the tsx package addition

4. GraphQL Type Fix (timeWindowedEntitlements.ts line 56)

✅ Correct Technical Fix:

// Changed from:
.map((k) => `$${k}: BigInt!`)
// To:
.map((k) => `$${k}: numeric!`)

• Addresses GraphQL schema compatibility issue
• numeric! is the correct PostgreSQL/Hasura type for bigint fields
• Follows established patterns in the codebase
• Simple, focused change without side effects

5. Indexer Config Update (config.local.yaml line 162)

✅ Proper Configuration:

• Updates Credits contract address from placeholder to actual deployed address
• Address 0x5081a39b8A5f0E35a8D959395a630b68B74Dd30f matches LocalTestnet deployment (nonce 2)
• Maintains consistency with other contract addresses in the config
• Clear commenting about local deployment requirement

---

🔒 Security Assessment

✅ Secure for Development Environment:

• Private keys are well-known Anvil test keys, not production secrets
• Contract addresses are deterministic local deployment addresses
• No sensitive information exposed or logged inappropriately
• Docker configurations use standard development credentials

---

⚡ Performance Considerations

Resource Usage:

• Setup requires significant resources: Anvil, PostgreSQL, Hasura, Indexer
• 30GB gas limit configuration (line 23) - appropriate for local development
• Proper cleanup ensures no resource leaks
• Background processes managed correctly with PID tracking

Efficiency:

• Proper pagination in GraphQL queries (default 1000 page size)
• Efficient state management in credits calculation
• Docker containers properly stopped and volumes cleaned between runs

---

🎯 Recommendations

Minor Enhancements:

1. Add contract deployment verification:

   # After deployment, verify contracts are functional
   cast call "$CREDITS_ADDRESS" "epochId()" --rpc-url "$RPC_URL" || exit 1

2. Consider .env.example file for better environment variable documentation

3. Cross-platform Docker handling: Add Linux alternatives to macOS-specific Docker startup logic

Documentation Improvements:

1. Consider adding a "Common Errors" section to LOCAL_GUIDE.md
2. Add estimated resource requirements (disk space, memory)

---

✅ Final Verdict

APPROVE - This PR provides significant value to developers working with the credits system. The implementation follows best practices, includes comprehensive documentation, and addresses a real development need.

Key Benefits:

• Dramatically simplifies local credits testing setup
• Reduces developer onboarding time
• Provides complete end-to-end verification flow
• Excellent error handling and user experience

The warnings noted in previous reviews are acceptable for development tooling and don't impact the overall quality of this contribution.

---