@ravnexchange/sdk 0.1.13 → 0.1.15

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;
@@ -8,14 +8,28 @@ type TxLike = {
     serialized?: 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.
+     * this helper exists to prevent. Also called on the swap before RAVN's fee is sent on its own
+     * (`fee.transaction`): resolve to the receipt itself (viem's `waitForTransactionReceipt`,
+     * ethers' `wait()`), as the fee is only sent when it says success AND is this hash's own (a
+     * cancelled or replaced swap resolves with another transaction's). Resolving to nothing, or
+     * anything else, 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<unknown>;
+    /**
+     * 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 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; a native-coin fee is always a plain transaction of its own. 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}`>;
     /**
@@ -34,7 +48,8 @@ export interface ExecuteAndTrackHandlers {
     hasAllowance?(approval: ApprovalDTO): Promise<boolean>;
 }
 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;
     pollIntervalMs?: number;
 }
@@ -48,14 +63,62 @@ 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;
 }
+/** 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.
  */
 export declare function executeAndTrack(client: RavnClient, params: ExecuteParams, handlers: ExecuteAndTrackHandlers, options?: ExecuteAndTrackOptions): Promise<ExecuteAndTrackResult>;
 export {};

package/dist/execute-and-track.js

@@ -1,24 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.depositFeePayment = depositFeePayment;
 exports.executeAndTrack = executeAndTrack;
 const polling_1 = require("./polling");
+const BITCOIN_CHAIN_ID = -1;
+const SOLANA_CHAIN_ID = -2;
+const EVM_TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+/** 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.
+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());
+};
 /**
- * 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.
  */
 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) => {
+    const pollStatus = async (ref, txHash, feeSent = false) => {
         if (!pollUntilTerminal)
             return undefined;
-        for (;;) {
-            const status = await client.getStatus(quoteToken, ref);
-            if ((0, polling_1.isPollingTerminal)(status.status))
-                return status;
+        // 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; the real fix is /v1/status staying non-terminal
+        // while a given fee tx is unproven.
+        for (let recheck = feeSent;;) {
+            const status = await client.getStatus(quoteToken, ref, txHash);
+            if ((0, polling_1.isPollingTerminal)(status.status)) {
+                if (!recheck || status.status !== "success")
+                    return status;
+                recheck = false;
+            }
             await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
         }
     };
@@ -49,9 +82,53 @@ async function executeAndTrack(client, params, handlers, options = {}) {
     }
     if (execution.executionType === "TRANSACTION") {
         const approvalTxHash = await maybeSendApproval(execution.approval);
-        const txHash = await handlers.sendTransaction(execution.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 feeTx = execution.fee?.transaction;
+        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: atomic, so it never outlives a swap
+            // that reverted. One hash back means one transaction carried both.
+            const [swapHash, feeHash = swapHash] = await handlers.sendCalls([execution.transaction, feeTx]);
+            if (!swapHash)
+                throw new Error("executeAndTrack: sendCalls returned no transaction hash");
+            txHash = swapHash;
+            feeTxHash = feeHash;
+        }
+        else {
+            txHash = await handlers.sendTransaction(execution.transaction);
+            if (feeTx) {
+                // On its own, only once the swap has confirmed: a reverted, dropped or replaced one pays
+                // no fee. Declined or failed, the swap still runs and is tracked; no fee is owed on it.
+                try {
+                    if (!receiptSucceeded(await handlers.waitForReceipt(txHash, execution.transaction.chainId), txHash)) {
+                        throw new Error("executeAndTrack: no successful receipt for the swap transaction itself, so RAVN's fee was not sent");
+                    }
+                    feeTxHash = await handlers.sendTransaction(feeTx);
+                    // 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 handlers.waitForReceipt(feeTxHash, feeTx.chainId);
+                }
+                catch (err) {
+                    feeError = err;
+                }
+            }
+        }
         const statusRef = execution.statusRef ?? txHash;
-        return { execution, quoteToken, approvalTxHash, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
+        // 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 = feeTxHash ?? (execution.statusRef ? txHash : undefined);
+        const statusTxHash = proof && EVM_TX_HASH.test(proof) ? proof : undefined;
+        if (feeTxHash && !statusTxHash) {
+            feeError ?? (feeError = new Error(`executeAndTrack: ${feeTxHash} is not an on-chain transaction hash, so RAVN can't prove the fee`));
+        }
+        return {
+            execution, quoteToken, approvalTxHash, txHash, statusRef, statusTxHash, feeTxHash, feeError,
+            finalStatus: await pollStatus(statusRef, statusTxHash, !!feeTxHash && !!statusTxHash),
+        };
     }
     if (execution.executionType === "SIGNATURE") {
         if (!handlers.signTypedData) {
@@ -75,6 +152,14 @@ async function executeAndTrack(client, params, handlers, options = {}) {
     }
     // 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 };
+    // 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.
+    try {
+        return { execution, quoteToken, statusRef: execution.statusRef, feePayment: depositFeePayment(execution) };
+    }
+    catch (feeError) {
+        return { execution, quoteToken, statusRef: execution.statusRef, feeError };
+    }
 }

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 } from "./execute-and-track";
+export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackResult, DepositFeePayment, } from "./execute-and-track";

package/dist/index.js

@@ -14,11 +14,12 @@ 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.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; } });

package/dist/types.d.ts

@@ -154,6 +154,22 @@ export type ExecutionDTO = {
     submit?: {
         url: string;
     };
+    /**
+     * Only when your key sets a fee and the route has no fee of its own (Eco, Layerswap, Mayan's
+     * 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";
     /** Pass this, not the quote's own token, to submitSignature and getStatus. */
@@ -180,24 +196,42 @@ 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 (today Rift). Skip it
-     * and the swap still fills on `deposit.amount`; no fee is owed to you. */
+    /** Only when your key sets a fee and the venue has no fee of its own (Rift; private swaps from
+     * 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, in the input token, paid by your user to RAVN; your
- * share is paid out as usual. `deposit.amount` already leaves it out. */
+/** RAVN's integrator fee beside a deposit (or a transaction), in the input token, paid by your user
+ * to RAVN; your share is paid out as usual. `deposit.amount` (the transaction) already leaves it out. */
 export interface DepositFeeDTO {
     /** Base units of the input token. */
     amount: string;
     /** 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. */
+    /** 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;
@@ -236,6 +270,15 @@ export interface GetQuoteParams {
     rankingMode?: "best_output" | "fastest";
     /** 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravnexchange/sdk",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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",