@andrewkimjoseph/celina-sdk 0.9.7 → 0.9.9

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

@@ -0,0 +1,110 @@
+import type { CeloClientFactory } from "../clients/celo-client.js";
+/** Resolved Celo mainnet registry token (symbol, address, decimals). */
+export interface ResolvedToken {
+    /** Registry address, or `"native"` for CELO. */
+    address: `0x${string}` | "native";
+    /** Canonical registry symbol (e.g. `USDm`, `GoodDollar`). */
+    symbol: string;
+    /** Token decimals for amount parsing. */
+    decimals: number;
+}
+/** Celo mainnet token registry lookups and balance reads. */
+export declare class TokenService {
+    private readonly clientFactory;
+    constructor(clientFactory: CeloClientFactory);
+    /**
+     * Resolve a Celo mainnet registry token by symbol, alias, or registry address.
+     * @throws If the token is not in the Celo registry
+     */
+    resolveToken(token: string): ResolvedToken;
+    /** Fetch registry token metadata on Celo mainnet. */
+    getTokenInfo(token: string): Promise<{
+        network: "mainnet";
+        address: `0x${string}` | "native";
+        name: string;
+        symbol: string;
+        decimals: number;
+    }>;
+    /** CELO and ERC-20 balances for registry tokens (defaults: CELO, USDm). */
+    getBalances(address: `0x${string}`, tokens?: string[]): Promise<{
+        network: "mainnet";
+        address: `0x${string}`;
+        balances: ({
+            token: string;
+            address: "native";
+            raw: string;
+            formatted: string;
+        } | {
+            token: string;
+            address: `0x${string}`;
+            raw: string;
+            formatted: string;
+        })[];
+    }>;
+    /**
+     * Scan fiat-pegged registry stablecoins for an address; omits zero balances by default.
+     * GoodDollar and WETH are excluded — use `getTokenBalance` or GoodDollar tools.
+     * @param address - Wallet to scan
+     * @param options.stablecoins - Subset of registry symbols to check
+     * @param options.includeZero - Include tokens with zero balance
+     */
+    getStablecoinBalances(address: `0x${string}`, options?: {
+        stablecoins?: string[];
+        includeZero?: boolean;
+    }): Promise<{
+        network: string;
+        address: `0x${string}`;
+        totalChecked: number;
+        stablecoins: ({
+            symbol: string;
+            address: `0x${string}`;
+            issuer: string;
+            useCase: string;
+            raw: string;
+            formatted: string;
+            readError: boolean;
+        } | {
+            symbol: string;
+            address: `0x${string}`;
+            issuer: string;
+            useCase: string;
+            raw: string;
+            formatted: string;
+            readError?: undefined;
+        })[];
+    }>;
+    /** Balance for a Celo mainnet registry token (symbol or registry address). */
+    getTokenBalance(token: string, accountAddress: `0x${string}`): Promise<{
+        network: "mainnet";
+        tokenAddress: "native";
+        accountAddress: `0x${string}`;
+        name: string;
+        symbol: string;
+        decimals: number;
+        raw: string;
+        formatted: string;
+    } | {
+        network: "mainnet";
+        tokenAddress: `0x${string}`;
+        accountAddress: `0x${string}`;
+        name: string;
+        symbol: string;
+        decimals: number;
+        raw: string;
+        formatted: string;
+    }>;
+    /**
+     * Parse a human-readable amount string to base units for the given decimals.
+     * @param amount - Decimal string (e.g. `"10"` or `"0.05"`)
+     * @param decimals - Token decimals from `resolveToken`
+     */
+    parseAmount(amount: string, decimals: number): bigint;
+    /**
+     * Ensure `owner` holds at least `amount` of the input token before swap/route work.
+     * @param spendToken - ERC-20 to check (defaults to registry address; use WCELO when swapping native CELO)
+     */
+    assertSpendableBalance(owner: `0x${string}`, resolved: ResolvedToken, amount: string, options?: {
+        spendToken?: `0x${string}` | "native";
+        hint?: string;
+    }): Promise<void>;
+}

package/build/src/services/token.service.js

@@ -0,0 +1,189 @@
+/**
+ * Token registry lookups and balance reads on Celo mainnet.
+ */
+import { erc20Abi, formatUnits, parseUnits } from "viem";
+import { findKnownToken, KNOWN_TOKEN_SYMBOLS, resolveStablecoins, suggestKnownTokens, } from "../config/chains.js";
+import { normalizeAddress } from "../utils/normalize-address.js";
+/** Celo mainnet token registry lookups and balance reads. */
+export class TokenService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    /**
+     * Resolve a Celo mainnet registry token by symbol, alias, or registry address.
+     * @throws If the token is not in the Celo registry
+     */
+    resolveToken(token) {
+        const known = findKnownToken(token.trim());
+        if (!known) {
+            const suggestions = suggestKnownTokens(token);
+            if (suggestions.length > 0) {
+                throw new Error(`Unknown token "${token}" on Celo mainnet. Did you mean ${suggestions.map((entry) => entry.symbol).join(", ")}?`);
+            }
+            throw new Error(`Unknown token "${token}" on Celo mainnet. Use ${KNOWN_TOKEN_SYMBOLS.join(", ")}.`);
+        }
+        return {
+            address: known.address,
+            symbol: known.symbol,
+            decimals: known.decimals,
+        };
+    }
+    /** Fetch registry token metadata on Celo mainnet. */
+    async getTokenInfo(token) {
+        const resolved = this.resolveToken(token);
+        return {
+            network: "mainnet",
+            address: resolved.address,
+            name: resolved.address === "native" ? "Celo" : resolved.symbol,
+            symbol: resolved.symbol,
+            decimals: resolved.decimals,
+        };
+    }
+    /** CELO and ERC-20 balances for registry tokens (defaults: CELO, USDm). */
+    async getBalances(address, tokens = ["CELO", "USDm"]) {
+        const { public: client } = this.clientFactory.getClients();
+        const balances = await Promise.all(tokens.map(async (tokenInput) => {
+            const token = this.resolveToken(tokenInput);
+            if (token.address === "native") {
+                const balance = await client.getBalance({ address });
+                return {
+                    token: token.symbol,
+                    address: "native",
+                    raw: balance.toString(),
+                    formatted: formatUnits(balance, token.decimals),
+                };
+            }
+            const balance = await client.readContract({
+                address: token.address,
+                abi: erc20Abi,
+                functionName: "balanceOf",
+                args: [address],
+            });
+            return {
+                token: token.symbol,
+                address: token.address,
+                raw: balance.toString(),
+                formatted: formatUnits(balance, token.decimals),
+            };
+        }));
+        return { network: "mainnet", address, balances };
+    }
+    /**
+     * Scan fiat-pegged registry stablecoins for an address; omits zero balances by default.
+     * GoodDollar and WETH are excluded — use `getTokenBalance` or GoodDollar tools.
+     * @param address - Wallet to scan
+     * @param options.stablecoins - Subset of registry symbols to check
+     * @param options.includeZero - Include tokens with zero balance
+     */
+    async getStablecoinBalances(address, options) {
+        const coins = resolveStablecoins(options?.stablecoins);
+        const { public: client } = this.clientFactory.getClients();
+        const results = await client.multicall({
+            contracts: coins.map((coin) => ({
+                address: coin.address,
+                abi: erc20Abi,
+                functionName: "balanceOf",
+                args: [address],
+            })),
+            allowFailure: true,
+        });
+        const balances = coins.map((coin, index) => {
+            const result = results[index];
+            if (result.status === "failure") {
+                return {
+                    symbol: coin.symbol,
+                    address: coin.address,
+                    issuer: coin.issuer,
+                    useCase: coin.useCase,
+                    raw: "0",
+                    formatted: "0",
+                    readError: true,
+                };
+            }
+            const raw = result.result;
+            return {
+                symbol: coin.symbol,
+                address: coin.address,
+                issuer: coin.issuer,
+                useCase: coin.useCase,
+                raw: raw.toString(),
+                formatted: formatUnits(raw, coin.decimals),
+            };
+        });
+        const stablecoins = options?.includeZero
+            ? balances
+            : balances.filter((balance) => balance.raw !== "0");
+        return {
+            network: "mainnet",
+            address,
+            totalChecked: coins.length,
+            stablecoins,
+        };
+    }
+    /** Balance for a Celo mainnet registry token (symbol or registry address). */
+    async getTokenBalance(token, accountAddress) {
+        const resolved = this.resolveToken(token);
+        const account = normalizeAddress(accountAddress, "account address");
+        const { public: client } = this.clientFactory.getClients();
+        if (resolved.address === "native") {
+            const balance = await client.getBalance({ address: account });
+            return {
+                network: "mainnet",
+                tokenAddress: "native",
+                accountAddress: account,
+                name: "Celo",
+                symbol: "CELO",
+                decimals: resolved.decimals,
+                raw: balance.toString(),
+                formatted: formatUnits(balance, resolved.decimals),
+            };
+        }
+        const balance = await client.readContract({
+            address: resolved.address,
+            abi: erc20Abi,
+            functionName: "balanceOf",
+            args: [account],
+        });
+        return {
+            network: "mainnet",
+            tokenAddress: resolved.address,
+            accountAddress: account,
+            name: resolved.symbol,
+            symbol: resolved.symbol,
+            decimals: resolved.decimals,
+            raw: balance.toString(),
+            formatted: formatUnits(balance, resolved.decimals),
+        };
+    }
+    /**
+     * Parse a human-readable amount string to base units for the given decimals.
+     * @param amount - Decimal string (e.g. `"10"` or `"0.05"`)
+     * @param decimals - Token decimals from `resolveToken`
+     */
+    parseAmount(amount, decimals) {
+        return parseUnits(amount, decimals);
+    }
+    /**
+     * Ensure `owner` holds at least `amount` of the input token before swap/route work.
+     * @param spendToken - ERC-20 to check (defaults to registry address; use WCELO when swapping native CELO)
+     */
+    async assertSpendableBalance(owner, resolved, amount, options) {
+        const { public: client } = this.clientFactory.getClients();
+        const required = this.parseAmount(amount, resolved.decimals);
+        const spend = options?.spendToken ?? resolved.address;
+        const balance = spend === "native"
+            ? await client.getBalance({ address: owner })
+            : await client.readContract({
+                address: spend,
+                abi: erc20Abi,
+                functionName: "balanceOf",
+                args: [owner],
+            });
+        if (balance < required) {
+            const available = formatUnits(balance, resolved.decimals);
+            throw new Error(`Insufficient ${resolved.symbol} balance. Required ${amount} ${resolved.symbol}, available ${available}.${options?.hint ?? ""}`);
+        }
+    }
+}
+//# sourceMappingURL=token.service.js.map

package/build/src/services/token.service.js.map

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

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

@@ -0,0 +1,68 @@
+/**
+ * Token sends: estimateSend simulates gas; prepareSend builds unsigned tx steps.
+ * Calldata is tagged with CELINA_DATA_SUFFIX for on-chain attribution.
+ */
+import { type Hex } from "viem";
+import type { CeloClientFactory } from "../clients/celo-client.js";
+import { type SerializedPreparedFlow } from "../types/prepared.js";
+export type SendEstimateResult = {
+    network: "mainnet";
+    from: `0x${string}`;
+    to: `0x${string}`;
+    token: string;
+    amount: string;
+    gas: string | null;
+    insufficientBalance?: boolean;
+    message?: string;
+};
+/** Token sends, gas fee reads, and `prepareSend` flows with CELINA calldata tags. */
+export declare class TransactionService {
+    private readonly clientFactory;
+    private readonly tokenService;
+    constructor(clientFactory: CeloClientFactory);
+    /**
+     * Simulate gas for a CELO or ERC-20 transfer from `from`.
+     * @param from - Sender wallet address
+     * @param to - Recipient address
+     * @param token - Symbol (e.g. `CELO`, `USDm`) or contract address
+     * @param amount - Human-readable amount (e.g. `"10"`)
+     * @returns Gas estimate in units as a decimal string, or a structured insufficient-balance result when simulation reverts.
+     */
+    estimateSend(from: `0x${string}`, to: `0x${string}`, token: string, amount: string): Promise<SendEstimateResult>;
+    /**
+     * Build an unsigned send flow (native CELO or ERC-20 transfer).
+     * @param from - Sender wallet address (must match connected wallet when signing)
+     * @param to - Recipient address
+     * @param token - Symbol or contract address
+     * @param amount - Human-readable amount
+     * @returns Single-step `SerializedPreparedFlow` for wagmi `sendTransactionAsync`
+     */
+    prepareSend(from: `0x${string}`, to: `0x${string}`, token: string, amount: string): Promise<SerializedPreparedFlow>;
+    /** Current gas fee data including EIP-1559 fees when supported. */
+    getGasFeeData(): Promise<{
+        network: "mainnet";
+        baseFeePerGas: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        gasPrice: string;
+        eip1559: boolean;
+    }>;
+    /** Generic transaction gas estimate (not token-transfer specific). */
+    estimateTransaction(params: {
+        from: `0x${string}`;
+        to: `0x${string}`;
+        value?: string;
+        data?: Hex;
+    }): Promise<{
+        network: "mainnet";
+        from: `0x${string}`;
+        to: `0x${string}`;
+        gasLimit: string;
+        gasPrice: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        estimatedCost: string;
+        estimatedCostFormatted: string;
+        isEip1559: boolean;
+    }>;
+}

package/build/src/services/transaction.service.js

@@ -0,0 +1,198 @@
+/**
+ * Token sends: estimateSend simulates gas; prepareSend builds unsigned tx steps.
+ * Calldata is tagged with CELINA_DATA_SUFFIX for on-chain attribution.
+ */
+import { concat, encodeFunctionData, erc20Abi, parseEther, parseGwei, } from "viem";
+import { MENTO_CELO_ADDRESS } from "../config/chains.js";
+import { CELINA_DATA_SUFFIX } from "../config/celina-tag.js";
+import { normalizeAddress } from "../utils/normalize-address.js";
+import { serializePreparedFlow, } from "../types/prepared.js";
+import { TokenService } from "./token.service.js";
+import { insufficientBalanceEstimateMessage, isInsufficientBalanceSimulationError, } from "../utils/transaction-errors.js";
+function taggedCalldata(data) {
+    return concat([data, CELINA_DATA_SUFFIX]);
+}
+/** Token sends, gas fee reads, and `prepareSend` flows with CELINA calldata tags. */
+export class TransactionService {
+    clientFactory;
+    tokenService;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+        this.tokenService = new TokenService(clientFactory);
+    }
+    /**
+     * Simulate gas for a CELO or ERC-20 transfer from `from`.
+     * @param from - Sender wallet address
+     * @param to - Recipient address
+     * @param token - Symbol (e.g. `CELO`, `USDm`) or contract address
+     * @param amount - Human-readable amount (e.g. `"10"`)
+     * @returns Gas estimate in units as a decimal string, or a structured insufficient-balance result when simulation reverts.
+     */
+    async estimateSend(from, to, token, amount) {
+        const { public: client } = this.clientFactory.getClients();
+        const resolved = this.tokenService.resolveToken(token);
+        const base = {
+            network: "mainnet",
+            from,
+            to,
+            token: resolved.symbol,
+            amount,
+        };
+        try {
+            if (resolved.address === "native") {
+                const tokenAmount = parseEther(amount);
+                const gas = await client.estimateContractGas({
+                    account: from,
+                    address: MENTO_CELO_ADDRESS,
+                    abi: erc20Abi,
+                    functionName: "transfer",
+                    args: [to, tokenAmount],
+                });
+                return { ...base, gas: gas.toString() };
+            }
+            const tokenAmount = this.tokenService.parseAmount(amount, resolved.decimals);
+            const gas = await client.estimateContractGas({
+                account: from,
+                address: resolved.address,
+                abi: erc20Abi,
+                functionName: "transfer",
+                args: [to, tokenAmount],
+            });
+            return { ...base, gas: gas.toString() };
+        }
+        catch (error) {
+            if (isInsufficientBalanceSimulationError(error)) {
+                return {
+                    ...base,
+                    gas: null,
+                    insufficientBalance: true,
+                    message: insufficientBalanceEstimateMessage(resolved.symbol),
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Build an unsigned send flow (native CELO or ERC-20 transfer).
+     * @param from - Sender wallet address (must match connected wallet when signing)
+     * @param to - Recipient address
+     * @param token - Symbol or contract address
+     * @param amount - Human-readable amount
+     * @returns Single-step `SerializedPreparedFlow` for wagmi `sendTransactionAsync`
+     */
+    async prepareSend(from, to, token, amount) {
+        const resolved = this.tokenService.resolveToken(token);
+        if (resolved.address === "native") {
+            const tokenAmount = parseEther(amount);
+            const data = taggedCalldata(encodeFunctionData({
+                abi: erc20Abi,
+                functionName: "transfer",
+                args: [to, tokenAmount],
+            }));
+            const flow = {
+                network: "mainnet",
+                from,
+                summary: `Send ${amount} CELO to ${to}`,
+                steps: [
+                    {
+                        kind: "erc20",
+                        to: MENTO_CELO_ADDRESS,
+                        data,
+                        value: "0",
+                        description: `Send ${amount} CELO`,
+                    },
+                ],
+            };
+            return serializePreparedFlow(flow);
+        }
+        const tokenAmount = this.tokenService.parseAmount(amount, resolved.decimals);
+        const data = taggedCalldata(encodeFunctionData({
+            abi: erc20Abi,
+            functionName: "transfer",
+            args: [to, tokenAmount],
+        }));
+        const flow = {
+            network: "mainnet",
+            from,
+            summary: `Send ${amount} ${resolved.symbol} to ${to}`,
+            steps: [
+                {
+                    kind: "erc20",
+                    to: resolved.address,
+                    data,
+                    value: "0",
+                    description: `Transfer ${amount} ${resolved.symbol}`,
+                },
+            ],
+        };
+        return serializePreparedFlow(flow);
+    }
+    /** Current gas fee data including EIP-1559 fees when supported. */
+    async getGasFeeData() {
+        const { public: client } = this.clientFactory.getClients();
+        const [block, gasPrice] = await Promise.all([
+            client.getBlock({ blockTag: "latest" }),
+            client.getGasPrice(),
+        ]);
+        const baseFeePerGas = block.baseFeePerGas;
+        if (baseFeePerGas) {
+            const maxPriorityFeePerGas = parseGwei("2");
+            const maxFeePerGas = baseFeePerGas * 2n + maxPriorityFeePerGas;
+            return {
+                network: "mainnet",
+                baseFeePerGas: baseFeePerGas.toString(),
+                maxFeePerGas: maxFeePerGas.toString(),
+                maxPriorityFeePerGas: maxPriorityFeePerGas.toString(),
+                gasPrice: gasPrice.toString(),
+                eip1559: true,
+            };
+        }
+        return {
+            network: "mainnet",
+            baseFeePerGas: "0",
+            maxFeePerGas: gasPrice.toString(),
+            maxPriorityFeePerGas: "0",
+            gasPrice: gasPrice.toString(),
+            eip1559: false,
+        };
+    }
+    /** Generic transaction gas estimate (not token-transfer specific). */
+    async estimateTransaction(params) {
+        const from = normalizeAddress(params.from, "from address");
+        const to = normalizeAddress(params.to, "to address");
+        const { public: client } = this.clientFactory.getClients();
+        const value = params.value ? BigInt(params.value) : 0n;
+        const data = params.data ?? "0x";
+        let gasLimit;
+        try {
+            gasLimit = await client.estimateGas({
+                account: from,
+                to,
+                value,
+                data,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Transaction gas estimation failed: ${message}. ` +
+                "Ensure from/to addresses differ for empty transfers, or provide valid calldata.");
+        }
+        const feeData = await this.getGasFeeData();
+        const maxFee = BigInt(feeData.maxFeePerGas);
+        const estimatedCost = gasLimit * maxFee;
+        const estimatedCostCelo = Number(estimatedCost) / 1e18;
+        return {
+            network: "mainnet",
+            from,
+            to,
+            gasLimit: gasLimit.toString(),
+            gasPrice: feeData.gasPrice,
+            maxFeePerGas: feeData.maxFeePerGas,
+            maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
+            estimatedCost: estimatedCost.toString(),
+            estimatedCostFormatted: `${estimatedCostCelo} CELO`,
+            isEip1559: feeData.eip1559,
+        };
+    }
+}
+//# sourceMappingURL=transaction.service.js.map

package/build/src/services/transaction.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.service.js","sourceRoot":"","sources":["../../../src/services/transaction.service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,MAAM,EACN,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,SAAS,GAEV,MAAM,MAAM,CAAC;AAEd,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAEL,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,kCAAkC,EAClC,oCAAoC,GACrC,MAAM,gCAAgC,CAAC;AAaxC,SAAS,cAAc,CAAC,IAAS;IAC/B,OAAO,MAAM,CAAC,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,qFAAqF;AACrF,MAAM,OAAO,kBAAkB;IAGA;IAFZ,YAAY,CAAe;IAE5C,YAA6B,aAAgC;QAAhC,kBAAa,GAAb,aAAa,CAAmB;QAC3D,IAAI,CAAC,YAAY,GAAG,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,IAAmB,EACnB,EAAiB,EACjB,KAAa,EACb,MAAc;QAEd,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEvD,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,SAAkB;YAC3B,IAAI;YACJ,EAAE;YACF,KAAK,EAAE,QAAQ,CAAC,MAAM;YACtB,MAAM;SACP,CAAC;QAEF,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;gBACvC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC;oBAC3C,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,kBAAkB;oBAC3B,GAAG,EAAE,QAAQ;oBACb,YAAY,EAAE,UAAU;oBACxB,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,CAAC;iBACxB,CAAC,CAAC;gBAEH,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC1C,CAAC;YAED,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC7E,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC;gBAC3C,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,UAAU;gBACxB,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,CAAC;aACxB,CAAC,CAAC;YAEH,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,oCAAoC,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChD,OAAO;oBACL,GAAG,IAAI;oBACP,GAAG,EAAE,IAAI;oBACT,mBAAmB,EAAE,IAAI;oBACzB,OAAO,EAAE,kCAAkC,CAAC,QAAQ,CAAC,MAAM,CAAC;iBAC7D,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CACf,IAAmB,EACnB,EAAiB,EACjB,KAAa,EACb,MAAc;QAEd,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEvD,IAAI,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAClC,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,IAAI,GAAG,cAAc,CACzB,kBAAkB,CAAC;gBACjB,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,UAAU;gBACxB,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,CAAC;aACxB,CAAC,CACH,CAAC;YAEF,MAAM,IAAI,GAAiB;gBACzB,OAAO,EAAE,SAAS;gBAClB,IAAI;gBACJ,OAAO,EAAE,QAAQ,MAAM,YAAY,EAAE,EAAE;gBACvC,KAAK,EAAE;oBACL;wBACE,IAAI,EAAE,OAAO;wBACb,EAAE,EAAE,kBAAkB;wBACtB,IAAI;wBACJ,KAAK,EAAE,GAAG;wBACV,WAAW,EAAE,QAAQ,MAAM,OAAO;qBACnC;iBACF;aACF,CAAC;YACF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC7E,MAAM,IAAI,GAAG,cAAc,CACzB,kBAAkB,CAAC;YACjB,GAAG,EAAE,QAAQ;YACb,YAAY,EAAE,UAAU;YACxB,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,CAAC;SACxB,CAAC,CACH,CAAC;QAEF,MAAM,IAAI,GAAiB;YACzB,OAAO,EAAE,SAAS;YAClB,IAAI;YACJ,OAAO,EAAE,QAAQ,MAAM,IAAI,QAAQ,CAAC,MAAM,OAAO,EAAE,EAAE;YACrD,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,OAAO;oBACb,EAAE,EAAE,QAAQ,CAAC,OAAO;oBACpB,IAAI;oBACJ,KAAK,EAAE,GAAG;oBACV,WAAW,EAAE,YAAY,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE;iBACrD;aACF;SACF,CAAC;QACF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,aAAa;QACjB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAC3D,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC1C,MAAM,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;YACvC,MAAM,CAAC,WAAW,EAAE;SACrB,CAAC,CAAC;QAEH,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;QAE1C,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,oBAAoB,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAC5C,MAAM,YAAY,GAAG,aAAa,GAAG,EAAE,GAAG,oBAAoB,CAAC;YAE/D,OAAO;gBACL,OAAO,EAAE,SAAkB;gBAC3B,aAAa,EAAE,aAAa,CAAC,QAAQ,EAAE;gBACvC,YAAY,EAAE,YAAY,CAAC,QAAQ,EAAE;gBACrC,oBAAoB,EAAE,oBAAoB,CAAC,QAAQ,EAAE;gBACrD,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;gBAC7B,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,SAAkB;YAC3B,aAAa,EAAE,GAAG;YAClB,YAAY,EAAE,QAAQ,CAAC,QAAQ,EAAE;YACjC,oBAAoB,EAAE,GAAG;YACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YAC7B,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,mBAAmB,CAAC,MAKzB;QACC,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC3D,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;QACrD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;QAEjC,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;gBAClC,OAAO,EAAE,IAAI;gBACb,EAAE;gBACF,KAAK;gBACL,IAAI;aACL,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,MAAM,IAAI,KAAK,CACb,sCAAsC,OAAO,IAAI;gBAC/C,iFAAiF,CACpF,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC5C,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;QACxC,MAAM,iBAAiB,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;QAEvD,OAAO;YACL,OAAO,EAAE,SAAkB;YAC3B,IAAI;YACJ,EAAE;YACF,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YAC7B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;YAClD,aAAa,EAAE,aAAa,CAAC,QAAQ,EAAE;YACvC,sBAAsB,EAAE,GAAG,iBAAiB,OAAO;YACnD,SAAS,EAAE,OAAO,CAAC,OAAO;SAC3B,CAAC;IACJ,CAAC;CACF"}

package/build/src/services/uniswap-path-router.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Uniswap v4 path routing: BFS over pool index and V4Quoter best-path selection.
+ */
+import type { PublicClient } from "viem";
+import { type UniswapPoolKey } from "../config/uniswap.js";
+/** Single hop descriptor in a Uniswap v4 multi-hop path. */
+export type UniswapPathKey = {
+    intermediateCurrency: `0x${string}`;
+    fee: number;
+    tickSpacing: number;
+    hooks: `0x${string}`;
+    hookData: `0x${string}`;
+};
+/** Best quoted route between two v4 currencies. */
+export type UniswapSwapRoute = {
+    currencyIn: `0x${string}`;
+    currencyOut: `0x${string}`;
+    pools: UniswapPoolKey[];
+    pathKeys: UniswapPathKey[];
+    hops: number;
+};
+/**
+ * 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 declare function findBestUniswapRoute(client: PublicClient, currencyIn: `0x${string}`, currencyOut: `0x${string}`, amountIn: bigint): Promise<{
+    route: UniswapSwapRoute;
+    amountOut: bigint;
+    indexSource: string;
+} | null>;
+/**
+ * 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 declare function applySlippage(amountOut: bigint, slippagePercent: number): bigint;