@ravnexchange/sdk 0.2.3 → 0.2.5

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

@@ -39,9 +39,13 @@ export interface ExecuteAndTrackHandlers {
      * (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
+     * TRANSACTION's native-coin fee only when its `batch` says so (a coin sell's fee minted to RAVN as
+     * WETH, Robinhood Chain and Arbitrum), else a plain transaction of its own (with sendDeposit, a
+     * DEPOSIT's calls go together only when its `batch` says so). 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.
+     * the whole batch (no fee leaves without the swap). A heavy swap needs the most: Fly's on
+     * Robinhood Chain measured 430–560k gas (2026-10-20). 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. */
@@ -51,6 +55,20 @@ export interface ExecuteAndTrackHandlers {
      * TRANSACTION carrying `submit` (broadcastViaRavn quotes), which RAVN checks and sends itself.
      */
     signSolanaTransaction?(serialized: string): Promise<string>;
+    /**
+     * With `sendDeposit`: sign a Bitcoin DEPOSIT's ready-made PSBT (`deposit.psbt`, base64: the
+     * deposit, RAVN's fee as a second output, change back to the sender), finalize and broadcast it,
+     * and return its txid. Reject only when nothing was broadcast: a rejection loses its hash, and
+     * executeAndTrack called again builds a new deposit.
+     */
+    sendBitcoinPsbt?(psbt: string): Promise<string>;
+    /**
+     * With `sendDeposit`: sign a Solana DEPOSIT's ready-made transaction (`deposit.transaction`,
+     * base64: the deposit and RAVN's fee) and send it, returning its signature. It must land within
+     * about a minute of execute (its blockhash expires). Reject only when nothing was sent: a
+     * rejection loses its signature, and executeAndTrack called again builds a new deposit.
+     */
+    sendSolanaTransaction?(serialized: string): Promise<string>;
     /**
      * The API sends `approval` whenever the venue generically needs an allowance: it deliberately
      * never reads the chain to check whether the caller already has one (that's an RPC round-trip
@@ -89,6 +107,17 @@ export interface ExecuteAndTrackOptions {
      * 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;
+    /**
+     * Send a DEPOSIT too, from the ready-to-sign payload RAVN returns with RAVN's fee inside it, then
+     * track it like any swap: EVM `calls` (sendCalls when `batch` allows, else the deposit, its
+     * receipt, then the fee), Bitcoin `deposit.psbt` (sendBitcoinPsbt), Solana `deposit.transaction`
+     * (sendSolanaTransaction). A deposit it can't send (no such payload, e.g. a Bitcoin sender that
+     * isn't bc1q…, or no handler for its chain) comes back unsent, as without this option, with
+     * `depositNotSent` saying why: send that one and `feePayment` yourself. Default false: a deposit
+     * is never sent from here. Turning it on, send a deposit yourself only when `depositNotSent` is
+     * set, or the user pays twice (a sandbox one has neither it nor `txHash`: it's never sent).
+     */
+    sendDeposit?: boolean;
     /** 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;
@@ -118,9 +147,12 @@ export interface ExecuteAndTrackResult {
     /** 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). */
+    /** DEPOSIT only: the fee payment to make beside the deposit (see depositFeePayment). Absent once
+     * sendDeposit sent the deposit: its fee went with it. */
     feePayment?: DepositFeePayment;
-    /** Set once pollUntilTerminal reaches a terminal status. Absent for DEPOSIT (see below) or when polling is turned off. */
+    /** With sendDeposit, a DEPOSIT it didn't send, and why: send it and `feePayment` yourself. */
+    depositNotSent?: string;
+    /** Set once pollUntilTerminal reaches a terminal status. Absent for a DEPOSIT this didn't send, or when polling is turned off. */
     finalStatus?: StatusDTO;
 }
 /** What executeAndTrack knew when it reported progress or stopped: every hash sent so far, and the

package/dist/execute-and-track.js

@@ -192,7 +192,7 @@ async function executeAndTrack(client, params, handlers, options = {}) {
         // 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") {
+        if (execution.sandbox && (execution.executionType !== "DEPOSIT" || options.sendDeposit)) {
             const statusRef = execution.statusRef ?? SANDBOX_REF;
             return { execution, quoteToken, statusRef, finalStatus: await pollStatus(statusRef) };
         }
@@ -217,6 +217,26 @@ async function executeAndTrack(client, params, handlers, options = {}) {
             }
             return hash;
         };
+        // RAVN's fee on its own, only once `hash` (the swap, or the deposit) 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. Confirmed before polling starts: a swap that fills
+        // first would otherwise end the polling on the one poll that had to prove the fee.
+        const sendFeeAfter = async (hash, chainId, fee, statusTxHash) => {
+            let feeTxHash;
+            try {
+                if (!receiptSucceeded(await orAbort(handlers.waitForReceipt(hash, chainId), stop.signal), hash)) {
+                    throw new Error("executeAndTrack: no successful receipt for the swap (or deposit) transaction itself, so RAVN's fee was not sent");
+                }
+                checkpoint();
+                feeTxHash = await handlers.sendTransaction(fee);
+                report("fee_sent", { feeTxHash, statusTxHash: statusTxHash(feeTxHash) });
+                await orAbort(handlers.waitForReceipt(feeTxHash, fee.chainId), stop.signal);
+                return { feeTxHash };
+            }
+            catch (feeError) {
+                return { feeTxHash, feeError };
+            }
+        };
         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.
@@ -266,12 +286,13 @@ async function executeAndTrack(client, params, handlers, options = {}) {
             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.
+            // RAVN says whether the fee may share the swap's confirmation (`batch`): a token fee, or a coin
+            // sell's fee minted to RAVN as WETH (a coin sent from a batch is an internal transfer, which
+            // proves nothing on those chains), never at a venue that can't take a batch (THORChain, Bebop,
+            // a two-hop route). An API answering without `batch` (before calls + batch): a token fee only.
+            const batchFee = execution.batch ?? BigInt(feeTx?.value ?? "1") === 0n;
+            if (feeTx && batchFee && handlers.sendCalls) {
+                // Atomic, so neither the fee nor the swap's approval outlives a swap that reverted.
                 const batchApproval = await neededApproval(approval);
                 const reset = batchApproval?.reset && { ...batchApproval.reset, chainId: batchApproval.chainId };
                 const approvals = batchApproval ? [...(reset ? [reset] : []), batchApproval] : [];
@@ -298,25 +319,8 @@ async function executeAndTrack(client, params, handlers, options = {}) {
                 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;
-                    }
-                }
+                if (feeTx)
+                    ({ feeTxHash, feeError } = await sendFeeAfter(txHash, transaction.chainId, feeTx, (f) => proof(txHash, f)));
             }
             // Stopped before or during the fee: say so, even with polling off (no fee was sent on it).
             checkpoint();
@@ -357,19 +361,97 @@ async function executeAndTrack(client, params, handlers, options = {}) {
             report("swap_sent", { statusRef });
             return { execution, quoteToken, resetTxHash: partial.resetTxHash, approvalTxHash, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        // 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.
+        // DEPOSIT, unsent: 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.
+        const { statusRef, deposit, calls, fee } = execution;
+        const unsent = (depositNotSent) => {
+            const base = { execution, quoteToken, statusRef, ...(depositNotSent ? { depositNotSent } : {}) };
+            try {
+                return { ...base, feePayment: depositFeePayment(execution) };
+            }
+            catch (feeError) {
+                return { ...base, feeError };
+            }
+        };
         checkpoint();
-        try {
-            return { execution, quoteToken, statusRef: execution.statusRef, feePayment: depositFeePayment(execution) };
+        if (!options.sendDeposit)
+            return unsent();
+        // Typed away, but a newer API can answer with a type this version doesn't know: never sent.
+        const type = execution.executionType;
+        if (type !== "DEPOSIT")
+            return unsent(`executionType ${type} isn't one this SDK version can send`);
+        // sendDeposit: from the payload RAVN built, RAVN's fee inside it.
+        if (calls?.length) {
+            const feeTx = fee?.transaction;
+            const [depositTx, ...rest] = calls;
+            // As RAVN builds them: deposit.amount to deposit.address (the coin, or the token's
+            // transfer(address,uint256) call), then the fee exactly as given.
+            const same = (a, b) => a.to?.toLowerCase() === b.to?.toLowerCase() && a.data?.toLowerCase() === b.data?.toLowerCase() && BigInt(a.value ?? "0") === BigInt(b.value ?? "0");
+            const to = deposit.address.toLowerCase();
+            const amount = BigInt(deposit.amount);
+            const value = BigInt(depositTx.value ?? "0");
+            const paysDeposit = (value === amount && depositTx.to?.toLowerCase() === to && (depositTx.data ?? "0x") === "0x") ||
+                (value === 0n && depositTx.data?.toLowerCase() === `0xa9059cbb${to.slice(2).padStart(64, "0")}${amount.toString(16).padStart(64, "0")}`);
+            if (!paysDeposit || (feeTx ? !(rest.length === 1 && same(rest[0], feeTx)) : rest.length !== 0)) {
+                return unsent("its calls aren't the deposit of deposit.amount to deposit.address, then RAVN's fee as given");
+            }
+            const evmHash = (hash) => (EVM_TX_HASH.test(hash) ? hash : undefined);
+            let txHash;
+            let feeTxHash;
+            let feeError;
+            checkpoint();
+            if (feeTx && execution.batch && handlers.sendCalls) {
+                const hashes = await handlers.sendCalls(calls);
+                sent = true;
+                // Fewer hashes back than calls: the last one carried the rest.
+                if (!hashes[0])
+                    throw new Error("executeAndTrack: sendCalls returned no transaction hash");
+                txHash = hashes[0];
+                feeTxHash = hashes[Math.min(1, hashes.length - 1)];
+                report("swap_sent", { txHash, statusRef });
+                report("fee_sent", { feeTxHash, statusTxHash: evmHash(feeTxHash) });
+            }
+            else {
+                txHash = await handlers.sendTransaction(depositTx);
+                sent = true;
+                report("swap_sent", { txHash, statusRef });
+                if (feeTx)
+                    ({ feeTxHash, feeError } = await sendFeeAfter(txHash, depositTx.chainId, feeTx, evmHash));
+            }
+            checkpoint();
+            const statusTxHash = feeTxHash && evmHash(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, txHash, statusRef, statusTxHash, feeTxHash, feeError,
+                finalStatus: await pollStatus(statusRef, statusTxHash, !!statusTxHash),
+            };
         }
-        catch (feeError) {
-            return { execution, quoteToken, statusRef: execution.statusRef, feeError };
+        // Bitcoin and Solana: one transaction pays the deposit and RAVN's fee; RAVN finds the fee there.
+        const payload = deposit.psbt ?? deposit.transaction;
+        if (!payload) {
+            const chainId = deposit.chainId ?? fee?.chainId;
+            return unsent(chainId === BITCOIN_CHAIN_ID
+                ? "RAVN returned no PSBT for it (it builds one only from a bc1q… userAddress, when it can within a few seconds)"
+                : chainId === SOLANA_CHAIN_ID
+                    ? "RAVN returned no transaction for it (it builds one only for a deposit carrying RAVN's fee, when it can within a few seconds)"
+                    : "RAVN returned nothing ready to sign for it");
         }
+        const handler = deposit.psbt ? "sendBitcoinPsbt" : "sendSolanaTransaction";
+        if (!handlers[handler])
+            return unsent(`no ${handler} handler was provided`);
+        checkpoint();
+        // Called as a method: a class-instance wallet needs its `this`.
+        const txHash = await handlers[handler](payload);
+        sent = true;
+        report("swap_sent", { txHash, statusRef });
+        return { execution, quoteToken, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
     };
     try {
         return await run();

package/dist/types.d.ts

@@ -175,25 +175,28 @@ 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) 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.
+     * routes paying no referrer, Fly Trade's coin sells where its own fee can't be proven:
+     * Robinhood Chain, Arbitrum and others) from an EVM chain: RAVN's fee, a transfer of the input
+     * token to RAVN, or on Robinhood Chain and Arbitrum a coin sell's fee as WETH minted to RAVN
+     * (the coin sent to WETH's `depositTo`; `fee.token` in the quote is WETH); `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, or a coin sell whose fee
+     * is WETH minted to RAVN (`batch` true; a native-coin fee must otherwise 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;
     /** EVM: everything to send, in order (approval.reset, approval, the swap or the deposit
      * transfer, RAVN's fee). Each once the one before has succeeded (stop if one reverts), or, when
      * `batch` is true, all in one atomic wallet batch (EIP-5792 `wallet_sendCalls`,
      * `atomicRequired: true`): simulate it first, and send them one by one if that fails or the
-     * last call needs more than ~400k gas. */
+     * swap's call needs more than ~400k gas. */
     calls?: CallDTO[];
     /** Whether `calls` (more than one) may go in one atomic wallet batch. */
     batch?: boolean;
@@ -249,7 +252,7 @@ export type ExecutionDTO = {
      * transfer, RAVN's fee). Each once the one before has succeeded (stop if one reverts), or, when
      * `batch` is true, all in one atomic wallet batch (EIP-5792 `wallet_sendCalls`,
      * `atomicRequired: true`): simulate it first, and send them one by one if that fails or the
-     * last call needs more than ~400k gas. */
+     * swap's call needs more than ~400k gas. */
     calls?: CallDTO[];
     /** Whether `calls` (more than one) may go in one atomic wallet batch. */
     batch?: boolean;
@@ -264,14 +267,17 @@ export interface CallDTO {
 /** 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. */
+    /** Base units of the input token (the same in WETH, 18 decimals, where a coin sell's fee is
+     * minted as WETH). */
     amount: string;
     /** RAVN's fee address on the input chain. */
     address: string;
     chainId: number;
     /** 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
+     * 4337) — an ERC-20 fee anywhere, and a coin sell's fee minted to RAVN as WETH (Robinhood Chain,
+     * Arbitrum: the coin sent to WETH's `depositTo`, booked and paid out in WETH, proven by WETH's
+     * Transfer log wherever it rides); 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)

package/package.json

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