@ravnexchange/sdk 0.1.14 → 0.2.0

package/dist/client.d.ts

@@ -32,8 +32,10 @@ export declare class RavnClient {
      * the execution's statusRef, submitSignature's statusRef, or the origin tx hash. POST, not GET:
      * a 2-hop quoteToken in a query string can exceed header limits and fail with 431. `txHash`:
      * a two-hop route's hop-1 transaction, or the fee payment a DEPOSIT's `fee.transaction` asked
-     * for; it's how RAVN proves the fee your share is paid from. */
-    getStatus(quoteToken: string, ref: string, txHash?: string): Promise<StatusDTO>;
+     * for; it's how RAVN proves the fee your share is paid from. `signal` aborts the request. */
+    getStatus(quoteToken: string, ref: string, txHash?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<StatusDTO>;
     /** GET /v1/tokens: RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */
     getTokens(chainId: number): Promise<TokenDTO[]>;
     /** GET /v1/chains: every chain RAVN lists tokens for. Static; safe to cache client-side. */

package/dist/client.js

@@ -16,26 +16,39 @@ class RavnClient {
         // Called unbound, never as this.fetchImpl(...): a browser's own fetch (the default, or one
         // passed in) throws "Illegal invocation" when `this` is the client, failing every call.
         const fetchImpl = this.fetchImpl;
-        const res = await fetchImpl(`${this.baseUrl}${path}`, {
-            ...init,
-            headers: {
-                "content-type": "application/json",
-                ...(this.apiKey ? { "x-api-key": this.apiKey } : {}),
-                ...init.headers,
-            },
-        });
+        let res;
+        try {
+            res = await fetchImpl(`${this.baseUrl}${path}`, {
+                ...init,
+                headers: {
+                    "content-type": "application/json",
+                    ...(this.apiKey ? { "x-api-key": this.apiKey } : {}),
+                    ...init.headers,
+                },
+            });
+        }
+        catch (err) {
+            // The caller's own abort is theirs, as is; anything else is the one error type this client
+            // promises, never a raw fetch TypeError.
+            if (init.signal?.aborted)
+                throw err;
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new types_1.RavnApiError("NETWORK_ERROR", `No response from ${path}: ${reason}`, undefined, undefined, { cause: err });
+        }
         let body;
         try {
             body = (await res.json());
         }
-        catch {
+        catch (err) {
+            if (init.signal?.aborted)
+                throw err;
             // A non-JSON body (an intermediary's HTML error page, an empty 204/502/504) must still
             // surface as the one error type this client promises, never a raw SyntaxError.
-            throw new types_1.RavnApiError("INTERNAL", `HTTP ${res.status}: response was not valid JSON`, undefined, undefined);
+            throw new types_1.RavnApiError("INTERNAL", `HTTP ${res.status}: response was not valid JSON`, undefined, undefined, { status: res.status });
         }
         if (!res.ok || body.error) {
             const err = body.error ?? { code: "INTERNAL", message: `HTTP ${res.status}` };
-            throw new types_1.RavnApiError(err.code, err.message, err.details, body.meta);
+            throw new types_1.RavnApiError(err.code, err.message, err.details, body.meta, { status: res.status });
         }
         return body.data;
     }
@@ -67,11 +80,12 @@ class RavnClient {
      * the execution's statusRef, submitSignature's statusRef, or the origin tx hash. POST, not GET:
      * a 2-hop quoteToken in a query string can exceed header limits and fail with 431. `txHash`:
      * a two-hop route's hop-1 transaction, or the fee payment a DEPOSIT's `fee.transaction` asked
-     * for; it's how RAVN proves the fee your share is paid from. */
-    getStatus(quoteToken, ref, txHash) {
+     * for; it's how RAVN proves the fee your share is paid from. `signal` aborts the request. */
+    getStatus(quoteToken, ref, txHash, options = {}) {
         return this.request("/status", {
             method: "POST",
             body: JSON.stringify({ quoteToken, ref, ...(txHash ? { txHash } : {}) }),
+            signal: options.signal,
         });
     }
     /** GET /v1/tokens: RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */

package/dist/execute-and-track.d.ts

@@ -1,5 +1,5 @@
 import type { RavnClient } from "./client";
-import type { ApprovalDTO, ExecuteParams, ExecutionDTO, StatusDTO } from "./types";
+import type { ApprovalDTO, DepositFeeDTO, ExecuteParams, ExecutionDTO, StatusDTO } from "./types";
 type TxLike = {
     to?: string;
     data?: string;
@@ -7,15 +7,43 @@ type TxLike = {
     chainId?: number;
     serialized?: string;
 };
+/**
+ * The parts of a transaction receipt executeAndTrack reads. viem's and wagmi's
+ * `waitForTransactionReceipt`, ethers v5 and v6 (`tx.wait()`, `provider.waitForTransaction`) and
+ * web3.js receipts all fit as they are.
+ */
+export type TransactionReceiptLike = {
+    status?: unknown;
+    transactionHash: string;
+} | {
+    status?: unknown;
+    hash: string;
+};
 export interface ExecuteAndTrackHandlers {
-    /** Broadcast a transaction (an approval, or the main swap tx) and return its hash. */
+    /** Broadcast a transaction (an approval, the main swap tx, or RAVN's fee) and return its hash. */
     sendTransaction(tx: TxLike): Promise<string>;
     /**
-     * Wait for a transaction hash to confirm. Called on the approval before the main tx is ever
-     * sent: sending both back-to-back races the allowance and is the most common integration bug
-     * this helper exists to prevent.
+     * Wait for a transaction hash to confirm and resolve to its receipt. Called on the approval
+     * before the main tx is ever sent: sending both back-to-back races the allowance and is the most
+     * common integration bug this helper exists to prevent. Also called on the swap before RAVN's fee
+     * is sent on its own (`fee.transaction`): the fee is only sent when the receipt says success AND
+     * is this hash's own (a cancelled or replaced swap resolves with another transaction's). A
+     * handler resolving to nothing doesn't compile: it would never get the fee sent. `null` (ethers
+     * with 0 confirmations) sends no fee: a fee on a swap that didn't run is the user's money lost.
      */
-    waitForReceipt(hash: string, chainId?: number): Promise<void>;
+    waitForReceipt(hash: string, chainId?: number): Promise<TransactionReceiptLike | null>;
+    /**
+     * Optional: send several calls in ONE wallet confirmation that succeeds or fails as a whole
+     * (EIP-5792 `wallet_sendCalls` with `atomicRequired: true`, a smart account) and resolve, once
+     * they have landed, to the on-chain hash of the transaction that carried each call, in order
+     * (the same hash repeated, or just one, for one transaction). Not a batch id or a 4337
+     * userOpHash: RAVN proves its fee from that transaction. When given, a token-paid RAVN fee rides
+     * in the swap's own confirmation, and so does the swap's approval when it needs one; a
+     * native-coin fee is always a plain transaction of its own. The batch's gas limit is your
+     * wallet's (EIP-5792 carries none): give it headroom, as a wallet estimating it tight reverts
+     * the whole batch. Reject only when nothing was sent: a rejection loses the swap's hash.
+     */
+    sendCalls?(txs: TxLike[]): Promise<string[]>;
     /** Sign an EIP-712 typed-data payload. Only called for SIGNATURE executions. */
     signTypedData?(typedData: Record<string, unknown>): Promise<`0x${string}`>;
     /**
@@ -33,13 +61,42 @@ export interface ExecuteAndTrackHandlers {
      */
     hasAllowance?(approval: ApprovalDTO): Promise<boolean>;
 }
+/** What just happened: a transaction's hash is known (sent, not yet confirmed), a swap was signed
+ * for RAVN to submit (`signedTransaction` for a Solana swap, `signature` for an order), or a status
+ * poll answered. */
+export type ExecuteAndTrackStage = "reset_sent" | "approval_sent" | "swap_signed" | "swap_sent" | "fee_sent" | "status";
+export interface ExecuteAndTrackProgress {
+    stage: ExecuteAndTrackStage;
+    /** Everything known so far. Persist it: it's all you need to keep tracking the swap if this
+     * call never returns (a closed tab, a crash). "swap_sent" carries `statusRef`. */
+    partial: ExecuteAndTrackPartial;
+}
 export interface ExecuteAndTrackOptions {
-    /** Default true. Set false to get a ref back immediately and poll getStatus yourself. */
+    /** Default true. Set false to get a ref back once the swap (and RAVN's fee, when one is sent) is
+     * out, and poll getStatus yourself with `statusTxHash`. */
     pollUntilTerminal?: boolean;
+    /** Default 4000. Also where the backoff after a failed call starts (doubling, up to a minute). */
     pollIntervalMs?: number;
+    /** How often to poll a swap that's `expired`: a refund is due and can take hours (Across returns
+     * it in a later settlement bundle). Default 60000. */
+    expiredPollIntervalMs?: number;
+    /** Stop polling this long after the first status poll, rejecting with an ExecuteAndTrackError
+     * ("TIMEOUT") that carries every hash: keep polling getStatus with them yourself. Default: no
+     * limit (a swap may sit `expired` for hours). */
+    maxWaitMs?: number;
+    /** Stop: nothing more goes to the wallet and polling ends, rejecting with an
+     * ExecuteAndTrackError ("ABORTED"). A wallet prompt already open isn't withdrawn; whatever it
+     * sends is in the error's `partial`. A submitSignature or submitTransaction call already under
+     * way is awaited first: its answer is the swap's only handle. */
+    signal?: AbortSignal;
+    /** Called with every hash the moment it exists (approval, swap with its statusRef, fee) and with
+     * every status poll. An error it throws is ignored: it never stops a swap that's out. */
+    onProgress?(progress: ExecuteAndTrackProgress): void;
 }
 export interface ExecuteAndTrackResult {
     execution: ExecutionDTO;
+    /** The `approval.reset` (approve to 0) sent before the approval, when the token needed one. */
+    resetTxHash?: string;
     approvalTxHash?: string;
     txHash?: string;
     /** Pass to client.getStatus(quoteToken, statusRef). Same as `execution.quoteToken`, NOT the
@@ -48,14 +105,94 @@ export interface ExecuteAndTrackResult {
     /** Pass to client.getStatus(quoteToken, statusRef). For TRANSACTION, the execution's own
      * statusRef when it has one (compose, Garden, Relay), else txHash: not always a tx hash. */
     statusRef?: string;
+    /** Pass as getStatus's third argument (`txHash`) on every poll you make yourself, from the first
+     * one until a terminal status and once more after a success (RAVN's node may be a block behind
+     * yours): the fee payment's transaction when one was sent (already confirmed by the time this
+     * returns), else, with a statusRef, the swap's own tx (a two-hop route's hop 1 proves its fee;
+     * ignored elsewhere). It's how RAVN proves the fee your share is paid from: the venue's own
+     * tracker saying "delivered" doesn't book it. */
+    statusTxHash?: string;
+    /** The transaction that carried RAVN's fee (`execution.fee.transaction`), once sent. Sent isn't
+     * paid (a batch can revert): RAVN's status polls are what prove it. */
+    feeTxHash?: string;
+    /** Why RAVN's fee wasn't sent (or its receipt not seen): the swap still runs and is tracked, but
+     * no fee is owed to you on it unless `feeTxHash` is set and it landed. */
+    feeError?: unknown;
+    /** DEPOSIT only: the fee payment to make beside the deposit (see depositFeePayment). */
+    feePayment?: DepositFeePayment;
     /** Set once pollUntilTerminal reaches a terminal status. Absent for DEPOSIT (see below) or when polling is turned off. */
     finalStatus?: StatusDTO;
 }
+/** What executeAndTrack knew when it reported progress or stopped: every hash sent so far, and the
+ * last status it saw. `signedTransaction` (broadcastViaRavn): the signed Solana swap handed to
+ * submitTransaction; post it again with the same quoteToken (RAVN never sends it twice) to learn
+ * whether it landed, before signing anything new. `signature` (SIGNATURE): the signed order handed
+ * to submitSignature; "swap_signed" with no "swap_sent" after it means the call failed or got no
+ * answer, and the venue may still have taken the order: check before signing a new one. */
+export type ExecuteAndTrackPartial = Partial<ExecuteAndTrackResult> & {
+    lastStatus?: StatusDTO;
+    signedTransaction?: string;
+    signature?: `0x${string}`;
+};
+/**
+ * How executeAndTrack rejects once anything has been sent or signed (an approval, the swap, a
+ * signature handed to RAVN), and on any abort or timeout: `partial` carries every hash, so the
+ * swap is never lost. Keep polling getStatus(partial.quoteToken, partial.statusRef,
+ * partial.statusTxHash). Before anything is sent, errors come as they are (a RavnApiError from
+ * execute, the wallet's own rejection).
+ */
+export declare class ExecuteAndTrackError extends Error {
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    readonly code: "ABORTED" | "TIMEOUT" | "FAILED";
+    readonly partial: ExecuteAndTrackPartial;
+    /** What failed underneath: a RavnApiError, the wallet's error, or your signal's reason. */
+    readonly cause?: unknown;
+    constructor(message: string, 
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    code: "ABORTED" | "TIMEOUT" | "FAILED", partial: ExecuteAndTrackPartial, cause?: unknown);
+}
+/** How to pay a DEPOSIT's `fee`, so it's proven against this swap. See DepositFeeDTO. Either way,
+ * poll RAVN's getStatus until a terminal status even when the venue's own tracker (e.g. Rift's API)
+ * already says delivered: RAVN books the fee on its own status polls. */
+export type DepositFeePayment = 
+/** EVM: send `transaction` exactly as given once the deposit has confirmed, then pass its
+ * on-chain hash as `txHash` on every getStatus poll; at least one must come after it confirmed,
+ * or nothing is owed. A token fee (`value` "0") may instead ride in the deposit's own atomic
+ * wallet batch: pass the hash of the transaction that carried it (not a batch id or userOpHash).
+ * A native-coin fee: a plain transaction of its own. */
+{
+    kind: "transaction";
+    transaction: NonNullable<DepositFeeDTO["transaction"]>;
+}
+/** Bitcoin: an extra output paying `amount` sats to `address` in the SAME transaction that pays
+ * the deposit. One deposit per transaction: a fee output proves one swap. */
+ | {
+    kind: "bitcoin_output";
+    address: string;
+    amount: string;
+}
+/** Solana: a transfer of `amount` to `address` in the SAME transaction that pays the deposit
+ * exactly `deposit.amount` (SOL as lamports, not wrapped). SOL: a System transfer of `amount`
+ * lamports to `address`. A token: `createAssociatedTokenAccountIdempotent` for `address`'s
+ * associated token account for the input mint (under the mint's token program), then
+ * `transferChecked` of `amount` to it. Sent in a transaction of its own, it isn't found. */
+ | {
+    kind: "solana_transfer";
+    address: string;
+    amount: string;
+};
+/** The fee payment a DEPOSIT execution asks for beside its deposit; undefined when it has none. */
+export declare function depositFeePayment(execution: ExecutionDTO): DepositFeePayment | undefined;
 /**
- * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → status
- * polling, using caller-supplied signing/sending functions. The SDK stays wallet-agnostic (no
- * RPC dependency); this just gets the ORDER right, which quickstart's own docs flag as the
- * most common integration failure: sending the main tx before the approval has confirmed.
+ * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → RAVN's fee
+ * payment (if any) → status polling, using caller-supplied signing/sending functions. The SDK
+ * stays wallet-agnostic (no RPC dependency); this just gets the ORDER right, which quickstart's
+ * own docs flag as the most common integration failure: sending the main tx before the approval
+ * has confirmed. A failed API call is retried where repeating it is safe (status polls and
+ * submitTransaction on a 429, 5xx or no response; execute and submitSignature only when rate
+ * limited), waiting the API's retryAfterSec. Once anything
+ * is sent, it rejects only with an ExecuteAndTrackError carrying every hash; `onProgress` hears
+ * each one first.
  */
 export declare function executeAndTrack(client: RavnClient, params: ExecuteParams, handlers: ExecuteAndTrackHandlers, options?: ExecuteAndTrackOptions): Promise<ExecuteAndTrackResult>;
 export {};

package/dist/execute-and-track.js

@@ -1,80 +1,380 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecuteAndTrackError = void 0;
+exports.depositFeePayment = depositFeePayment;
 exports.executeAndTrack = executeAndTrack;
+const types_1 = require("./types");
 const polling_1 = require("./polling");
 /**
- * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → status
- * polling, using caller-supplied signing/sending functions. The SDK stays wallet-agnostic (no
- * RPC dependency); this just gets the ORDER right, which quickstart's own docs flag as the
- * most common integration failure: sending the main tx before the approval has confirmed.
+ * How executeAndTrack rejects once anything has been sent or signed (an approval, the swap, a
+ * signature handed to RAVN), and on any abort or timeout: `partial` carries every hash, so the
+ * swap is never lost. Keep polling getStatus(partial.quoteToken, partial.statusRef,
+ * partial.statusTxHash). Before anything is sent, errors come as they are (a RavnApiError from
+ * execute, the wallet's own rejection).
+ */
+class ExecuteAndTrackError extends Error {
+    constructor(message, 
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    code, partial, cause) {
+        super(message);
+        this.code = code;
+        this.partial = partial;
+        this.name = "ExecuteAndTrackError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+exports.ExecuteAndTrackError = ExecuteAndTrackError;
+const BITCOIN_CHAIN_ID = -1;
+const SOLANA_CHAIN_ID = -2;
+const EVM_TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+// What a sandbox status poll is sent as ref when there's no tx hash: RAVN doesn't read it.
+const SANDBOX_REF = "sandbox";
+const EXPIRED_POLL_INTERVAL_MS = 60000;
+const MAX_BACKOFF_MS = 60000;
+// ponytail: a fixed cap, ~4 min of backoff at the default interval; past it the call rejects with
+// every hash to resume from. Make it an option if integrators need to ride out longer outages.
+const MAX_ATTEMPTS = 8;
+/** The fee payment a DEPOSIT execution asks for beside its deposit; undefined when it has none. */
+function depositFeePayment(execution) {
+    if (execution.executionType !== "DEPOSIT" || !execution.fee)
+        return undefined;
+    const { transaction, address, amount, chainId } = execution.fee;
+    if (transaction)
+        return { kind: "transaction", transaction };
+    if (chainId === BITCOIN_CHAIN_ID)
+        return { kind: "bitcoin_output", address, amount };
+    if (chainId === SOLANA_CHAIN_ID)
+        return { kind: "solana_transfer", address, amount };
+    throw new Error(`depositFeePayment: no known way to pay a fee on chain ${chainId}`);
+}
+// Only a receipt that says success (viem "success", ethers 1; web3.js 1n/true, so == on purpose) and
+// is `hash`'s own (viem/ethers v5 transactionHash, ethers v6 hash): viem resolves a cancelled swap
+// with the replacement's successful receipt. Typed unknown: JS callers can still hand it anything.
+const receiptSucceeded = (receipt, hash) => {
+    const r = receipt;
+    const own = r?.transactionHash ?? r?.hash;
+    return (r?.status === "success" || r?.status == 1) && (typeof own !== "string" || own.toLowerCase() === hash.toLowerCase());
+};
+// The same call can succeed later: no response at all, a 429, or a 5xx.
+const transient = (err) => err instanceof types_1.RavnApiError && (err.code === "NETWORK_ERROR" || err.status === 429 || (err.status ?? 0) >= 500);
+// Refused before anything was done, so safe to repeat even a call that isn't safe to repeat after
+// a BUILD_FAILED (submit-signature: the venue may have taken the order).
+const rateLimited = (err) => err instanceof types_1.RavnApiError && (err.code === "RATE_LIMITED" || err.code === "VENUE_RATE_LIMITED" || err.status === 429);
+// `promise`, or the signal's reason as soon as it aborts: a wallet or custom fetch may ignore the
+// signal. `promise` is always handled, so one that rejects after the abort is never unhandled.
+const orAbort = (promise, signal) => new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    // Promise.resolve: a JS handler may hand back the value itself rather than a promise.
+    Promise.resolve(promise).then((value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+    }, (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+    });
+    if (signal.aborted)
+        return onAbort();
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(signal.reason);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+/**
+ * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → RAVN's fee
+ * payment (if any) → status polling, using caller-supplied signing/sending functions. The SDK
+ * stays wallet-agnostic (no RPC dependency); this just gets the ORDER right, which quickstart's
+ * own docs flag as the most common integration failure: sending the main tx before the approval
+ * has confirmed. A failed API call is retried where repeating it is safe (status polls and
+ * submitTransaction on a 429, 5xx or no response; execute and submitSignature only when rate
+ * limited), waiting the API's retryAfterSec. Once anything
+ * is sent, it rejects only with an ExecuteAndTrackError carrying every hash; `onProgress` hears
+ * each one first.
  */
 async function executeAndTrack(client, params, handlers, options = {}) {
-    const { pollUntilTerminal = true, pollIntervalMs = 4000 } = options;
-    const execution = await client.execute(params);
-    const { quoteToken } = execution;
-    const pollStatus = async (ref) => {
-        if (!pollUntilTerminal)
-            return undefined;
-        for (;;) {
-            const status = await client.getStatus(quoteToken, ref);
-            if ((0, polling_1.isPollingTerminal)(status.status))
-                return status;
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    const { pollUntilTerminal = true, pollIntervalMs = 4000, expiredPollIntervalMs = EXPIRED_POLL_INTERVAL_MS, maxWaitMs } = options;
+    const partial = {};
+    let sent = false;
+    const report = (stage, fields) => {
+        Object.assign(partial, fields);
+        try {
+            // An async hook (a database write) may reject: handled here too, never unhandled.
+            Promise.resolve(options.onProgress?.({ stage, partial: { ...partial } })).catch(() => { });
+        }
+        catch {
+            // The swap is out either way: a failing progress hook must not stop its fee or tracking.
         }
     };
-    // Sends and confirms an approval unless the caller already knows it's covered; see
-    // ExecuteAndTrackHandlers.hasAllowance's doc comment for why the API can't decide this itself.
-    const maybeSendApproval = async (approval) => {
-        if (!approval)
-            return undefined;
-        if (await handlers.hasAllowance?.(approval))
-            return undefined;
-        const hash = await handlers.sendTransaction(approval);
-        await handlers.waitForReceipt(hash, approval.chainId);
-        return hash;
+    // One signal for everything that waits: the caller's abort, or maxWaitMs once polling starts.
+    const stop = new AbortController();
+    let stopCode;
+    const halt = (code, reason) => {
+        if (stop.signal.aborted)
+            return;
+        stopCode = code;
+        stop.abort(reason);
     };
-    if (execution.executionType === "TRANSACTION" && execution.submit) {
-        // Never broadcast this one ourselves: a payment Layerswap can't match sits at Layerswap, and
-        // RAVN's check before sending is what catches it.
-        if (!handlers.signSolanaTransaction) {
-            throw new Error("executeAndTrack: this execution must be submitted through RAVN and requires signSolanaTransaction, none was provided");
+    const onAbort = () => halt("ABORTED", options.signal?.reason);
+    if (options.signal?.aborted)
+        onAbort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    let deadline;
+    // Before each step that asks the wallet for something: never send once stopped.
+    const checkpoint = () => {
+        if (stop.signal.aborted)
+            throw stop.signal.reason;
+    };
+    // Calls `call` until it succeeds, fails in a way `retryable` says repeating can't fix, or
+    // MAX_ATTEMPTS: waiting the API's retryAfterSec, else an interval doubling from pollIntervalMs.
+    const withRetries = async (call, retryable) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await call();
+            }
+            catch (err) {
+                if (attempt >= MAX_ATTEMPTS || !retryable(err))
+                    throw err;
+                const askedMs = (err.retryAfterSec ?? 0) * 1000;
+                await sleep(Math.max(askedMs, Math.min(pollIntervalMs * 2 ** (attempt - 1), MAX_BACKOFF_MS)), stop.signal);
+            }
         }
-        if (!execution.transaction.serialized) {
-            throw new Error("executeAndTrack: TRANSACTION execution with submit is missing transaction.serialized");
+    };
+    const run = async () => {
+        checkpoint();
+        // Only a rate limit: a BUILD_FAILED wants a fresh quote, and a repeat can open a second order
+        // at the venue (a NEAR deposit address, a Houdini or Garden order).
+        const execution = await withRetries(() => orAbort(client.execute(params), stop.signal), rateLimited);
+        const { quoteToken } = execution;
+        Object.assign(partial, { execution, quoteToken, statusRef: execution.statusRef });
+        const pollStatus = async (ref, txHash, feeSent = false) => {
+            if (!pollUntilTerminal)
+                return undefined;
+            if (maxWaitMs !== undefined) {
+                deadline = setTimeout(() => halt("TIMEOUT", new Error(`executeAndTrack: no terminal status within maxWaitMs (${maxWaitMs} ms)`)), maxWaitMs);
+            }
+            // A success answered before RAVN's node sees the fee tx proves nothing, and the row is then
+            // left to a cron that books no fee: one more poll after it.
+            // ponytail: one re-poll covers a block of lag; /v1/status also stays "processing" while a
+            // reported fee tx is unreadable (ravn-mvp #411).
+            for (let recheck = feeSent;;) {
+                checkpoint();
+                const status = await withRetries(() => orAbort(client.getStatus(quoteToken, ref, txHash, { signal: stop.signal }), stop.signal), transient);
+                report("status", { lastStatus: status });
+                if ((0, polling_1.isPollingTerminal)(status.status)) {
+                    if (!recheck || status.status !== "success")
+                        return status;
+                    recheck = false;
+                }
+                await sleep(status.status === "expired" ? expiredPollIntervalMs : pollIntervalMs, stop.signal);
+            }
+        };
+        // A sandbox execution is never real, but a venue with no sandbox stand-in returns its live
+        // payload: nothing in it is signed or sent (a signed order or Solana payment is a live
+        // instrument even though RAVN drops it). RAVN answers its status synthetically, for any ref.
+        if (execution.sandbox && execution.executionType !== "DEPOSIT") {
+            const statusRef = execution.statusRef ?? SANDBOX_REF;
+            return { execution, quoteToken, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        const signedTransaction = await handlers.signSolanaTransaction(execution.transaction.serialized);
-        const { txHash } = await client.submitTransaction({ quoteToken, signedTransaction });
-        const statusRef = execution.statusRef ?? txHash;
-        return { execution, quoteToken, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
-    }
-    if (execution.executionType === "TRANSACTION") {
-        const approvalTxHash = await maybeSendApproval(execution.approval);
-        const txHash = await handlers.sendTransaction(execution.transaction);
-        const statusRef = execution.statusRef ?? txHash;
-        return { execution, quoteToken, approvalTxHash, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
-    }
-    if (execution.executionType === "SIGNATURE") {
-        if (!handlers.signTypedData) {
-            throw new Error("executeAndTrack: this execution requires signTypedData, none was provided");
+        // The approval to send, if any: none when the caller already knows it's covered (see
+        // ExecuteAndTrackHandlers.hasAllowance).
+        const neededApproval = async (approval) => approval && !(handlers.hasAllowance && (await orAbort(handlers.hasAllowance(approval), stop.signal))) ? approval : undefined;
+        // Sends and confirms it, after its reset (approve to 0) when the token needs one first.
+        const maybeSendApproval = async (approval) => {
+            const needed = await neededApproval(approval);
+            if (!needed)
+                return undefined;
+            let hash = "";
+            for (const tx of needed.reset ? [{ ...needed.reset, chainId: needed.chainId }, needed] : [needed]) {
+                checkpoint();
+                hash = await handlers.sendTransaction(tx);
+                sent = true;
+                if (tx === needed)
+                    report("approval_sent", { approvalTxHash: hash });
+                else
+                    report("reset_sent", { resetTxHash: hash });
+                await orAbort(handlers.waitForReceipt(hash, needed.chainId), stop.signal);
+            }
+            return hash;
+        };
+        if (execution.executionType === "TRANSACTION" && execution.submit) {
+            // Never broadcast this one ourselves: a payment Layerswap can't match sits at Layerswap, and
+            // RAVN's check before sending is what catches it.
+            if (!handlers.signSolanaTransaction) {
+                throw new Error("executeAndTrack: this execution must be submitted through RAVN and requires signSolanaTransaction, none was provided");
+            }
+            if (!execution.transaction.serialized) {
+                throw new Error("executeAndTrack: TRANSACTION execution with submit is missing transaction.serialized");
+            }
+            const serialized = execution.transaction.serialized;
+            checkpoint();
+            const signedTransaction = await handlers.signSolanaTransaction(serialized);
+            checkpoint();
+            // From here RAVN may have sent it, even on a failed call. A retry with the same signed
+            // transaction never sends it twice, so retrying is how to find out; a failure that names
+            // the signature (BUILD_FAILED's details.txHash) is kept too.
+            sent = true;
+            report("swap_signed", { signedTransaction });
+            const submit = async () => {
+                try {
+                    return await client.submitTransaction({ quoteToken, signedTransaction });
+                }
+                catch (err) {
+                    const named = err instanceof types_1.RavnApiError ? err.details?.txHash : undefined;
+                    if (typeof named === "string")
+                        Object.assign(partial, { txHash: named, statusRef: execution.statusRef ?? named });
+                    throw err;
+                }
+            };
+            const { txHash } = await withRetries(submit, transient);
+            const statusRef = execution.statusRef ?? txHash;
+            report("swap_sent", { txHash, statusRef });
+            return { execution, quoteToken, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
+        }
+        if (execution.executionType === "TRANSACTION") {
+            // RAVN's fee, when the route has none of its own (Eco, Layerswap, Mayan plain MCTP). From
+            // Solana there's nothing to send: it's a transfer inside transaction.serialized.
+            const { approval, transaction } = execution;
+            const feeTx = execution.fee?.transaction;
+            // What proves the fee, from the first poll on: its own transaction, else (a statusRef: a
+            // two-hop route) hop 1's. Only an EVM tx hash: /v1/status refuses anything else (a Solana
+            // signature, a batch id) on every poll.
+            const proof = (swapHash, feeHash) => {
+                const hash = feeHash ?? (execution.statusRef ? swapHash : undefined);
+                return hash && EVM_TX_HASH.test(hash) ? hash : undefined;
+            };
+            let txHash;
+            let feeTxHash;
+            let feeError;
+            if (feeTx && BigInt(feeTx.value) === 0n && handlers.sendCalls) {
+                // A token fee may ride in the swap's own confirmation, and the swap's approval with it:
+                // atomic, so neither outlives a swap that reverted. Only here: ExecutionDTO doesn't name
+                // its venue, and the first-party app never batches THORChain (Bifrost ignores a router
+                // deposit whose tx.to is the user's own 7702 account) or Bebop (its settlement needs gas
+                // headroom a batch leaves to the wallet); fee-beside routes are neither.
+                const batchApproval = await neededApproval(approval);
+                const reset = batchApproval?.reset && { ...batchApproval.reset, chainId: batchApproval.chainId };
+                const approvals = batchApproval ? [...(reset ? [reset] : []), batchApproval] : [];
+                checkpoint();
+                const hashes = await handlers.sendCalls([...approvals, transaction, feeTx]);
+                // The wallet resolved, so something may be out: from here an error carries what's known.
+                sent = true;
+                // Fewer hashes back than calls: the last one carried the rest.
+                const carrier = (i) => hashes[Math.min(i, hashes.length - 1)];
+                if (!carrier(0))
+                    throw new Error("executeAndTrack: sendCalls returned no transaction hash");
+                txHash = carrier(approvals.length);
+                feeTxHash = carrier(approvals.length + 1);
+                if (reset)
+                    report("reset_sent", { resetTxHash: carrier(0) });
+                if (batchApproval)
+                    report("approval_sent", { approvalTxHash: carrier(approvals.length - 1) });
+                report("swap_sent", { txHash, statusRef: execution.statusRef ?? txHash, statusTxHash: proof(txHash) });
+                report("fee_sent", { feeTxHash, statusTxHash: proof(txHash, feeTxHash) });
+            }
+            else {
+                await maybeSendApproval(approval);
+                checkpoint();
+                txHash = await handlers.sendTransaction(transaction);
+                sent = true;
+                report("swap_sent", { txHash, statusRef: execution.statusRef ?? txHash, statusTxHash: proof(txHash) });
+                if (feeTx) {
+                    // On its own, only once the swap has confirmed: a reverted, dropped or replaced one pays
+                    // no fee. Declined or failed (or stopped first), the swap still runs and is tracked; no
+                    // fee is owed on it.
+                    try {
+                        if (!receiptSucceeded(await orAbort(handlers.waitForReceipt(txHash, transaction.chainId), stop.signal), txHash)) {
+                            throw new Error("executeAndTrack: no successful receipt for the swap transaction itself, so RAVN's fee was not sent");
+                        }
+                        checkpoint();
+                        feeTxHash = await handlers.sendTransaction(feeTx);
+                        report("fee_sent", { feeTxHash, statusTxHash: proof(txHash, feeTxHash) });
+                        // Confirmed before polling starts: a swap that fills first would otherwise end the
+                        // polling on the one poll that had to prove the fee.
+                        await orAbort(handlers.waitForReceipt(feeTxHash, feeTx.chainId), stop.signal);
+                    }
+                    catch (err) {
+                        feeError = err;
+                    }
+                }
+            }
+            // Stopped before or during the fee: say so, even with polling off (no fee was sent on it).
+            checkpoint();
+            const statusRef = execution.statusRef ?? txHash;
+            const statusTxHash = proof(txHash, feeTxHash);
+            if (feeTxHash && !statusTxHash) {
+                feeError ?? (feeError = new Error(`executeAndTrack: ${feeTxHash} is not an on-chain transaction hash, so RAVN can't prove the fee`));
+            }
+            partial.feeError = feeError;
+            return {
+                execution, quoteToken, resetTxHash: partial.resetTxHash, approvalTxHash: partial.approvalTxHash, txHash, statusRef, statusTxHash, feeTxHash, feeError,
+                finalStatus: await pollStatus(statusRef, statusTxHash, !!feeTxHash && !!statusTxHash),
+            };
+        }
+        if (execution.executionType === "SIGNATURE") {
+            if (!handlers.signTypedData) {
+                throw new Error("executeAndTrack: this execution requires signTypedData, none was provided");
+            }
+            if (!execution.typedData) {
+                throw new Error("executeAndTrack: SIGNATURE execution is missing typedData");
+            }
+            // A signed order isn't allowance-free: CoW's vault relayer and Bebop/0x's Permit2 still pull
+            // the sell token with transferFrom, so this on-chain allowance (separate from approvalData's
+            // gasless per-trade signature) must be confirmed before signing, otherwise the order is
+            // accepted and simply never fills, with no error to explain why.
+            const approvalTxHash = await maybeSendApproval(execution.approval);
+            checkpoint();
+            // Called as methods: a class-instance wallet needs its `this`.
+            const approvalSignature = execution.approvalData ? await handlers.signTypedData(execution.approvalData) : undefined;
+            checkpoint();
+            const signature = await handlers.signTypedData(execution.typedData);
+            checkpoint();
+            // From here the venue may take the order even when the call fails (BUILD_FAILED, no answer),
+            // so only a rate limit, refused before anything was placed, is retried.
+            sent = true;
+            report("swap_signed", { signature });
+            const { statusRef } = await withRetries(() => client.submitSignature({ quoteToken, signature, approvalSignature }), rateLimited);
+            report("swap_sent", { statusRef });
+            return { execution, quoteToken, resetTxHash: partial.resetTxHash, approvalTxHash, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        if (!execution.typedData) {
-            throw new Error("executeAndTrack: SIGNATURE execution is missing typedData");
+        // DEPOSIT: nothing to sign or send from here; the user moves funds to execution.deposit.address
+        // out-of-band, and this helper has no way to know when that happens. Returned without polling;
+        // start polling yourself (getStatus / useRavnStatus) once the deposit is actually sent. Pay
+        // `feePayment` as it says, pass an EVM fee transaction's hash as getStatus's `txHash`, and poll
+        // RAVN to a terminal status even if the venue's own tracker says delivered first.
+        // A fee it can't describe never stops the deposit, which fills without it.
+        checkpoint();
+        try {
+            return { execution, quoteToken, statusRef: execution.statusRef, feePayment: depositFeePayment(execution) };
         }
-        // A signed order isn't allowance-free: CoW's vault relayer and Bebop/0x's Permit2 still pull
-        // the sell token with transferFrom, so this on-chain allowance (separate from approvalData's
-        // gasless per-trade signature) must be confirmed before signing, otherwise the order is
-        // accepted and simply never fills, with no error to explain why.
-        const approvalTxHash = await maybeSendApproval(execution.approval);
-        let approvalSignature;
-        if (execution.approvalData) {
-            approvalSignature = await handlers.signTypedData(execution.approvalData);
+        catch (feeError) {
+            return { execution, quoteToken, statusRef: execution.statusRef, feeError };
         }
-        const signature = await handlers.signTypedData(execution.typedData);
-        const { statusRef } = await client.submitSignature({ quoteToken, signature, approvalSignature });
-        return { execution, quoteToken, approvalTxHash, statusRef, finalStatus: await pollStatus(statusRef) };
+    };
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (stopCode) {
+            const why = stopCode === "ABORTED" ? "aborted" : `no terminal status within maxWaitMs (${maxWaitMs} ms)`;
+            throw new ExecuteAndTrackError(`executeAndTrack: ${why}`, stopCode, { ...partial }, stop.signal.reason);
+        }
+        if (!sent)
+            throw err;
+        const why = err instanceof Error ? err.message : String(err);
+        throw new ExecuteAndTrackError(`executeAndTrack: ${why}`, "FAILED", { ...partial }, err);
+    }
+    finally {
+        clearTimeout(deadline);
+        options.signal?.removeEventListener("abort", onAbort);
     }
-    // DEPOSIT: nothing to sign or send from here; the user moves funds to execution.deposit.address
-    // out-of-band, and this helper has no way to know when that happens. Returned without polling;
-    // start polling yourself (getStatus / useRavnStatus) once the deposit is actually sent.
-    return { execution, quoteToken, statusRef: execution.statusRef };
 }

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { RavnClient } from "./client";
 export type { RavnClientConfig } from "./client";
 export * from "./types";
 export { isPollingTerminal } from "./polling";
-export { executeAndTrack } from "./execute-and-track";
-export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackResult, } from "./execute-and-track";
+export { depositFeePayment, executeAndTrack, ExecuteAndTrackError } from "./execute-and-track";
+export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackPartial, ExecuteAndTrackProgress, ExecuteAndTrackResult, ExecuteAndTrackStage, DepositFeePayment, TransactionReceiptLike, } from "./execute-and-track";

package/dist/index.js

@@ -14,11 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeAndTrack = exports.isPollingTerminal = exports.RavnClient = void 0;
+exports.ExecuteAndTrackError = exports.executeAndTrack = exports.depositFeePayment = exports.isPollingTerminal = exports.RavnClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "RavnClient", { enumerable: true, get: function () { return client_1.RavnClient; } });
 __exportStar(require("./types"), exports);
 var polling_1 = require("./polling");
 Object.defineProperty(exports, "isPollingTerminal", { enumerable: true, get: function () { return polling_1.isPollingTerminal; } });
 var execute_and_track_1 = require("./execute-and-track");
+Object.defineProperty(exports, "depositFeePayment", { enumerable: true, get: function () { return execute_and_track_1.depositFeePayment; } });
 Object.defineProperty(exports, "executeAndTrack", { enumerable: true, get: function () { return execute_and_track_1.executeAndTrack; } });
+Object.defineProperty(exports, "ExecuteAndTrackError", { enumerable: true, get: function () { return execute_and_track_1.ExecuteAndTrackError; } });

package/dist/polling.d.ts

@@ -1,7 +1,12 @@
 import type { SettlementStatus } from "./types";
 /**
- * Whether a status is done changing. "unknown" counts as terminal even though it isn't a real
- * outcome: it means the venue has no live tracker (see StatusDTO.tracking), so it will never
- * change and polling forever would just spin. Only "pending"/"processing" keep polling.
+ * Whether a status is done changing: "success", "refunded" and "failed", RAVN's own final states,
+ * plus "unknown", which isn't a real outcome but means the venue has no live tracker (see
+ * StatusDTO.tracking), so it will never change and polling forever would just spin. Everything
+ * else keeps polling: "expired" means the deal lapsed and a refund is due but hasn't landed
+ * (Across returns it in a later settlement bundle, hours on; poll it on a longer interval), and
+ * "not_found" that the venue has no record of this swap: brief right after sending (Relay indexes
+ * seconds behind the chain), otherwise permanent (the fill found isn't this quote's swap). RAVN
+ * keeps watching both; bound your own polling (executeAndTrack's maxWaitMs or signal).
  */
 export declare function isPollingTerminal(status: SettlementStatus): boolean;

package/dist/polling.js

@@ -2,10 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPollingTerminal = isPollingTerminal;
 /**
- * Whether a status is done changing. "unknown" counts as terminal even though it isn't a real
- * outcome: it means the venue has no live tracker (see StatusDTO.tracking), so it will never
- * change and polling forever would just spin. Only "pending"/"processing" keep polling.
+ * Whether a status is done changing: "success", "refunded" and "failed", RAVN's own final states,
+ * plus "unknown", which isn't a real outcome but means the venue has no live tracker (see
+ * StatusDTO.tracking), so it will never change and polling forever would just spin. Everything
+ * else keeps polling: "expired" means the deal lapsed and a refund is due but hasn't landed
+ * (Across returns it in a later settlement bundle, hours on; poll it on a longer interval), and
+ * "not_found" that the venue has no record of this swap: brief right after sending (Relay indexes
+ * seconds behind the chain), otherwise permanent (the fill found isn't this quote's swap). RAVN
+ * keeps watching both; bound your own polling (executeAndTrack's maxWaitMs or signal).
  */
 function isPollingTerminal(status) {
-    return status !== "pending" && status !== "processing";
+    return status === "success" || status === "refunded" || status === "failed" || status === "unknown";
 }

package/dist/types.d.ts

@@ -31,7 +31,12 @@ export interface QuoteDTO {
         amount: string;
     };
     /** `supported: false` means the venue has no fee mechanism at all (bps will be 0 either
-     * way); distinct from `supported: true, bps: 0`, a real, intentional zero fee. */
+     * way); distinct from `supported: true, bps: 0`, a real, intentional zero fee. On NEAR Intents
+     * `bps`/`amount` include 1Click's own fee, taken from the input on every swap with or without
+     * yours (the output already reflects it): 20 bps with no fee set (1 bp when both tokens are
+     * USDC, USDT or DAI, or the same asset), with yours half of it plus the larger of that half and
+     * 20 (1) bps, and its 20 (1) bps on top of RAVN's own fee beside a private swap: NEAR never
+     * shows `bps: 0`. */
     fee: {
         bps: number;
         amount: string;
@@ -132,9 +137,20 @@ export interface ApprovalDTO {
     spender?: string;
     amount: string;
     unlimitedRecommended?: boolean;
+    /** Send this first and wait for it to be mined, then the approval: `approve(spender, 0)`. Only on
+     * a token whose approve reverts on a change from one non-zero allowance to another (Ethereum
+     * USDT) when the sender holds a partial one. executeAndTrack does this. */
+    reset?: {
+        to: string;
+        data: string;
+        value: string;
+    };
 }
 export type ExecutionDTO = {
     executionType: "TRANSACTION";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
     /** Pass this, not the quote's own token, to getStatus. Compose: the post-bind token. */
     quoteToken: string;
     /** The venue's own tracking key (compose hop-2 handle, Garden order id, Relay request id).
@@ -156,19 +172,25 @@ export type ExecutionDTO = {
     };
     /**
      * Only when your key sets a fee and the route has no fee of its own (Eco, Layerswap, Mayan's
-     * routes paying no referrer): RAVN's fee, a transfer of the input token to RAVN;
-     * `transaction` already leaves it out. Skip it and the swap still fills; no fee is owed to
-     * you. With no `statusRef` here (you poll with the swap's own tx hash), a wallet that batches
-     * atomically (EIP-5792 `wallet_sendCalls`, one transaction) may send `fee.transaction` in the
-     * same batch as `transaction`, and the swap's tx proves it (an ERC-20 sell only: a native coin
-     * batched leaves nothing to read). Otherwise — including a batch the wallet splits into
-     * several transactions — send it as a transaction of its own from the user's regular wallet
-     * once the swap has confirmed, and pass its hash as `txHash` to getStatus. A fee paid on a
-     * swap the venue refunds stays with RAVN.
+     * routes paying no referrer) from an EVM chain: RAVN's fee, a transfer of the input token to
+     * RAVN; `transaction` already leaves it out. From Solana there is none to send: the fee is a
+     * transfer inside `transaction.serialized`. Skip it and the swap still fills; no fee is owed to
+     * you. A wallet that batches (EIP-5792 `wallet_sendCalls`) or relays (smart account, 7702,
+     * 4337) may send `fee.transaction` with `transaction` in one confirmation (one fee-bearing swap
+     * per transaction: a second fee in it isn't proven), for an ERC-20 sell
+     * (a native-coin fee must be a plain transaction of its own, so a contract wallet that can't
+     * send one — a Safe, a 4337 account — can't pay it). Pass the on-chain hash of the transaction
+     * that carried the fee (not an EIP-5792 batch id or a 4337 userOpHash) as `txHash` to getStatus
+     * — not needed with no `statusRef` here, when the fee rode in the swap's own transaction. Sent
+     * on its own, send it once the swap has confirmed. A fee paid on a swap the venue refunds
+     * stays with RAVN.
      */
     fee?: DepositFeeDTO;
 } | {
     executionType: "SIGNATURE";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
     /** Pass this, not the quote's own token, to submitSignature and getStatus. */
     quoteToken: string;
     statusRef?: string;
@@ -181,6 +203,9 @@ export type ExecutionDTO = {
     };
 } | {
     executionType: "DEPOSIT";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
     /** Pass this, not the quote's own token, to getStatus. */
     quoteToken: string;
     /** `expiresAt` (ISO 8601), when set, is when the deposit must have ARRIVED (confirmed on
@@ -194,9 +219,9 @@ export type ExecutionDTO = {
     /** Poll getStatus with this, not `deposit.address`. */
     statusRef: string;
     /** Only when your key sets a fee and the venue has no fee of its own (Rift; private swaps from
-     * an EVM chain or Bitcoin). Skip it and the swap still fills on `deposit.amount`; no fee is
-     * owed to you. A fee paid on a swap the venue then refunds stays with RAVN and nothing is owed
-     * on it, so send an EVM fee payment once the deposit has confirmed. */
+     * an EVM chain, Bitcoin or Solana). Skip it and the swap still fills on `deposit.amount`; no
+     * fee is owed to you. A fee paid on a swap the venue then refunds stays with RAVN and nothing
+     * is owed on it, so send an EVM fee payment once the deposit has confirmed. */
     fee?: DepositFeeDTO;
 };
 /** RAVN's integrator fee beside a deposit (or a transaction), in the input token, paid by your user
@@ -207,12 +232,28 @@ export interface DepositFeeDTO {
     /** RAVN's fee address on the input chain. */
     address: string;
     chainId: number;
-    /** EVM: send this transaction too, exactly as given and as a transaction of its own from the
-     * user's regular wallet (it names the order, which ties the fee to this swap; bundled into a
-     * smart-wallet batch it can't be proven, and nothing is owed on it), then pass its hash as
-     * `txHash` to getStatus once it has confirmed (simplest: on every poll). Absent on Bitcoin: pay `amount` to `address`
-     * as an extra output of the SAME transaction that pays the deposit; RAVN finds it there once
-     * that transaction confirms. One deposit per Bitcoin transaction: a fee output proves one swap. */
+    /** EVM: send this transaction too, exactly as given (it carries a tag naming this swap): on its
+     * own, or in the same wallet batch or relay as the deposit or swap (EIP-5792, smart account, 7702,
+     * 4337) — an ERC-20 fee anywhere; a native-coin fee only beside a NEAR Intents deposit on
+     * Ethereum, Base or Polygon (proven from those chains' internal transfers). Any other native-coin
+     * fee must be a plain transaction of its own (a contract wallet that can't send one can't pay it).
+     * Then pass the on-chain hash of the transaction that carried it (not a batch id or a userOpHash)
+     * as `txHash` to getStatus once it has confirmed (simplest: on every poll). One fee-bearing swap
+     * per transaction: a batch carrying two fees, or a fee beside another fee-bearing swap, proves only
+     * one. Batch a token deposit, or a native-coin deposit to NEAR Intents (it credits coin a smart
+     * account moves); send any other native-coin deposit as a plain transfer, as an exchange may not
+     * credit coin a contract moved. Absent on Bitcoin:
+     * pay `amount` to `address` as an extra output of the SAME transaction that pays the deposit;
+     * RAVN finds it there once that transaction confirms. One deposit per Bitcoin transaction: a fee
+     * output proves one swap. Absent on Solana too: add the fee to the SAME transaction that pays the
+     * deposit exactly `deposit.amount` (SOL as lamports to the deposit wallet, not wrapped) — SOL: a
+     * System transfer of `amount` lamports to `address`; a token: `transferChecked` of `amount` to
+     * `address`'s associated token account for the input mint (under the mint's token program), after
+     * `createAssociatedTokenAccountIdempotent` in case RAVN has none for that token yet (its rent,
+     * ~0.0015 SOL once per token, is normally in the quote's network cost). RAVN finds it there once
+     * that transaction is finalized, among the deposit address's first and latest transactions; a fee
+     * sent in a transaction of its own isn't found. One deposit per Solana transaction: a fee proves
+     * one swap. It can't be sent after the deposit, so on a swap the venue refunds it stays with RAVN. */
     transaction?: {
         to: string;
         data: string;
@@ -249,8 +290,22 @@ export interface GetQuoteParams {
      * carry slippage.noMinimum: true and guaranteedMin: null; slippageBps does not protect them. */
     allowNoMinimum?: boolean;
     rankingMode?: "best_output" | "fastest";
+    /** The race's time limit in ms, counted from its start: once it has passed and some venue has
+     * priced the swap, slower venues are left out (with none priced yet, the first price ends the
+     * wait; a quote with slippage.noMinimum counts only 2000 ms past the limit). A positive integer;
+     * default 6000, clamped to 1000–15000. An API that predates it ignores it. */
+    timeoutMs?: number;
     /** Drop specific venues from this race, e.g. a risk objection to one of them. */
     excludeVenues?: string[];
+    /** Race only these venues, e.g. ["bebop"] for an RFQ-only race. Every other venue is left
+     * out, including ones RAVN adds later; excludeVenues still applies on top. Matches the quote's
+     * venue.id, the venue you deal with, not every venue funds pass through: RAVN's multi-step
+     * routes (compose, relay quotes with hops) and venues such as Rift, Across (swapping before or
+     * after bridging) and Mayan (a Solana order starting in another token swaps through Jupiter
+     * first) route through others. An empty list is
+     * rejected (INVALID_REQUEST); if none of them can quote, NO_LIQUIDITY lists every left-out
+     * venue in error.details.excludedVenues. */
+    onlyVenues?: string[];
     /** Settle privately: the race narrows to NEAR Intents (Confidential Intents) and Houdini Swap,
      * and NO_LIQUIDITY replaces a public fill if neither can quote. Houdini is sent the request's IP,
      * user-agent and clientTimezone for compliance screening; its terms bar US persons and
@@ -295,10 +350,25 @@ export interface ErrorMeta {
     requestId: string;
     version: string;
 }
-/** Thrown for every non-2xx response. `code` is the stable, machine-readable string from the API. */
+/** Every `code` the API sends (see the API's Errors page), plus NETWORK_ERROR: no response came
+ * back at all (offline, DNS, CORS, a dropped connection). New codes can appear: compare against
+ * these, don't switch on them exhaustively. */
+export type RavnErrorCode = "INVALID_REQUEST" | "UNSUPPORTED_TOKEN" | "UNSUPPORTED_CHAIN" | "NO_LIQUIDITY" | "QUOTE_EXPIRED" | "QUOTE_INVALID" | "QUOTE_NOT_EXECUTABLE" | "RATE_LIMITED" | "UNAUTHORIZED" | "NOT_CONFIGURED" | "NOT_FOUND" | "BUILD_FAILED" | "VENUE_RATE_LIMITED" | "ORDER_REJECTED" | "INTERNAL" | "NETWORK_ERROR";
+/** Thrown for every failed call: a non-2xx response, or none at all (NETWORK_ERROR). `code` is the
+ * stable, machine-readable string from the API. */
 export declare class RavnApiError extends Error {
-    readonly code: string;
+    readonly code: RavnErrorCode | (string & {});
     readonly details: unknown;
     readonly meta: ErrorMeta | undefined;
-    constructor(code: string, message: string, details: unknown, meta: ErrorMeta | undefined);
+    /** The HTTP status; undefined when no response came back (NETWORK_ERROR). */
+    readonly status?: number;
+    /** Seconds the API asked you to wait before trying the same call again (`details.retryAfterSec`,
+     * sent with RATE_LIMITED and VENUE_RATE_LIMITED). */
+    readonly retryAfterSec?: number;
+    /** NETWORK_ERROR: the fetch error underneath. */
+    readonly cause?: unknown;
+    constructor(code: RavnErrorCode | (string & {}), message: string, details: unknown, meta: ErrorMeta | undefined, init?: {
+        status?: number;
+        cause?: unknown;
+    });
 }

package/dist/types.js

@@ -8,14 +8,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RavnApiError = void 0;
-/** Thrown for every non-2xx response. `code` is the stable, machine-readable string from the API. */
+/** Thrown for every failed call: a non-2xx response, or none at all (NETWORK_ERROR). `code` is the
+ * stable, machine-readable string from the API. */
 class RavnApiError extends Error {
-    constructor(code, message, details, meta) {
+    constructor(code, message, details, meta, init = {}) {
         super(message);
         this.code = code;
         this.details = details;
         this.meta = meta;
         this.name = "RavnApiError";
+        this.status = init.status;
+        const retryAfterSec = details?.retryAfterSec;
+        this.retryAfterSec = typeof retryAfterSec === "number" ? retryAfterSec : undefined;
+        if (init.cause !== undefined)
+            this.cause = init.cause;
     }
 }
 exports.RavnApiError = RavnApiError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravnexchange/sdk",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "description": "Typed client for the RAVN integrator API (/api/v1): quote, execute, submit-signature, status.",
   "keywords": ["ravn", "cross-chain", "swap", "swap-api", "dex-aggregator", "bitcoin", "native-btc", "solana", "evm", "crypto", "defi", "typescript", "sdk", "api-client"],
   "main": "./dist/index.js",