bridge: Lack of Atomicity

[sameh-farouk]

Describe the bug

There's a critical section in handleRefundReady and handleWithdrawReady where the bridge submits a transaction to Stellar and then updates the TFChain state.
A crash between these two operations (or any failure to submit the TFChain transaction) could lead to a transaction being executed on Stellar but not marked as complete on TFChain, potentially causing it to be re-processed.

[sameh-farouk]

I was considering implementing a defensive check by filtering transactions on Horizon based on the memo field. The idea is to detect if a transaction with the same memo (which represents the enqueue ID of the burn operation on TFChain) has already been submitted via the bridge.

While this isn’t a foolproof solution, it would provide a much stronger safeguard than having no verification at all.

Unfortunately, it seems Horizon doesn’t provide a direct or performant way to filter transactions by memo. Still, it might be worth investigating further.

[sameh-farouk]

Here is a summary of the entire proposed flow for your bridge, designed to be robust against crashes and prevent double execution when sending funds to Stellar.

This system relies on three key components:

1. A Unique Identifier: The transaction id from the source chain (an TFChain burn transaction id), which we'll call BURN_TX_ID.
2. An Off-Chain Database: A fast key-value store like Redis(AOF mode), which acts as the daemon's internal DB.
3. An On-Chain Proof: The Memo field in the Stellar transaction, which provides an immutable link back to the source transaction.

---

A. The "Happy Path" Flow (No Crashes)

This is the standard process when everything works correctly.

1. Initiation (Source Chain): A user burns tokens on the source blockchain (TFChain). This action creates a unique BURN_TX_ID.
2. Detection (Daemon): Your bridge daemon detects this new burn event.
3. Mark as Processing (Database): Before sending any funds, the daemon immediately writes to its Redis database:
   • Key: BURN_TX_ID
   • Value: "PROCESSING"
4. Execute Payment (Stellar): The daemon builds and submits a payment transaction on the Stellar network.
   • The transaction's Memo field is critically set to the BURN_TX_ID.
5. Finalize (Database): Once the Stellar payment is confirmed, the daemon updates the record in Redis:
   • Key: BURN_TX_ID
   • Value: "COMPLETED"

B. The Crash Recovery Flow

This flow is triggered if the daemon crashes and restarts.

1. Restart and Re-Detect: The daemon starts up and re-detects the same burn event with BURN_TX_ID because it was never marked as fully complete in your primary source of truth.
2. Check Internal State (Database): The daemon queries its Redis database for the BURN_TX_ID. It does not assume this is a new transaction.
   • If the value is "COMPLETED", it ignores the event and moves on.
   • If the value is "PROCESSING", it means a crash occurred, and the state is uncertain. It proceeds to the next step.
3. Reconcile with On-Chain Truth (Stellar): To resolve the uncertainty, the daemon queries the Stellar Horizon API.
   • Query: "Get the recent transactions (how far back TBD) for the bridge's account."
   • Filter: The daemon loops through the results, looking for a transaction whose Memo matches the BURN_TX_ID from its database.
4. Decide and Resolve:
   • If a matching transaction is found: This is proof the payment was successful. The daemon can now safely update its database record to "COMPLETED" and prevent a double payment.
   • If no matching transaction is found: This is proof the payment failed or was never sent. The daemon can now safely re-attempt the Stellar payment (resuming at Step 4 of the Happy Path).

---

In short, the database acts as a high-speed cache for transaction state, while the on-chain check serves as the slower, but definitive, safety net used only when recovering from an uncertain state like a crash.