@defuse-protocol/intents-sdk 0.43.3 → 0.44.0

package/dist/src/sdk.d.cts

@@ -1,10 +1,10 @@
 import { IntentHash, IntentPrimitive } from "./intents/shared-types.cjs";
 import { IIntentSigner } from "./intents/interfaces/intent-signer.cjs";
-import { BatchWithdrawalResult, Bridge, FeeEstimation, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, NearTxInfo, ParsedAssetInfo, PartialRPCEndpointMap, ProcessWithdrawalArgs, QuoteOptions, SignAndSendArgs, SignAndSendWithdrawalArgs, TxInfo, TxNoInfo, WithdrawalIdentifier, WithdrawalParams, WithdrawalResult } from "./shared-types.cjs";
+import { BatchWithdrawalResult, Bridge, CreateWithdrawalCompletionPromisesParams, FeeEstimation, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, NearTxInfo, ParsedAssetInfo, PartialRPCEndpointMap, ProcessWithdrawalArgs, QuoteOptions, SignAndSendArgs, SignAndSendWithdrawalArgs, TxInfo, TxNoInfo, WithdrawalParams, WithdrawalResult } from "./shared-types.cjs";
 import { IIntentRelayer } from "./intents/interfaces/intent-relayer.cjs";
 import { ISaltManager } from "./intents/interfaces/salt-manager.cjs";
 import { IntentPayloadBuilder } from "./intents/intent-payload-builder.cjs";
-import { ILogger, NearIntentsEnv, RetryOptions } from "@defuse-protocol/internal-utils";
+import { ILogger, NearIntentsEnv } from "@defuse-protocol/internal-utils";
 
 //#region src/sdk.d.ts
 interface IntentsSDKConfig {
@@ -13,6 +13,13 @@ interface IntentsSDKConfig {
   rpc?: PartialRPCEndpointMap;
   referral: string;
   solverRelayApiKey?: string;
+  features?: {
+    /**
+     * Route migrated POA tokens (*.omft.near) through Omni Bridge.
+     * Enable this to use Omni Bridge for POA tokens that have been migrated to the Omni infrastructure.
+     */
+    routeMigratedPoaTokensThroughOmniBridge?: boolean;
+  };
 }
 declare class IntentsSDK implements IIntentsSDK {
   protected env: NearIntentsEnv;
@@ -96,33 +103,87 @@ declare class IntentsSDK implements IIntentsSDK {
     quoteOptions?: QuoteOptions;
     logger?: ILogger;
   }): Promise<FeeEstimation>;
-  protected getWithdrawalsIdentifiers({
-    withdrawalParams,
-    intentTx
-  }: {
-    withdrawalParams: WithdrawalParams[];
-    intentTx: NearTxInfo;
-  }): WithdrawalIdentifier[];
+  /**
+   * Wait for withdrawal(s) to complete on the destination chain.
+   *
+   * **Important:** Waits until the withdrawal completes, fails, or the chain-specific
+   * p99 timeout is exceeded. Use `AbortSignal.timeout()` to set a shorter timeout budget.
+   *
+   * @throws {WithdrawalWatchError} When status polling fails (timeout or consecutive errors).
+   *   Inspect `error.cause` to determine the reason.
+   * @throws {WithdrawalFailedError} When the withdrawal fails on the destination chain.
+   * @throws {DOMException} When the provided AbortSignal is aborted (name: "AbortError").
+   *
+   * @param args.withdrawalParams - Single withdrawal or array of withdrawals
+   * @param args.intentTx - The NEAR transaction info from the published intent
+   * @param args.signal - Optional AbortSignal for cancellation/timeout
+   * @param args.logger - Optional logger for debugging
+   *
+   * @example
+   * ```typescript
+   * // With timeout
+   * const result = await sdk.waitForWithdrawalCompletion({
+   *   withdrawalParams,
+   *   intentTx,
+   *   signal: AbortSignal.timeout(5 * 60 * 1000), // 5 minute timeout
+   * });
+   * ```
+   */
   waitForWithdrawalCompletion(args: {
     withdrawalParams: WithdrawalParams;
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<TxInfo | TxNoInfo>;
   waitForWithdrawalCompletion(args: {
     withdrawalParams: WithdrawalParams[];
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<Array<TxInfo | TxNoInfo>>;
+  /**
+   * Create promises that resolve when each withdrawal completes on the destination chain.
+   * Use this for granular control over handling individual withdrawals as they complete,
+   * rather than waiting for all to finish.
+   *
+   * **Important:** Each promise waits until the withdrawal completes, fails, or the
+   * chain-specific p99 timeout is exceeded. Use `AbortSignal.timeout()` to set a
+   * shorter timeout budget.
+   *
+   * @throws {WithdrawalWatchError} When status polling fails (timeout or consecutive errors).
+   *   Inspect `error.cause` to determine the reason.
+   * @throws {WithdrawalFailedError} When the withdrawal fails on the destination chain.
+   * @throws {DOMException} When the provided AbortSignal is aborted (name: "AbortError").
+   *
+   * @param params.withdrawalParams - Array of withdrawal parameters
+   * @param params.intentTx - The NEAR transaction info from the published intent
+   * @param params.signal - Optional AbortSignal for cancellation/timeout
+   * @param params.logger - Optional logger for debugging
+   * @returns Array of promises, one per withdrawal, that resolve with transaction info
+   *
+   * @example
+   * ```typescript
+   * const promises = sdk.createWithdrawalCompletionPromises({
+   *   withdrawalParams: [withdrawal1, withdrawal2],
+   *   intentTx,
+   *   signal: AbortSignal.timeout(5 * 60 * 1000), // 5 minute timeout
+   * });
+   *
+   * // Handle each withdrawal as it completes
+   * for (const promise of promises) {
+   *   promise.then((result) => console.log('Withdrawal completed:', result));
+   * }
+   * ```
+   */
+  createWithdrawalCompletionPromises(params: CreateWithdrawalCompletionPromisesParams): Array<Promise<TxInfo | TxNoInfo>>;
   parseAssetId(assetId: string): ParsedAssetInfo;
   signAndSendIntent(args: SignAndSendArgs): Promise<IntentPublishResult>;
   private withSaltRetry;
   signAndSendWithdrawalIntent(args: SignAndSendWithdrawalArgs<WithdrawalParams> | SignAndSendWithdrawalArgs<WithdrawalParams[]>): Promise<IntentPublishResult>;
   waitForIntentSettlement(args: {
     intentHash: IntentHash;
+    /** AbortSignal for cancellation/timeout. Use AbortSignal.timeout(ms) for timeout. */
+    signal?: AbortSignal;
     logger?: ILogger;
   }): Promise<NearTxInfo>;
   getIntentStatus({

package/dist/src/sdk.d.ts

@@ -1,10 +1,10 @@
 import { IntentHash, IntentPrimitive } from "./intents/shared-types.js";
 import { IIntentSigner } from "./intents/interfaces/intent-signer.js";
-import { BatchWithdrawalResult, Bridge, FeeEstimation, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, NearTxInfo, ParsedAssetInfo, PartialRPCEndpointMap, ProcessWithdrawalArgs, QuoteOptions, SignAndSendArgs, SignAndSendWithdrawalArgs, TxInfo, TxNoInfo, WithdrawalIdentifier, WithdrawalParams, WithdrawalResult } from "./shared-types.js";
+import { BatchWithdrawalResult, Bridge, CreateWithdrawalCompletionPromisesParams, FeeEstimation, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, NearTxInfo, ParsedAssetInfo, PartialRPCEndpointMap, ProcessWithdrawalArgs, QuoteOptions, SignAndSendArgs, SignAndSendWithdrawalArgs, TxInfo, TxNoInfo, WithdrawalParams, WithdrawalResult } from "./shared-types.js";
 import { IIntentRelayer } from "./intents/interfaces/intent-relayer.js";
 import { ISaltManager } from "./intents/interfaces/salt-manager.js";
 import { IntentPayloadBuilder } from "./intents/intent-payload-builder.js";
-import { ILogger, NearIntentsEnv, RetryOptions } from "@defuse-protocol/internal-utils";
+import { ILogger, NearIntentsEnv } from "@defuse-protocol/internal-utils";
 
 //#region src/sdk.d.ts
 interface IntentsSDKConfig {
@@ -13,6 +13,13 @@ interface IntentsSDKConfig {
   rpc?: PartialRPCEndpointMap;
   referral: string;
   solverRelayApiKey?: string;
+  features?: {
+    /**
+     * Route migrated POA tokens (*.omft.near) through Omni Bridge.
+     * Enable this to use Omni Bridge for POA tokens that have been migrated to the Omni infrastructure.
+     */
+    routeMigratedPoaTokensThroughOmniBridge?: boolean;
+  };
 }
 declare class IntentsSDK implements IIntentsSDK {
   protected env: NearIntentsEnv;
@@ -96,33 +103,87 @@ declare class IntentsSDK implements IIntentsSDK {
     quoteOptions?: QuoteOptions;
     logger?: ILogger;
   }): Promise<FeeEstimation>;
-  protected getWithdrawalsIdentifiers({
-    withdrawalParams,
-    intentTx
-  }: {
-    withdrawalParams: WithdrawalParams[];
-    intentTx: NearTxInfo;
-  }): WithdrawalIdentifier[];
+  /**
+   * Wait for withdrawal(s) to complete on the destination chain.
+   *
+   * **Important:** Waits until the withdrawal completes, fails, or the chain-specific
+   * p99 timeout is exceeded. Use `AbortSignal.timeout()` to set a shorter timeout budget.
+   *
+   * @throws {WithdrawalWatchError} When status polling fails (timeout or consecutive errors).
+   *   Inspect `error.cause` to determine the reason.
+   * @throws {WithdrawalFailedError} When the withdrawal fails on the destination chain.
+   * @throws {DOMException} When the provided AbortSignal is aborted (name: "AbortError").
+   *
+   * @param args.withdrawalParams - Single withdrawal or array of withdrawals
+   * @param args.intentTx - The NEAR transaction info from the published intent
+   * @param args.signal - Optional AbortSignal for cancellation/timeout
+   * @param args.logger - Optional logger for debugging
+   *
+   * @example
+   * ```typescript
+   * // With timeout
+   * const result = await sdk.waitForWithdrawalCompletion({
+   *   withdrawalParams,
+   *   intentTx,
+   *   signal: AbortSignal.timeout(5 * 60 * 1000), // 5 minute timeout
+   * });
+   * ```
+   */
   waitForWithdrawalCompletion(args: {
     withdrawalParams: WithdrawalParams;
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<TxInfo | TxNoInfo>;
   waitForWithdrawalCompletion(args: {
     withdrawalParams: WithdrawalParams[];
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<Array<TxInfo | TxNoInfo>>;
+  /**
+   * Create promises that resolve when each withdrawal completes on the destination chain.
+   * Use this for granular control over handling individual withdrawals as they complete,
+   * rather than waiting for all to finish.
+   *
+   * **Important:** Each promise waits until the withdrawal completes, fails, or the
+   * chain-specific p99 timeout is exceeded. Use `AbortSignal.timeout()` to set a
+   * shorter timeout budget.
+   *
+   * @throws {WithdrawalWatchError} When status polling fails (timeout or consecutive errors).
+   *   Inspect `error.cause` to determine the reason.
+   * @throws {WithdrawalFailedError} When the withdrawal fails on the destination chain.
+   * @throws {DOMException} When the provided AbortSignal is aborted (name: "AbortError").
+   *
+   * @param params.withdrawalParams - Array of withdrawal parameters
+   * @param params.intentTx - The NEAR transaction info from the published intent
+   * @param params.signal - Optional AbortSignal for cancellation/timeout
+   * @param params.logger - Optional logger for debugging
+   * @returns Array of promises, one per withdrawal, that resolve with transaction info
+   *
+   * @example
+   * ```typescript
+   * const promises = sdk.createWithdrawalCompletionPromises({
+   *   withdrawalParams: [withdrawal1, withdrawal2],
+   *   intentTx,
+   *   signal: AbortSignal.timeout(5 * 60 * 1000), // 5 minute timeout
+   * });
+   *
+   * // Handle each withdrawal as it completes
+   * for (const promise of promises) {
+   *   promise.then((result) => console.log('Withdrawal completed:', result));
+   * }
+   * ```
+   */
+  createWithdrawalCompletionPromises(params: CreateWithdrawalCompletionPromisesParams): Array<Promise<TxInfo | TxNoInfo>>;
   parseAssetId(assetId: string): ParsedAssetInfo;
   signAndSendIntent(args: SignAndSendArgs): Promise<IntentPublishResult>;
   private withSaltRetry;
   signAndSendWithdrawalIntent(args: SignAndSendWithdrawalArgs<WithdrawalParams> | SignAndSendWithdrawalArgs<WithdrawalParams[]>): Promise<IntentPublishResult>;
   waitForIntentSettlement(args: {
     intentHash: IntentHash;
+    /** AbortSignal for cancellation/timeout. Use AbortSignal.timeout(ms) for timeout. */
+    signal?: AbortSignal;
     logger?: ILogger;
   }): Promise<NearTxInfo>;
   getIntentStatus({

package/dist/src/sdk.js

@@ -1,4 +1,5 @@
 import { FeeExceedsAmountError } from "./classes/errors.js";
+import { RouteEnum } from "./constants/route-enum.js";
 import { Chains } from "./lib/caip2.js";
 import { AuroraEngineBridge } from "./bridges/aurora-engine-bridge/aurora-engine-bridge.js";
 import { DirectBridge } from "./bridges/direct-bridge/direct-bridge.js";
@@ -15,10 +16,10 @@ import { IntentRelayerPublic } from "./intents/intent-relayer-impl/intent-relaye
 import { noopIntentSigner } from "./intents/intent-signer-impl/intent-signer-noop.js";
 import { zip } from "./lib/array.js";
 import { configureEvmRpcUrls, configureStellarRpcUrls } from "./lib/configure-rpc-config.js";
-import { determineRouteConfig } from "./lib/route-config.js";
+import { createWithdrawalIdentifiers, watchWithdrawal } from "./core/withdrawal-watcher.js";
 import { SaltManager } from "./intents/salt-manager.js";
 import { IntentPayloadBuilder } from "./intents/intent-payload-builder.js";
-import { PUBLIC_NEAR_RPC_URLS, RETRY_CONFIGS, RelayPublishError, assert, configsByEnvironment, nearFailoverRpcProvider, solverRelay } from "@defuse-protocol/internal-utils";
+import { PUBLIC_NEAR_RPC_URLS, RelayPublishError, assert, configsByEnvironment, nearFailoverRpcProvider, solverRelay } from "@defuse-protocol/internal-utils";
 import { HotBridge } from "@hot-labs/omni-sdk";
 import { stringify } from "viem";
 import * as v from "valibot";
@@ -45,7 +46,10 @@ var IntentsSDK = class {
 				nearProvider,
 				solverRelayApiKey: this.solverRelayApiKey
 			}),
-			new PoaBridge({ env: this.env }),
+			new PoaBridge({
+				env: this.env,
+				routeMigratedPoaTokensThroughOmniBridge: args.features?.routeMigratedPoaTokensThroughOmniBridge
+			}),
 			new HotBridge$1({
 				env: this.env,
 				solverRelayApiKey: this.solverRelayApiKey,
@@ -63,7 +67,8 @@ var IntentsSDK = class {
 			new OmniBridge({
 				env: this.env,
 				nearProvider,
-				solverRelayApiKey: this.solverRelayApiKey
+				solverRelayApiKey: this.solverRelayApiKey,
+				routeMigratedPoaTokensThroughOmniBridge: args.features?.routeMigratedPoaTokensThroughOmniBridge
 			}),
 			new DirectBridge({
 				env: this.env,
@@ -205,42 +210,87 @@ var IntentsSDK = class {
 		}
 		throw new Error(`Cannot determine bridge for withdrawal = ${stringify(args.withdrawalParams)}`);
 	}
-	getWithdrawalsIdentifiers({ withdrawalParams, intentTx }) {
-		const indexes = /* @__PURE__ */ new Map();
-		return withdrawalParams.map((w) => {
-			const routeConfig = determineRouteConfig(this, w);
-			const route = routeConfig.route;
-			const currentIndex = indexes.get(route) ?? 0;
-			indexes.set(route, currentIndex + 1);
-			return {
-				routeConfig,
-				index: currentIndex,
-				withdrawalParams: w,
-				tx: intentTx
-			};
-		});
-	}
 	async waitForWithdrawalCompletion(args) {
-		const wids = this.getWithdrawalsIdentifiers({
-			withdrawalParams: Array.isArray(args.withdrawalParams) ? args.withdrawalParams : [args.withdrawalParams],
-			intentTx: args.intentTx
+		const withdrawalParamsArray = Array.isArray(args.withdrawalParams) ? args.withdrawalParams : [args.withdrawalParams];
+		const promises = this.createWithdrawalCompletionPromises({
+			withdrawalParams: withdrawalParamsArray,
+			intentTx: args.intentTx,
+			signal: args.signal,
+			logger: args.logger
 		});
-		const result = await Promise.all(wids.map((wid) => {
-			for (const bridge of this.bridges) if (bridge.is(wid.routeConfig)) return bridge.waitForWithdrawalCompletion({
-				tx: args.intentTx,
-				index: wid.index,
-				withdrawalParams: wid.withdrawalParams,
-				routeConfig: wid.routeConfig,
-				signal: args.signal,
-				retryOptions: args.retryOptions,
-				logger: args.logger
-			});
-			throw new Error(`Unsupported route = ${stringify(wid.routeConfig)}`);
-		}));
+		const result = await Promise.all(promises);
 		if (Array.isArray(args.withdrawalParams)) return result;
 		assert(result.length === 1, "Unexpected result length");
 		return result[0];
 	}
+	/**
+	* Create promises that resolve when each withdrawal completes on the destination chain.
+	* Use this for granular control over handling individual withdrawals as they complete,
+	* rather than waiting for all to finish.
+	*
+	* **Important:** Each promise waits until the withdrawal completes, fails, or the
+	* chain-specific p99 timeout is exceeded. Use `AbortSignal.timeout()` to set a
+	* shorter timeout budget.
+	*
+	* @throws {WithdrawalWatchError} When status polling fails (timeout or consecutive errors).
+	*   Inspect `error.cause` to determine the reason.
+	* @throws {WithdrawalFailedError} When the withdrawal fails on the destination chain.
+	* @throws {DOMException} When the provided AbortSignal is aborted (name: "AbortError").
+	*
+	* @param params.withdrawalParams - Array of withdrawal parameters
+	* @param params.intentTx - The NEAR transaction info from the published intent
+	* @param params.signal - Optional AbortSignal for cancellation/timeout
+	* @param params.logger - Optional logger for debugging
+	* @returns Array of promises, one per withdrawal, that resolve with transaction info
+	*
+	* @example
+	* ```typescript
+	* const promises = sdk.createWithdrawalCompletionPromises({
+	*   withdrawalParams: [withdrawal1, withdrawal2],
+	*   intentTx,
+	*   signal: AbortSignal.timeout(5 * 60 * 1000), // 5 minute timeout
+	* });
+	*
+	* // Handle each withdrawal as it completes
+	* for (const promise of promises) {
+	*   promise.then((result) => console.log('Withdrawal completed:', result));
+	* }
+	* ```
+	*/
+	createWithdrawalCompletionPromises(params) {
+		const { withdrawalParams, intentTx, signal, logger } = params;
+		const widsPromise = createWithdrawalIdentifiers({
+			bridges: this.bridges,
+			withdrawalParams,
+			intentTx
+		});
+		const hotChainLastPromise = /* @__PURE__ */ new Map();
+		return withdrawalParams.map(async (_, index) => {
+			const entry = (await widsPromise)[index];
+			assert(entry != null, `Missing wid for index ${index}`);
+			if (entry.bridge.route === RouteEnum.HotBridge) {
+				const landingChain = entry.wid.landingChain;
+				const previousPromise = hotChainLastPromise.get(landingChain);
+				const sequentialPromise = (async () => {
+					if (previousPromise) await Promise.allSettled([previousPromise]);
+					return watchWithdrawal({
+						bridge: entry.bridge,
+						wid: entry.wid,
+						signal,
+						logger
+					});
+				})();
+				hotChainLastPromise.set(landingChain, sequentialPromise);
+				return sequentialPromise;
+			}
+			return watchWithdrawal({
+				bridge: entry.bridge,
+				wid: entry.wid,
+				signal,
+				logger
+			});
+		});
+	}
 	parseAssetId(assetId) {
 		for (const bridge of this.bridges) {
 			const parsed = bridge.parseAssetId(assetId);
@@ -320,7 +370,7 @@ var IntentsSDK = class {
 			logger: args.logger,
 			intentSigner: noopIntentSigner,
 			intentRelayer: this.intentRelayer
-		}).waitForSettlement(args.intentHash);
+		}).waitForSettlement(args.intentHash, { signal: args.signal });
 		return tx;
 	}
 	async getIntentStatus({ intentHash, logger }) {
@@ -353,7 +403,6 @@ var IntentsSDK = class {
 		const destinationTx = await this.waitForWithdrawalCompletion({
 			withdrawalParams,
 			intentTx,
-			retryOptions: args.retryOptions ?? RETRY_CONFIGS.FIVE_MINS_STEADY,
 			logger: args.logger
 		});
 		if (!Array.isArray(args.withdrawalParams)) return {

package/dist/src/shared-types.d.cts

@@ -5,7 +5,7 @@ import { IntentHash, IntentPayloadFactory, IntentPrimitive, IntentRelayParamsFac
 import { IIntentSigner } from "./intents/interfaces/intent-signer.cjs";
 import { OnBeforePublishIntentHook } from "./intents/intent-executer-impl/intent-executer.cjs";
 import { Chain, Chains } from "./lib/caip2.cjs";
-import { ILogger, RetryOptions, solverRelay } from "@defuse-protocol/internal-utils";
+import { ILogger, solverRelay } from "@defuse-protocol/internal-utils";
 
 //#region src/shared-types.d.ts
 interface IntentPublishResult {
@@ -106,7 +106,6 @@ type ProcessWithdrawalArgs<T extends WithdrawalParams | WithdrawalParams[]> = {
     signedIntents?: SignedIntentsComposition;
   };
   referral?: string;
-  retryOptions?: RetryOptions;
   logger?: ILogger;
 };
 interface IIntentsSDK {
@@ -114,6 +113,8 @@ interface IIntentsSDK {
   signAndSendIntent(args: SignAndSendArgs): Promise<IntentPublishResult>;
   waitForIntentSettlement(args: {
     intentHash: IntentHash;
+    /** AbortSignal for cancellation/timeout. Use AbortSignal.timeout(ms) for timeout. */
+    signal?: AbortSignal;
     logger?: ILogger;
   }): Promise<NearTxInfo>;
   getIntentStatus(args: {
@@ -140,16 +141,15 @@ interface IIntentsSDK {
     withdrawalParams: WithdrawalParams;
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<TxInfo | TxNoInfo>;
   waitForWithdrawalCompletion(args: {
     withdrawalParams: WithdrawalParams[];
     intentTx: NearTxInfo;
     signal?: AbortSignal;
-    retryOptions?: RetryOptions;
     logger?: ILogger;
   }): Promise<Array<TxInfo | TxNoInfo>>;
+  createWithdrawalCompletionPromises(params: CreateWithdrawalCompletionPromisesParams): Array<Promise<TxInfo | TxNoInfo>>;
   createWithdrawalIntents(args: {
     withdrawalParams: WithdrawalParams;
     feeEstimation: FeeEstimation;
@@ -176,6 +176,12 @@ interface TxInfo {
 interface TxNoInfo {
   hash: null;
 }
+interface CreateWithdrawalCompletionPromisesParams {
+  withdrawalParams: WithdrawalParams[];
+  intentTx: NearTxInfo;
+  signal?: AbortSignal;
+  logger?: ILogger;
+}
 interface WithdrawalParams {
   assetId: string;
   amount: bigint;
@@ -201,7 +207,6 @@ type VirtualChainRouteConfig = {
 };
 type PoaBridgeRouteConfig = {
   route: RouteEnum["PoaBridge"];
-  chain: Chain;
 };
 type HotBridgeRouteConfig = {
   route: RouteEnum["HotBridge"];
@@ -266,7 +271,7 @@ interface FeeEstimation {
   underlyingFees: UnderlyingFees;
 }
 interface Bridge {
-  is(routeConfig: RouteConfig): boolean;
+  readonly route: RouteEnumValues;
   supports(params: Pick<WithdrawalParams, "assetId" | "routeConfig">): Promise<boolean>;
   parseAssetId(assetId: string): ParsedAssetInfo | null;
   /**
@@ -295,22 +300,51 @@ interface Bridge {
     feeEstimation: FeeEstimation;
     referral?: string;
   }): Promise<IntentPrimitive[]>;
-  waitForWithdrawalCompletion(args: {
-    tx: NearTxInfo;
-    index: number;
+  /**
+   * Creates a complete withdrawal identifier with all required info.
+   * Derives landingChain from withdrawalParams.routeConfig.chain if available, otherwise from assetId.
+   */
+  createWithdrawalIdentifier(args: {
     withdrawalParams: WithdrawalParams;
-    routeConfig: RouteConfig;
-    signal?: AbortSignal;
-    retryOptions?: RetryOptions;
+    index: number;
+    tx: NearTxInfo;
+  }): WithdrawalIdentifier;
+  /**
+   * One-shot status check for a withdrawal.
+   * Returns the current status without polling.
+   */
+  describeWithdrawal(args: WithdrawalIdentifier & {
     logger?: ILogger;
-  }): Promise<TxInfo | TxNoInfo>;
+  }): Promise<WithdrawalStatus>;
 }
 interface WithdrawalIdentifier {
-  routeConfig: RouteConfig;
+  /** Actual chain where funds arrive; Near for virtual/internal routes */
+  landingChain: Chain;
+  /** Per-bridge withdrawal sequence number */
   index: number;
   withdrawalParams: WithdrawalParams;
   tx: NearTxInfo;
 }
+/**
+ * Represents the current state of a withdrawal as returned by bridge adapters.
+ *
+ * Error handling follows AWS SDK "describe" API patterns:
+ * - **Thrown errors**: Infrastructure failures (network, auth, service unavailable).
+ *   Meaning: "I couldn't check the status."
+ * - **`failed` status**: Job-level failure reported by the bridge.
+ *   Meaning: "I checked, and the withdrawal failed."
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-job-status.html
+ */
+type WithdrawalStatus = {
+  status: "pending";
+} | {
+  status: "completed";
+  txHash: string | null;
+} | {
+  status: "failed";
+  reason: string;
+};
 type ParsedAssetInfo = ({
   blockchain: Chain;
   bridgeName: BridgeNameEnumValues;
@@ -334,4 +368,4 @@ type RPCEndpointMap = Record<typeof Chains.Near | HotBridgeEVMChain, string[]> &
 type DeepPartial<T> = T extends object ? T extends Array<infer U> ? Array<DeepPartial<U>> : T extends Function ? T : { [P in keyof T]?: DeepPartial<T[P]> } : T;
 type PartialRPCEndpointMap = DeepPartial<RPCEndpointMap>;
 //#endregion
-export { BatchWithdrawalResult, Bridge, FeeEstimation, HotBridgeRouteConfig, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, InternalTransferRouteConfig, NearTxInfo, NearWithdrawalRouteConfig, OmniBridgeRouteConfig, ParsedAssetInfo, PartialRPCEndpointMap, PoaBridgeRouteConfig, ProcessWithdrawalArgs, QuoteOptions, RouteConfig, SignAndSendArgs, SignAndSendWithdrawalArgs, SignedIntentsComposition, TxInfo, TxNoInfo, VirtualChainRouteConfig, WithdrawalIdentifier, WithdrawalParams, WithdrawalResult };
+export { BatchWithdrawalResult, Bridge, CreateWithdrawalCompletionPromisesParams, FeeEstimation, HotBridgeRouteConfig, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, InternalTransferRouteConfig, NearTxInfo, NearWithdrawalRouteConfig, OmniBridgeRouteConfig, ParsedAssetInfo, PartialRPCEndpointMap, PoaBridgeRouteConfig, ProcessWithdrawalArgs, QuoteOptions, RouteConfig, SignAndSendArgs, SignAndSendWithdrawalArgs, SignedIntentsComposition, TxInfo, TxNoInfo, VirtualChainRouteConfig, WithdrawalIdentifier, WithdrawalParams, WithdrawalResult };