feat: claim migration QA improvements and local dev setup

[vutuanlinh2k2]

Summary

• Add configurable CORS origins to SP1 prover API via CORS_ALLOWED_ORIGINS env var for production deployments
• Add claim-relayer service for gasless claim submissions with rate limiting and input validation
• Add PRODUCTION-TEST-GUIDE.md with comprehensive end-to-end testing documentation
• Improve local dev setup for liquid staking with new scripts and enhanced deployment tooling

Changes

Claim Migration (packages/migration-claim/)

• SP1 Prover API: Configurable CORS origins via CORS_ALLOWED_ORIGINS env var
  • Supports comma-separated values (e.g., https://app.tangle.tools,https://staging.tangle.tools)
  • Falls back to allowing all origins if not set
• Claim Relayer (apps/claim-relayer/): Express.js service for gasless claims
  • Rate limiting (10 req/min per IP)
  • Full input validation (pubkey, merkle proof, zk proof, recipient)
  • Transaction simulation before submission
• Production Test Guide: Step-by-step documentation for end-to-end testing
• Deploy script enhancements: Local and production mode support with better output

Local Development

• New start-local-dev.sh script for liquid staking local environment
• New advance-rounds.sh script for testing reward distribution
• Enhanced LocalTestnet.s.sol deployment script
• Improved indexer handlers for liquid delegation

🤖 Generated with Claude Code

[drewstone]

@claude review

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

Code Review Complete

I've reviewed all the changes in this PR for claim migration QA improvements and local dev setup. Here's my comprehensive analysis:

✅ Overall Assessment

This PR significantly improves the production readiness and developer experience for the claim migration system. The changes are well-structured and address important security, deployment, and testing concerns.

📋 Review Feedback by Component

🔒 Security Analysis

SP1 Prover API CORS Implementation packages/migration-claim/sp1/prover-api/src/main.rs:168-183

• ✅ Good: Configurable CORS origins via environment variable
• ⚠️ Issue: When CORS_ALLOWED_ORIGINS is empty/not set, it falls back to allowing all origins (Any)
• 🔧 Recommendation: In production, this should fail safe and require explicit configuration:

let cors = match &cors_origins {
    Some(origins) if !origins.is_empty() => {
        // Current implementation
    }
    _ if env::var("SP1_PROVER") == Ok("network".to_string()) => {
        // Production mode should require explicit CORS configuration
        error!("CORS_ALLOWED_ORIGINS is required in network mode");
        std::process::exit(1);
    }
    _ => CorsLayer::new().allow_origin(Any) // Only allow for local testing
};

Claim Relayer Service apps/claim-relayer/src/index.ts

• ✅ Excellent: Comprehensive input validation (lines 167-227)
• ✅ Good: Rate limiting implementation (10 req/min per IP)
• ✅ Good: Transaction simulation before submission (line 267)
• ⚠️ Minor: Rate limiting by IP only - could be bypassed with proxies
• 🔧 Recommendation: Consider adding additional rate limiting by pubkey to prevent abuse:

const pubkeyRateLimit = new Map<string, { count: number; resetTime: number }>();
// Check both IP and pubkey rate limits

🏗️ Code Quality & Best Practices

SP1 Program Changes packages/migration-claim/sp1/program/src/main.rs:35-84

• ✅ Excellent: Clear security documentation and comments
• ✅ Good: Proper challenge wrapping to match substrate signing format
• ✅ Good: Derives public key from SS58 address (prevents spoofing)
• ✅ Good: Robust error handling with descriptive messages

Indexer Handler Updates indexer/src/handlers/liquidDelegation.ts:144-145

• ✅ Good: Added missing harvestedRewards field initialization
• ✅ Good: Proper integration with points/rewards system

📖 Documentation Quality

Production Test Guide packages/migration-claim/PRODUCTION-TEST-GUIDE.md

• ✅ Excellent: Comprehensive step-by-step guide
• ✅ Good: Clear prerequisite requirements and fund calculations
• ✅ Good: Network-specific instructions for Base Sepolia
• 🔧 Suggestion: Add troubleshooting section for common deployment issues

🛠️ Development Experience

Local Development Scripts

• ✅ Excellent: scripts/local-env/start-local-dev.sh provides complete environment setup
• ✅ Good: advance-rounds.sh enables time-dependent testing
• ✅ Good: Proper cleanup and error handling throughout
• ✅ Good: Clear logging and status reporting

Deployment Script Enhancements packages/migration-claim/scripts/deploy-tangle-migration.sh

• ✅ Good: Production vs local mode handling
• ✅ Good: Proper validation of required environment variables
• ⚠️ Minor: Script doesn't validate RPC network matches expected chain ID
• 🔧 Recommendation: Add chain ID verification:

EXPECTED_CHAIN_ID=$([ "$PRODUCTION" = true ] && echo "84532" || echo "31337")
ACTUAL_CHAIN_ID=$(cast chain-id --rpc-url "$RPC_URL")
if [ "$ACTUAL_CHAIN_ID" != "$EXPECTED_CHAIN_ID" ]; then
    echo "Error: RPC chain ID $ACTUAL_CHAIN_ID doesn't match expected $EXPECTED_CHAIN_ID"
    exit 1
fi

⚡ Performance Considerations

1. Claim Relayer: Uses in-memory maps for rate limiting - will reset on restart. For production, consider Redis for persistent rate limiting.

2. SP1 Prover: Proper use of spawn_blocking for CPU-intensive proof generation (line 241-244)

3. Indexer: Efficient event handling with proper entity caching

🚨 Potential Issues

Low Severity

1. CORS Fallback: Should fail-safe in production rather than allow all origins
2. Rate Limiting: Only by IP, easily bypassed with proxies
3. Chain ID Validation: Deployment script doesn't verify network matches expectations

No Critical Issues Found

• No security vulnerabilities detected
• No obvious bugs or logical errors
• Error handling is comprehensive throughout

📝 Final Recommendations

1. Implement fail-safe CORS for production environment
2. Add pubkey-based rate limiting to complement IP-based limiting
3. Add chain ID validation to deployment script
4. Consider persistent rate limiting for production relayer service
5. Add troubleshooting section to production guide

✅ Review Complete

This PR demonstrates excellent engineering practices with security-first design, comprehensive testing documentation, and significant improvements to developer experience. The code is production-ready with the minor enhancements noted above.

---

Review Checklist:

• Read and understand the overall PR scope
• Review CORS implementation in SP1 prover API
• Analyze claim-relayer service for security and best practices
• Check production test guide documentation
• Review local development setup improvements
• Examine Rust/SP1 program changes
• Review deployment script enhancements
• Check indexer handler updates
• Provide comprehensive feedback with specific recommendations
  |

[claude]

Claude finished @vutuanlinh2k2's task —— View job

---

PR Review Complete ✅

I've conducted a thorough review of this claim migration QA improvements and local dev setup PR. Here's my comprehensive analysis:

Overall Assessment

This PR significantly enhances the production readiness and developer experience for the claim migration system. The changes demonstrate excellent security awareness and engineering practices.

✅ Strengths

Security Implementations

SP1 Prover API CORS Enhancement (packages/migration-claim/sp1/prover-api/src/main.rs:183-186)

• Excellent: Now requires explicit CORS configuration in production mode
• Security improvement: Prevents accidental deployment with open CORS in production
• Fail-safe design: System exits if CORS_ALLOWED_ORIGINS is missing when SP1_PROVER=network

Claim Relayer Security (apps/claim-relayer/src/index.ts)

• Excellent: Comprehensive dual rate limiting (IP + pubkey)
• Strong: Full input validation including hex format checking (lines 183-244)
• Best practice: Transaction simulation before submission (line 292)
• Good: Chain ID verification on startup (lines 398-404)

SP1 Program Security (packages/migration-claim/sp1/program/src/main.rs:39-47)

• Excellent: Security-first design deriving pubkey from SS58 address (prevents spoofing)
• Well-documented: Clear security rationale in comments
• Correct: Proper substrate signing context matching

Code Quality

Production Documentation (packages/migration-claim/PRODUCTION-TEST-GUIDE.md)

• Excellent: Comprehensive step-by-step production testing guide
• Complete: Covers all prerequisites, tools, accounts, and funds needed
• Practical: Includes realistic fund estimates and troubleshooting context

Local Development Experience (scripts/local-env/start-local-dev.sh)

• Excellent: Complete environment setup automation
• Robust: Proper cleanup, error handling, and dependency checking
• Developer-friendly: Clear logging and progress reporting

Deployment Script Improvements (packages/migration-claim/scripts/deploy-tangle-migration.sh)

• Good: Production vs local mode handling with proper validation
• Clear: Better output formatting and error messages
• Reliable: RPC connection validation before deployment

⚠️ Minor Issues & Recommendations

1. Rate Limiting Enhancement Opportunity

Location: apps/claim-relayer/src/index.ts:31-32

The current dual rate limiting is good, but could be more robust:

// Consider persisting rate limits for production
const rateLimitMap = new Map<string, { count: number; resetTime: number }>();
const pubkeyRateLimitMap = new Map<string, { count: number; resetTime: number }>();

Recommendation: For production deployment, consider using Redis or similar persistent storage to maintain rate limits across service restarts.

2. Indexer Handler Enhancement

Location: indexer/src/handlers/liquidDelegation.ts:144-145

The addition of missing harvestedRewards field is good:

harvestedRewards: BigInt(0),
rewardsEarned: BigInt(0),

Note: This properly initializes the field but ensure downstream consumers handle the BigInt type correctly.

📋 Architecture Review

SP1 Integration

• Excellent: Proper use of NetworkMode::Mainnet for consistency
• Good: Comprehensive logging for debugging proof generation
• Secure: On-chain verification option with proper error handling

Claims System

• Well-designed: Clear separation between prover API and claim relayer
• Secure: Multiple validation layers (client, relayer, contract)
• User-friendly: Gasless claims with comprehensive error messages

Local Development

• Complete: Full stack setup with all necessary components
• Efficient: Docker integration for persistence layers
• Maintainable: Modular scripts for different use cases

🚨 No Critical Issues Found

All security-sensitive code has been properly implemented:

• ✅ Input validation is comprehensive
• ✅ Rate limiting is properly implemented
• ✅ Error handling is robust
• ✅ Security contexts are correctly applied

📝 Final Recommendations

1. Consider persistent rate limiting for production claim-relayer deployment
2. Monitor proof generation costs in production (PROVE token consumption)
3. Add health check monitoring for production services
4. Consider adding metrics collection for production observability

Review Checklist Complete:

• Read and understand the overall PR scope
• Analyze security-critical changes (CORS, claim-relayer)
• Review SP1 prover API modifications
• Examine claim-relayer service implementation
• Check local development setup improvements
• Review documentation updates
• Provide comprehensive feedback with specific recommendations

Verdict: This PR demonstrates excellent engineering practices with security-first design, comprehensive documentation, and significant developer experience improvements. The code is production-ready. ✅

---

[vutuanlinh2k2]

Created a checklist based on Claude's recommendation here