[ANCHOR-1162] Add optimistic locking to prevent TOCTOU race in transaction processing

[JiahuiWho]

Description

• Add @Version optimistic locking to JdbcSepTransaction to prevent concurrent modifications from silently overwriting each other
• Add Flyway migration (V25) to backfill version column on all transaction tables
• Handle OptimisticLockingFailureException in RpcService and TransactionService with clear retry error messages, and retry logic in TransactionService and rpcService

tests

• Fix flaky Sep31PlatformApiTests due to race between event delivery and DB write
• Removed SEP-6 deposit with pending-external status (see comments)

Context

A bounty report identified a TOCTOU race condition: the RPC handler reads a transaction, validates in memory, then saves — with no concurrency control. Two concurrent requests can both pass validation against stale state, causing silent data corruption (e.g., double-refund). Optimistic locking makes the second concurrent save fail explicitly instead.

Testing

• New RpcServiceTest — verifies OptimisticLockingFailureException returns JSON-RPC error code -32603 with retry message
• New TransactionServiceTest — verifiesOptimisticLockingFailureException on save is caught and re-thrown as BadRequestException

[JiahuiWho]

This is no longer a valid test after implement optimistic lock since step 2 and step 3 are essentially competing with each other. The realistic way is

pending_user_transfer_start -> notify_offchain_funds_sent
pending external -> notify_offchain_funds_received


Which has already been covered by other test cases

[Copilot]

Pull request overview

Adds optimistic locking and retry/error-handling to prevent TOCTOU races during transaction updates, ensuring concurrent modifications are detected and surfaced as retryable failures instead of silently overwriting state.

Changes:

• Add @Version to JdbcSepTransaction and a Flyway migration (V25) to add a version column to SEP 6/24/31 transaction tables.
• Add optimistic-lock retry loops and retryable error messaging in RpcService and TransactionService.
• Add/adjust tests for optimistic locking handling and tweak reference server event processing to wait for transaction visibility.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
platform/src/main/java/org/stellar/anchor/platform/data/JdbcSepTransaction.java	Adds JPA @Version field to enable optimistic locking.
platform/src/main/resources/db/migration/V25__add_optimistic_lock_version.sql	Adds version column to transaction tables.
platform/src/main/java/org/stellar/anchor/platform/service/TransactionService.java	Retries PATCH transaction updates on optimistic-lock conflicts and maps failures to retryable errors.
platform/src/main/java/org/stellar/anchor/platform/service/RpcService.java	Retries RPC processing on optimistic-lock conflicts; clears persistence context between retries.
platform/src/test/kotlin/org/stellar/anchor/platform/service/TransactionServiceTest.kt	Adds unit test coverage for optimistic-lock failure mapping to BadRequestException.
platform/src/test/kotlin/org/stellar/anchor/platform/service/RpcServiceTest.kt	Adds unit test coverage for optimistic-lock failure mapping to JSON-RPC internal error with retry message.
kotlin-reference-server/src/main/kotlin/org/stellar/reference/event/processor/Sep31EventProcessor.kt	Adds retry/wait to reduce flakiness when events arrive before transaction is readable via API.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[philipliu]

I'd return a conflict error to the client instead of silently retrying. A optimistic lock failure means that the state has changed since the RPC call was made. That's not really a transient issue that should be retried automatically since the call can now be invalid. The client should reread the state if they observe this error and decide whether to retry.