@andrewkimjoseph/celina-sdk 0.9.8 → 0.10.0

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

@@ -0,0 +1,168 @@
+import { v4QuoterAbi } from "../abis/uniswap-v4-quoter.js";
+import { normalizeUniswapPoolKey, UNISWAP_V4, } from "../config/uniswap.js";
+import { getUniswapPoolIndex, poolsBetween, } from "./uniswap-pool-discovery.js";
+/** Maximum pools in a route (2 intermediate currencies → 3 pools). */
+const MAX_POOLS = 3;
+function otherToken(poolKey, currency) {
+    const c = currency.toLowerCase();
+    if (poolKey.currency0.toLowerCase() === c)
+        return poolKey.currency1;
+    if (poolKey.currency1.toLowerCase() === c)
+        return poolKey.currency0;
+    return null;
+}
+function buildPathKeys(pools, currencyIn) {
+    let current = currencyIn;
+    const pathKeys = [];
+    for (const poolKey of pools) {
+        const out = otherToken(poolKey, current);
+        if (!out) {
+            throw new Error("Invalid swap path for Uniswap v4 pools.");
+        }
+        pathKeys.push({
+            intermediateCurrency: out,
+            fee: poolKey.fee,
+            tickSpacing: poolKey.tickSpacing,
+            hooks: poolKey.hooks,
+            hookData: "0x",
+        });
+        current = out;
+    }
+    return pathKeys;
+}
+function enumeratePaths(index, currencyIn, currencyOut) {
+    const start = currencyIn.toLowerCase();
+    const goal = currencyOut.toLowerCase();
+    if (start === goal) {
+        return [];
+    }
+    const results = [];
+    const queue = [{ currency: 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.currency);
+        if (!neighbors) {
+            continue;
+        }
+        for (const neighbor of neighbors) {
+            if (node.visited.has(neighbor)) {
+                continue;
+            }
+            // A pair can have several pools (different fee tiers); branch over each so
+            // the quoter can pick the genuinely best-priced one.
+            for (const poolKey of poolsBetween(index, node.currency, neighbor)) {
+                const nextPools = [...node.pools, poolKey];
+                if (neighbor === goal) {
+                    results.push(nextPools);
+                    continue;
+                }
+                if (nextPools.length < MAX_POOLS) {
+                    queue.push({
+                        currency: neighbor,
+                        pools: nextPools,
+                        visited: new Set([...node.visited, neighbor]),
+                    });
+                }
+            }
+        }
+    }
+    return results;
+}
+async function quotePath(client, currencyIn, pools, amountIn) {
+    if (pools.length === 0) {
+        return 0n;
+    }
+    if (pools.length === 1) {
+        const poolKey = normalizeUniswapPoolKey(pools[0]);
+        const zeroForOne = currencyIn.toLowerCase() === poolKey.currency0.toLowerCase();
+        const { result } = await client.simulateContract({
+            address: UNISWAP_V4.v4Quoter,
+            abi: v4QuoterAbi,
+            functionName: "quoteExactInputSingle",
+            args: [
+                {
+                    poolKey,
+                    zeroForOne,
+                    exactAmount: amountIn,
+                    hookData: "0x",
+                },
+            ],
+        });
+        return result[0];
+    }
+    const pathKeys = buildPathKeys(pools, currencyIn);
+    const { result } = await client.simulateContract({
+        address: UNISWAP_V4.v4Quoter,
+        abi: v4QuoterAbi,
+        functionName: "quoteExactInput",
+        args: [
+            {
+                exactCurrency: currencyIn,
+                path: pathKeys,
+                exactAmount: amountIn,
+            },
+        ],
+    });
+    return result[0];
+}
+/**
+ * Quote all candidate paths and return the highest-output Uniswap v4 route.
+ * @param client - Celo public client for quoter simulation
+ * @param currencyIn - Input currency address (native CELO maps to WCELO upstream)
+ * @param currencyOut - Output currency address
+ * @param amountIn - Input amount in base units
+ * @returns Best route and quoter output, or `null` when no path quotes successfully
+ */
+export async function findBestUniswapRoute(client, currencyIn, currencyOut, amountIn) {
+    const index = await getUniswapPoolIndex(client);
+    const candidatePaths = enumeratePaths(index, currencyIn, currencyOut);
+    // Quote every candidate path concurrently; failed quotes (e.g. uninitialized
+    // pools or insufficient liquidity) are dropped rather than aborting the rest.
+    const quotes = await Promise.allSettled(candidatePaths.map(async (pools) => ({
+        pools,
+        amountOut: await quotePath(client, currencyIn, pools, amountIn),
+    })));
+    let best = null;
+    for (const quote of quotes) {
+        if (quote.status !== "fulfilled") {
+            continue;
+        }
+        const { pools, amountOut } = quote.value;
+        if (amountOut <= 0n) {
+            continue;
+        }
+        if (!best || amountOut > best.amountOut) {
+            best = {
+                amountOut,
+                route: {
+                    currencyIn,
+                    currencyOut,
+                    pools,
+                    pathKeys: buildPathKeys(pools, currencyIn),
+                    hops: pools.length,
+                },
+            };
+        }
+    }
+    if (!best) {
+        return null;
+    }
+    return {
+        route: best.route,
+        amountOut: best.amountOut,
+        indexSource: index.source,
+    };
+}
+/**
+ * Apply slippage tolerance to a quoted output amount.
+ * @param amountOut - Quoted output in base units
+ * @param slippagePercent - Max slippage in percent (e.g. `0.5` for 0.5%)
+ */
+export function applySlippage(amountOut, slippagePercent) {
+    const bps = BigInt(Math.round(slippagePercent * 100));
+    return (amountOut * (10000n - bps)) / 10000n;
+}
+//# sourceMappingURL=uniswap-path-router.js.map

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * Uniswap v4 pool discovery: subgraph index with on-chain hub fallback.
+ */
+import { type PublicClient } from "viem";
+import { type UniswapPoolKey } from "../config/uniswap.js";
+/** One edge in the v4 pool routing graph. */
+export type UniswapPoolEdge = {
+    poolKey: UniswapPoolKey;
+    tokenA: `0x${string}`;
+    tokenB: `0x${string}`;
+};
+/** Cached routing graph of v4 pools on Celo mainnet. */
+export type UniswapPoolIndex = {
+    edges: UniswapPoolEdge[];
+    /** Currency address (lowercase) → neighbor currencies in the graph. */
+    adjacency: Map<string, Set<string>>;
+    /**
+     * Sorted pair key (`tokenLo|tokenHi`, lowercase) → every pool connecting that
+     * pair. A single token pair can have several pools across fee tiers, so the
+     * router must consider all of them to find the best rate.
+     */
+    poolsByPair: Map<string, UniswapPoolKey[]>;
+    /** Whether pools came from the v4 subgraph or on-chain hub probing. */
+    source: "subgraph" | "onchain";
+    fetchedAt: number;
+};
+/**
+ * Compute the Uniswap v4 pool id (keccak256 of sorted pool key fields).
+ * @param poolKey - Pool key (normalized so currency0 sorts before currency1)
+ */
+export declare function computeUniswapPoolId(poolKey: UniswapPoolKey): `0x${string}`;
+/**
+ * Load or refresh the v4 pool index (subgraph first, on-chain hub fallback).
+ * @param client - Celo public client for StateView probing
+ * @param options.forceRefresh - Bypass TTL cache when true
+ */
+export declare function getUniswapPoolIndex(client: PublicClient, options?: {
+    forceRefresh?: boolean;
+}): Promise<UniswapPoolIndex>;
+/**
+ * All pools connecting two tokens in a cached index (one per fee tier / hooks).
+ * @param index - Pool graph from `getUniswapPoolIndex`
+ * @param tokenA - First currency address
+ * @param tokenB - Second currency address
+ */
+export declare function poolsBetween(index: UniswapPoolIndex, tokenA: `0x${string}`, tokenB: `0x${string}`): UniswapPoolKey[];
+/**
+ * Find a pool key connecting two tokens in a cached index, if present.
+ * @param index - Pool graph from `getUniswapPoolIndex`
+ * @param tokenA - First currency address
+ * @param tokenB - Second currency address
+ */
+export declare function findPoolBetween(index: UniswapPoolIndex, tokenA: `0x${string}`, tokenB: `0x${string}`): UniswapPoolKey | null;
+/** Reset cached index (for tests). */
+export declare function resetUniswapPoolIndexCache(): void;

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

@@ -0,0 +1,198 @@
+/**
+ * Uniswap v4 pool discovery: subgraph index with on-chain hub fallback.
+ */
+import { encodeAbiParameters, keccak256, parseAbiParameters, } from "viem";
+import { stateViewAbi } from "../abis/uniswap-state-view.js";
+import { normalizeUniswapPoolKey, UNISWAP_DEFAULT_TICK_SPACING, UNISWAP_FEE_TIERS, UNISWAP_HUB_CURRENCIES, UNISWAP_POOL_CACHE_TTL_MS, UNISWAP_SUBGRAPH_URL, UNISWAP_V4, } from "../config/uniswap.js";
+let cachedIndex = null;
+/** Canonical lowercase key for the unordered pair `(a, b)`. */
+function pairKey(a, b) {
+    const lo = a.toLowerCase();
+    const hi = b.toLowerCase();
+    return lo < hi ? `${lo}|${hi}` : `${hi}|${lo}`;
+}
+/**
+ * Compute the Uniswap v4 pool id (keccak256 of sorted pool key fields).
+ * @param poolKey - Pool key (normalized so currency0 sorts before currency1)
+ */
+export function computeUniswapPoolId(poolKey) {
+    const normalized = normalizeUniswapPoolKey(poolKey);
+    return keccak256(encodeAbiParameters(parseAbiParameters("address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks"), [
+        normalized.currency0,
+        normalized.currency1,
+        normalized.fee,
+        normalized.tickSpacing,
+        normalized.hooks,
+    ]));
+}
+/**
+ * Build a routing index from raw pool keys: dedup by pool id, then derive the
+ * edge list, currency adjacency, and per-pair pool buckets.
+ */
+function buildPoolIndex(poolKeys, source) {
+    const edges = [];
+    const adjacency = new Map();
+    const poolsByPair = new Map();
+    const seen = new Set();
+    for (const key of poolKeys) {
+        const normalized = normalizeUniswapPoolKey(key);
+        const id = computeUniswapPoolId(normalized);
+        if (seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        const a = normalized.currency0.toLowerCase();
+        const b = normalized.currency1.toLowerCase();
+        edges.push({
+            poolKey: normalized,
+            tokenA: normalized.currency0,
+            tokenB: normalized.currency1,
+        });
+        if (!adjacency.has(a))
+            adjacency.set(a, new Set());
+        if (!adjacency.has(b))
+            adjacency.set(b, new Set());
+        adjacency.get(a).add(b);
+        adjacency.get(b).add(a);
+        const pk = pairKey(a, b);
+        const bucket = poolsByPair.get(pk);
+        if (bucket) {
+            bucket.push(normalized);
+        }
+        else {
+            poolsByPair.set(pk, [normalized]);
+        }
+    }
+    return { edges, adjacency, poolsByPair, source, fetchedAt: Date.now() };
+}
+async function fetchSubgraphPools() {
+    try {
+        const response = await fetch(UNISWAP_SUBGRAPH_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: `{
+          pools(first: 500, orderBy: totalValueLockedUSD, orderDirection: desc) {
+            feeTier
+            tickSpacing
+            hooks
+            token0 { id }
+            token1 { id }
+          }
+        }`,
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const json = (await response.json());
+        const pools = json.data?.pools;
+        if (!pools?.length) {
+            return null;
+        }
+        return pools.map((pool) => ({
+            currency0: pool.token0.id,
+            currency1: pool.token1.id,
+            fee: Number(pool.feeTier),
+            tickSpacing: Number(pool.tickSpacing),
+            hooks: (pool.hooks || UNISWAP_V4.zeroHooks),
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+async function probePoolOnChain(client, currencyA, currencyB, fee, tickSpacing) {
+    const poolKey = normalizeUniswapPoolKey({
+        currency0: currencyA,
+        currency1: currencyB,
+        fee,
+        tickSpacing,
+        hooks: UNISWAP_V4.zeroHooks,
+    });
+    const poolId = computeUniswapPoolId(poolKey);
+    try {
+        const [slot0, liquidity] = await Promise.all([
+            client.readContract({
+                address: UNISWAP_V4.stateView,
+                abi: stateViewAbi,
+                functionName: "getSlot0",
+                args: [poolId],
+            }),
+            client.readContract({
+                address: UNISWAP_V4.stateView,
+                abi: stateViewAbi,
+                functionName: "getLiquidity",
+                args: [poolId],
+            }),
+        ]);
+        if (slot0[0] > 0n && liquidity > 0n) {
+            return poolKey;
+        }
+    }
+    catch {
+        // pool not initialized
+    }
+    return null;
+}
+async function buildOnChainIndex(client) {
+    const hubs = [...UNISWAP_HUB_CURRENCIES];
+    const probes = [];
+    for (let i = 0; i < hubs.length; i++) {
+        for (let j = i + 1; j < hubs.length; j++) {
+            const [currency0, currency1] = hubs[i].toLowerCase() < hubs[j].toLowerCase()
+                ? [hubs[i], hubs[j]]
+                : [hubs[j], hubs[i]];
+            for (const fee of UNISWAP_FEE_TIERS) {
+                const tickSpacing = UNISWAP_DEFAULT_TICK_SPACING[fee] ??
+                    UNISWAP_DEFAULT_TICK_SPACING[3000];
+                probes.push(probePoolOnChain(client, currency0, currency1, fee, tickSpacing));
+            }
+        }
+    }
+    const poolKeys = (await Promise.all(probes)).filter((poolKey) => poolKey !== null);
+    return buildPoolIndex(poolKeys, "onchain");
+}
+/**
+ * Load or refresh the v4 pool index (subgraph first, on-chain hub fallback).
+ * @param client - Celo public client for StateView probing
+ * @param options.forceRefresh - Bypass TTL cache when true
+ */
+export async function getUniswapPoolIndex(client, options) {
+    const now = Date.now();
+    if (!options?.forceRefresh &&
+        cachedIndex &&
+        now - cachedIndex.fetchedAt < UNISWAP_POOL_CACHE_TTL_MS) {
+        return cachedIndex;
+    }
+    const subgraphPools = await fetchSubgraphPools();
+    if (subgraphPools?.length) {
+        cachedIndex = buildPoolIndex(subgraphPools, "subgraph");
+        return cachedIndex;
+    }
+    cachedIndex = await buildOnChainIndex(client);
+    return cachedIndex;
+}
+/**
+ * All pools connecting two tokens in a cached index (one per fee tier / hooks).
+ * @param index - Pool graph from `getUniswapPoolIndex`
+ * @param tokenA - First currency address
+ * @param tokenB - Second currency address
+ */
+export function poolsBetween(index, tokenA, tokenB) {
+    return index.poolsByPair.get(pairKey(tokenA, tokenB)) ?? [];
+}
+/**
+ * Find a pool key connecting two tokens in a cached index, if present.
+ * @param index - Pool graph from `getUniswapPoolIndex`
+ * @param tokenA - First currency address
+ * @param tokenB - Second currency address
+ */
+export function findPoolBetween(index, tokenA, tokenB) {
+    return poolsBetween(index, tokenA, tokenB)[0] ?? null;
+}
+/** Reset cached index (for tests). */
+export function resetUniswapPoolIndexCache() {
+    cachedIndex = null;
+}
+//# sourceMappingURL=uniswap-pool-discovery.js.map

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

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

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

@@ -0,0 +1,82 @@
+import type { CeloClientFactory } from "../clients/celo-client.js";
+import { type SerializedPreparedFlow } from "../types/prepared.js";
+/** Optional parameters for Uniswap v4 swap estimates and prepares. */
+export interface UniswapSwapParams {
+    /** Max slippage tolerance in percent (default `0.5`). */
+    slippageTolerance?: number;
+    /** Swap deadline in minutes from now (default `5`). */
+    deadlineMinutes?: number;
+    /** Address receiving output tokens (default: `from`). */
+    recipient?: `0x${string}`;
+}
+/** Uniswap v4 quotes, gas estimates, and `prepareSwap` flows on Celo mainnet. */
+export declare class UniswapService {
+    private readonly clientFactory;
+    private readonly tokenService;
+    constructor(clientFactory: CeloClientFactory);
+    private resolvePair;
+    private baseQuoteFields;
+    private buildSwapRoute;
+    private buildUniversalRouterCalldata;
+    private getApprovalSteps;
+    private estimateCallGas;
+    private estimateSwapGasWithAllowance;
+    /**
+     * Expected Uniswap v4 output for a token pair — no wallet required.
+     * @param tokenIn - Input token symbol or address
+     * @param tokenOut - Output token symbol or address
+     * @param amount - Human-readable input amount
+     * @param _from - Deprecated; ignored. Balance checks run on prepare/estimate only.
+     */
+    getSwapQuote(tokenIn: string, tokenOut: string, amount: string, _from?: `0x${string}`): Promise<{
+        route: {
+            pools: import("../config/uniswap.js").UniswapPoolKey[];
+        };
+        protocol: "uniswap_v4";
+        network: "mainnet";
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        expectedOut: string;
+        routeHops: number;
+        indexSource: string | undefined;
+    }>;
+    /**
+     * Simulate gas for a Uniswap v4 swap from `from`, including Permit2 approvals when needed.
+     * @param from - Sender wallet address
+     * @param tokenIn - Input token symbol or address
+     * @param tokenOut - Output token symbol or address
+     * @param amount - Human-readable input amount
+     * @param params - Optional slippage, deadline, and recipient
+     */
+    estimateSwap(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: UniswapSwapParams): Promise<{
+        from: `0x${string}`;
+        recipient: `0x${string}`;
+        amountOutMin: string;
+        approvalStepsNeeded: number;
+        approvalGas: string[];
+        swapGas: string | undefined;
+        swapGasEstimated: boolean;
+        slippageTolerance: number;
+        deadline: string;
+        deadlineMinutes: number;
+        protocol: "uniswap_v4";
+        network: "mainnet";
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        expectedOut: string;
+        routeHops: number;
+        indexSource: string | undefined;
+    }>;
+    /**
+     * Build unsigned Uniswap v4 steps (ERC-20 approve → Permit2 approve → swap when needed).
+     * @param from - Sender wallet address
+     * @param tokenIn - Input token symbol or address
+     * @param tokenOut - Output token symbol or address
+     * @param amount - Human-readable input amount
+     * @param params - Optional slippage, deadline, and recipient
+     * @returns 1–3 step `SerializedPreparedFlow` for sequential wallet signing
+     */
+    prepareSwap(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: UniswapSwapParams): Promise<SerializedPreparedFlow>;
+}