@andrewkimjoseph/celina-sdk 0.4.11 → 0.5.0

package/build/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GAIxB,MAAM,mBAAmB,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AAapC,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC"}

package/build/tools/schemas/common.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export declare const addressSchema: z.ZodString;
+export declare const optionalWalletAddressSchema: z.ZodOptional<z.ZodString>;
+export declare const addressOrEnsSchema: z.ZodString;
+export declare const blockIdSchema: z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodLiteral<"latest">, z.ZodLiteral<"pending">]>;
+export declare const tokenSymbolSchema: z.ZodString;
+export declare const ensNameSchema: z.ZodString;
+export declare const tokenIdSchema: z.ZodString;
+export declare const abiSchema: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+export declare const paginationFields: {
+    readonly page: z.ZodOptional<z.ZodNumber>;
+    readonly page_size: z.ZodOptional<z.ZodNumber>;
+    readonly offset: z.ZodOptional<z.ZodNumber>;
+    readonly limit: z.ZodOptional<z.ZodNumber>;
+};
+export declare const hexDataSchema: z.ZodOptional<z.ZodString>;
+export declare const carbonWriteSchema: z.ZodObject<{
+    wallet_address: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    wallet_address: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    wallet_address: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const mentoFxQuoteSchema: z.ZodObject<{
+    token_in: z.ZodString;
+    token_out: z.ZodString;
+    amount: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+}, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+}>;
+export declare const mentoFxWalletSchema: z.ZodObject<{
+    token_in: z.ZodString;
+    token_out: z.ZodString;
+    amount: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+} & {
+    recipient: z.ZodOptional<z.ZodString>;
+    slippage_tolerance: z.ZodOptional<z.ZodNumber>;
+    deadline_minutes: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+    recipient?: string | undefined;
+    slippage_tolerance?: number | undefined;
+    deadline_minutes?: number | undefined;
+}, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+    recipient?: string | undefined;
+    slippage_tolerance?: number | undefined;
+    deadline_minutes?: number | undefined;
+}>;
+export declare const uniswapQuoteSchema: z.ZodObject<{
+    token_in: z.ZodString;
+    token_out: z.ZodString;
+    amount: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+}, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+}>;
+export declare const uniswapWalletSchema: z.ZodObject<{
+    token_in: z.ZodString;
+    token_out: z.ZodString;
+    amount: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+} & {
+    recipient: z.ZodOptional<z.ZodString>;
+    slippage_tolerance: z.ZodOptional<z.ZodNumber>;
+    deadline_minutes: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+    recipient?: string | undefined;
+    slippage_tolerance?: number | undefined;
+    deadline_minutes?: number | undefined;
+}, {
+    amount: string;
+    token_in: string;
+    token_out: string;
+    from?: string | undefined;
+    recipient?: string | undefined;
+    slippage_tolerance?: number | undefined;
+    deadline_minutes?: number | undefined;
+}>;

package/build/tools/schemas/common.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export const addressSchema = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address");
+export const optionalWalletAddressSchema = addressSchema
+    .optional()
+    .describe("Wallet on Celo mainnet. Omit to use the connected wallet or MCP CELO_PRIVATE_KEY signer.");
+export const addressOrEnsSchema = z
+    .string()
+    .min(3)
+    .describe("Recipient 0x address or ENS name (e.g. andrewkimjoseph.celo.eth, celina.eth)");
+export const blockIdSchema = z.union([
+    z.number().int().nonnegative(),
+    z.string().regex(/^0x[a-fA-F0-9]+$/, "Invalid block hash"),
+    z.literal("latest"),
+    z.literal("pending"),
+]);
+export const tokenSymbolSchema = z
+    .string()
+    .describe("Celo mainnet token symbol (e.g. CELO, USDm, USDC, USDT)");
+export const ensNameSchema = z
+    .string()
+    .min(3)
+    .describe("ENS name, e.g. celina.eth or vitalik.eth");
+export const tokenIdSchema = z.string().describe("NFT token ID (decimal string)");
+export const abiSchema = z
+    .array(z.record(z.unknown()))
+    .min(1)
+    .describe("Contract ABI as a JSON array");
+export const paginationFields = {
+    page: z.number().int().min(1).optional(),
+    page_size: z.number().int().min(1).optional(),
+    offset: z.number().int().min(0).optional(),
+    limit: z.number().int().min(1).optional(),
+};
+export const hexDataSchema = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]*$/)
+    .optional()
+    .describe("Optional transaction calldata (hex)");
+export const carbonWriteSchema = z
+    .object({
+    wallet_address: optionalWalletAddressSchema,
+    from: addressSchema.optional(),
+})
+    .passthrough();
+export const mentoFxQuoteSchema = z.object({
+    token_in: tokenSymbolSchema.describe("Input token symbol or address"),
+    token_out: tokenSymbolSchema.describe("Output token symbol or address"),
+    amount: z.string().describe("Human-readable amount of token_in, e.g. 100"),
+    from: optionalWalletAddressSchema,
+});
+export const mentoFxWalletSchema = mentoFxQuoteSchema.extend({
+    recipient: addressSchema
+        .optional()
+        .describe("Address that receives output tokens (defaults to signer)"),
+    slippage_tolerance: z
+        .number()
+        .min(0)
+        .max(20)
+        .optional()
+        .describe("Max slippage in percent (default 0.5)"),
+    deadline_minutes: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Transaction deadline in minutes (default 5)"),
+});
+export const uniswapQuoteSchema = z.object({
+    token_in: tokenSymbolSchema,
+    token_out: tokenSymbolSchema,
+    amount: z.string().describe("Human-readable amount of token_in"),
+    from: optionalWalletAddressSchema,
+});
+export const uniswapWalletSchema = uniswapQuoteSchema.extend({
+    recipient: addressSchema.optional(),
+    slippage_tolerance: z.number().min(0).max(20).optional(),
+    deadline_minutes: z.number().int().positive().optional(),
+});
+//# sourceMappingURL=common.js.map

package/build/tools/schemas/common.js.map

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

package/build/tools/swap-routing.d.ts

@@ -0,0 +1,24 @@
+import type { CelinaClient } from "../index.js";
+export type SwapProtocol = "mento_fx" | "uniswap_v4";
+export interface SwapQuoteResult {
+    protocol: SwapProtocol;
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    expectedOut: string;
+    routeHops: number;
+    network: "mainnet";
+    alternatives?: Array<{
+        protocol: SwapProtocol;
+        expectedOut: string;
+        error?: string;
+    }>;
+}
+export interface SwapPrepareParams {
+    recipient?: `0x${string}`;
+    slippageTolerance?: number;
+    deadlineMinutes?: number;
+}
+/** Quote a swap across Mento FX and Uniswap v4; returns the best available route. */
+export declare function getSwapQuoteWithFallback(celina: CelinaClient, tokenIn: string, tokenOut: string, amount: string, from?: `0x${string}`): Promise<SwapQuoteResult>;
+export declare function prepareSwapWithFallback(celina: CelinaClient, from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: SwapPrepareParams, protocol?: SwapProtocol): Promise<import("../index.js").SerializedPreparedFlow>;

package/build/tools/swap-routing.js

@@ -0,0 +1,105 @@
+function parseExpectedOut(value) {
+    const n = Number(value.replace(/,/g, ""));
+    return Number.isFinite(n) ? n : 0;
+}
+function isMentoRouteError(message) {
+    return /no mento fx route|mento fx market is currently closed/i.test(message);
+}
+function isUniswapRouteError(message) {
+    return /no uniswap v4 route|insufficient liquidity in uniswap v4/i.test(message);
+}
+function isInsufficientBalanceError(message) {
+    return /insufficient .+ balance/i.test(message);
+}
+function rejectionMessage(reason) {
+    return reason instanceof Error ? reason.message : String(reason);
+}
+async function tryMentoQuote(celina, tokenIn, tokenOut, amount, from) {
+    const quote = await celina.mentoFx.getFxQuote(tokenIn, tokenOut, amount, from);
+    return {
+        protocol: "mento_fx",
+        tokenIn: quote.tokenIn,
+        tokenOut: quote.tokenOut,
+        amountIn: quote.amountIn,
+        expectedOut: quote.expectedOut,
+        routeHops: quote.routeHops,
+        network: quote.network,
+    };
+}
+async function tryUniswapQuote(celina, tokenIn, tokenOut, amount, from) {
+    const quote = await celina.uniswap.getSwapQuote(tokenIn, tokenOut, amount, from);
+    return {
+        protocol: "uniswap_v4",
+        tokenIn: quote.tokenIn,
+        tokenOut: quote.tokenOut,
+        amountIn: quote.amountIn,
+        expectedOut: quote.expectedOut,
+        routeHops: quote.routeHops,
+        network: quote.network,
+    };
+}
+/** Quote a swap across Mento FX and Uniswap v4; returns the best available route. */
+export async function getSwapQuoteWithFallback(celina, tokenIn, tokenOut, amount, from) {
+    const [mentoResult, uniswapResult] = await Promise.allSettled([
+        tryMentoQuote(celina, tokenIn, tokenOut, amount, from),
+        tryUniswapQuote(celina, tokenIn, tokenOut, amount, from),
+    ]);
+    const successes = [];
+    const alternatives = [];
+    if (mentoResult.status === "fulfilled") {
+        successes.push(mentoResult.value);
+    }
+    else {
+        const message = rejectionMessage(mentoResult.reason);
+        if (!isMentoRouteError(message)) {
+            alternatives.push({ protocol: "mento_fx", expectedOut: "0", error: message });
+        }
+    }
+    if (uniswapResult.status === "fulfilled") {
+        successes.push(uniswapResult.value);
+    }
+    else {
+        const message = rejectionMessage(uniswapResult.reason);
+        if (!isUniswapRouteError(message)) {
+            alternatives.push({ protocol: "uniswap_v4", expectedOut: "0", error: message });
+        }
+    }
+    if (successes.length === 0) {
+        const failures = [mentoResult, uniswapResult]
+            .filter((result) => result.status === "rejected")
+            .map((result) => rejectionMessage(result.reason));
+        const balanceError = failures.find(isInsufficientBalanceError);
+        if (balanceError) {
+            throw new Error(balanceError);
+        }
+        throw new Error(`No swap route for ${tokenIn} → ${tokenOut} via Mento FX or Uniswap v4.`);
+    }
+    successes.sort((a, b) => parseExpectedOut(b.expectedOut) - parseExpectedOut(a.expectedOut));
+    const best = successes[0];
+    const otherProtocols = successes.slice(1).map((q) => ({
+        protocol: q.protocol,
+        expectedOut: q.expectedOut,
+    }));
+    return {
+        ...best,
+        alternatives: otherProtocols.length > 0 ? otherProtocols : alternatives,
+    };
+}
+export async function prepareSwapWithFallback(celina, from, tokenIn, tokenOut, amount, params, protocol) {
+    const chosen = protocol ??
+        (await getSwapQuoteWithFallback(celina, tokenIn, tokenOut, amount, from))
+            .protocol;
+    if (chosen === "mento_fx") {
+        return celina.mentoFx.prepareFx(from, tokenIn, tokenOut, amount, {
+            recipient: params?.recipient,
+            slippageTolerance: params?.slippageTolerance,
+            deadlineMinutes: params?.deadlineMinutes,
+        });
+    }
+    return celina.uniswap.prepareSwap(from, tokenIn, tokenOut, amount, {
+        recipient: params?.recipient,
+        slippageTolerance: params?.slippageTolerance,
+        deadlineMinutes: params?.deadlineMinutes,
+    });
+}
+//# sourceMappingURL=swap-routing.js.map

package/build/tools/swap-routing.js.map

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

package/build/tools/types.d.ts

@@ -0,0 +1,134 @@
+import type { z } from "zod";
+import type { CelinaClient } from "../index.js";
+import type { CarbonWriteBody } from "../services/carbon.service.js";
+export type ToolSurface = "mcp" | "celeste";
+export type ToolFamily = "read" | "prepare" | "execute";
+export type WalletInput = {
+    address?: string;
+    wallet_address?: string;
+    from?: string;
+};
+export type McpToolAnnotations = {
+    readOnlyHint?: boolean;
+    idempotentHint?: boolean;
+    destructiveHint?: boolean;
+    openWorldHint?: boolean;
+};
+export type McpToolMeta = {
+    title?: string;
+    annotations?: McpToolAnnotations;
+    /** MCP adapter uses okSelfSession for QR registration flows. */
+    responseKind?: "default" | "self_session";
+};
+export type ToolRuntimeHooks = {
+    beforePrepareSend?: (params: {
+        sender: `0x${string}`;
+        token: string;
+        amount: string;
+    }) => Promise<void>;
+    carbon?: {
+        validateBody?: (toolName: string, body: Record<string, unknown>) => void;
+        prepare?: (toolName: string, sender: `0x${string}`, prepareFn: (body: CarbonWriteBody) => Promise<unknown>, body: CarbonWriteBody, options?: {
+            marketPriceFallback?: boolean;
+            concentrated?: boolean;
+        }) => Promise<unknown>;
+    };
+};
+export type TransactionExecutors = {
+    estimateSend: (to: `0x${string}`, token: string, amount: string) => Promise<unknown>;
+    sendToken: (to: `0x${string}`, token: string, amount: string) => Promise<unknown>;
+};
+export type MentoFxExecutors = {
+    estimate: (tokenIn: string, tokenOut: string, amount: string, options?: {
+        recipient?: `0x${string}`;
+        slippageTolerance?: number;
+        deadlineMinutes?: number;
+    }) => Promise<unknown>;
+    execute: (tokenIn: string, tokenOut: string, amount: string, options?: {
+        recipient?: `0x${string}`;
+        slippageTolerance?: number;
+        deadlineMinutes?: number;
+    }) => Promise<unknown>;
+};
+export type UniswapExecutors = {
+    estimate: (tokenIn: string, tokenOut: string, amount: string, options?: {
+        recipient?: `0x${string}`;
+        slippageTolerance?: number;
+        deadlineMinutes?: number;
+    }) => Promise<unknown>;
+    execute: (tokenIn: string, tokenOut: string, amount: string, options?: {
+        recipient?: `0x${string}`;
+        slippageTolerance?: number;
+        deadlineMinutes?: number;
+    }) => Promise<unknown>;
+};
+export type AaveExecutors = {
+    supply: (token: string, amount: string) => Promise<unknown>;
+    withdraw: (token: string, amount?: string, withdrawMax?: boolean) => Promise<unknown>;
+};
+export type CarbonWriteExecutors = {
+    executeLimitOrder: (body: Record<string, unknown>) => Promise<unknown>;
+    executeRangeOrder: (body: Record<string, unknown>) => Promise<unknown>;
+    executeRecurringStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeConcentratedStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeFullRangeStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeRepriceStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeEditStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeDepositBudget: (body: Record<string, unknown>) => Promise<unknown>;
+    executeWithdrawBudget: (body: Record<string, unknown>) => Promise<unknown>;
+    executePauseStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeResumeStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeDeleteStrategy: (body: Record<string, unknown>) => Promise<unknown>;
+    executeTrade: (body: Record<string, unknown>) => Promise<unknown>;
+};
+export type GoodDollarWriteExecutors = {
+    claimDailyUbi: () => Promise<unknown>;
+};
+export type SelfExecutors = {
+    verifyAgent: (args: Record<string, unknown>) => Promise<unknown>;
+    lookupAgent: (agentId: number) => Promise<unknown>;
+    verifyRequest: (args: Record<string, unknown>) => Promise<unknown>;
+    registerAgent: (args: Record<string, unknown>) => Promise<unknown>;
+    checkRegistration: (sessionId: string) => Promise<unknown>;
+    getIdentity: () => Promise<unknown>;
+    refreshProof: (args: Record<string, unknown>) => Promise<unknown>;
+    deregisterAgent: () => Promise<unknown>;
+    signRequest: (args: Record<string, unknown>) => Promise<unknown>;
+    authenticatedFetch: (args: Record<string, unknown>) => Promise<unknown>;
+};
+export type ToolRuntimeExecutors = {
+    transaction?: TransactionExecutors;
+    mentoFx?: MentoFxExecutors;
+    uniswap?: UniswapExecutors;
+    aave?: AaveExecutors;
+    carbonWrite?: CarbonWriteExecutors;
+    gooddollarWrite?: GoodDollarWriteExecutors;
+    self?: SelfExecutors;
+};
+export interface ToolRuntime {
+    celina: CelinaClient;
+    resolveWallet: (input?: WalletInput) => `0x${string}`;
+    hooks?: ToolRuntimeHooks;
+    executors?: ToolRuntimeExecutors;
+    /** MCP session wallet metadata for get_wallet_address. */
+    mcpWallet?: {
+        address: `0x${string}`;
+        hasWallet: boolean;
+    };
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodTypeAny;
+    families: ToolFamily[];
+    surfaces?: ToolSurface[];
+    mcp?: McpToolMeta;
+    handler: (runtime: ToolRuntime, input: Record<string, unknown>) => Promise<unknown>;
+}
+export type FilterToolsOptions = {
+    surface?: ToolSurface;
+    families?: ToolFamily[];
+    names?: string[];
+    carbonPrepareEnabled?: boolean;
+    carbonExecuteEnabled?: boolean;
+};

package/build/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

package/build/tools/utils/carbon-prepare-handler.d.ts

@@ -0,0 +1,6 @@
+import type { CarbonWriteBody } from "../../services/carbon.service.js";
+import type { ToolRuntime } from "../types.js";
+export declare function runCarbonPrepare(runtime: ToolRuntime, toolName: string, prepareFn: (body: CarbonWriteBody) => Promise<unknown>, input: Record<string, unknown>, options?: {
+    marketPriceFallback?: boolean;
+    concentrated?: boolean;
+}): Promise<unknown>;

package/build/tools/utils/carbon-prepare-handler.js

@@ -0,0 +1,17 @@
+import { finalizeCarbonPrepare } from "../../utils/finalize-carbon-prepare.js";
+import { resolveWalletFromRuntime } from "./wallet.js";
+export async function runCarbonPrepare(runtime, toolName, prepareFn, input, options) {
+    const sender = resolveWalletFromRuntime(runtime, {
+        wallet_address: input.wallet_address,
+        from: input.from,
+    });
+    const body = { ...input, wallet_address: sender };
+    if (runtime.hooks?.carbon?.prepare) {
+        return runtime.hooks.carbon.prepare(toolName, sender, prepareFn, body, options);
+    }
+    runtime.hooks?.carbon?.validateBody?.(toolName, body);
+    const prepared = await prepareFn(body);
+    const preparedFlow = await finalizeCarbonPrepare(runtime.celina.carbon, sender, prepared, body);
+    return { ...prepared, preparedFlow };
+}
+//# sourceMappingURL=carbon-prepare-handler.js.map

package/build/tools/utils/carbon-prepare-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carbon-prepare-handler.js","sourceRoot":"","sources":["../../../src/tools/utils/carbon-prepare-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAE/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAoB,EACpB,QAAgB,EAChB,SAAsD,EACtD,KAA8B,EAC9B,OAAmE;IAEnE,MAAM,MAAM,GAAG,wBAAwB,CAAC,OAAO,EAAE;QAC/C,cAAc,EAAE,KAAK,CAAC,cAAoC;QAC1D,IAAI,EAAE,KAAK,CAAC,IAA0B;KACvC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,EAAqB,CAAC;IAErE,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,YAAY,GAAG,MAAM,qBAAqB,CAC9C,OAAO,CAAC,MAAM,CAAC,MAAM,EACrB,MAAM,EACN,QAAuD,EACvD,IAAI,CACL,CAAC;IACF,OAAO,EAAE,GAAI,QAAmB,EAAE,YAAY,EAAE,CAAC;AACnD,CAAC"}

package/build/tools/utils/normalize-token.d.ts

@@ -0,0 +1,2 @@
+/** Normalize common LLM token shorthands before registry lookup. */
+export declare function normalizeRegistryTokenInput(token: string): string;

package/build/tools/utils/normalize-token.js

@@ -0,0 +1,12 @@
+const REGISTRY_ALIASES = {
+    GD: "GoodDollar",
+    "G$": "GoodDollar",
+    GOODDOLLAR: "GoodDollar",
+};
+/** Normalize common LLM token shorthands before registry lookup. */
+export function normalizeRegistryTokenInput(token) {
+    const trimmed = token.trim();
+    const upper = trimmed.toUpperCase();
+    return REGISTRY_ALIASES[upper] ?? REGISTRY_ALIASES[trimmed] ?? trimmed;
+}
+//# sourceMappingURL=normalize-token.js.map

package/build/tools/utils/normalize-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-token.js","sourceRoot":"","sources":["../../../src/tools/utils/normalize-token.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAA2B;IAC/C,EAAE,EAAE,YAAY;IAChB,IAAI,EAAE,YAAY;IAClB,UAAU,EAAE,YAAY;CACzB,CAAC;AAEF,oEAAoE;AACpE,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,gBAAgB,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;AACzE,CAAC"}

package/build/tools/utils/wallet.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRuntime, WalletInput } from "../types.js";
+export declare function resolveWalletFromRuntime(runtime: ToolRuntime, input?: WalletInput): `0x${string}`;

package/build/tools/utils/wallet.js

@@ -0,0 +1,4 @@
+export function resolveWalletFromRuntime(runtime, input) {
+    return runtime.resolveWallet(input);
+}
+//# sourceMappingURL=wallet.js.map

package/build/tools/utils/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../../src/tools/utils/wallet.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,wBAAwB,CACtC,OAAoB,EACpB,KAAmB;IAEnB,OAAO,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrewkimjoseph/celina-sdk",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Celina SDK — Celo mainnet reads and unsigned transaction preparation for frontend apps.",
   "type": "module",
   "sideEffects": false,
@@ -16,6 +16,11 @@
       "types": "./tests/testing-entry.ts",
       "import": "./tests/testing-entry.ts",
       "default": "./tests/testing-entry.ts"
+    },
+    "./tools": {
+      "types": "./build/tools/index.d.ts",
+      "import": "./build/tools/index.js",
+      "default": "./build/tools/index.js"
     }
   },
   "files": [
@@ -69,6 +74,7 @@
   },
   "homepage": "https://andrewkimjoseph.gitbook.io/celina-sdk",
   "dependencies": {
+    "zod": "^3.24.3",
     "@amplitude/analytics-node": "^1.5.21",
     "@noble/ed25519": "^3.1.0",
     "@bancor/carbon-sdk": "0.0.130-DEV",

package/tests/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="../assets/celina-banner.png" alt="Celina — Give your LLM a wallet on Celo">
+</p>
+
 # Celina operations test framework
 
 Live Celo mainnet smoke tests driven by a single operation catalog in `tests/catalog/operations.ts`. Add one `OperationSpec` when you ship a new SDK method or MCP tool.

package/tests/catalog/domains/blockchain.ts

@@ -42,6 +42,30 @@ export const blockchainOperations: OperationSpec[] = [
       assertHasKeys(result, ["number", "hash"]);
     },
   },
+  {
+    id: "blockchain.getBlockWithTransactions",
+    domain: "blockchain",
+    layer: "read",
+    sdk: {
+      invoke: (client, fx) =>
+        client.blockchain.getBlock(Number(fx.latestBlockNumber), {
+          includeTransactions: true,
+        }),
+    },
+    mcp: {
+      tool: "get_block",
+      arguments: (fx) => ({
+        blockId: Number(fx.latestBlockNumber),
+        includeTransactions: true,
+      }),
+    },
+    assert: (result) => {
+      const obj = assertHasKeys(result, ["number", "hash", "transactions"]);
+      expect(() => JSON.stringify(result)).not.toThrow();
+      const txs = assertArray(obj.transactions);
+      expect(txs.length).toBeGreaterThan(0);
+    },
+  },
   {
     id: "blockchain.getLatestBlocks",
     domain: "blockchain",

package/tests/catalog/operations.ts

@@ -16,6 +16,7 @@ import {
 } from "./domains/chain-ext.js";
 import { selfOperations } from "./domains/self.js";
 import { carbonOperations } from "./domains/carbon.js";
+import { getMcpToolNames } from "../../src/tools/catalog.js";
 import type { OperationSpec } from "./types.js";
 
 export const OPERATIONS: OperationSpec[] = [
@@ -45,4 +46,13 @@ export const SDK_OPERATIONS = OPERATIONS.filter(
     Boolean(spec.sdk),
 );
 
-export const MCP_TOOL_NAMES = MCP_OPERATIONS.map((spec) => spec.mcp.tool);
+/** MCP tool names from the SDK tools catalog (stdio: prepare + execute Carbon). */
+export const MCP_TOOL_NAMES = getMcpToolNames({
+  carbonPrepareEnabled: true,
+  carbonExecuteEnabled: true,
+});
+
+/** @deprecated Use MCP_TOOL_NAMES — kept for tests that import the operations-derived list. */
+export const MCP_TOOL_NAMES_FROM_OPERATIONS = MCP_OPERATIONS.map(
+  (spec) => spec.mcp.tool,
+);

package/tests/testing-entry.ts

@@ -9,6 +9,11 @@ export {
   OPERATIONS,
   SDK_OPERATIONS,
 } from "./catalog/operations.js";
+export {
+  ALL_TOOL_DEFINITIONS,
+  getMcpToolNames,
+  getCelesteToolNames,
+} from "../src/tools/catalog.js";
 export { getMainnetFixtures, type MainnetFixtures } from "./fixtures/mainnet.js";
 export {
   allowsDestructiveTests,