Order and wallet saga

Opinion money flow and trade flow form a coordinated saga, not one database transaction. Polyflight uses its separate native wallet lifecycle.

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

Opinion sell policy

Polynion Admin controls Allow Partial Share Sell separately for each operator. It defaults to disabled for existing and new operators; enabling or disabling requires explicit confirmation. Operators can inspect the current read-only value on the Dashboard overview or in GET /api/operator/auth/session at operator.allow_partial_share_sell.

When disabled, the client offers only a 100% sell of the selected outcome's holding (Yes or No), including fractional shares. It does not close the opposite outcome. Quotes, order submission, and the trade processor reject partial amounts with PARTIAL_SHARE_SELL_DISABLED. A changed holding or policy may invalidate an unexecuted request; refresh the position and quote rather than increasing the amount of an existing order.

Execution checks the current policy against the locked position before committing the trade. A committed sell's wallet credit and recovery continue with its immutable original amount, even if the policy is later disabled. Redemptions and first-party Credits trades are unaffected.

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 wallet logs 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 from the operator wallet ledger first
• a failed order/callback does not prove the wallet credit failed; inspect the original operation before paying anything
• if a wallet response echoes user, key, currency, or amount, those values must match the dispatched request; contradictory evidence is held as unknown, not treated as success

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
• do not replay after timeout until the operator wallet ledger confirms the original outcome
• treat manual_review as operational incident, not user-facing success

Evidence and resolution

Use Cash Flow Triage to inspect unresolved Opinion orders/redemptions, wallet attempts, redacted request/response evidence, and resolution history. It requires trades:read, redemptions:read, and balance_operations:read; Market PnL alone requires only the first two.

The operator supplies original ledger evidence through Operator Support. Only authorized Polynion administrators can record a completed/failed cash-outcome decision. Recording that decision does not send a debit, credit, or refund, and a failed-but-unpaid payout can remain outstanding debt.

Keep callback recovery separate: replaying an event repairs notification delivery only. It does not resolve unknown wallet cash or replace the immutable execution amount, FX, fee snapshot, or idempotency key.