feat: implement single-shot transition guards and fix doc lints

[N-thnI]

Closes #593

---

Closes #708

---

Pull Request Template

📝 Description

🎯 Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Performance improvement
• Security enhancement
• Other (please describe):

🔧 Changes Made

Files Modified

New Files Added

Key Changes

🧪 Testing

• Unit tests pass
• Integration tests pass
• Manual testing completed
• No breaking changes introduced
• Cross-platform compatibility verified
• Edge cases tested

Test Coverage

📋 Contract-Specific Checks

• Soroban contract builds successfully
• WASM compilation works
• Gas usage optimized
• Security considerations reviewed
• Events properly emitted
• Contract functions tested
• Error handling implemented
• Access control verified

Contract Testing Details

📋 Review Checklist

• Code follows project style guidelines
• Documentation updated if needed
• No sensitive data exposed
• Error handling implemented
• Edge cases considered
• Code is self-documenting
• No hardcoded values
• Proper logging implemented

🔍 Code Quality

• Clippy warnings addressed
• Code formatting follows rustfmt standards
• No unused imports or variables
• Functions are properly documented
• Complex logic is commented

🚀 Performance & Security

• Gas optimization reviewed
• No potential security vulnerabilities
• Input validation implemented
• Access controls properly configured
• No sensitive information in logs

📚 Documentation

• README updated if needed
• Code comments added for complex logic
• API documentation updated
• Changelog updated (if applicable)

🔗 Related Issues

Closes #
Fixes #
Related to #

📋 Additional Notes

🧪 How to Test

📸 Screenshots (if applicable)

⚠️ Breaking Changes

🔄 Migration Steps (if applicable)

---

📋 Reviewer Checklist

Code Review

• Code is readable and well-structured
• Logic is correct and efficient
• Error handling is appropriate
• Security considerations addressed
• Performance impact assessed

Contract Review

• Contract logic is sound
• Gas usage is reasonable
• Events are properly emitted
• Access controls are correct
• Edge cases are handled

Documentation Review

• Code is self-documenting
• Comments explain complex logic
• README updates are clear
• API changes are documented

Testing Review

• Tests cover new functionality
• Tests are meaningful and pass
• Edge cases are tested
• Integration tests work correctly

#593

[drips-wave]

@N-thnI 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