Issue 16: Two-Phase Commit Controller Handling On-Chain Execution Deficits

[elizabetheonoja-art]

File: /src/soroban/tx_state.rs

Category: Soroban / Transactions

Description: The TxStateController implements a two-phase commit pattern but has no actual compensation logic. When a Soroban contract call fails after the database state has been updated, there is no automatic rollback of the database changes. The current implementation merely sets status flags — it does not execute compensating transactions.

Parameters:

• Settlements per batch: up to 500 resource transfers
• DB rollback window: 30 seconds after failure
• Compensating transaction timeout: 60 seconds
• Consistency model: atomic (all-or-nothing)

Codebase Navigation:

1. src/soroban/tx_state.rs:28 — TwoPhaseCommit — has db_state_backup but never populated
2. src/soroban/tx_state.rs:45 — commit — no actual commit logic
3. src/soroban/tx_state.rs:56 — rollback — no compensating transaction

Resolution Blueprint:

1. Implement actual prepare phase: before executing a Soroban settlement, snapshot the relevant database rows (resource balances, deduction records) and store the snapshot in the db_state_backup field
2. Implement actual commit phase: after successful Soroban execution, mark the transaction as committed and delete the backup snapshot
3. Implement actual rollback phase: on failure, restore the database state from the backup snapshot and submit a compensating Soroban transaction (if the on-chain state was partially modified)
4. Add a background TxReaper task that periodically scans for transactions in Pending state for more than 30 seconds and automatically rolls them back
5. Expose GET /api/v1/soroban/transactions showing all transactions and their current state with timestamps

Acceptance Criteria:

• Database state atomically rolled back on Soroban failure
• Compensating Soroban transaction submitted within 60 seconds of failure
• Stale pending transactions auto-rolled back within 30 seconds
• Integration test validates prepare → fail → rollback cycle

[Penielka]

can i be assigned this to fix

[grantfox-oss]

🦊 GrantFox — @Penielka has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #16)
2. Your PR will be reviewed by the Utility-Protocol maintainers

Good luck! Track your progress on GrantFox.