feat: Add gradient-based gas optimization profiling to Soroban contract CI pipeline

[rindicomfort]

Resolves #667

Summary of Changes

This Pull Request implements an automated, gradient-based gas optimization profiling and regression check pipeline for the Soroban smart contracts.

1. Contract Profiling Test Suite

• Added test_gas_benchmarks to contracts/tests/integration_soroban.rs.
• Leverages the Soroban SDK's testutils environment and e.cost_estimate().resources() to programmatically log resource footprints (CPU instructions, memory bytes, storage read/write counts, and write bytes) for all 20 contract functions.

2. Profiling & Regression Checking Script

• Created scripts/gas-benchmark.sh and scripts/analyze-gas.py to:
  • Run the benchmark suite via cargo test.
  • Maintain a baseline JSON snapshot (gas-benchmarks/baseline.json).
  • Calculate regressions against the baseline using a configurable threshold (default: 10%). Fails execution (exit code 1) if any function exceeds the threshold.
  • Record commit-by-commit historical performance trends in gas-benchmarks/trends.json.
  • Draw a dynamic visual trend SVG chart (gas-benchmarks/gas_trend.svg) graphing CPU instruction history for top functions.
  • Render a stratified text-based call tree for each function, detailing the exact CPU breakdown:
    • WASM Execution (bytecode logic)
    • Storage Reads (estimated resource costs for reading entries)
    • Storage Writes (estimated resource costs for writing entries + bytes written)
    • Host/Auth/Events (overhead of security checks and event emissions)

3. CI/CD Integration

• Configured a new GHA job rust-gas-benchmark in .github/workflows/ci.yml.
• Runs on every Pull Request to act as a quality gate (regression check).
• On pushes/merges to main, automatically regenerates the baseline snapshot and commits it back to the repository ([skip ci]).
• Integrates with the GitHub Actions Step Summary ($GITHUB_STEP_SUMMARY) to display formatting, status badges, the trend graph, and stratified call trees.
• Included the job in both the merge-protection and ci-success quality gates.

4. Developer Documentation

• Created a comprehensive user manual in gas-benchmarks/README.md explaining how to execute tests locally, change regression thresholds, add new function benchmarks, and interpret the resource allocation metrics.

[drips-wave]

@rindicomfort 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

[Smartdevs17]

⚠️ Merge failed — could not merge.

Possible reasons:

• CI checks not passing
• Branch protection rules
• Other merge requirements not met

---

🤖 Drips Wave Merge Agent