Order and wallet saga

Money flow and trade flow are coordinated saga, not one DB transaction.

Buy-side flow

1. user requests quote
2. OpenPoly computes quote with current FX and fees
3. user submits order
4. OpenPoly creates order record
5. OpenPoly debits operator wallet
6. if debit succeeds -> OpenPoly executes AMM trade
7. OpenPoly commits final order state
8. OpenPoly emits webhook event

Sell or redemption flow

1. OpenPoly computes credits-equivalent proceeds
2. OpenPoly computes external payout amount
3. OpenPoly settles internal state
4. OpenPoly credits operator wallet
5. OpenPoly emits success or failure webhook event

Common order statuses

• queued
• processing
• operator_debit_pending
• operator_debited
• operator_credit_pending
• processed
• failed
• compensation_pending
• compensated
• manual_review

Failure handling

Debit failed

• order -> failed
• no AMM trade
• failure webhook emitted

Debit unknown

• order -> manual_review
• no AMM trade until resolved
• operator lookup and human follow-up required

Credit failed or unknown

• payout-side record can move to manual_review
• do not blindly re-credit with new idempotency key
• confirm remote state through lookup first

Manual review rule

manual_review means automatic path stopped because final wallet state or business completion is not safe to assume.

Typical triggers:

• wallet result unknown
• compensation needed
• payout-side credit failed after internal state advanced

Compensation

If debit succeeded but downstream completion failed, OpenPoly may require reversal or compensation flow. That is why order lifecycle includes:

• compensation_pending
• compensated

Operator guidance

• track every mutation by idempotency_key
• use lookup endpoint before any retry after timeout
• treat manual_review as operational incident, not user-facing success