@bananapus/nana-sdk-core 3.2.0 → 3.4.1

package/dist/cjs/v6/index.js

@@ -14,7 +14,7 @@ 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.getDefifaHoldings = void 0;
+exports.getDefifaHoldings = exports.payRetrySlippageBps = exports.PAY_MAX_SLIPPAGE_BPS = exports.decodePayFailure = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./currency.js"), exports);
 __exportStar(require("./fees.js"), exports);
@@ -30,12 +30,17 @@ __exportStar(require("./priceFeeds.js"), exports);
 __exportStar(require("./permit2.js"), exports);
 __exportStar(require("./projectPayers.js"), exports);
 __exportStar(require("./cashOut.js"), exports);
+var executionErrors_js_1 = require("./executionErrors.js");
+Object.defineProperty(exports, "decodePayFailure", { enumerable: true, get: function () { return executionErrors_js_1.decodePayFailure; } });
+Object.defineProperty(exports, "PAY_MAX_SLIPPAGE_BPS", { enumerable: true, get: function () { return executionErrors_js_1.PAY_MAX_SLIPPAGE_BPS; } });
+Object.defineProperty(exports, "payRetrySlippageBps", { enumerable: true, get: function () { return executionErrors_js_1.payRetrySlippageBps; } });
 __exportStar(require("./nft.js"), exports);
 __exportStar(require("./nftInventory.js"), exports);
 __exportStar(require("./defifa.js"), exports);
 var defifaHoldings_js_1 = require("./defifaHoldings.js");
 Object.defineProperty(exports, "getDefifaHoldings", { enumerable: true, get: function () { return defifaHoldings_js_1.getDefifaHoldings; } });
 __exportStar(require("./tokens.js"), exports);
+__exportStar(require("./uniswapV3.js"), exports);
 __exportStar(require("./uniswapV4.js"), exports);
 __exportStar(require("./uniswapV4Fees.js"), exports);
 __exportStar(require("./permissions.js"), exports);

package/dist/cjs/v6/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v6/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,gDAA8B;AAC9B,4CAA0B;AAC1B,8CAA4B;AAC5B,iDAA+B;AAC/B,gDAA8B;AAC9B,8CAA4B;AAC5B,qDAAmC;AACnC,+CAA6B;AAC7B,iDAA+B;AAC/B,2CAAyB;AACzB,kDAAgC;AAChC,+CAA6B;AAC7B,qDAAmC;AACnC,+CAA6B;AAC7B,2CAAyB;AACzB,oDAAkC;AAClC,8CAA4B;AAC5B,yDAI6B;AAH3B,sHAAA,iBAAiB,OAAA;AAInB,8CAA4B;AAC5B,iDAA+B;AAC/B,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,6CAA2B;AAC3B,8CAA4B;AAC5B,iDAA+B;AAC/B,6DAA2C;AAC3C,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/v6/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,gDAA8B;AAC9B,4CAA0B;AAC1B,8CAA4B;AAC5B,iDAA+B;AAC/B,gDAA8B;AAC9B,8CAA4B;AAC5B,qDAAmC;AACnC,+CAA6B;AAC7B,iDAA+B;AAC/B,2CAAyB;AACzB,kDAAgC;AAChC,+CAA6B;AAC7B,qDAAmC;AACnC,+CAA6B;AAC7B,2DAO8B;AAN5B,sHAAA,gBAAgB,OAAA;AAChB,0HAAA,oBAAoB,OAAA;AACpB,yHAAA,mBAAmB,OAAA;AAKrB,2CAAyB;AACzB,oDAAkC;AAClC,8CAA4B;AAC5B,yDAI6B;AAH3B,sHAAA,iBAAiB,OAAA;AAInB,8CAA4B;AAC5B,iDAA+B;AAC/B,iDAA+B;AAC/B,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,6CAA2B;AAC3B,8CAA4B;AAC5B,iDAA+B;AAC/B,6DAA2C;AAC3C,qDAAmC"}

package/dist/cjs/v6/pay.d.ts

@@ -122,29 +122,50 @@ export interface PreparedUserPay {
     preview: PayPreview;
     minReturnedTokens: bigint;
 }
+/** `prepareUserPay`'s tolerance on its quote and fallback minimum: 1%. */
+export declare const PAY_DEFAULT_SLIPPAGE_BPS = 100n;
 /**
  * Prepare a person's payment with {@link buildUserPayMetadata}: preview it,
  * and set the minimum the terminal enforces on the beneficiary's balance.
  *
- * When the project's buyback hook honors `skipSplits` and its pool is in the
- * paid token, this quotes that pool (fee and price impact included) and sends
- * the slippage-floored quote as an explicit minimum. The hook then swaps
- * whenever the pool beats the payer's share of a mint, and reverts below the
- * floor. Without it the hook routes by its TWAP floor, which reaches zero on
- * large buys against a thin pool and sends them to minting even when the pool
- * pays far more.
+ * When the project's buyback hook would swap, this quotes its pool (fee and
+ * price impact included) and sends the slippage-floored quote as an explicit
+ * minimum, so the payer gets the pool's rate whenever it
+ * beats minting. The hook compares that minimum to the swap output plus the
+ * leftover mint: the whole leftover mint when the swapped tokens go through
+ * the reserved split (`skipSplits` false, and always on hook 1.1.1, which
+ * ignores `skipSplits`), its beneficiary share when they skip it. The
+ * terminal minimum is the beneficiary's part of that guarantee, plus what the
+ * terminal issues itself (such as for NFT splits). The quoted payment is
+ * previewed again first, and stays on the mint path if the hook would not
+ * swap with that minimum. Without a quote the hook routes by its TWAP floor,
+ * which reaches zero on large buys against a thin pool and sends them to
+ * minting even when the pool pays far more.
  *
- * Otherwise (no pool, hook 1.1.1, a router converting the token first, or a
- * failed quote) the hook routes by TWAP. The minimum is then the payer's mint
+ * Behind a router terminal, its registry or its gateway, when the router
+ * converts the paid token first with one swap, the pool is the one in the
+ * token it converts to, quoted on what that swap is quoted to return. If the
+ * conversion returns noticeably less, the hook's minimum reverts the payment.
+ * If it returns more, the hook mints once minting reaches the minimum, which
+ * happens only when the pool beats minting by less than `slippageBps` plus
+ * that gain. The payer still receives at least the minimum, and no fixed
+ * minimum avoids this when the pool's edge is inside the conversion's
+ * uncertainty. Other routes, such as cashing a project token out first, keep
+ * the fallback.
+ *
+ * Otherwise (no pool, or a failed quote) the minimum is the payer's mint
  * entitlement when the hook would swap, since the hook never settles below it,
- * and the terminal's own issuance when it would not.
+ * and the terminal's own issuance when it would not. If the payment then
+ * reverts, {@link decodePayFailure} says why. To let the payer accept less,
+ * prepare again with a larger `slippageBps`: the hook's minimum is in the
+ * metadata, so lowering `minReturnedTokens` alone does not relax it.
  *
  * When the ruleset calls buyback hook 1.4 directly (or through the omnichain
  * deployer) instead of through the registry, the metadata is keyed to the hook,
  * which reads nothing else.
  *
  * @param args.slippageBps Tolerance on the pool quote and on the fallback
- * minimum. Defaults to 100 (1%).
+ * minimum. Defaults to {@link PAY_DEFAULT_SLIPPAGE_BPS}.
  * @param args.skipSplits Whether the beneficiary keeps the swapped tokens
  * without the reserved split. Defaults to true, as a person's pay card does;
  * pass false for payments that should honor the project's splits, such as

package/dist/cjs/v6/pay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../../src/v6/pay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../../../src/v6/pay.ts"],"names":[],"mappings":"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"}

package/dist/cjs/v6/pay.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAY_DEFAULT_SLIPPAGE_BPS = void 0;
 exports.buildPayTx = buildPayTx;
 exports.previewPay = previewPay;
 exports.effectivePayPreview = effectivePayPreview;
@@ -12,7 +13,9 @@ const constants_js_1 = require("../constants.js");
 const juicebox_js_1 = require("../generated/juicebox.js");
 const hook_js_1 = require("../utils/hook.js");
 const cashOut_js_1 = require("./cashOut.js");
+const terminals_js_1 = require("./terminals.js");
 const types_js_1 = require("./types.js");
+const uniswapV3_js_1 = require("./uniswapV3.js");
 const uniswapV4_js_1 = require("./uniswapV4.js");
 /**
  * Build a `pay(projectId, token, amount, beneficiary, minReturnedTokens, memo,
@@ -312,35 +315,293 @@ const poolKeyOfAbi = [
         ],
     },
 ];
+/** `prepareUserPay`'s tolerance on its quote and fallback minimum: 1%. */
+exports.PAY_DEFAULT_SLIPPAGE_BPS = 100n;
+/**
+ * The buyback pool a payment's spec reports, and the terminal token it is
+ * keyed to, or null. A router converts the paid token first, so its pool is
+ * keyed to another token the project accepts. The pool id is the key's hash,
+ * so a match proves the key.
+ */
+async function buybackPoolOf(client, { chainId, hook, projectId, token, poolId, }) {
+    const poolOf = async (terminalToken) => ({
+        terminalToken,
+        key: await client.readContract({
+            address: hook,
+            abi: poolKeyOfAbi,
+            functionName: "poolKeyOf",
+            args: [
+                projectId,
+                terminalToken.toLowerCase() === constants_js_1.NATIVE_TOKEN.toLowerCase()
+                    ? viem_1.zeroAddress
+                    : terminalToken,
+            ],
+        }),
+    });
+    const paid = await poolOf(token);
+    if ((0, uniswapV4_js_1.uniswapV4PoolId)(paid.key) === poolId)
+        return paid;
+    const contexts = await (0, terminals_js_1.getAccountingContexts)(client, { chainId, projectId });
+    const pools = await Promise.all(contexts
+        .filter((c) => c.token.toLowerCase() !== token.toLowerCase())
+        .map((c) => poolOf(c.token)));
+    return pools.find((p) => (0, uniswapV4_js_1.uniswapV4PoolId)(p.key) === poolId) ?? null;
+}
+const previewPayForOutputs = juicebox_js_1.jbMultiTerminalAbi.find((item) => item.type === "function" && item.name === "previewPayFor").outputs;
+// Only these reads of the router and core: their full ABIs would weigh on every pay card.
+const routerConversionAbi = [
+    {
+        type: "function",
+        name: "projectIdOf",
+        stateMutability: "view",
+        inputs: [{ name: "token", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "primaryTerminalOf",
+        stateMutability: "view",
+        inputs: [
+            { name: "projectId", type: "uint256" },
+            { name: "token", type: "address" },
+        ],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        type: "function",
+        name: "previewTerminalPayOf",
+        stateMutability: "view",
+        inputs: [
+            { name: "destTerminal", type: "address" },
+            { name: "projectId", type: "uint256" },
+            { name: "token", type: "address" },
+            { name: "amount", type: "uint256" },
+            { name: "beneficiary", type: "address" },
+            { name: "metadata", type: "bytes" },
+        ],
+        outputs: previewPayForOutputs,
+    },
+    {
+        type: "function",
+        name: "wrappedNativeToken",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        type: "function",
+        name: "previewSwapAmountOutOf",
+        stateMutability: "view",
+        inputs: [
+            { name: "tokenIn", type: "address" },
+            { name: "tokenOut", type: "address" },
+            { name: "amount", type: "uint256" },
+            { name: "metadata", type: "bytes" },
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "discoverBestPool",
+        stateMutability: "view",
+        inputs: [
+            { name: "normalizedTokenIn", type: "address" },
+            { name: "normalizedTokenOut", type: "address" },
+        ],
+        outputs: [
+            {
+                name: "",
+                type: "tuple",
+                components: [
+                    { name: "isV4", type: "bool" },
+                    { name: "v3Pool", type: "address" },
+                    {
+                        name: "v4Key",
+                        type: "tuple",
+                        components: [
+                            { name: "currency0", type: "address" },
+                            { name: "currency1", type: "address" },
+                            { name: "fee", type: "uint24" },
+                            { name: "tickSpacing", type: "int24" },
+                            { name: "hooks", type: "address" },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+];
+const v3PoolFeeAbi = [
+    {
+        type: "function",
+        name: "fee",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint24" }],
+    },
+];
+/**
+ * What the router terminal's swap of the whole payment into `tokenOut` is
+ * quoted to return (fee and price impact included), and the floor it reverts
+ * below, from the pool the router picks. Null when the route is not that one
+ * swap, such as when the router cashes a project token out first.
+ */
+async function routerConversionOf(client, { chainId, tokenIn, tokenOut, amount, }) {
+    const router = (0, types_js_1.v6Address)("JBRouterTerminal", chainId);
+    const [sourceProjectId, wrapped] = await Promise.all([
+        client.readContract({
+            address: (0, types_js_1.v6Address)("JBTokens", chainId),
+            abi: routerConversionAbi,
+            functionName: "projectIdOf",
+            args: [tokenIn],
+        }),
+        client.readContract({
+            address: router,
+            abi: routerConversionAbi,
+            functionName: "wrappedNativeToken",
+        }),
+    ]);
+    // The router cashes a project token out before any swap.
+    if (sourceProjectId !== 0n)
+        return null;
+    const isNative = (t) => t.toLowerCase() === constants_js_1.NATIVE_TOKEN.toLowerCase() ||
+        t.toLowerCase() === viem_1.zeroAddress;
+    const wrap = (t) => (isNative(t) ? wrapped : t);
+    const [floor, pool] = await Promise.all([
+        client.readContract({
+            address: router,
+            abi: routerConversionAbi,
+            functionName: "previewSwapAmountOutOf",
+            args: [tokenIn, tokenOut, amount, "0x"],
+        }),
+        client.readContract({
+            address: router,
+            abi: routerConversionAbi,
+            functionName: "discoverBestPool",
+            args: [wrap(tokenIn), wrap(tokenOut)],
+        }),
+    ]);
+    let expected;
+    if (pool.isV4) {
+        // V4 pools hold the native token itself, which the router uses for wrapped input.
+        const unwrap = (t) => wrap(t).toLowerCase() === wrapped.toLowerCase() ? viem_1.zeroAddress : t;
+        const zeroForOne = (0, uniswapV4_js_1.uniswapV4SwapDirection)({
+            poolKey: pool.v4Key,
+            tokenIn: unwrap(tokenIn),
+            tokenOut: unwrap(tokenOut),
+        });
+        if (zeroForOne === null)
+            return null;
+        expected = await (0, uniswapV4_js_1.quoteUniswapV4ExactInputSingle)(client, {
+            chainId,
+            poolKey: pool.v4Key,
+            zeroForOne,
+            amountIn: amount,
+        });
+    }
+    else {
+        expected = await (0, uniswapV3_js_1.quoteUniswapV3ExactInputSingle)(client, {
+            chainId,
+            tokenIn: wrap(tokenIn),
+            tokenOut: wrap(tokenOut),
+            fee: await client.readContract({
+                address: pool.v3Pool,
+                abi: v3PoolFeeAbi,
+                functionName: "fee",
+            }),
+            amountIn: amount,
+        });
+    }
+    return expected >= floor ? { expected, floor } : null;
+}
+/**
+ * The buyback spec the destination returns when the router's conversion
+ * returns what it is quoted to, and the router's floor. The hook's input is
+ * the conversion less anything taken before it, such as an NFT split, and the
+ * hook mints instead of swapping once minting that input reaches a fixed
+ * minimum, so the minimum is set from this spec. Null when the route is not
+ * one swap of the whole payment.
+ */
+async function routedBuybackSpecOf(client, { chainId, projectId, tokenIn, tokenOut, amount, beneficiary, metadata, hook, reservedPercent, }) {
+    const conversion = await routerConversionOf(client, {
+        chainId,
+        tokenIn,
+        tokenOut,
+        amount,
+    });
+    if (!conversion)
+        return null;
+    const destination = await client.readContract({
+        address: (0, types_js_1.v6Address)("JBDirectory", chainId),
+        abi: routerConversionAbi,
+        functionName: "primaryTerminalOf",
+        args: [projectId, tokenOut],
+    });
+    const [, , , specs] = await client.readContract({
+        address: (0, types_js_1.v6Address)("JBRouterTerminal", chainId),
+        abi: routerConversionAbi,
+        functionName: "previewTerminalPayOf",
+        args: [
+            destination,
+            projectId,
+            tokenOut,
+            conversion.expected,
+            beneficiary,
+            metadata,
+        ],
+    });
+    const raw = specs.find((s) => s.hook.toLowerCase() === hook.toLowerCase());
+    const spec = raw && decodeBuybackPaySpec(raw, reservedPercent);
+    return spec ? { spec, floor: conversion.floor } : null;
+}
 /**
  * Prepare a person's payment with {@link buildUserPayMetadata}: preview it,
  * and set the minimum the terminal enforces on the beneficiary's balance.
  *
- * When the project's buyback hook honors `skipSplits` and its pool is in the
- * paid token, this quotes that pool (fee and price impact included) and sends
- * the slippage-floored quote as an explicit minimum. The hook then swaps
- * whenever the pool beats the payer's share of a mint, and reverts below the
- * floor. Without it the hook routes by its TWAP floor, which reaches zero on
- * large buys against a thin pool and sends them to minting even when the pool
- * pays far more.
+ * When the project's buyback hook would swap, this quotes its pool (fee and
+ * price impact included) and sends the slippage-floored quote as an explicit
+ * minimum, so the payer gets the pool's rate whenever it
+ * beats minting. The hook compares that minimum to the swap output plus the
+ * leftover mint: the whole leftover mint when the swapped tokens go through
+ * the reserved split (`skipSplits` false, and always on hook 1.1.1, which
+ * ignores `skipSplits`), its beneficiary share when they skip it. The
+ * terminal minimum is the beneficiary's part of that guarantee, plus what the
+ * terminal issues itself (such as for NFT splits). The quoted payment is
+ * previewed again first, and stays on the mint path if the hook would not
+ * swap with that minimum. Without a quote the hook routes by its TWAP floor,
+ * which reaches zero on large buys against a thin pool and sends them to
+ * minting even when the pool pays far more.
+ *
+ * Behind a router terminal, its registry or its gateway, when the router
+ * converts the paid token first with one swap, the pool is the one in the
+ * token it converts to, quoted on what that swap is quoted to return. If the
+ * conversion returns noticeably less, the hook's minimum reverts the payment.
+ * If it returns more, the hook mints once minting reaches the minimum, which
+ * happens only when the pool beats minting by less than `slippageBps` plus
+ * that gain. The payer still receives at least the minimum, and no fixed
+ * minimum avoids this when the pool's edge is inside the conversion's
+ * uncertainty. Other routes, such as cashing a project token out first, keep
+ * the fallback.
  *
- * Otherwise (no pool, hook 1.1.1, a router converting the token first, or a
- * failed quote) the hook routes by TWAP. The minimum is then the payer's mint
+ * Otherwise (no pool, or a failed quote) the minimum is the payer's mint
  * entitlement when the hook would swap, since the hook never settles below it,
- * and the terminal's own issuance when it would not.
+ * and the terminal's own issuance when it would not. If the payment then
+ * reverts, {@link decodePayFailure} says why. To let the payer accept less,
+ * prepare again with a larger `slippageBps`: the hook's minimum is in the
+ * metadata, so lowering `minReturnedTokens` alone does not relax it.
  *
  * When the ruleset calls buyback hook 1.4 directly (or through the omnichain
  * deployer) instead of through the registry, the metadata is keyed to the hook,
  * which reads nothing else.
  *
  * @param args.slippageBps Tolerance on the pool quote and on the fallback
- * minimum. Defaults to 100 (1%).
+ * minimum. Defaults to {@link PAY_DEFAULT_SLIPPAGE_BPS}.
  * @param args.skipSplits Whether the beneficiary keeps the swapped tokens
  * without the reserved split. Defaults to true, as a person's pay card does;
  * pass false for payments that should honor the project's splits, such as
  * fees or revenue routed into a project.
  */
-async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSplits = true, ...args }) {
+async function prepareUserPay(client, { tiers, slippageBps = exports.PAY_DEFAULT_SLIPPAGE_BPS, skipSplits = true, ...args }) {
     const { chainId, projectId, token } = args;
     let metadata = buildUserPayMetadata({ chainId, tiers, skipSplits });
     let read = await readPay(client, { ...args, metadata });
@@ -362,47 +623,104 @@ async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSplits =
                 maxBigInt(mintEntitlementOf(buyback, weight) - 2n, 0n)
             : terminalBeneficiaryTokenCount, slippageBps),
     };
-    if (!buyback?.skipSplits || buyback.amountToSwapWith === 0n)
+    if (!buyback || buyback.amountToSwapWith === 0n)
         return fallback;
     try {
-        const poolKey = await client.readContract({
-            address: buyback.hook,
-            abi: poolKeyOfAbi,
-            functionName: "poolKeyOf",
-            args: [
-                projectId,
-                token.toLowerCase() === constants_js_1.NATIVE_TOKEN.toLowerCase()
-                    ? viem_1.zeroAddress
-                    : token,
-            ],
+        const pool = await buybackPoolOf(client, {
+            chainId,
+            hook: buyback.hook,
+            projectId,
+            token,
+            poolId: buyback.poolId,
         });
-        // A router converts the paid token first, so its pool is a different one.
-        if ((0, uniswapV4_js_1.uniswapV4PoolId)(poolKey) !== buyback.poolId)
+        if (!pool)
             return fallback;
+        let swap = buyback;
+        if (pool.terminalToken !== token) {
+            // A router converts the payment first, and its preview gave the hook the
+            // router's slippage floor. A minimum quoted on that would let a normal
+            // conversion mint while the pool pays more, so quote what the hook
+            // receives when the conversion returns its quote. A conversion well
+            // below its quote then fails with a reason.
+            const routed = await routedBuybackSpecOf(client, {
+                chainId,
+                projectId,
+                tokenIn: token,
+                tokenOut: pool.terminalToken,
+                amount: args.amount,
+                beneficiary: args.beneficiary,
+                metadata,
+                hook: buyback.hook,
+                reservedPercent: buyback.reservedPercent,
+            });
+            // The floor preview must be this route's: no more than the floor reached the hook.
+            if (!routed ||
+                routed.floor < buyback.amountToSwapWith ||
+                routed.spec.poolId !== buyback.poolId) {
+                return fallback;
+            }
+            swap = routed.spec;
+        }
         const quote = await (0, uniswapV4_js_1.quoteUniswapV4ExactInputSingle)(client, {
             chainId,
-            poolKey,
-            zeroForOne: !buyback.projectTokenIs0,
-            amountIn: buyback.amountToSwapWith,
+            poolKey: pool.key,
+            zeroForOne: !swap.projectTokenIs0,
+            amountIn: swap.amountToSwapWith,
         });
         const minimumSwapAmountOut = (0, cashOut_js_1.slippageFloor)(quote, slippageBps);
         // The pool loses to minting: leave the payment on the mint path.
-        if (minimumSwapAmountOut <= buyback.tokenCountWithoutHook)
+        if (minimumSwapAmountOut <= swap.tokenCountWithoutHook)
             return fallback;
-        const directMint = splitOf(directMintOf(buyback, weight), buyback.reservedPercent);
+        const quotedMetadata = buildUserPayMetadata({
+            chainId,
+            tiers,
+            minimumSwapAmountOut,
+            skipSplits,
+            ...(hook ? { hook } : {}),
+        });
+        // The hook rejects a minimum it cannot route, such as on a pool with no
+        // liquidity in range, and then the payment stays on the mint path.
+        const [, quotedBeneficiaryCount, quotedReservedCount, quotedSpecs] = await client.readContract({
+            address: args.terminal,
+            abi: juicebox_js_1.jbMultiTerminalAbi,
+            functionName: "previewPayFor",
+            args: [projectId, token, args.amount, args.beneficiary, quotedMetadata],
+        });
+        // It must still swap, and in the quoted pool: a router may pick another route.
+        const quotedSpec = quotedSpecs.find((s) => s.hook.toLowerCase() === buyback.hook.toLowerCase());
+        if (!quotedSpec ||
+            quotedSpec.noop ||
+            decodeBuybackPaySpec(quotedSpec, buyback.reservedPercent)?.poolId !==
+                buyback.poolId) {
+            return fallback;
+        }
+        // A router folds the hook's estimate into its counts, so only the
+        // multi-terminal's own counts are known to be its issuance.
+        const issuedByTerminal = args.terminal.toLowerCase() ===
+            (0, types_js_1.v6Address)("JBMultiTerminal", chainId).toLowerCase()
+            ? {
+                beneficiaryTokenCount: quotedBeneficiaryCount,
+                reservedTokenCount: quotedReservedCount,
+            }
+            : { beneficiaryTokenCount: 0n, reservedTokenCount: 0n };
+        const directMint = directMintOf(swap, weight);
+        // The swapped tokens skip the split, or are reminted through it with the
+        // direct mint. The terminal's own issuance, such as for NFT splits, adds.
+        const settle = (swapTokenCount) => {
+            const split = swap.skipSplits
+                ? splitOf(directMint, swap.reservedPercent)
+                : splitOf(swapTokenCount + directMint, swap.reservedPercent);
+            return {
+                beneficiaryTokenCount: (swap.skipSplits ? swapTokenCount : 0n) +
+                    split.beneficiaryTokenCount +
+                    issuedByTerminal.beneficiaryTokenCount,
+                reservedTokenCount: split.reservedTokenCount + issuedByTerminal.reservedTokenCount,
+            };
+        };
         return {
-            metadata: buildUserPayMetadata({
-                chainId,
-                tiers,
-                minimumSwapAmountOut,
-                skipSplits,
-                ...(hook ? { hook } : {}),
-            }),
-            preview: {
-                beneficiaryTokenCount: quote + directMint.beneficiaryTokenCount,
-                reservedTokenCount: directMint.reservedTokenCount,
-            },
-            minReturnedTokens: minimumSwapAmountOut,
+            metadata: quotedMetadata,
+            preview: settle(quote),
+            minReturnedTokens: settle(minimumSwapAmountOut).beneficiaryTokenCount,
         };
     }
     catch {