SW4P Documentation
OpenAPIOpen app
Browse documentation
Intent Lifecycle

Intent Lifecycle

SW4P uses one shared intent model for routes that extend beyond the narrower helper corridor. An intent is submitted once, quoted once, and then moves through a solver auction and settlement lifecycle.

Lifecycle States

The backend state machine in sw4p-backend/src/intent.rs exposes these states:

StateMeaning
INTENT_SUBMITTEDIntent accepted before quote persistence is complete.
AUCTION_OPENSolver auction is open and the house filler baseline exists.
INTENT_QUOTINGA quote is being prepared or refreshed.
INTENT_QUOTEDA quote exists and can still be cancelled or escalated.
INTENT_FILLINGThe winning filler is executing the fill.
INTENT_FILLEDFill execution completed and settlement handoff is ready.
INTENT_SETTLINGThe settlement path is running.
INTENT_SETTLEDSettlement finished but final completion handling may still be in flight.
INTENT_COMPLETEDTerminal success.
INTENT_EXPIREDAuction or fill deadline expired.
INTENT_FAILEDTerminal failure.
INTENT_CANCELLEDUser-initiated cancellation before irreversible execution.

Canonical Flow

  1. Client calls submitIntent().
  2. Backend validates the request and persists the quoted intent.
  3. Route planning picks the baseline route description and fee model.
  4. If solver auctions are enabled, the backend opens an auction and transitions the intent to AUCTION_OPEN.
  5. The house filler baseline quote is published to the auction book.
  6. External solvers can connect to /sdk/v2/auctions/feed, authenticate, and receive auction events.
  7. External solvers can submit better quotes through the auction API.
  8. When the auction closes, the best quote wins. If no external quote beats the baseline, the house filler wins.
  9. The winning filler executes the fill and confirms it.
  10. Settlement completes and the intent reaches INTENT_COMPLETED, INTENT_FAILED, or INTENT_EXPIRED.

What Builders Should Poll

  • Use getIntentStatus() as the canonical status surface.
  • Treat state as the durable lifecycle field.
  • Use quote, fill_tx_hash, settlement_tx_hash, and output_amount as supporting evidence, not as substitutes for state transitions.

Cancellation Rules

Not every state is cancellable. The backend explicitly treats INTENT_SUBMITTED, AUCTION_OPEN, INTENT_QUOTING, and INTENT_QUOTED as cancellable states. Once the intent is filling or settling, cancellation is no longer a safe assumption.

Operator Note

Operator visibility for auctions lives in: