@andrewkimjoseph/celina-sdk 0.15.1 → 0.15.2

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

@@ -0,0 +1,352 @@
+/**
+ * Uniswap v4 swaps on Celo mainnet: quote, estimate, and prepare flows.
+ * Uses V4Quoter for pricing and Universal Router + Permit2 for execution calldata.
+ * Pool discovery prefers the v4 subgraph; falls back to on-chain hub probing when unavailable.
+ */
+import { encodeFunctionData, erc20Abi, formatUnits, maxUint256, } from "viem";
+import { permit2Abi } from "../abis/permit2.js";
+import { universalRouterAbi } from "../abis/universal-router.js";
+import { Actions, CommandType, RoutePlanner, V4Planner, } from "../clients/uniswap-sdk.js";
+import { appendCelinaCalldataTag } from "../config/celina-tag.js";
+import { UNISWAP_V4, uniswapInputTokenAddress, toUniswapRoutingCurrency, } from "../config/uniswap.js";
+import { ALLOWANCE_MAPPING_SLOTS, erc20AllowanceStateOverride, isLikelyTransferFailed, } from "../utils/erc20-allowance-storage.js";
+import { serializePreparedFlow, } from "../types/prepared.js";
+import { CHAIN } from "../config/chains.js";
+import { findBestUniswapRoute, applySlippage } from "./uniswap-path-router.js";
+import { TokenService } from "./token.service.js";
+const DEFAULT_SLIPPAGE = 0.5;
+const DEFAULT_DEADLINE_MINUTES = 5;
+const PERMIT2_MAX_UINT160 = (1n << 160n) - 1n;
+function trimDisplayDecimals(value) {
+    const num = Number(value);
+    if (!Number.isFinite(num))
+        return value;
+    if (Math.abs(num) >= 1000) {
+        return num.toLocaleString(undefined, { maximumFractionDigits: 2 });
+    }
+    if (Math.abs(num) >= 1) {
+        return num.toLocaleString(undefined, { maximumFractionDigits: 4 });
+    }
+    return num.toLocaleString(undefined, { maximumSignificantDigits: 6 });
+}
+function swapOptions(params) {
+    const slippageTolerance = params?.slippageTolerance ?? DEFAULT_SLIPPAGE;
+    const deadlineMinutes = params?.deadlineMinutes ?? DEFAULT_DEADLINE_MINUTES;
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + deadlineMinutes * 60);
+    return { slippageTolerance, deadlineMinutes, deadline };
+}
+function formatUniswapError(error, tokenIn, tokenOut) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/insufficient liquidity|amountOut.*0/i.test(message)) {
+        throw new Error(`Insufficient liquidity in Uniswap v4 pools for ${tokenIn} → ${tokenOut}.`);
+    }
+    throw error instanceof Error ? error : new Error(message);
+}
+/** Uniswap v4 quotes, gas estimates, and `prepareSwap` flows on Celo mainnet. */
+export class UniswapService {
+    clientFactory;
+    tokenService;
+    attributionTags;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+        this.tokenService = new TokenService(clientFactory);
+        this.attributionTags = clientFactory.getConfig().attributionTags;
+    }
+    resolvePair(tokenIn, tokenOut) {
+        const resolvedIn = this.tokenService.resolveToken(tokenIn);
+        const resolvedOut = this.tokenService.resolveToken(tokenOut);
+        const routingIn = toUniswapRoutingCurrency(resolvedIn.address);
+        const routingOut = toUniswapRoutingCurrency(resolvedOut.address);
+        const inputToken = uniswapInputTokenAddress(resolvedIn.address);
+        return { resolvedIn, resolvedOut, routingIn, routingOut, inputToken };
+    }
+    baseQuoteFields(resolvedIn, resolvedOut, amount, expectedOutWei, routeHops, indexSource) {
+        return {
+            protocol: "uniswap_v4",
+            network: "mainnet",
+            tokenIn: resolvedIn.symbol,
+            tokenOut: resolvedOut.symbol,
+            amountIn: amount,
+            expectedOut: formatUnits(expectedOutWei, resolvedOut.decimals),
+            routeHops,
+            indexSource,
+        };
+    }
+    async buildSwapRoute(tokenIn, tokenOut, amount, params, from) {
+        const { public: client } = this.clientFactory.getClients();
+        const { resolvedIn, resolvedOut, routingIn, routingOut, inputToken } = this.resolvePair(tokenIn, tokenOut);
+        if (routingIn.toLowerCase() === routingOut.toLowerCase()) {
+            throw new Error("tokenIn and tokenOut must be different.");
+        }
+        const amountInWei = this.tokenService.parseAmount(amount, resolvedIn.decimals);
+        if (from) {
+            const celoHint = resolvedIn.address === "native"
+                ? " Uniswap v4 swaps require wrapped CELO (WCELO), not native CELO."
+                : "";
+            await this.tokenService.assertSpendableBalance(from, resolvedIn, amount, {
+                spendToken: inputToken === "native" ? "native" : inputToken,
+                hint: celoHint,
+            });
+        }
+        const quote = await findBestUniswapRoute(client, routingIn, routingOut, amountInWei);
+        if (!quote) {
+            throw new Error(`No Uniswap v4 route for ${resolvedIn.symbol} → ${resolvedOut.symbol}.`);
+        }
+        const { slippageTolerance, deadlineMinutes, deadline } = swapOptions(params);
+        const amountOutMin = applySlippage(quote.amountOut, slippageTolerance);
+        return {
+            client,
+            resolvedIn,
+            resolvedOut,
+            routingIn,
+            routingOut,
+            inputToken,
+            amountInWei,
+            route: quote.route,
+            expectedOutWei: quote.amountOut,
+            amountOutMin,
+            slippageTolerance,
+            deadlineMinutes,
+            deadline,
+            indexSource: quote.indexSource,
+        };
+    }
+    buildUniversalRouterCalldata(built, _recipient) {
+        const { route, amountInWei, amountOutMin, deadline, routingIn, routingOut, } = built;
+        const v4Planner = new V4Planner();
+        const routePlanner = new RoutePlanner();
+        const amountIn = amountInWei.toString();
+        const amountOutMinimum = amountOutMin.toString();
+        if (route.hops === 1) {
+            const poolKey = route.pools[0];
+            const zeroForOne = routingIn.toLowerCase() === poolKey.currency0.toLowerCase();
+            v4Planner.addAction(Actions.SWAP_EXACT_IN_SINGLE, [
+                {
+                    poolKey,
+                    zeroForOne,
+                    amountIn,
+                    amountOutMinimum,
+                    hookData: "0x",
+                },
+            ]);
+            v4Planner.addAction(Actions.SETTLE_ALL, [routingIn, amountIn]);
+            v4Planner.addAction(Actions.TAKE_ALL, [routingOut, amountOutMinimum]);
+        }
+        else {
+            v4Planner.addAction(Actions.SWAP_EXACT_IN, [
+                {
+                    currencyIn: routingIn,
+                    path: route.pathKeys,
+                    amountIn,
+                    amountOutMinimum,
+                },
+            ]);
+            v4Planner.addAction(Actions.SETTLE_ALL, [routingIn, amountIn]);
+            v4Planner.addAction(Actions.TAKE_ALL, [routingOut, amountOutMinimum]);
+        }
+        routePlanner.addCommand(CommandType.V4_SWAP, [
+            v4Planner.actions,
+            v4Planner.params,
+        ]);
+        const data = encodeFunctionData({
+            abi: universalRouterAbi,
+            functionName: "execute",
+            args: [
+                routePlanner.commands,
+                [v4Planner.finalize()],
+                deadline,
+            ],
+        });
+        return {
+            to: UNISWAP_V4.universalRouter,
+            data,
+            value: 0n,
+        };
+    }
+    async getApprovalSteps(client, from, inputToken, tokenSymbol, amountInWei, deadline) {
+        if (inputToken === "native") {
+            return [];
+        }
+        const steps = [];
+        const token = inputToken;
+        const erc20Allowance = await client.readContract({
+            address: token,
+            abi: erc20Abi,
+            functionName: "allowance",
+            args: [from, UNISWAP_V4.permit2],
+        });
+        if (erc20Allowance < amountInWei) {
+            steps.push({
+                kind: "erc20",
+                to: token,
+                data: appendCelinaCalldataTag(encodeFunctionData({
+                    abi: erc20Abi,
+                    functionName: "approve",
+                    args: [UNISWAP_V4.permit2, maxUint256],
+                }), this.attributionTags),
+                value: "0",
+                description: `Approve ${tokenSymbol} for Uniswap Permit2`,
+            });
+        }
+        const permit2Allowance = await client.readContract({
+            address: UNISWAP_V4.permit2,
+            abi: permit2Abi,
+            functionName: "allowance",
+            args: [from, token, UNISWAP_V4.universalRouter],
+        });
+        const now = BigInt(Math.floor(Date.now() / 1000));
+        if (permit2Allowance[0] < amountInWei ||
+            BigInt(permit2Allowance[1]) <= now) {
+            steps.push({
+                kind: "contract",
+                to: UNISWAP_V4.permit2,
+                data: appendCelinaCalldataTag(encodeFunctionData({
+                    abi: permit2Abi,
+                    functionName: "approve",
+                    args: [
+                        token,
+                        UNISWAP_V4.universalRouter,
+                        PERMIT2_MAX_UINT160,
+                        Number(deadline),
+                    ],
+                }), this.attributionTags),
+                value: "0",
+                description: `Permit2 approve ${tokenSymbol} for Uniswap Universal Router`,
+            });
+        }
+        return steps;
+    }
+    async estimateCallGas(client, from, to, data, value = 0n) {
+        const gas = await client.estimateGas({
+            account: from,
+            to,
+            data,
+            value,
+        });
+        return gas.toString();
+    }
+    async estimateSwapGasWithAllowance(client, from, to, data, token, amount) {
+        const request = { account: from, to, data, value: 0n };
+        for (const mappingSlot of ALLOWANCE_MAPPING_SLOTS) {
+            try {
+                const gas = await client.estimateGas({
+                    ...request,
+                    stateOverride: erc20AllowanceStateOverride(token, from, UNISWAP_V4.permit2, amount, mappingSlot),
+                });
+                return gas.toString();
+            }
+            catch (error) {
+                if (!isLikelyTransferFailed(error)) {
+                    throw error;
+                }
+            }
+        }
+        throw new Error("Could not estimate Uniswap swap gas: failed to simulate ERC-20 allowance for this token.");
+    }
+    /**
+     * 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.
+     */
+    async getSwapQuote(tokenIn, tokenOut, amount, _from) {
+        try {
+            const built = await this.buildSwapRoute(tokenIn, tokenOut, amount, undefined, undefined);
+            return {
+                ...this.baseQuoteFields(built.resolvedIn, built.resolvedOut, amount, built.expectedOutWei, built.route.hops, built.indexSource),
+                route: {
+                    pools: built.route.pools,
+                },
+            };
+        }
+        catch (error) {
+            formatUniswapError(error, tokenIn, tokenOut);
+        }
+    }
+    /**
+     * 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
+     */
+    async estimateSwap(from, tokenIn, tokenOut, amount, params) {
+        try {
+            const built = await this.buildSwapRoute(tokenIn, tokenOut, amount, params, from);
+            const recipient = params?.recipient ?? from;
+            const approvalSteps = await this.getApprovalSteps(built.client, from, built.inputToken, built.resolvedIn.symbol, built.amountInWei, built.deadline);
+            const swapTx = this.buildUniversalRouterCalldata(built, recipient);
+            const taggedSwapData = appendCelinaCalldataTag(swapTx.data, this.attributionTags);
+            const approvalGasEntries = await Promise.all(approvalSteps.map(async (step) => this.estimateCallGas(built.client, from, step.to, step.data)));
+            let swapGas;
+            let swapGasEstimated = true;
+            try {
+                swapGas =
+                    built.inputToken !== "native" && approvalSteps.length > 0
+                        ? await this.estimateSwapGasWithAllowance(built.client, from, swapTx.to, taggedSwapData, built.inputToken, built.amountInWei)
+                        : await this.estimateCallGas(built.client, from, swapTx.to, taggedSwapData);
+            }
+            catch {
+                swapGasEstimated = false;
+            }
+            return {
+                ...this.baseQuoteFields(built.resolvedIn, built.resolvedOut, amount, built.expectedOutWei, built.route.hops, built.indexSource),
+                from,
+                recipient,
+                amountOutMin: formatUnits(built.amountOutMin, built.resolvedOut.decimals),
+                approvalStepsNeeded: approvalSteps.length,
+                approvalGas: approvalGasEntries,
+                swapGas,
+                swapGasEstimated,
+                slippageTolerance: built.slippageTolerance,
+                deadline: built.deadline.toString(),
+                deadlineMinutes: built.deadlineMinutes,
+            };
+        }
+        catch (error) {
+            formatUniswapError(error, tokenIn, tokenOut);
+        }
+    }
+    /**
+     * 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
+     */
+    async prepareSwap(from, tokenIn, tokenOut, amount, params) {
+        try {
+            const built = await this.buildSwapRoute(tokenIn, tokenOut, amount, params, from);
+            const recipient = params?.recipient ?? from;
+            const displayIn = trimDisplayDecimals(amount);
+            const displayOut = trimDisplayDecimals(formatUnits(built.expectedOutWei, built.resolvedOut.decimals));
+            const approvalSteps = await this.getApprovalSteps(built.client, from, built.inputToken, built.resolvedIn.symbol, built.amountInWei, built.deadline);
+            const swapTx = this.buildUniversalRouterCalldata(built, recipient);
+            const steps = [
+                ...approvalSteps,
+                {
+                    kind: "contract",
+                    to: swapTx.to,
+                    data: appendCelinaCalldataTag(swapTx.data, this.attributionTags),
+                    value: swapTx.value.toString(),
+                    description: `Swap ${displayIn} ${built.resolvedIn.symbol} → ~${displayOut} ${built.resolvedOut.symbol} via Uniswap v4`,
+                },
+            ];
+            const flow = {
+                chainId: CHAIN.id,
+                from,
+                summary: `Uniswap v4: ${displayIn} ${built.resolvedIn.symbol} → ${displayOut} ${built.resolvedOut.symbol}${recipient !== from ? ` (recipient ${recipient})` : ""}`,
+                steps,
+            };
+            return serializePreparedFlow(flow);
+        }
+        catch (error) {
+            formatUniswapError(error, tokenIn, tokenOut);
+        }
+    }
+}
+//# sourceMappingURL=uniswap.service.js.map

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

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

package/build/src/simulation/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Browser-safe prepared-step simulation (no Node analytics / wallet product logic).
+ */
+export type { PreparedTx } from "../types/prepared.js";
+export { simulatePreparedStep, type SimulatePreparedStepOptions, type SimulatePreparedStepParams, } from "./simulate-prepared-step.js";

package/build/src/simulation/index.js

@@ -0,0 +1,2 @@
+export { simulatePreparedStep, } from "./simulate-prepared-step.js";
+//# sourceMappingURL=index.js.map

package/build/src/simulation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/simulation/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,oBAAoB,GAGrB,MAAM,6BAA6B,CAAC"}

package/build/src/simulation/simulate-prepared-step.d.ts

@@ -0,0 +1,17 @@
+import { type PublicClient, type StateOverride } from "viem";
+import type { PreparedTx } from "../types/prepared.js";
+/** Optional host overrides for Celo fee abstraction or custom state. */
+export type SimulatePreparedStepOptions = {
+    /** Celo fee-abstraction currency — host-provided, never auto-resolved by the SDK. */
+    feeCurrency?: `0x${string}`;
+    stateOverride?: StateOverride;
+};
+export type SimulatePreparedStepParams = {
+    account: `0x${string}`;
+    step: PreparedTx;
+};
+/**
+ * Simulate a prepared transaction step against current chain state.
+ * Throws when the transaction would revert — call immediately before send.
+ */
+export declare function simulatePreparedStep(publicClient: PublicClient, params: SimulatePreparedStepParams, options?: SimulatePreparedStepOptions): Promise<void>;

package/build/src/simulation/simulate-prepared-step.js

@@ -0,0 +1,42 @@
+import { isInsufficientBalanceSimulationError } from "../utils/transaction-errors.js";
+function stepRequest(account, step) {
+    return {
+        account,
+        to: step.to,
+        data: (step.data ?? "0x"),
+        value: step.value ? BigInt(step.value) : 0n,
+    };
+}
+function simulationErrorMessage(step, cause) {
+    const base = cause instanceof Error ? cause.message : String(cause);
+    if (isInsufficientBalanceSimulationError(cause)) {
+        return (`Simulation failed for "${step.description}": insufficient balance. (${base})`);
+    }
+    return `Simulation failed for "${step.description}": ${base}`;
+}
+/**
+ * Simulate a prepared transaction step against current chain state.
+ * Throws when the transaction would revert — call immediately before send.
+ */
+export async function simulatePreparedStep(publicClient, params, options) {
+    const request = stepRequest(params.account, params.step);
+    const stateOverride = options?.stateOverride;
+    try {
+        if (options?.feeCurrency) {
+            await publicClient.estimateGas({
+                ...request,
+                feeCurrency: options.feeCurrency,
+                ...(stateOverride ? { stateOverride } : {}),
+            });
+            return;
+        }
+        await publicClient.call({
+            ...request,
+            ...(stateOverride ? { stateOverride } : {}),
+        });
+    }
+    catch (error) {
+        throw new Error(simulationErrorMessage(params.step, error));
+    }
+}
+//# sourceMappingURL=simulate-prepared-step.js.map

package/build/src/simulation/simulate-prepared-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulate-prepared-step.js","sourceRoot":"","sources":["../../../src/simulation/simulate-prepared-step.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAC;AActF,SAAS,WAAW,CAClB,OAAsB,EACtB,IAAgB;IAOhB,OAAO;QACL,OAAO;QACP,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAQ;QAChC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,IAAgB,EAAE,KAAc;IAC9D,MAAM,IAAI,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpE,IAAI,oCAAoC,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,CACL,0BAA0B,IAAI,CAAC,WAAW,6BAA6B,IAAI,GAAG,CAC/E,CAAC;IACJ,CAAC;IAED,OAAO,0BAA0B,IAAI,CAAC,WAAW,MAAM,IAAI,EAAE,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,YAA0B,EAC1B,MAAkC,EAClC,OAAqC;IAErC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,CAAC;IAE7C,IAAI,CAAC;QACH,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACzB,MAAM,YAAY,CAAC,WAAW,CAAC;gBAC7B,GAAG,OAAO;gBACV,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACE,CAAC,CAAC;YACjD,OAAO;QACT,CAAC;QAED,MAAM,YAAY,CAAC,IAAI,CAAC;YACtB,GAAG,OAAO;YACV,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/build/src/tools/catalog.d.ts

@@ -0,0 +1,11 @@
+import type { FilterToolsOptions, ToolDefinition, ToolFamily } from "./types.js";
+export declare const ALL_TOOL_DEFINITIONS: ToolDefinition[];
+export declare function getToolNames(options?: FilterToolsOptions): string[];
+export declare function getMcpToolNames(options?: Omit<FilterToolsOptions, "surface">): string[];
+export declare function getBrowserToolNames(options?: Omit<FilterToolsOptions, "surface">): string[];
+export declare function getToolsByFamily(family: ToolFamily): ToolDefinition[];
+export declare function getToolDefinition(name: string): ToolDefinition | undefined;
+export declare function assertSnakeCaseRecordKeys(label: string, keys: string[]): void;
+export declare function getToolInputSchemaShape(definition: ToolDefinition): Record<string, unknown> | undefined;
+export declare function assertSnakeCaseInputKeys(definition: ToolDefinition): void;
+export declare function validateToolCatalogSnakeCase(): void;

package/build/src/tools/catalog.js

@@ -0,0 +1,43 @@
+import { allDomainToolDefinitions } from "./domains/index.js";
+import { filterToolDefinitions } from "./filter.js";
+export const ALL_TOOL_DEFINITIONS = allDomainToolDefinitions;
+export function getToolNames(options = {}) {
+    return filterToolDefinitions(ALL_TOOL_DEFINITIONS, options).map((d) => d.name);
+}
+export function getMcpToolNames(options = {}) {
+    return getToolNames({ ...options, surface: "mcp" });
+}
+export function getBrowserToolNames(options = {}) {
+    return getToolNames({ ...options, surface: "browser" });
+}
+export function getToolsByFamily(family) {
+    return filterToolDefinitions(ALL_TOOL_DEFINITIONS, { families: [family] });
+}
+export function getToolDefinition(name) {
+    return ALL_TOOL_DEFINITIONS.find((d) => d.name === name);
+}
+const SNAKE_CASE_KEY = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+export function assertSnakeCaseRecordKeys(label, keys) {
+    for (const key of keys) {
+        if (!SNAKE_CASE_KEY.test(key)) {
+            throw new Error(`${label}: key "${key}" must be snake_case (lowercase letters, digits, underscores).`);
+        }
+    }
+}
+export function getToolInputSchemaShape(definition) {
+    const shape = definition.inputSchema;
+    if (!shape || typeof shape !== "object" || !("shape" in shape)) {
+        return undefined;
+    }
+    return shape.shape;
+}
+export function assertSnakeCaseInputKeys(definition) {
+    const keys = Object.keys(getToolInputSchemaShape(definition) ?? {});
+    assertSnakeCaseRecordKeys(`Tool "${definition.name}" input`, keys);
+}
+export function validateToolCatalogSnakeCase() {
+    for (const def of ALL_TOOL_DEFINITIONS) {
+        assertSnakeCaseInputKeys(def);
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/build/src/tools/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../src/tools/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,CAAC,MAAM,oBAAoB,GAAqB,wBAAwB,CAAC;AAE/E,MAAM,UAAU,YAAY,CAAC,UAA8B,EAAE;IAC3D,OAAO,qBAAqB,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,UAA+C,EAAE;IAEjD,OAAO,YAAY,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,UAA+C,EAAE;IAEjD,OAAO,YAAY,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,OAAO,qBAAqB,CAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,cAAc,GAAG,+BAA+B,CAAC;AAEvD,MAAM,UAAU,yBAAyB,CAAC,KAAa,EAAE,IAAc;IACrE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,UAAU,GAAG,gEAAgE,CACtF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,UAA0B;IAE1B,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC;IACrC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAQ,KAA4C,CAAC,KAAK,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,UAA0B;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACpE,yBAAyB,CAAC,SAAS,UAAU,CAAC,IAAI,SAAS,EAAE,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACvC,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/build/src/tools/domains/aave.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare const aaveToolDefinitions: ToolDefinition[];

package/build/src/tools/domains/aave.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { AAVE_SUPPORTED_SYMBOLS, resolveAaveAsset, } from "../../config/aave.js";
+import { optionalWalletAddressSchema, tokenSymbolSchema } from "../schemas/common.js";
+import { resolveWalletFromRuntime } from "../utils/wallet.js";
+const supported = AAVE_SUPPORTED_SYMBOLS.join(", ");
+const aaveTokenField = tokenSymbolSchema.describe(`Aave asset symbol on Celo (${supported}). Pass the symbol only.`);
+const readOnly = {
+    readOnlyHint: true,
+    idempotentHint: true,
+};
+export const aaveToolDefinitions = [
+    {
+        name: "get_aave_balances",
+        description: `Read supplied Aave V3 balances (aToken holdings) on Celo in underlying token units including accrued interest. Each balance has formatted (human-readable, e.g. "0.000002") and raw (atomic units — do not quote raw to users). Supported: ${supported}. Omit address to use the session wallet when CELO_PRIVATE_KEY is set.`,
+        inputSchema: z.object({
+            address: optionalWalletAddressSchema,
+            tokens: z.array(aaveTokenField).optional(),
+            include_zero: z.boolean().optional(),
+        }),
+        families: ["read"],
+        mcp: { title: "Get Aave Balances", annotations: readOnly },
+        handler: async (runtime, input) => {
+            const target = resolveWalletFromRuntime(runtime, {
+                address: input.address,
+            });
+            return runtime.celina.aave.getBalances(target, {
+                tokens: input.tokens,
+                includeZero: input.include_zero,
+            });
+        },
+    },
+    {
+        name: "supply_aave",
+        description: `Supply tokens to Aave V3 on Celo. Supported: ${supported}. Requires CELO_PRIVATE_KEY.`,
+        inputSchema: z.object({
+            token: aaveTokenField,
+            amount: z.string(),
+        }),
+        families: ["execute"],
+        surfaces: ["mcp"],
+        requiresEnv: ["CELO_PRIVATE_KEY"],
+        mcp: {
+            title: "Supply Aave",
+            annotations: { destructiveHint: true, openWorldHint: true },
+        },
+        handler: async (runtime, input) => {
+            const aave = runtime.executors?.aave;
+            if (!aave)
+                throw new Error("Aave executor not configured.");
+            const asset = resolveAaveAsset(input.token);
+            return aave.supply(asset.symbol, input.amount);
+        },
+    },
+    {
+        name: "withdraw_aave",
+        description: `Withdraw tokens from Aave V3 on Celo. Supported: ${supported}. Requires CELO_PRIVATE_KEY.`,
+        inputSchema: z.object({
+            token: aaveTokenField,
+            amount: z.string().optional(),
+            withdraw_max: z.boolean().optional(),
+        }),
+        families: ["execute"],
+        surfaces: ["mcp"],
+        requiresEnv: ["CELO_PRIVATE_KEY"],
+        mcp: {
+            title: "Withdraw Aave",
+            annotations: { destructiveHint: true, openWorldHint: true },
+        },
+        handler: async (runtime, input) => {
+            const aave = runtime.executors?.aave;
+            if (!aave)
+                throw new Error("Aave executor not configured.");
+            const asset = resolveAaveAsset(input.token);
+            return aave.withdraw(asset.symbol, input.amount, input.withdraw_max);
+        },
+    },
+    {
+        name: "prepare_aave_supply",
+        description: "Prepare unsigned Aave V3 supply steps. User signs in wallet.",
+        inputSchema: z.object({
+            token: z.string(),
+            amount: z.string(),
+            from: optionalWalletAddressSchema,
+        }),
+        families: ["prepare"],
+        surfaces: ["browser"],
+        handler: async (runtime, input) => {
+            const sender = resolveWalletFromRuntime(runtime, {
+                from: input.from,
+            });
+            const asset = resolveAaveAsset(input.token);
+            return runtime.celina.aave.prepareSupply(sender, asset.symbol, input.amount);
+        },
+    },
+    {
+        name: "prepare_aave_withdraw",
+        description: "Prepare unsigned Aave V3 withdraw. User signs in wallet. For full/max/all withdrawals set withdraw_max true — do not pass a human amount unless the user names a specific partial amount.",
+        inputSchema: z.object({
+            token: z.string(),
+            amount: z.string().optional(),
+            withdraw_max: z.boolean().optional(),
+            from: optionalWalletAddressSchema,
+        }),
+        families: ["prepare"],
+        surfaces: ["browser"],
+        handler: async (runtime, input) => {
+            const sender = resolveWalletFromRuntime(runtime, {
+                from: input.from,
+            });
+            const asset = resolveAaveAsset(input.token);
+            return runtime.celina.aave.prepareWithdraw(sender, asset.symbol, input.amount, input.withdraw_max);
+        },
+    },
+];
+//# sourceMappingURL=aave.js.map

package/build/src/tools/domains/aave.js.map

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

package/build/src/tools/domains/agentkarma.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare const agentKarmaToolDefinitions: ToolDefinition[];