[sdk]: add retry logic to execute gen and improve interface (#744)

Author: ddboy19912

docs/content/developers/intent-gateway/placing-orders.mdx

@@ -223,7 +223,7 @@ The generator is bidirectional — it pauses at two points to hand control back
 
 **Second yield** — `ORDER_PLACED`. After the transaction is confirmed, the generator yields `{ status: "ORDER_PLACED", order, receipt }` where `order` is the finalized `Order` (with `nonce`, `id`, and `inputs` populated from the `OrderPlaced` event) and `receipt` is the full viem `TransactionReceipt` of the placement transaction.
 
-**Subsequent yields** — status updates. The generator then yields `IntentOrderStatusUpdate` objects continuously until the order reaches a terminal state (`FILLED`, `FAILED`, `PARTIAL_FILL_EXHAUSTED`). Call `gen.next()` with no arguments to advance after each update.
+**Subsequent yields** — status updates. The generator then yields `IntentOrderStatusUpdate` objects continuously until the order reaches a terminal state (`FILLED`, `EXPIRED`). `FAILED` events are informational — the executor automatically retries by looping back to bid polling. Call `gen.next()` with no arguments to advance after each update.
 
 ```typescript lineNumbers title="execute.ts" icon="typescript"
 import { IntentOrderStatus, DEFAULT_GRAFFITI } from "@hyperbridge/sdk"
@@ -282,19 +282,20 @@ async function runOrder(order: Order) {
         console.log("Partial fill:", filledAssets, "| total filled:", totalFilledAssets, "| remaining:", remainingAssets)
         break
       }
-      case IntentOrderStatus.PARTIAL_FILL_EXHAUSTED:
-        // Order deadline reached, or no new bids arrived for the remaining amount
-        // The order is still live on-chain — cancel it or wait for a solver to fill the rest manually
-        console.warn("Could not fully fill order after max attempts. Remaining:", update.remainingAssets)
-        return
       case IntentOrderStatus.FILLED:
         // Order fully filled; escrow released to the solver
         console.log("Order fully filled! tx:", update.transactionHash)
         return
-      case IntentOrderStatus.FAILED:
-        // Unrecoverable error (e.g. bundler rejection, RPC failure)
-        console.error("Order failed:", update.error)
+      case IntentOrderStatus.EXPIRED:
+        // Order deadline reached, or no new bids arrived for the remaining amount
+        // The order is still live on-chain — cancel it or wait for a solver to fill the rest manually
+        console.warn("Order expired:", update.error, "Remaining:", update.remainingAssets)
         return
+      case IntentOrderStatus.FAILED:
+        // Retryable error (e.g. bundler rejection, simulation failure)
+        // The executor automatically retries — this is informational only
+        console.warn("Retryable error, retrying:", update.error)
+        break
     }
   }
 }
@@ -312,9 +313,9 @@ async function runOrder(order: Order) {
 | `BID_SELECTED` | Best bid chosen | `commitment`, `selectedSolver`, `userOpHash` |
 | `USEROP_SUBMITTED` | UserOp sent to bundler | `commitment`, `userOpHash`, `transactionHash` |
 | `PARTIAL_FILL` | Same-chain partial fill confirmed; loop restarts | `commitment`, `filledAssets`, `totalFilledAssets`, `remainingAssets` |
-| `PARTIAL_FILL_EXHAUSTED` | Deadline reached or no new bids for remainder | `commitment`, `totalFilledAssets`, `remainingAssets`, `error` |
 | `FILLED` | Order fully filled | `commitment`, `userOpHash`, `transactionHash` |
-| `FAILED` | Unrecoverable error | `error` |
+| `EXPIRED` | Deadline reached or no new bids available — terminal | `commitment`, `totalFilledAssets`, `remainingAssets`, `error` |
+| `FAILED` | Retryable error (e.g. bundler rejection) — executor retries automatically | `commitment`, `totalFilledAssets`, `remainingAssets`, `error` |
 
 ### `execute()` options
 
@@ -324,9 +325,13 @@ async function runOrder(order: Order) {
 | `bidTimeoutMs` | `number` | `60000` | Max time (ms) to wait for bids before proceeding with whatever has arrived |
 | `pollIntervalMs` | `number` | SDK default | How frequently (ms) to poll the coprocessor for new bids |
 
-### `PARTIAL_FILL_EXHAUSTED`
+### `EXPIRED`
+
+When `EXPIRED` fires, the order deadline has been reached or no new bids are available. The user can cancel and reclaim the remaining escrow. See [Cancelling Orders](./cancelling-orders) for cancellation options.
+
+### `FAILED` (retryable)
 
-When `PARTIAL_FILL_EXHAUSTED` fires, the user can cancel and reclaim the remaining escrow. See [Cancelling Orders](./cancelling-orders) for cancellation options.
+`FAILED` events are informational — the executor automatically retries by looping back to bid polling. Common causes include bundler gas price rejections or bid simulation failures. The retry continues until the order reaches `FILLED` or `EXPIRED`.
 
 ---
 

docs/content/developers/sdk/api/intent-gateway.mdx

@@ -345,7 +345,7 @@ type IntentOrderStatusUpdate =
   | { status: "USEROP_SUBMITTED"; commitment: HexString; userOpHash: HexString; selectedSolver: HexString; transactionHash?: HexString }
   | { status: "FILLED"; commitment: HexString; userOpHash: HexString; selectedSolver: HexString; transactionHash?: HexString; totalFilledAssets: TokenInfo[]; remainingAssets: TokenInfo[] }
   | { status: "PARTIAL_FILL"; commitment: HexString; userOpHash: HexString; selectedSolver: HexString; transactionHash?: HexString; filledAssets: TokenInfo[]; totalFilledAssets: TokenInfo[]; remainingAssets: TokenInfo[] }
-  | { status: "PARTIAL_FILL_EXHAUSTED"; commitment: HexString; totalFilledAssets?: TokenInfo[]; remainingAssets?: TokenInfo[]; error: string }
+  | { status: "EXPIRED"; commitment: HexString; totalFilledAssets?: TokenInfo[]; remainingAssets?: TokenInfo[]; error: string }
   | { status: "FAILED"; commitment?: HexString; totalFilledAssets?: TokenInfo[]; remainingAssets?: TokenInfo[]; error: string }
 ```
 
@@ -359,8 +359,8 @@ type IntentOrderStatusUpdate =
 | `USEROP_SUBMITTED` | `commitment`, `userOpHash`, `selectedSolver`, `transactionHash?` | UserOperation sent to the bundler |
 | `FILLED` | `commitment`, `userOpHash`, `selectedSolver`, `transactionHash?`, `totalFilledAssets`, `remainingAssets` | Order fully filled on the destination chain |
 | `PARTIAL_FILL` | `commitment`, `userOpHash`, `selectedSolver`, `transactionHash?`, `filledAssets`, `totalFilledAssets`, `remainingAssets` | Order partially filled; more fills may follow |
-| `PARTIAL_FILL_EXHAUSTED` | `commitment`, `totalFilledAssets?`, `remainingAssets?`, `error` | No further fills expected for a partially filled order |
-| `FAILED` | `commitment?`, `totalFilledAssets?`, `remainingAssets?`, `error` | Order execution failed unrecoverably |
+| `EXPIRED` | `commitment`, `totalFilledAssets?`, `remainingAssets?`, `error` | Order deadline reached or no new bids available — terminal |
+| `FAILED` | `commitment?`, `totalFilledAssets?`, `remainingAssets?`, `error` | Retryable error (e.g. bundler rejection, simulation failure) — executor retries automatically |
 
 ---
 

sdk/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hyperbridge/sdk",
-	"version": "1.8.7",
+	"version": "1.8.8",
 	"description": "The hyperclient SDK provides utilities for querying proofs and statuses for cross-chain requests from HyperBridge.",
 	"type": "module",
 	"types": "./dist/node/index.d.ts",

sdk/packages/sdk/src/protocols/intents/OrderExecutor.ts

@@ -50,10 +50,11 @@ export class OrderExecutor {
 	 *
 	 * **Status progression (same-chain orders):**
 	 * `AWAITING_BIDS` → `BIDS_RECEIVED` → `BID_SELECTED` → `USEROP_SUBMITTED`
-	 * → (`FILLED` | `PARTIAL_FILL`)* → (`FILLED` | `PARTIAL_FILL_EXHAUSTED`)
+	 * → (`FILLED` | `PARTIAL_FILL`)* → (`FILLED` | `EXPIRED`)
 	 *
-	 * **Error statuses:** `FAILED` (fatal, no fills) or `PARTIAL_FILL_EXHAUSTED`
-	 * (deadline reached or no new bids after at least one partial fill).
+	 * **Error statuses:** `FAILED` (retryable error during bid selection/submission,
+	 * triggers automatic retry) or `EXPIRED` (deadline reached or no new bids —
+	 * terminal, no further retries).
 	 *
 	 * @param options - Execution parameters including the placed order, its
 	 *   session private key, bid collection settings, and poll interval.
@@ -121,18 +122,13 @@ export class OrderExecutor {
 			while (true) {
 				const currentBlock = await this.ctx.dest.client.getBlockNumber()
 				if (currentBlock >= order.deadline) {
-					const isPartiallyFilled = totalFilledAssets.some((a) => a.amount > 0n)
 					const deadlineError = `Order deadline reached (block ${currentBlock} >= ${order.deadline})`
-					if (isPartiallyFilled) {
-						yield {
-							status: "PARTIAL_FILL_EXHAUSTED",
-							commitment,
-							totalFilledAssets,
-							remainingAssets,
-							error: deadlineError,
-						}
-					} else {
-						yield { status: "FAILED", commitment, error: deadlineError }
+					yield {
+						status: "EXPIRED",
+						commitment,
+						totalFilledAssets,
+						remainingAssets,
+						error: deadlineError,
 					}
 					return
 				}
@@ -175,22 +171,18 @@ export class OrderExecutor {
 				})
 
 				if (freshBids.length === 0) {
-					const isPartiallyFilled = totalFilledAssets.some((a) => a.amount > 0n)
 					const solverClause = solver && !solverLockExpired ? ` for requested solver ${solver.address}` : ""
+					const isPartiallyFilled = totalFilledAssets.some((a) => a.amount > 0n)
 					const noBidsError = isPartiallyFilled
 						? `No new bids${solverClause} after partial fill`
 						: `No new bids${solverClause} available within ${bidTimeoutMs}ms timeout`
 
-					if (isPartiallyFilled) {
-						yield {
-							status: "PARTIAL_FILL_EXHAUSTED",
-							commitment,
-							totalFilledAssets,
-							remainingAssets,
-							error: noBidsError,
-						}
-					} else {
-						yield { status: "FAILED", commitment, error: noBidsError }
+					yield {
+						status: "EXPIRED",
+						commitment,
+						totalFilledAssets,
+						remainingAssets,
+						error: noBidsError,
 					}
 					return
 				}
@@ -208,7 +200,9 @@ export class OrderExecutor {
 						remainingAssets,
 						error: `Failed to select bid and submit: ${err instanceof Error ? err.message : String(err)}`,
 					}
-					return
+					// Back off before retrying
+					await sleep(pollIntervalMs)
+					continue
 				}
 
 				const usedKey = userOpHashKey(result.userOp)
@@ -265,7 +259,10 @@ export class OrderExecutor {
 					remainingAssets = targetAssets.map((target) => {
 						const filled = totalFilledAssets.find((a) => a.token === target.token)
 						const filledAmt = filled?.amount ?? 0n
-						return { token: target.token, amount: filledAmt >= target.amount ? 0n : target.amount - filledAmt }
+						return {
+							token: target.token,
+							amount: filledAmt >= target.amount ? 0n : target.amount - filledAmt,
+						}
 					})
 
 					const fullyFilled = remainingAssets.every((a) => a.amount === 0n)

sdk/packages/sdk/src/types/index.ts

@@ -1321,7 +1321,7 @@ export const IntentOrderStatus = Object.freeze({
 	USEROP_SUBMITTED: "USEROP_SUBMITTED",
 	FILLED: "FILLED",
 	PARTIAL_FILL: "PARTIAL_FILL",
-	PARTIAL_FILL_EXHAUSTED: "PARTIAL_FILL_EXHAUSTED",
+	EXPIRED: "EXPIRED",
 	FAILED: "FAILED",
 })
 
@@ -1368,7 +1368,7 @@ export type IntentOrderStatusUpdate =
 			remainingAssets: TokenInfo[]
 	  }
 	| {
-			status: "PARTIAL_FILL_EXHAUSTED"
+			status: "EXPIRED"
 			commitment: HexString
 			totalFilledAssets?: TokenInfo[]
 			remainingAssets?: TokenInfo[]

sdk/packages/simplex/src/tests/strategies/fx.mainnet.test.ts

@@ -534,8 +534,8 @@ describe.skip("Filler V2 FX - Base mainnet same-chain swap", () => {
 							txHash: status.transactionHash,
 						})
 						break
-					case "PARTIAL_FILL_EXHAUSTED":
-						tlog("PARTIAL_FILL_EXHAUSTED", { commitment: status.commitment, error: status.error })
+					case "EXPIRED":
+						tlog("EXPIRED", { commitment: status.commitment, error: status.error })
 						break
 					case "FAILED":
 						tlog("FAILED", status)