feat: Deploy Soroban project TTL refresh operator script and runbook

[anuoluwaponiorimi]

Summary

This PR implements a comprehensive TTL (Time-To-Live) refresh operator script and operational runbook for the SplitNaira smart contract, enabling operators to maintain project storage and prevent data expiration.

Implementation Details

🔧 TTL Refresh Operator Script (scripts/refresh-project-ttl.mjs)

Key Features:

• Flexible Operation Modes: Single project, multiple projects, or bulk refresh
• Safety First: Dry-run mode for safe testing without transaction costs
• Robust Error Handling: Retry logic with exponential backoff for RPC failures
• Comprehensive Validation: Project existence checks and configuration validation
• Progress Tracking: Real-time progress reporting for bulk operations
• Environment Configuration: Configurable via environment variables

Usage Examples:

# Refresh a single project
npm run refresh:project-ttl -- --project-id "my_project"

# Refresh multiple projects
npm run refresh:project-ttl -- --project-id "proj1" --project-id "proj2"

# Dry run for all projects (safe testing)
npm run refresh:project-ttl -- --all --dry-run

📚 Operational Runbook (docs/runbooks/ttl-refresh-operations.md)

Comprehensive Coverage:

• TTL Background: Detailed explanation of Soroban TTL mechanics
• Operational Procedures: Step-by-step maintenance and emergency response
• Troubleshooting Guide: Common issues and resolution strategies
• Cost Analysis: Transaction fee estimation and optimization
• Security Guidelines: Best practices for safe operations
• Monitoring Recommendations: Proactive TTL management strategies

🔄 Contract Integration

The script leverages the existing refresh_project_storage function in the SplitNaira contract:

• Permissionless: Any account can call the function (safe by design)
• Automatic TTL Extension: Extends TTL for project data and collaborator claims
• Error Handling: Returns clear errors for non-existent projects
• Idempotent: Safe to call repeatedly

Testing

✅ Contract Tests: All 63 existing tests pass
✅ Script Validation: Help, argument parsing, and error handling verified
✅ Build Process: Contract compilation and type generation successful
✅ Integration: Script properly integrates with existing project structure

Configuration

Required Environment Variables:

• CONTRACT_ID: SplitNaira contract address
• OPERATOR_SECRET_KEY: Secret key for transaction signing

Optional Configuration:

• SOROBAN_RPC_URL: RPC endpoint (defaults to testnet)
• SOROBAN_NETWORK_PASSPHRASE: Network passphrase
• SIMULATOR_ACCOUNT: Account for simulation

Security Considerations

• No Privilege Escalation: Script only extends TTL, cannot modify project data
• Safe Operations: Dry-run mode prevents accidental mainnet operations
• Key Management: Environment-based secret key configuration
• Network Verification: Built-in network and contract validation

Operational Impact

Benefits:

• Data Preservation: Prevents important project data from expiring
• Operational Efficiency: Automated bulk operations with progress tracking
• Cost Optimization: Selective refresh and batch processing capabilities
• Risk Mitigation: Comprehensive error handling and recovery procedures

Cost Considerations:

• Single project: ~0.00001 XLM
• 100 projects: ~0.001 XLM
• 1000 projects: ~0.01 XLM

Future Enhancements

The runbook outlines potential improvements:

• Automated TTL monitoring dashboards
• Smart refresh scheduling based on activity patterns
• Integration with existing monitoring systems
• Enhanced reporting and analytics

Related Issues

Closes Split-Naira#363 - Deploy Soroban project TTL refresh operator script and runbook
Closes Split-Naira#357 - Related TTL management requirements
Closes Split-Naira#323 - Operational tooling improvements
Closes Split-Naira#324 - Documentation and runbook updates

Checklist

• Script implements all required functionality
• Comprehensive error handling and validation
• Detailed operational runbook with procedures
• Integration with existing project structure
• All existing tests pass
• Security considerations addressed
• Documentation updated (runbooks README)
• Package.json script added for easy access

---

Ready for Review: This implementation provides a production-ready TTL management solution with comprehensive documentation and operational procedures.