@andrewkimjoseph/celina-sdk 0.27.6 → 0.28.0

package/build/src/services/uniswap-v3-path-router.js

@@ -0,0 +1,183 @@
+/**
+ * Uniswap v3 path routing: BFS over the hub-pool index and QuoterV2 selection.
+ */
+import { encodeFunctionData, encodePacked } from "viem";
+import { swapRouter02Abi, v3QuoterAbi } from "../abis/uniswap-v3.js";
+import { UNISWAP_V3 } from "../config/uniswap.js";
+import { getUniswapV3PoolIndex, poolsBetweenV3, } from "./uniswap-v3-pool-discovery.js";
+const MAX_POOLS = 3;
+/** Token on the other side of a canonical v3 pool. */
+export function otherV3Token(pool, token) {
+    const current = token.toLowerCase();
+    if (pool.token0.toLowerCase() === current)
+        return pool.token1;
+    if (pool.token1.toLowerCase() === current)
+        return pool.token0;
+    throw new Error("Token is not in the Uniswap v3 pool.");
+}
+/** Packed v3 path: token, fee, token, fee, token. */
+export function encodeV3Path(tokenIn, pools) {
+    const types = ["address"];
+    const values = [tokenIn];
+    let current = tokenIn;
+    for (const pool of pools) {
+        const out = otherV3Token(pool, current);
+        types.push("uint24", "address");
+        values.push(pool.fee, out);
+        current = out;
+    }
+    return encodePacked(types, values);
+}
+/**
+ * SwapRouter02 calldata. Single- and multi-hop swaps are wrapped in
+ * `multicall(deadline, bytes[])` because exactInput has no deadline field.
+ */
+export function buildSwapRouter02Calldata(args) {
+    const { pools, tokenIn, recipient, amountIn, amountOutMin, deadline } = args;
+    if (pools.length === 0) {
+        throw new Error("Uniswap v3 route has no pools.");
+    }
+    const inner = pools.length === 1
+        ? encodeFunctionData({
+            abi: swapRouter02Abi,
+            functionName: "exactInputSingle",
+            args: [
+                {
+                    tokenIn,
+                    tokenOut: otherV3Token(pools[0], tokenIn),
+                    fee: pools[0].fee,
+                    recipient,
+                    amountIn,
+                    amountOutMinimum: amountOutMin,
+                    sqrtPriceLimitX96: 0n,
+                },
+            ],
+        })
+        : encodeFunctionData({
+            abi: swapRouter02Abi,
+            functionName: "exactInput",
+            args: [
+                {
+                    path: encodeV3Path(tokenIn, pools),
+                    recipient,
+                    amountIn,
+                    amountOutMinimum: amountOutMin,
+                },
+            ],
+        });
+    return encodeFunctionData({
+        abi: swapRouter02Abi,
+        functionName: "multicall",
+        args: [deadline, [inner]],
+    });
+}
+export function enumerateV3Paths(index, tokenIn, tokenOut) {
+    const start = tokenIn.toLowerCase();
+    const goal = tokenOut.toLowerCase();
+    if (start === goal) {
+        return [];
+    }
+    const results = [];
+    const queue = [
+        { token: start, pools: [], visited: new Set([start]) },
+    ];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (node.pools.length >= MAX_POOLS) {
+            continue;
+        }
+        const neighbors = index.adjacency.get(node.token);
+        if (!neighbors) {
+            continue;
+        }
+        for (const neighbor of neighbors) {
+            if (node.visited.has(neighbor)) {
+                continue;
+            }
+            for (const pool of poolsBetweenV3(index, node.token, neighbor)) {
+                const nextPools = [...node.pools, pool];
+                if (neighbor === goal) {
+                    results.push(nextPools);
+                    continue;
+                }
+                if (nextPools.length < MAX_POOLS) {
+                    queue.push({
+                        token: neighbor,
+                        pools: nextPools,
+                        visited: new Set([...node.visited, neighbor]),
+                    });
+                }
+            }
+        }
+    }
+    return results;
+}
+export function countV3CandidatePaths(index, tokenIn, tokenOut) {
+    return enumerateV3Paths(index, tokenIn, tokenOut).length;
+}
+async function quoteV3Path(client, tokenIn, pools, amountIn) {
+    if (pools.length === 0) {
+        return 0n;
+    }
+    if (pools.length === 1) {
+        const pool = pools[0];
+        const { result } = await client.simulateContract({
+            address: UNISWAP_V3.quoterV2,
+            abi: v3QuoterAbi,
+            functionName: "quoteExactInputSingle",
+            args: [
+                {
+                    tokenIn,
+                    tokenOut: otherV3Token(pool, tokenIn),
+                    amountIn,
+                    fee: pool.fee,
+                    sqrtPriceLimitX96: 0n,
+                },
+            ],
+        });
+        return result[0];
+    }
+    const { result } = await client.simulateContract({
+        address: UNISWAP_V3.quoterV2,
+        abi: v3QuoterAbi,
+        functionName: "quoteExactInput",
+        args: [encodeV3Path(tokenIn, pools), amountIn],
+    });
+    return result[0];
+}
+/**
+ * Quote candidate v3 paths and return the highest output.
+ * @param maxPaths - Cap on simulateContract calls for this venue
+ */
+export async function findBestV3Route(client, tokenIn, tokenOut, amountIn, maxPaths, index) {
+    const poolIndex = index ?? (await getUniswapV3PoolIndex(client));
+    const candidatePaths = enumerateV3Paths(poolIndex, tokenIn, tokenOut)
+        .sort((a, b) => a.length - b.length)
+        .slice(0, Math.max(0, maxPaths));
+    const quotes = await Promise.allSettled(candidatePaths.map(async (pools) => ({
+        pools,
+        amountOut: await quoteV3Path(client, tokenIn, pools, amountIn),
+    })));
+    let best = null;
+    for (const quote of quotes) {
+        if (quote.status !== "fulfilled" || quote.value.amountOut <= 0n) {
+            continue;
+        }
+        if (!best || quote.value.amountOut > best.amountOut) {
+            best = {
+                amountOut: quote.value.amountOut,
+                route: {
+                    tokenIn,
+                    tokenOut,
+                    pools: quote.value.pools,
+                    hops: quote.value.pools.length,
+                },
+            };
+        }
+    }
+    if (!best) {
+        return null;
+    }
+    return { ...best, indexSource: poolIndex.source };
+}
+//# sourceMappingURL=uniswap-v3-path-router.js.map

package/build/src/services/uniswap-v3-path-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniswap-v3-path-router.js","sourceRoot":"","sources":["../../../src/services/uniswap-v3-path-router.ts"],"names":[],"mappings":"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"}

package/build/src/services/uniswap-v3-pool-discovery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Uniswap v3 pool discovery: on-chain hub probing via the Celo v3 factory.
+ * Hub-to-hub pools only — there is no v3 subgraph in this SDK.
+ */
+import type { PublicClient } from "viem";
+import { type UniswapV3Pool } from "../config/uniswap.js";
+/** One edge in the v3 pool routing graph. */
+export type UniswapV3PoolEdge = {
+    pool: UniswapV3Pool;
+    tokenA: `0x${string}`;
+    tokenB: `0x${string}`;
+};
+/** Cached routing graph of v3 hub pools on Celo mainnet. */
+export type UniswapV3PoolIndex = {
+    edges: UniswapV3PoolEdge[];
+    adjacency: Map<string, Set<string>>;
+    /** Sorted pair key (`tokenLo|tokenHi`) → pools across fee tiers. */
+    poolsByPair: Map<string, UniswapV3Pool[]>;
+    source: "onchain";
+    fetchedAt: number;
+};
+/**
+ * Load or refresh the v3 hub-pool index.
+ * @param client - Celo public client for factory probing
+ * @param options.forceRefresh - Bypass TTL cache when true
+ */
+export declare function getUniswapV3PoolIndex(client: PublicClient, options?: {
+    forceRefresh?: boolean;
+}): Promise<UniswapV3PoolIndex>;
+/** All v3 pools connecting two tokens in a cached index. */
+export declare function poolsBetweenV3(index: UniswapV3PoolIndex, tokenA: `0x${string}`, tokenB: `0x${string}`): UniswapV3Pool[];
+/** Reset cached v3 index (for tests). */
+export declare function resetUniswapV3PoolIndexCache(): void;

package/build/src/services/uniswap-v3-pool-discovery.js

@@ -0,0 +1,141 @@
+import { uniswapV3FactoryAbi, uniswapV3PoolAbi } from "../abis/uniswap-v3.js";
+import { UNISWAP_HUB_CURRENCIES, UNISWAP_POOL_CACHE_TTL_MS, UNISWAP_V3, UNISWAP_V3_FEE_TIERS, UNISWAP_V4, } from "../config/uniswap.js";
+const ZERO_ADDRESS = UNISWAP_V4.nativeCurrency.toLowerCase();
+const MULTICALL_CHUNK_SIZE = 100;
+let cachedIndex = null;
+function pairKey(a, b) {
+    const lo = a.toLowerCase();
+    const hi = b.toLowerCase();
+    return lo < hi ? `${lo}|${hi}` : `${hi}|${lo}`;
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+function sortTokens(a, b) {
+    return a.toLowerCase() < b.toLowerCase() ? [a, b] : [b, a];
+}
+function buildPoolIndex(pools) {
+    const edges = [];
+    const adjacency = new Map();
+    const poolsByPair = new Map();
+    for (const pool of pools) {
+        const tokenA = pool.token0.toLowerCase();
+        const tokenB = pool.token1.toLowerCase();
+        edges.push({ pool, tokenA, tokenB });
+        const key = pairKey(tokenA, tokenB);
+        const existing = poolsByPair.get(key) ?? [];
+        existing.push(pool);
+        poolsByPair.set(key, existing);
+        for (const [from, to] of [
+            [tokenA, tokenB],
+            [tokenB, tokenA],
+        ]) {
+            const neighbors = adjacency.get(from) ?? new Set();
+            neighbors.add(to);
+            adjacency.set(from, neighbors);
+        }
+    }
+    return {
+        edges,
+        adjacency,
+        poolsByPair,
+        source: "onchain",
+        fetchedAt: Date.now(),
+    };
+}
+async function probeHubPools(client) {
+    const hubs = UNISWAP_HUB_CURRENCIES.filter((currency) => currency.toLowerCase() !== ZERO_ADDRESS);
+    const candidates = [];
+    for (let i = 0; i < hubs.length; i++) {
+        for (let j = i + 1; j < hubs.length; j++) {
+            const [token0, token1] = sortTokens(hubs[i], hubs[j]);
+            for (const fee of UNISWAP_V3_FEE_TIERS) {
+                candidates.push({ token0, token1, fee });
+            }
+        }
+    }
+    const discovered = [];
+    for (const batch of chunk(candidates, MULTICALL_CHUNK_SIZE)) {
+        const results = await client.multicall({
+            allowFailure: true,
+            contracts: batch.map((candidate) => ({
+                address: UNISWAP_V3.factory,
+                abi: uniswapV3FactoryAbi,
+                functionName: "getPool",
+                args: [candidate.token0, candidate.token1, candidate.fee],
+            })),
+        });
+        for (let i = 0; i < batch.length; i++) {
+            const result = results[i];
+            const candidate = batch[i];
+            if (result?.status !== "success") {
+                continue;
+            }
+            const address = result.result;
+            if (address.toLowerCase() === ZERO_ADDRESS) {
+                continue;
+            }
+            discovered.push({
+                address,
+                pool: {
+                    token0: candidate.token0,
+                    token1: candidate.token1,
+                    fee: candidate.fee,
+                },
+            });
+        }
+    }
+    if (discovered.length === 0) {
+        return [];
+    }
+    const withLiquidity = [];
+    for (const batch of chunk(discovered, MULTICALL_CHUNK_SIZE)) {
+        const results = await client.multicall({
+            allowFailure: true,
+            contracts: batch.map((entry) => ({
+                address: entry.address,
+                abi: uniswapV3PoolAbi,
+                functionName: "liquidity",
+            })),
+        });
+        for (let i = 0; i < batch.length; i++) {
+            const result = results[i];
+            if (result?.status !== "success") {
+                continue;
+            }
+            const liquidity = result.result;
+            if (liquidity > 0n) {
+                withLiquidity.push(batch[i].pool);
+            }
+        }
+    }
+    return withLiquidity;
+}
+/**
+ * Load or refresh the v3 hub-pool index.
+ * @param client - Celo public client for factory probing
+ * @param options.forceRefresh - Bypass TTL cache when true
+ */
+export async function getUniswapV3PoolIndex(client, options) {
+    const now = Date.now();
+    if (!options?.forceRefresh &&
+        cachedIndex &&
+        now - cachedIndex.fetchedAt < UNISWAP_POOL_CACHE_TTL_MS) {
+        return cachedIndex;
+    }
+    cachedIndex = buildPoolIndex(await probeHubPools(client));
+    return cachedIndex;
+}
+/** All v3 pools connecting two tokens in a cached index. */
+export function poolsBetweenV3(index, tokenA, tokenB) {
+    return index.poolsByPair.get(pairKey(tokenA, tokenB)) ?? [];
+}
+/** Reset cached v3 index (for tests). */
+export function resetUniswapV3PoolIndexCache() {
+    cachedIndex = null;
+}
+//# sourceMappingURL=uniswap-v3-pool-discovery.js.map

package/build/src/services/uniswap-v3-pool-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniswap-v3-pool-discovery.js","sourceRoot":"","sources":["../../../src/services/uniswap-v3-pool-discovery.ts"],"names":[],"mappings":"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"}

package/build/src/services/uniswap-venue-quote.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pick the better of the best Uniswap v3 path and the best Uniswap v4 path.
+ * A quote simulates at most MAX_QUOTE_PATHS paths across both venues.
+ */
+import type { PublicClient } from "viem";
+import type { UniswapProtocol } from "../config/uniswap.js";
+import { type UniswapV3SwapRoute } from "./uniswap-v3-path-router.js";
+import { type UniswapSwapRoute } from "./uniswap-path-router.js";
+export type UniswapQuotedRoute = {
+    protocol: "uniswap_v4";
+    amountOut: bigint;
+    indexSource: string;
+    hops: number;
+    route: UniswapSwapRoute;
+} | {
+    protocol: "uniswap_v3";
+    amountOut: bigint;
+    indexSource: string;
+    hops: number;
+    route: UniswapV3SwapRoute;
+};
+/**
+ * Quote v3 and v4, or only the pinned venue.
+ * @returns The winning route, or null when every attempted venue has no liquidity
+ */
+export declare function findBestUniswapQuote(client: PublicClient, currencyIn: `0x${string}`, currencyOut: `0x${string}`, amountIn: bigint, options?: {
+    protocol?: UniswapProtocol;
+}): Promise<UniswapQuotedRoute | null>;

package/build/src/services/uniswap-venue-quote.js

@@ -0,0 +1,114 @@
+import { getUniswapV3PoolIndex } from "./uniswap-v3-pool-discovery.js";
+import { countV3CandidatePaths, findBestV3Route, } from "./uniswap-v3-path-router.js";
+import { getUniswapPoolIndex } from "./uniswap-pool-discovery.js";
+import { countV4CandidatePaths, findBestUniswapRoute, MAX_QUOTE_PATHS, splitQuoteBudget, } from "./uniswap-path-router.js";
+function prefer(current, next) {
+    if (!next)
+        return current;
+    if (!current)
+        return next;
+    if (next.amountOut > current.amountOut)
+        return next;
+    if (next.amountOut < current.amountOut)
+        return current;
+    // Equal output: v3 needs at most one approval, v4 can need two.
+    if (next.protocol === "uniswap_v3" && current.protocol === "uniswap_v4") {
+        return next;
+    }
+    return current;
+}
+/**
+ * Quote v3 and v4, or only the pinned venue.
+ * @returns The winning route, or null when every attempted venue has no liquidity
+ */
+export async function findBestUniswapQuote(client, currencyIn, currencyOut, amountIn, options) {
+    const pinned = options?.protocol;
+    if (pinned === "uniswap_v4") {
+        const found = await findBestUniswapRoute(client, currencyIn, currencyOut, amountIn, MAX_QUOTE_PATHS);
+        if (!found)
+            return null;
+        return {
+            protocol: "uniswap_v4",
+            amountOut: found.amountOut,
+            indexSource: found.indexSource,
+            hops: found.route.hops,
+            route: found.route,
+        };
+    }
+    if (pinned === "uniswap_v3") {
+        const found = await findBestV3Route(client, currencyIn, currencyOut, amountIn, MAX_QUOTE_PATHS);
+        if (!found)
+            return null;
+        return {
+            protocol: "uniswap_v3",
+            amountOut: found.amountOut,
+            indexSource: found.indexSource,
+            hops: found.route.hops,
+            route: found.route,
+        };
+    }
+    const [v4IndexResult, v3IndexResult] = await Promise.allSettled([
+        getUniswapPoolIndex(client),
+        getUniswapV3PoolIndex(client),
+    ]);
+    const v4Index = v4IndexResult.status === "fulfilled" ? v4IndexResult.value : null;
+    const v3Index = v3IndexResult.status === "fulfilled" ? v3IndexResult.value : null;
+    if (!v4Index && !v3Index) {
+        throw v4IndexResult.status === "rejected"
+            ? v4IndexResult.reason
+            : v3IndexResult.status === "rejected"
+                ? v3IndexResult.reason
+                : new Error("Uniswap pool index unavailable.");
+    }
+    const caps = splitQuoteBudget(v4Index ? countV4CandidatePaths(v4Index, currencyIn, currencyOut) : 0, v3Index ? countV3CandidatePaths(v3Index, currencyIn, currencyOut) : 0);
+    const [v4Result, v3Result] = await Promise.allSettled([
+        v4Index
+            ? findBestUniswapRoute(client, currencyIn, currencyOut, amountIn, caps.first, v4Index)
+            : Promise.reject(v4IndexResult.status === "rejected"
+                ? v4IndexResult.reason
+                : new Error("Uniswap v4 pool index unavailable.")),
+        v3Index
+            ? findBestV3Route(client, currencyIn, currencyOut, amountIn, caps.second, v3Index)
+            : Promise.reject(v3IndexResult.status === "rejected"
+                ? v3IndexResult.reason
+                : new Error("Uniswap v3 pool index unavailable.")),
+    ]);
+    let best = null;
+    const failures = [];
+    if (v4Result.status === "fulfilled") {
+        if (v4Result.value) {
+            best = prefer(best, {
+                protocol: "uniswap_v4",
+                amountOut: v4Result.value.amountOut,
+                indexSource: v4Result.value.indexSource,
+                hops: v4Result.value.route.hops,
+                route: v4Result.value.route,
+            });
+        }
+    }
+    else {
+        failures.push(v4Result.reason);
+    }
+    if (v3Result.status === "fulfilled") {
+        if (v3Result.value) {
+            best = prefer(best, {
+                protocol: "uniswap_v3",
+                amountOut: v3Result.value.amountOut,
+                indexSource: v3Result.value.indexSource,
+                hops: v3Result.value.route.hops,
+                route: v3Result.value.route,
+            });
+        }
+    }
+    else {
+        failures.push(v3Result.reason);
+    }
+    if (best) {
+        return best;
+    }
+    if (failures.length > 0) {
+        throw failures[0];
+    }
+    return null;
+}
+//# sourceMappingURL=uniswap-venue-quote.js.map

package/build/src/services/uniswap-venue-quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniswap-venue-quote.js","sourceRoot":"","sources":["../../../src/services/uniswap-venue-quote.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,eAAe,GAEhB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GAEjB,MAAM,0BAA0B,CAAC;AAkBlC,SAAS,MAAM,CACb,OAAkC,EAClC,IAA+B;IAE/B,IAAI,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC;IAC1B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS;QAAE,OAAO,OAAO,CAAC;IACvD,gEAAgE;IAChE,IAAI,IAAI,CAAC,QAAQ,KAAK,YAAY,IAAI,OAAO,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAoB,EACpB,UAAyB,EACzB,WAA0B,EAC1B,QAAgB,EAChB,OAAwC;IAExC,MAAM,MAAM,GAAG,OAAO,EAAE,QAAQ,CAAC;IAEjC,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,oBAAoB,CACtC,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,eAAe,CAChB,CAAC;QACF,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,OAAO;YACL,QAAQ,EAAE,YAAY;YACtB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,eAAe,CACjC,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,eAAe,CAChB,CAAC;QACF,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,OAAO;YACL,QAAQ,EAAE,YAAY;YACtB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QAC9D,mBAAmB,CAAC,MAAM,CAAC;QAC3B,qBAAqB,CAAC,MAAM,CAAC;KAC9B,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,aAAa,CAAC,MAAM,KAAK,UAAU;YACvC,CAAC,CAAC,aAAa,CAAC,MAAM;YACtB,CAAC,CAAC,aAAa,CAAC,MAAM,KAAK,UAAU;gBACnC,CAAC,CAAC,aAAa,CAAC,MAAM;gBACtB,CAAC,CAAC,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,CAC3B,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EACrE,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CACtE,CAAC;IAEF,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QACpD,OAAO;YACL,CAAC,CAAC,oBAAoB,CAClB,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,IAAI,CAAC,KAAK,EACV,OAAO,CACR;YACH,CAAC,CAAC,OAAO,CAAC,MAAM,CACZ,aAAa,CAAC,MAAM,KAAK,UAAU;gBACjC,CAAC,CAAC,aAAa,CAAC,MAAM;gBACtB,CAAC,CAAC,IAAI,KAAK,CAAC,oCAAoC,CAAC,CACpD;QACL,OAAO;YACL,CAAC,CAAC,eAAe,CACb,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,IAAI,CAAC,MAAM,EACX,OAAO,CACR;YACH,CAAC,CAAC,OAAO,CAAC,MAAM,CACZ,aAAa,CAAC,MAAM,KAAK,UAAU;gBACjC,CAAC,CAAC,aAAa,CAAC,MAAM;gBACtB,CAAC,CAAC,IAAI,KAAK,CAAC,oCAAoC,CAAC,CACpD;KACN,CAAC,CAAC;IAEH,IAAI,IAAI,GAA8B,IAAI,CAAC;IAC3C,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE;gBAClB,QAAQ,EAAE,YAAY;gBACtB,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;gBACnC,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW;gBACvC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;gBAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE;gBAClB,QAAQ,EAAE,YAAY;gBACtB,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;gBACnC,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW;gBACvC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;gBAC/B,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/build/src/services/uniswap.service.d.ts

@@ -1,7 +1,8 @@
 import type { CeloClientFactory } from "../clients/celo-client.js";
+import { type UniswapProtocol } from "../config/uniswap.js";
 import { type SerializedPreparedFlow } from "../types/prepared.js";
 import { type SwapPairsResult } from "./swap-pairs.js";
-/** Optional parameters for Uniswap v4 swap estimates and prepares. */
+/** Optional parameters for Uniswap swap estimates and prepares. */
 export interface UniswapSwapParams {
     /** Max slippage tolerance in percent (default `0.5`). */
     slippageTolerance?: number;
@@ -9,8 +10,13 @@ export interface UniswapSwapParams {
     deadlineMinutes?: number;
     /** Address receiving output tokens (default: `from`). */
     recipient?: `0x${string}`;
+    /**
+     * When set, quote and prepare only this venue.
+     * Omit to compare v3 and v4 and keep the higher output.
+     */
+    protocol?: UniswapProtocol;
 }
-/** Uniswap v4 quotes, gas estimates, and `prepareSwap` flows on Celo mainnet. */
+/** Uniswap v3 and v4 quotes, gas estimates, and `prepareSwap` flows on Celo mainnet. */
 export declare class UniswapService {
     private readonly clientFactory;
     private readonly tokenService;
@@ -23,13 +29,18 @@ export declare class UniswapService {
     private getApprovalSteps;
     private estimateCallGas;
     private estimateSwapGasWithAllowance;
+    private venueLabel;
+    private buildSwapCalldata;
     /**
-     * Uniswap v4 registry-token pairs on Celo mainnet (direct pools and 2-hop routes).
+     * Uniswap registry-token pairs on Celo mainnet (v4 graph plus v3 hub pools).
+     * `protocol` stays `uniswap_v4` for existing consumers. Each pair's `venues`
+     * lists which versions can route it.
      * @param token - Optional registry symbol; when set, only pairs involving that token
      */
     listPairs(token?: string): Promise<SwapPairsResult>;
     /**
-     * Expected Uniswap v4 output for a token pair — no wallet required.
+     * Expected Uniswap output for a token pair — no wallet required.
+     * Compares v3 and v4 and returns the higher output.
      * @param tokenIn - Input token symbol or address
      * @param tokenOut - Output token symbol or address
      * @param amount - Human-readable input amount
@@ -37,9 +48,9 @@ export declare class UniswapService {
      */
     getSwapQuote(tokenIn: string, tokenOut: string, amount: string, _from?: `0x${string}`): Promise<{
         route: {
-            pools: import("../config/uniswap.js").UniswapPoolKey[];
+            pools: import("../config/uniswap.js").UniswapPoolKey[] | import("../config/uniswap.js").UniswapV3Pool[];
         };
-        protocol: "uniswap_v4";
+        protocol: UniswapProtocol;
         network: "mainnet";
         tokenIn: string;
         tokenOut: string;
@@ -49,7 +60,8 @@ export declare class UniswapService {
         indexSource: string | undefined;
     }>;
     /**
-     * Simulate gas for a Uniswap v4 swap from `from`, including Permit2 approvals when needed.
+     * Simulate gas for a Uniswap swap from `from`.
+     * v4 includes Permit2 approvals when needed. v3 includes one ERC-20 approval when needed.
      * @param from - Sender wallet address
      * @param tokenIn - Input token symbol or address
      * @param tokenOut - Output token symbol or address
@@ -67,7 +79,7 @@ export declare class UniswapService {
         slippageTolerance: number;
         deadline: string;
         deadlineMinutes: number;
-        protocol: "uniswap_v4";
+        protocol: UniswapProtocol;
         network: "mainnet";
         tokenIn: string;
         tokenOut: string;
@@ -77,7 +89,10 @@ export declare class UniswapService {
         indexSource: string | undefined;
     }>;
     /**
-     * Build unsigned Uniswap v4 steps (ERC-20 approve → Permit2 approve → swap when needed).
+     * Build unsigned Uniswap steps.
+     * v4: ERC-20 approve → Permit2 approve → Universal Router swap.
+     * v3: ERC-20 approve → SwapRouter02 multicall swap.
+     * Pass `params.protocol` to pin the venue from a quote the caller already chose.
      * @param from - Sender wallet address
      * @param tokenIn - Input token symbol or address
      * @param tokenOut - Output token symbol or address