Swap Statuses

​

Don’t hardcode status strings

• phase — which leg of the lifecycle: deploy | swap | settle | done
• category — the integrator-facing meaning, independent of chain:
  • waiting — queued, will be picked up automatically
  • active — a transaction is in flight right now
  • retrying — the last attempt failed or was deferred; will retry after backoff
  • success — terminal, funds delivered
  • failed — terminal, gave up
• terminal — true once no further automatic transition will happen (completed or dead)

​

Status reference

​

Happy paths

EVM:     pending_deploy → deploying → pending_swap → swapping → completed
Solana:  pending_settle → settling → completed

​

The error field

{ "code": "NO_ROUTE", "message": "No route available for this pair right now.", "retryable": true }

• error is null on any non-failing state. A non-null error never means success — success is always status: "completed" with error: null.
• Branch on error.code (stable), not on message.
• error.retryable reflects whether the worker will try again. A dead item always reports retryable: false.

​

Retries & backoff

5s → 15s → 30s → 45s → 1m → 5m → 15m

​

Reacting to states

function onSwapUpdate(s: { status: string; terminal: boolean; category: string; error?: { code: string } | null }) {
  if (!s.terminal) return;            // still in progress
  if (s.status === "completed") {
    fulfilOrder();                    // success
  } else {
    // status === "dead"
    flagForReview(s.error?.code);     // permanent failure
  }
}

def on_swap_update(s: dict) -> None:
    if not s["terminal"]:
        return                        # still in progress
    if s["status"] == "completed":
        fulfil_order()                # success
    else:                             # "dead"
        flag_for_review((s.get("error") or {}).get("code"))