Add per entrypoint gas snapshot for limits

[ekwe7]

closes #833

Description

This PR implements an automated, per-entrypoint gas snapshot infrastructure for our limit structures inside contracts/limits/. To enforce rigorous performance bounds for the GrantFox FWC26 campaign, this mechanism samples exact execution benchmarks (CPU instructions, ledger operations, and memory consumption) immediately upon entering and exiting contract workflows.

By tracking these profiles and exposing them directly within our integration testing framework, our CI/CD pipelines will now automatically fail if any code modification triggers a structural execution regression exceeding the strict >5% threshold.

Changes

⚡ Gas Monitoring & Snapshot Architecture (contracts/limits/)

• Per-Entrypoint Benchmarking: Injected resource profiling hooks at the boundary entries of all core functions to sample current environmental resource consumption metrics.
• Delta Computation Logs: Configured automated metrics calculation routines to parse raw usage deltas at transaction completion, exporting the processed footprint data into execution envelopes.
• Security Protocol Adherence:
  • Enforced explicit require_auth() checks across all modified state-mutating entrypoints to prevent unauthorized invocation profiling.
  • Upgraded all underlying accounting operations to use explicit overflow-safe math, avoiding unhandled panics inside resource tracing workflows.
  • Eradicated all unsafe .unwrap() invocations within the production path, standardizing on error-propagating return types.

🧪 Integration Testing Pipeline (contracts/limits/tests/gas_snap.rs)

• Automated Regression Matrix: Developed a dedicated testing framework that records snapshot variables to an external ledger path and asserts strict compliance checks against historical baseline files.
• 5% Tolerance Bounds: Programmed the test suite to throw an explicit failure if a code modification incurs a resource performance regression of greater than 5% over established metrics.

📝 Developer Reference Specifications

• NatSpec Documentation: Provided descriptive /// rustdoc block comments mapping performance configurations, tracking parameters, and architecture dependencies.

Verification & Execution Results

• Regression Trap Test: Verified that injecting a redundant storage read loop into a limit entrypoint instantly flags a performance regression, throwing a compilation block and failing the build.
• Workspace Verification Pass: Ran the integration test suites via cargo test and successfully verified statement coverage metrics far exceed the required >95% bar.

Checklist

• Per-entrypoint gas snapshots track CPU and memory metrics accurately.
• Every state-changing entrypoint explicitly executes authorization verification via require_auth().
• All mathematical expressions are built using overflow-safe structures without .unwrap() fallbacks.
• Test infrastructure inside gas_snap.rs automatically fails when execution footprints degrade by >5%.
• Total statements and code paths clear the 95% testing coverage threshold.
• Documentation adheres cleanly to the repository's NatSpec structural styles.

[drips-wave]

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

[greatest0fallt1me]

Merged into main via admin resolver (-X theirs).

[greatest0fallt1me]

Perfect. LGTM ✨ merging now.