⚡ refactor: DocumentDB Compatibility for Balance Updates

[danny-avila]

Summary

I updated the Transaction model's balance update logic to handle race conditions during concurrent token refill transactions. I introduced an optimistic concurrency control mechanism with retries and exponential backoff to guard against conflicts, and I added a new test case simulating 25 simultaneous auto refill transactions to verify that the final balance remains accurate.

• Refactored the updateBalance function to first read the current balance and then calculate the new tokenCredits ensuring the balance never drops below zero.
• Implemented a retry loop with exponential backoff and jitter to resolve concurrency conflicts when multiple transactions occur.
• Added conditional upsert logic for DocumentDB compatibility and fixed potential duplicate key errors.
• Logged detailed error messages to assist in debugging concurrency issues.
• Created a new test case in spendTokens.spec.js that concurrently initiates 25 auto refill transactions, then verifies the expected final balance and validates that all transactions are recorded correctly.
• Adjusted existing high balance tests to simulate increased usage and ensure consistency across multiple concurrent operations.

Change Type:

• Bug fix (non-breaking change which fixes an issue)

Testing:

• Ran local unit tests and simulated 25 concurrent auto refill transactions to ensure the final balance reflects all increments.
• Verified that all transactions are created and the aggregate increments match the computed balance.
• Confirmed that no warnings or errors appear during test execution.

Checklist:

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective
• Local unit tests pass with my changes
• Any changes dependent on mine have been merged and published in downstream modules