ci: gas budget regression gate

[neyij]

Pull Request Description

📋 Basic Information

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🧪 Test addition/update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🔒 Security fix
• 🎨 UI/UX improvement
• 🚀 Deployment/Infrastructure change

Related Issues

Closes #824

Priority Level

• 🔴 Critical (blocking other development)
• 🟡 High (significant impact)
• 🟢 Medium (moderate impact)
• 🔵 Low (minor improvement)

---

📝 Detailed Description

What does this PR do?

This PR introduces a CI gas budget regression gate that automatically detects and fails builds when smart contract CPU or instruction usage regresses by more than 5% compared to the established baseline.

The change adds an automated GitHub Actions workflow together with a regression analysis script to ensure performance regressions are detected before code is merged.

Why is this change needed?

Gas efficiency directly impacts contract execution costs and overall protocol performance. Without automated regression detection, seemingly harmless changes can gradually increase execution costs over time.

This CI gate provides continuous performance monitoring and prevents significant gas regressions from reaching the main branch.

How was this tested?

• Executed the repository's full test suite.
• Verified the regression script correctly detects acceptable and unacceptable gas usage changes.
• Confirmed CI succeeds when regressions remain within the configured threshold.
• Confirmed CI fails when CPU or instruction budgets exceed the allowed 5% regression.

Alternative Solutions Considered

Alternative approaches included performing manual gas benchmarking during code review or using external benchmarking services. An automated CI gate was chosen because it provides consistent enforcement and immediate feedback for contributors.

---

🏗️ Smart Contract Specific

Contract Changes

• Core contract logic modified
• Oracle integration changes (Pyth/Reflector)
• New functions added
• Existing functions modified
• Storage structure changes
• Events added/modified
• Error handling improved
• Gas optimization
• Access control changes
• Admin functions modified
• Fee structure changes

Oracle Integration

• Pyth oracle integration affected
• Reflector oracle integration affected
• Oracle configuration changes
• Price feed handling modified
• Oracle fallback mechanisms
• Price validation logic

Market Resolution Logic

• Hybrid resolution algorithm changed
• Dispute mechanism modified
• Fee structure updated
• Voting mechanism changes
• Community weight calculation
• Oracle weight calculation

Security Considerations

• Access control reviewed
• Reentrancy protection
• Input validation
• Overflow/underflow protection
• Oracle manipulation protection

---

🧪 Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• All tests passing locally
• Manual testing completed
• Oracle integration tested
• Edge cases covered
• Error conditions tested
• Gas usage optimized
• Cross-contract interactions tested

Test Results

cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings

# All tests passed successfully.

Manual Testing Steps

1. Executed the gas regression script against the baseline.
2. Verified CI passes when gas usage remains within the 5% threshold.
3. Simulated a regression exceeding the threshold and confirmed the workflow fails.

---

📚 Documentation

Documentation Updates

• README updated
• Code comments added/updated
• API documentation updated
• Examples updated
• Deployment instructions updated
• Contributing guidelines updated
• Architecture documentation updated

Breaking Changes

Breaking Changes:

None.

Migration Guide:

No migration required.

---

🔍 Code Quality

Code Review Checklist

• Code follows Rust/Soroban best practices
• Self-review completed
• No unnecessary code duplication
• Error handling is appropriate
• Logging/monitoring added where needed
• Security considerations addressed
• Performance implications considered
• Code is readable and well-commented
• Variable names are descriptive
• Functions are focused and small

Performance Impact

• Gas Usage: Prevents unnoticed CPU/instruction budget regressions.
• Storage Impact: None.
• Computational Complexity: No runtime impact on deployed contracts; checks execute only during CI.

Security Review

• No obvious security vulnerabilities
• Access controls properly implemented
• Input validation in place
• Oracle data properly validated
• No sensitive data exposed

---

🚀 Deployment & Integration

Deployment Notes

• Network: N/A
• Contract Address: N/A
• Migration Required: No
• Special Instructions: Ensure GitHub Actions has permission to execute the new workflow.

Integration Points

• Frontend integration considered
• API changes documented
• Backward compatibility maintained
• Third-party integrations updated

---

📊 Impact Assessment

User Impact

• End Users: No direct user-facing changes.
• Developers: Automatic detection of gas regressions during pull requests.
• Admins: Improved confidence that performance budgets remain stable over time.

Business Impact

• Revenue: Helps reduce unnecessary execution costs.
• User Experience: Improves long-term contract efficiency and reliability.
• Technical Debt: Reduces performance regressions and strengthens CI quality gates.

---

✅ Final Checklist

Pre-Submission

• Code follows Rust/Soroban best practices
• All CI checks passing
• No breaking changes (or breaking changes are documented)
• Ready for review
• PR description is complete and accurate
• All required sections filled out
• Test results included
• Documentation updated

Review Readiness

• Self-review completed
• Code is clean and well-formatted
• Commit messages are clear and descriptive
• Branch is up to date with main
• No merge conflicts

---

📸 Screenshots (if applicable)

N/A

---

🔗 Additional Resources

• Design Document: N/A
• Technical Spec: Issue Add gas budget CI regression gate #824
• Related Discussion: GrantFox FWC26 campaign
• External Documentation: N/A

---

💬 Notes for Reviewers

Please pay special attention to:

• The 5% regression threshold implementation.
• Workflow behavior across different CI environments.
• Accuracy of CPU and instruction budget comparisons.

Questions for reviewers

• Is the current regression threshold appropriate for future contract growth?
• Should additional metrics (memory usage or ledger reads/writes) also be enforced in the CI gate?

---

Thank you for reviewing this contribution.

[drips-wave]

@neyij Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits