feat: Implement four core features (#499, #501, #502, #503)

[Machundii]

Summary

This pull request implements four core features for Sorokit, addressing storage management, transaction scheduling, compliance reporting, and privacy enhancements.

Implemented Features

1. Soroban Storage Expiration Tracking and Renewal Utilities (#502)

• calculateStorageRent(contractId) - Estimates renewal requirements and identifies entries approaching expiration
• renewContractStorage(contractId) - Builds renewal operations for contract storage
• Configurable warning thresholds to identify entries nearing expiration
• Auto-renewal can be explicitly enabled or disabled
• Structured error handling with recovery guidance
• Comprehensive test coverage for active, near-expiry, expired, and renewal-failure scenarios
• APIs exported through src/soroban/index.ts and src/index.ts

Key Files:

• src/soroban/storageExpiration.ts - Implementation
• src/soroban/storageExpiration.test.ts - Tests

2. Prioritized Transaction Queues and Scheduled Batch Submission (#501)

• TransactionQueue class supporting low, normal, high, and critical priorities
• Critical and high-priority transactions are processed ahead of lower priorities
• Configurable batch size and scheduling intervals
• Dependent transactions cannot execute before their prerequisites
• Failed submissions return to queue according to retry policy
• Duplicate transaction entries are prevented
• Queue state exposes pending, processing, completed, and failed items
• Comprehensive test coverage for priority ordering, batching, retries, dependencies, and cancellation
• Existing direct submission APIs remain unaffected
• APIs exported through src/transaction/index.ts and src/index.ts

Key Files:

• src/transaction/transactionQueue.ts - Implementation
• src/transaction/transactionQueue.test.ts - Tests

3. Account Activity Reporting and Compliance Analysis Utilities (#503)

• generateComplianceReport(account, framework) - Generates framework-specific compliance reports
• Normalizes account activity into consistent reporting structure
• Transaction categories: transfers, payments, swaps, contract-interactions
• Framework-specific rule sets: AML, KYC, SOX, Basic, and custom
• Reports include configurable date ranges and account metadata
• Unsupported or incomplete activity is reported explicitly
• exportComplianceReport() - Export reports as JSON or CSV
• Comprehensive test coverage for categorization, date filtering, framework selection, and incomplete data
• APIs exported through src/account/index.ts and src/index.ts

Key Files:

• src/account/complianceReporting.ts - Implementation
• src/account/complianceReporting.test.ts - Tests

4. Privacy-Preserving Transaction Pooling and Mixing (#499)

• TransactionMixingPool class for coordinated privacy-preserving batches
• Multiple participants can contribute transactions to a single pool
• Eligible transactions are shuffled before batch construction
• Pool state prevents duplicate or already-submitted transactions
• Privacy and execution costs are calculated before participation
• Failed or expired participants can be removed without corrupting the pool
• Participation remains explicitly opt-in (isolated from normal transaction builders)
• Comprehensive test coverage for pooling, shuffling, cancellation, failure, and empty-pool scenarios
• Existing non-mixed transaction flows remain unchanged
• APIs exported through src/transaction/index.ts and src/index.ts

Key Files:

• src/transaction/transactionMixing.ts - Implementation
• src/transaction/transactionMixing.test.ts - Tests

Changes

• 8 new implementation files
• 8 new comprehensive test files
• Updated index files to export new APIs
• All APIs follow Sorokit's SorokitResult<T> response pattern
• Structured error handling with recovery guidance
• Full TypeScript type safety

Testing

All implementations include comprehensive test coverage:

• ✅ Priority ordering and batching (transaction queues)
• ✅ Dependency tracking and resolution
• ✅ Retry policies and failure handling
• ✅ Privacy analysis and anonymity calculations
• ✅ Compliance categorization and reporting
• ✅ Storage expiration and renewal workflows
• ✅ Edge cases and error conditions

Related Issues

• Closes Implement Soroban storage expiration tracking and renewal utilities #502 - Implement Soroban storage expiration tracking and renewal utilities
• Closes Implement prioritized transaction queues and scheduled batch submission #501 - Implement prioritized transaction queues and scheduled batch submission
• Closes Implement account activity reporting and compliance analysis utilities #503 - Implement account activity reporting and compliance analysis utilities
• Closes Implement privacy-preserving transaction pooling and mixing #499 - Implement privacy-preserving transaction pooling and mixing

[drips-wave]

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

[Just-Bamford]

@Machundii your PR has merge conflicts. Please resolve the conflicts and update the PR when done. Thanks.