@bananapus/nana-sdk-core 3.3.0 → 3.5.0

package/dist/esm/v6/pay.js

@@ -3,8 +3,10 @@ import { DEFAULT_ALLOW_OVERSPENDING, MAX_RESERVED_PERCENT, NATIVE_TOKEN, } from
 import { jbBuybackHookRegistryAbi, jbMultiTerminalAbi, } from "../generated/juicebox.js";
 import { createHookMetadata, hookMetadataId } from "../utils/hook.js";
 import { slippageFloor } from "./cashOut.js";
+import { getAccountingContexts } from "./terminals.js";
 import { v6Address } from "./types.js";
-import { quoteUniswapV4ExactInputSingle, uniswapV4PoolId, } from "./uniswapV4.js";
+import { quoteUniswapV3ExactInputSingle } from "./uniswapV3.js";
+import { quoteUniswapV4ExactInputSingle, uniswapV4PoolId, uniswapV4SwapDirection, } from "./uniswapV4.js";
 /**
  * Build a `pay(projectId, token, amount, beneficiary, minReturnedTokens, memo,
  * metadata)` transaction request for a v6 terminal.
@@ -279,6 +281,8 @@ async function resolvedBuybackHookOf(client, chainId, projectId) {
     return hook === zeroAddress ? null : hook;
 }
 const maxBigInt = (a, b) => (a > b ? a : b);
+/** What to tell the payer when {@link PreparedUserPay.quoteFailed} is set. */
+export const PAY_QUOTE_FAILED_MESSAGE = "Couldn't read the pool's price, so this payment's minimum is only the mint rate.";
 const poolKeyOfAbi = [
     {
         type: "function",
@@ -303,13 +307,337 @@ const poolKeyOfAbi = [
         ],
     },
 ];
+/**
+ * Whether a preview reverted with the buyback hook's
+ * `JBBuybackHook_SpecifiedSlippageExceeded`, which viem keeps as `raw` on the
+ * error's cause chain. The full revert decoder would weigh on every pay card.
+ */
+function rejectsMinimum(error) {
+    for (let e = error; e; e = e.cause) {
+        if (typeof e.raw === "string" && e.raw.startsWith("0xe2d708a9")) {
+            return true;
+        }
+    }
+    return false;
+}
+/** `prepareUserPay`'s tolerance on its quote and fallback minimum: 1%. */
+export const 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() === NATIVE_TOKEN.toLowerCase()
+                    ? zeroAddress
+                    : terminalToken,
+            ],
+        }),
+    });
+    const paid = await poolOf(token);
+    if (uniswapV4PoolId(paid.key) === poolId)
+        return paid;
+    const contexts = await 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) => uniswapV4PoolId(p.key) === poolId) ?? null;
+}
+const previewPayForOutputs = 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: "terminalsOf",
+        stateMutability: "view",
+        inputs: [{ name: "projectId", type: "uint256" }],
+        outputs: [{ name: "", type: "address[]" }],
+    },
+    {
+        type: "function",
+        name: "terminalOf",
+        stateMutability: "view",
+        inputs: [{ name: "projectId", type: "uint256" }],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        type: "function",
+        name: "ROUTER",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        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" }],
+    },
+];
+/**
+ * Whether a payment to `terminal` reaches the current router: directly,
+ * through the gateway, or through the registry's terminal for the project
+ * (which may be the gateway). The conversion reads quote that router.
+ */
+async function reachesRouter(client, chainId, projectId, terminal) {
+    const addressOf = (name) => {
+        try {
+            return v6Address(name, chainId).toLowerCase();
+        }
+        catch {
+            return null;
+        }
+    };
+    let reached = terminal.toLowerCase();
+    if (reached === addressOf("JBRouterTerminalRegistry")) {
+        reached = (await client.readContract({
+            address: terminal,
+            abi: routerConversionAbi,
+            functionName: "terminalOf",
+            args: [projectId],
+        })).toLowerCase();
+    }
+    if (reached === addressOf("JBRouterTerminalGateway")) {
+        reached = (await client.readContract({
+            address: reached,
+            abi: routerConversionAbi,
+            functionName: "ROUTER",
+        })).toLowerCase();
+    }
+    const router = addressOf("JBRouterTerminal");
+    return router !== null && reached === router;
+}
+/**
+ * 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 = v6Address("JBRouterTerminal", chainId);
+    const [sourceProjectId, wrapped] = await Promise.all([
+        client.readContract({
+            address: 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() === NATIVE_TOKEN.toLowerCase() ||
+        t.toLowerCase() === zeroAddress;
+    const wrap = (t) => (isNative(t) ? wrapped : t);
+    // The router wraps or unwraps the native token 1:1, without a pool.
+    if (wrap(tokenIn).toLowerCase() === wrap(tokenOut).toLowerCase())
+        return null;
+    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() ? zeroAddress : t;
+        const zeroForOne = uniswapV4SwapDirection({
+            poolKey: pool.v4Key,
+            tokenIn: unwrap(tokenIn),
+            tokenOut: unwrap(tokenOut),
+        });
+        if (zeroForOne === null)
+            return null;
+        expected = await quoteUniswapV4ExactInputSingle(client, {
+            chainId,
+            poolKey: pool.v4Key,
+            zeroForOne,
+            amountIn: amount,
+        });
+    }
+    else {
+        expected = await 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 destination terminal's preview of a router payment whose conversion
+ * returns what it is quoted to, and the router's floor. Null when the route is
+ * not one swap of the whole payment.
+ */
+async function quotedRoutePreviewOf(client, { chainId, projectId, tokenIn, tokenOut, amount, beneficiary, metadata, }) {
+    const conversion = await routerConversionOf(client, {
+        chainId,
+        tokenIn,
+        tokenOut,
+        amount,
+    });
+    if (!conversion)
+        return null;
+    const destination = await client.readContract({
+        address: v6Address("JBDirectory", chainId),
+        abi: routerConversionAbi,
+        functionName: "primaryTerminalOf",
+        args: [projectId, tokenOut],
+    });
+    const [, beneficiaryTokenCount, reservedTokenCount, specs] = await client.readContract({
+        address: v6Address("JBRouterTerminal", chainId),
+        abi: routerConversionAbi,
+        functionName: "previewTerminalPayOf",
+        args: [
+            destination,
+            projectId,
+            tokenOut,
+            conversion.expected,
+            beneficiary,
+            metadata,
+        ],
+    });
+    return {
+        preview: { beneficiaryTokenCount, reservedTokenCount },
+        specs,
+        floor: conversion.floor,
+    };
+}
+/**
+ * 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, { hook, reservedPercent, ...route }) {
+    const routed = await quotedRoutePreviewOf(client, route);
+    if (!routed)
+        return null;
+    const raw = routed.specs.find((s) => s.hook.toLowerCase() === hook.toLowerCase());
+    const spec = raw && decodeBuybackPaySpec(raw, reservedPercent);
+    return spec ? { spec, floor: routed.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 has a pool in the paid token, this quotes
- * that 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
+ * 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
@@ -321,23 +649,40 @@ const poolKeyOfAbi = [
  * 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, a router converting the token first, 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. If the payment then reverts, {@link decodePayFailure} says why.
+ * 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. When the project has no buyback hook and accepts one token,
+ * the minimum is what minting the quoted conversion issues, instead of the
+ * router's floor.
+ *
+ * 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. A quote whose reads fail
+ * twice returns `quoteFailed`, so the app can say the pool's rate is not
+ * protected. 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.
  */
-export async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSplits = true, ...args }) {
+export async function prepareUserPay(client, { tiers, slippageBps = 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 });
@@ -359,32 +704,115 @@ export async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSp
                 maxBigInt(mintEntitlementOf(buyback, weight) - 2n, 0n)
             : terminalBeneficiaryTokenCount, slippageBps),
     };
+    // A failed read is retried once: a dropped request must not silently weaken
+    // the minimum.
+    const withRetry = async (prepare) => {
+        try {
+            return await prepare();
+        }
+        catch {
+            try {
+                return await prepare();
+            }
+            catch {
+                return { ...fallback, quoteFailed: true };
+            }
+        }
+    };
+    const isRouter = args.terminal.toLowerCase() !==
+        v6Address("JBMultiTerminal", chainId).toLowerCase();
+    if (!buyback && isRouter) {
+        // The router previews minting on its conversion's floor, which sits up to
+        // its sigmoid slippage below the pool's quote. Require what minting the
+        // quoted conversion issues when the router has only that route: the
+        // project's one terminal is the multi-terminal, accepting one token, and
+        // the payment reaches the router these reads quote.
+        // ponytail: one accepted token only; multi-token projects need the
+        // router's route pick exposed.
+        return withRetry(async () => {
+            const [terminals, contexts, viaRouter] = await Promise.all([
+                client.readContract({
+                    address: v6Address("JBDirectory", chainId),
+                    abi: routerConversionAbi,
+                    functionName: "terminalsOf",
+                    args: [projectId],
+                }),
+                getAccountingContexts(client, { chainId, projectId }),
+                reachesRouter(client, chainId, projectId, args.terminal),
+            ]);
+            const tokenOut = contexts.length === 1 ? contexts[0].token : null;
+            if (!viaRouter ||
+                !tokenOut ||
+                terminals.length !== 1 ||
+                terminals[0].toLowerCase() !==
+                    v6Address("JBMultiTerminal", chainId).toLowerCase()) {
+                return fallback;
+            }
+            const routed = await quotedRoutePreviewOf(client, {
+                chainId,
+                projectId,
+                tokenIn: token,
+                tokenOut,
+                amount: args.amount,
+                beneficiary: args.beneficiary,
+                metadata,
+            });
+            if (!routed)
+                return fallback;
+            return {
+                metadata,
+                preview: routed.preview,
+                minReturnedTokens: slippageFloor(routed.preview.beneficiaryTokenCount, slippageBps),
+            };
+        });
+    }
     if (!buyback || buyback.amountToSwapWith === 0n)
         return fallback;
-    try {
-        const poolKey = await client.readContract({
-            address: buyback.hook,
-            abi: poolKeyOfAbi,
-            functionName: "poolKeyOf",
-            args: [
-                projectId,
-                token.toLowerCase() === NATIVE_TOKEN.toLowerCase()
-                    ? zeroAddress
-                    : token,
-            ],
+    return withRetry(async () => {
+        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 (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 quoteUniswapV4ExactInputSingle(client, {
             chainId,
-            poolKey,
-            zeroForOne: !buyback.projectTokenIs0,
-            amountIn: buyback.amountToSwapWith,
+            poolKey: pool.key,
+            zeroForOne: !swap.projectTokenIs0,
+            amountIn: swap.amountToSwapWith,
         });
         const minimumSwapAmountOut = 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 quotedMetadata = buildUserPayMetadata({
             chainId,
@@ -395,33 +823,46 @@ export async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSp
         });
         // 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: jbMultiTerminalAbi,
-            functionName: "previewPayFor",
-            args: [projectId, token, args.amount, args.beneficiary, quotedMetadata],
-        });
-        const swaps = quotedSpecs.some((s) => !s.noop && s.hook.toLowerCase() === buyback.hook.toLowerCase());
-        if (!swaps)
+        let quotedPreview;
+        try {
+            quotedPreview = await client.readContract({
+                address: args.terminal,
+                abi: jbMultiTerminalAbi,
+                functionName: "previewPayFor",
+                args: [projectId, token, args.amount, args.beneficiary, quotedMetadata],
+            });
+        }
+        catch (error) {
+            if (rejectsMinimum(error))
+                return fallback;
+            throw error;
+        }
+        const [, quotedBeneficiaryCount, quotedReservedCount, quotedSpecs] = quotedPreview;
+        // 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() ===
-            v6Address("JBMultiTerminal", chainId).toLowerCase()
-            ? {
+        const issuedByTerminal = isRouter
+            ? { beneficiaryTokenCount: 0n, reservedTokenCount: 0n }
+            : {
                 beneficiaryTokenCount: quotedBeneficiaryCount,
                 reservedTokenCount: quotedReservedCount,
-            }
-            : { beneficiaryTokenCount: 0n, reservedTokenCount: 0n };
-        const directMint = directMintOf(buyback, weight);
+            };
+        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 = buyback.skipSplits
-                ? splitOf(directMint, buyback.reservedPercent)
-                : splitOf(swapTokenCount + directMint, buyback.reservedPercent);
+            const split = swap.skipSplits
+                ? splitOf(directMint, swap.reservedPercent)
+                : splitOf(swapTokenCount + directMint, swap.reservedPercent);
             return {
-                beneficiaryTokenCount: (buyback.skipSplits ? swapTokenCount : 0n) +
+                beneficiaryTokenCount: (swap.skipSplits ? swapTokenCount : 0n) +
                     split.beneficiaryTokenCount +
                     issuedByTerminal.beneficiaryTokenCount,
                 reservedTokenCount: split.reservedTokenCount + issuedByTerminal.reservedTokenCount,
@@ -432,10 +873,7 @@ export async function prepareUserPay(client, { tiers, slippageBps = 100n, skipSp
             preview: settle(quote),
             minReturnedTokens: settle(minimumSwapAmountOut).beneficiaryTokenCount,
         };
-    }
-    catch {
-        return fallback;
-    }
+    });
 }
 /**
  * Build pay metadata instructing a project's JB721 tiers hook to mint specific tiers.