@andrewkimjoseph/celina-sdk 0.4.8 → 0.4.10

package/README.md

@@ -1,6 +1,6 @@
 # Celina SDK
 
-**`@andrewkimjoseph/celina-sdk@0.4.7`** — Celo mainnet library for frontend apps and agents: **reads** and **unsigned transaction preparation** (no private keys).
+Celo mainnet library for frontend apps and agents: **reads** and **unsigned transaction preparation** (no private keys).
 
 Pair with [wagmi](https://wagmi.sh) / viem — users sign prepared transactions in their wallet.
 
@@ -12,7 +12,7 @@ Celina is layered from chain logic through agent tooling:
 |-------|---------|------|
 | **SDK** | `@andrewkimjoseph/celina-sdk` | Reads, gas estimates, `prepare*` flows, Carbon REST + SDK hybrid |
 | **MCP** | `@andrewkimjoseph/celina-mcp` | MCP tools for Cursor / Claude / LM Studio — stdio writes or hosted reads + Carbon prepare |
-| **MCP host** | `celina-mcp-host` | Vercel Streamable HTTP — hosted reads + Carbon prepare (71 tools); no server-key writes or `execute_carbon_*` |
+| **MCP host** | `celina-mcp-host` | Vercel Streamable HTTP — hosted reads + Carbon prepare (72 tools); no server-key writes or `execute_carbon_*` |
 
 This repo is the **SDK**. Downstream packages depend on published npm semver (no local `file:` links in production).
 
@@ -92,7 +92,11 @@ Hybrid **Carbon REST** (`https://mcp.carbondefi.xyz`) plus **`@bancor/carbon-sdk
 - **`deep_link`** on prepare responses — Carbon REST trade/disposable UI URL (reference only; signing is via your wallet flow).
 - **`carbonActivityDeepLink(wallet)`** — post-execution activity explorer on [celo.carbondefi.xyz](https://celo.carbondefi.xyz).
 
-Set `CARBON_API_BASE_URL` to override the REST base. Hosted MCP exposes **12 read + 13 prepare** tools (71 total); `execute_carbon_*` requires local stdio with `CELO_PRIVATE_KEY`.
+Set `CARBON_API_BASE_URL` to override the REST base. Hosted MCP exposes **72 tools** (reads + Carbon prepare); `execute_carbon_*` requires local stdio with `CELO_PRIVATE_KEY`.
+
+### MCP session wallet (not in the SDK)
+
+Local **celina-mcp** with `CELO_PRIVATE_KEY` can omit wallet params on many tools and use **`get_wallet_address`** instead of shelling out for the signer. The SDK always requires an explicit `0x…` from your app (e.g. wagmi). See [MCP session wallet](docs/guides/mcp-session-wallet.md). **Celeste AI** is an independent app built on this SDK + browser wallet signing — it does not use celina-mcp.
 
 Full workflow: [Carbon DeFi guide](docs/guides/carbon.md).
 
@@ -110,10 +114,20 @@ MCP: `get_gooddollar_whitelisting_info`, `get_gooddollar_ubi_entitlement` (read)
 
 ## Related packages
 
-- [`@andrewkimjoseph/celina-mcp`](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) `@0.8.4` — MCP server (38 Carbon tools on stdio; hosted: 12 read + 13 prepare)
+- [`@andrewkimjoseph/celina-mcp`](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) `@0.8.5` — MCP server (`get_wallet_address`, optional address on wallet-scoped tools; 85 tools stdio, 72 hosted)
 - [`celina-mcp-host`](../celina-mcp-host/) — Vercel-hosted MCP endpoint (`https://mcp.usecelina.xyz/api/mcp`) — reads + Carbon prepare
 - [`@selfxyz/agent-sdk`](https://www.npmjs.com/package/@selfxyz/agent-sdk) — Self Agent ID browser flows
 
+## Roadmap
+
+- [x] Mento FX routing (`getFxQuote`, `estimateFx`, `prepareFx`)
+- [x] Uniswap v4 swaps (`getSwapQuote`, `estimateSwap`, `prepareSwap`)
+- [x] Aave lending tools (`prepareSupply`, `prepareWithdraw`) — USDT, WETH, USDm, USDC, CELO, EURm
+- [x] Self proof verification (`verifySelfAgent`, `verifySelfRequest`, ai.self.xyz)
+- [x] Self Agent ID (`lookupSelfAgent`, registration & lifecycle tools)
+- [x] Carbon DeFi on Celo — 25 operations (12 read + 13 prepare); see [Carbon guide](docs/guides/carbon.md)
+- [ ] Cross-chain bridging — bridge tokens to/from Celo (`getBridgeQuote`, `estimateBridge`, `prepareBridge`)
+
 ## License
 
 MIT

package/build/analytics/config.js

@@ -23,8 +23,6 @@ export function resolveAmplitudeApiKey(config) {
         DEFAULT_AMPLITUDE_API_KEY);
 }
 export function resolveDeviceId(config) {
-    return (config.analyticsDeviceId ??
-        process.env.CELINA_ANALYTICS_DEVICE_ID ??
-        DEFAULT_DEVICE_ID);
+    return config.analyticsDeviceId ?? DEFAULT_DEVICE_ID;
 }
 //# sourceMappingURL=config.js.map

package/build/analytics/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/analytics/config.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,yBAAyB,GAAG,kCAAkC,CAAC;AAE5E,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,mEAAmE;AACnE,MAAM,UAAU,kBAAkB,CAAC,MAAiB;IAClD,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,GAAG,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,CAAC,gBAAgB,KAAK,KAAK,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAiB;IACtD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CACL,MAAM,CAAC,eAAe;QACtB,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC7B,yBAAyB,CAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,CACL,MAAM,CAAC,iBAAiB;QACxB,OAAO,CAAC,GAAG,CAAC,0BAA0B;QACtC,iBAAiB,CAClB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/analytics/config.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,yBAAyB,GAAG,kCAAkC,CAAC;AAE5E,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAEvC,mEAAmE;AACnE,MAAM,UAAU,kBAAkB,CAAC,MAAiB;IAClD,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,GAAG,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,CAAC,gBAAgB,KAAK,KAAK,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAiB;IACtD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CACL,MAAM,CAAC,eAAe;QACtB,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAC7B,yBAAyB,CAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,MAAM,CAAC,iBAAiB,IAAI,iBAAiB,CAAC;AACvD,CAAC"}

package/build/analytics/consumer-package.d.ts

@@ -0,0 +1,9 @@
+/** Amplitude-safe id from npm `package.json` `name` (strip `@`, `/` and `-` → `_`). */
+export declare function sanitizePackageDeviceId(name: string): string;
+/**
+ * npm package name of the app that called `createCelinaClient()`, sanitized for Amplitude.
+ * Returns `undefined` when detection fails or the consumer is the SDK itself.
+ */
+export declare function detectConsumerPackageName(stack?: string): string | undefined;
+/** Test-only: clear cached consumer detection between cases. */
+export declare function resetConsumerPackageDetectionForTests(): void;

package/build/analytics/consumer-package.js

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const SDK_PACKAGE_NAME = "@andrewkimjoseph/celina-sdk";
+const SDK_DEVICE_IDS = new Set(["andrewkimjoseph_celina_sdk", "celina-sdk"]);
+let detectionCached = false;
+let detectedDeviceId;
+/** Amplitude-safe id from npm `package.json` `name` (strip `@`, `/` and `-` → `_`). */
+export function sanitizePackageDeviceId(name) {
+    const stripped = name.startsWith("@") ? name.slice(1) : name;
+    return stripped.replace(/\//g, "_").replace(/-/g, "_");
+}
+function getSdkPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 24; i++) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (pkg.name === SDK_PACKAGE_NAME) {
+                    return dir;
+                }
+            }
+            catch {
+                // ignore malformed package.json
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return undefined;
+}
+function isSdkFramePath(filePath, sdkRoot) {
+    const normalized = resolve(filePath);
+    if (sdkRoot) {
+        const root = resolve(sdkRoot);
+        if (normalized === root || normalized.startsWith(root + sep)) {
+            return true;
+        }
+    }
+    return normalized.includes(`${sep}node_modules${sep}@andrewkimjoseph${sep}celina-sdk${sep}`);
+}
+function readPackageNameFromFile(filePath) {
+    let dir = dirname(resolve(filePath));
+    for (let i = 0; i < 24; i++) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (typeof pkg.name === "string" && pkg.name.length > 0) {
+                    return pkg.name;
+                }
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return undefined;
+}
+function parseStackFramePaths(stack) {
+    const paths = [];
+    for (const line of stack.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("at ")) {
+            continue;
+        }
+        const parenMatch = /\(([^)]+)\)/.exec(trimmed);
+        let loc = parenMatch?.[1];
+        if (!loc) {
+            const bare = /^at (?:async )?(?:.+ )?(.+)$/.exec(trimmed);
+            loc = bare?.[1];
+        }
+        if (!loc) {
+            continue;
+        }
+        let filePath = loc.trim();
+        if (filePath.startsWith("file://")) {
+            try {
+                filePath = fileURLToPath(filePath);
+            }
+            catch {
+                continue;
+            }
+        }
+        filePath = filePath.replace(/:\d+:\d+$/, "").replace(/:\d+$/, "");
+        if (filePath) {
+            paths.push(filePath);
+        }
+    }
+    return paths;
+}
+/**
+ * npm package name of the app that called `createCelinaClient()`, sanitized for Amplitude.
+ * Returns `undefined` when detection fails or the consumer is the SDK itself.
+ */
+export function detectConsumerPackageName(stack) {
+    if (detectionCached) {
+        return detectedDeviceId;
+    }
+    detectionCached = true;
+    detectedDeviceId = undefined;
+    if (typeof process === "undefined") {
+        return detectedDeviceId;
+    }
+    try {
+        const stackTrace = stack ?? new Error().stack ?? "";
+        const sdkRoot = getSdkPackageRoot();
+        for (const framePath of parseStackFramePaths(stackTrace)) {
+            if (isSdkFramePath(framePath, sdkRoot)) {
+                continue;
+            }
+            const rawName = readPackageNameFromFile(framePath);
+            if (!rawName) {
+                continue;
+            }
+            const deviceId = sanitizePackageDeviceId(rawName);
+            if (SDK_DEVICE_IDS.has(deviceId)) {
+                continue;
+            }
+            detectedDeviceId = deviceId;
+            return detectedDeviceId;
+        }
+    }
+    catch {
+        detectedDeviceId = undefined;
+    }
+    return detectedDeviceId;
+}
+/** Test-only: clear cached consumer detection between cases. */
+export function resetConsumerPackageDetectionForTests() {
+    detectionCached = false;
+    detectedDeviceId = undefined;
+}
+//# sourceMappingURL=consumer-package.js.map

package/build/analytics/consumer-package.js.map

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

package/build/config/sdk-config.d.ts

@@ -16,7 +16,11 @@ export interface SdkConfig {
     analyticsEnabled?: boolean;
     /** Override bundled Amplitude project API key. */
     amplitudeApiKey?: string;
-    /** Amplitude `device_id` (default `celina-sdk`). */
+    /**
+     * Amplitude `device_id`. When omitted, auto-detected from the consuming package
+     * `package.json` name (sanitized, e.g. `celeste_ai`, `andrewkimjoseph_celina_mcp`),
+     * then `CELINA_ANALYTICS_DEVICE_ID`, then `celina-sdk`.
+     */
     analyticsDeviceId?: string;
 }
 /** Default Celo RPC when `rpcUrl` is omitted. */

package/build/config/sdk-config.js

@@ -1,3 +1,4 @@
+import { detectConsumerPackageName } from "../analytics/consumer-package.js";
 /** Default Celo RPC when `rpcUrl` is omitted. */
 export const DEFAULT_RPC_URL = "https://forno.celo.org";
 /**
@@ -23,7 +24,11 @@ export function resolveSdkConfig(opts) {
                 : undefined),
         analyticsEnabled: opts?.analyticsEnabled,
         amplitudeApiKey: opts?.amplitudeApiKey,
-        analyticsDeviceId: opts?.analyticsDeviceId,
+        analyticsDeviceId: opts?.analyticsDeviceId ??
+            (typeof process !== "undefined"
+                ? process.env.CELINA_ANALYTICS_DEVICE_ID
+                : undefined) ??
+            detectConsumerPackageName(),
     };
 }
 //# sourceMappingURL=sdk-config.js.map

package/build/config/sdk-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-config.js","sourceRoot":"","sources":["../../src/config/sdk-config.ts"],"names":[],"mappings":"AAsBA,iDAAiD;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAyB;IACxD,MAAM,mBAAmB,GACvB,IAAI,EAAE,mBAAmB;QACzB,CAAC,OAAO,OAAO,KAAK,WAAW;YAC7B,CAAC,CAAE,OAAO,CAAC,GAAG,CAAC,sBAAoD;YACnE,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,OAAO;QACL,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,eAAe;QACvC,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,iBAAiB,EACf,IAAI,EAAE,iBAAiB;YACvB,OAAO,CAAC,GAAG,CAAC,mBAAmB;YAC/B,4BAA4B;QAC9B,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,IAAI,IAAI;QAClD,mBAAmB;QACnB,WAAW,EACT,IAAI,EAAE,WAAW;YACjB,CAAC,OAAO,OAAO,KAAK,WAAW;gBAC7B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB;gBACjC,CAAC,CAAC,SAAS,CAAC;QAChB,gBAAgB,EAAE,IAAI,EAAE,gBAAgB;QACxC,eAAe,EAAE,IAAI,EAAE,eAAe;QACtC,iBAAiB,EAAE,IAAI,EAAE,iBAAiB;KAC3C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sdk-config.js","sourceRoot":"","sources":["../../src/config/sdk-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AA4B7E,iDAAiD;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAyB;IACxD,MAAM,mBAAmB,GACvB,IAAI,EAAE,mBAAmB;QACzB,CAAC,OAAO,OAAO,KAAK,WAAW;YAC7B,CAAC,CAAE,OAAO,CAAC,GAAG,CAAC,sBAAoD;YACnE,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,OAAO;QACL,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,eAAe;QACvC,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,iBAAiB,EACf,IAAI,EAAE,iBAAiB;YACvB,OAAO,CAAC,GAAG,CAAC,mBAAmB;YAC/B,4BAA4B;QAC9B,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,IAAI,IAAI;QAClD,mBAAmB;QACnB,WAAW,EACT,IAAI,EAAE,WAAW;YACjB,CAAC,OAAO,OAAO,KAAK,WAAW;gBAC7B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB;gBACjC,CAAC,CAAC,SAAS,CAAC;QAChB,gBAAgB,EAAE,IAAI,EAAE,gBAAgB;QACxC,eAAe,EAAE,IAAI,EAAE,eAAe;QACtC,iBAAiB,EACf,IAAI,EAAE,iBAAiB;YACvB,CAAC,OAAO,OAAO,KAAK,WAAW;gBAC7B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B;gBACxC,CAAC,CAAC,SAAS,CAAC;YACd,yBAAyB,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/build/utils/carbon-execution.js

@@ -2,6 +2,7 @@ import { encodeFunctionData, erc20Abi } from "viem";
 import { CELO_CARBON_CONTRACTS } from "../config/carbon.js";
 import { appendCelinaCalldataTag } from "../config/celina-tag.js";
 import { resolveCarbonTokenAddress } from "./carbon-token.js";
+import { applyCarbonStepLabels } from "./carbon-step-labels.js";
 const CARBON_CONTROLLER = CELO_CARBON_CONTRACTS.carbonControllerAddress;
 function collectApprovalSpecs(meta) {
     const specs = [];
@@ -95,6 +96,11 @@ export async function buildCarbonExecutionSteps(from, prepared, orderMeta, deps)
         throw new Error("Carbon prepare response did not include unsigned transaction steps.");
     }
     const approvalSteps = await buildApprovalSteps(from, deps.tokenService, deps.clientFactory, collectApprovalSpecs(orderMeta));
-    return [...approvalSteps, ...carbonSteps];
+    return applyCarbonStepLabels([...approvalSteps, ...carbonSteps], {
+        summary: prepared.preparedFlow?.summary ?? "Carbon transaction",
+        orderMeta,
+        strategyPreview: prepared.strategyPreview,
+        tokenService: deps.tokenService,
+    });
 }
 //# sourceMappingURL=carbon-execution.js.map

package/build/utils/carbon-execution.js.map

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

package/build/utils/carbon-step-labels.d.ts

@@ -0,0 +1,12 @@
+import type { PreparedTx } from "../types/prepared.js";
+import type { TokenService } from "../services/token.service.js";
+export type CarbonStepLabelContext = {
+    summary: string;
+    orderMeta: Record<string, unknown>;
+    strategyPreview?: unknown;
+    tokenService: TokenService;
+};
+/** Human-readable label for a Carbon controller transaction step. */
+export declare function describeCarbonControllerStep(ctx: CarbonStepLabelContext, index: number, total: number): string;
+/** Replace generic Carbon REST step descriptions with human-readable labels. */
+export declare function applyCarbonStepLabels(steps: PreparedTx[], ctx: CarbonStepLabelContext): PreparedTx[];

package/build/utils/carbon-step-labels.js

@@ -0,0 +1,180 @@
+const GENERIC_CARBON_STEP = /^Carbon transaction step \d+$/;
+function readRecord(value) {
+    return value && typeof value === "object"
+        ? value
+        : {};
+}
+function readPositive(value) {
+    if (value === undefined || value === null || value === "") {
+        return null;
+    }
+    const n = typeof value === "number" ? value : Number(String(value).replace(/,/g, ""));
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+function resolveSymbol(tokenService, token) {
+    if (token === undefined || token === null || token === "") {
+        return "?";
+    }
+    try {
+        return tokenService.resolveToken(String(token)).symbol;
+    }
+    catch {
+        return String(token).trim();
+    }
+}
+function formatAmount(value) {
+    if (value >= 1) {
+        return value.toLocaleString(undefined, { maximumFractionDigits: 4 });
+    }
+    return value.toLocaleString(undefined, { maximumFractionDigits: 6 });
+}
+function pairLabel(ctx) {
+    const meta = ctx.orderMeta;
+    const base = resolveSymbol(ctx.tokenService, meta.base_token ?? meta.base);
+    const quote = resolveSymbol(ctx.tokenService, meta.quote_token ?? meta.quote);
+    return `${base} / ${quote}`;
+}
+function directionFrom(ctx) {
+    const meta = ctx.orderMeta;
+    const preview = readRecord(ctx.strategyPreview);
+    const raw = String(preview.direction ?? meta.direction ?? "buy").toLowerCase();
+    return raw === "sell" ? "sell" : "buy";
+}
+function budgetLabel(ctx) {
+    const meta = ctx.orderMeta;
+    const preview = readRecord(ctx.strategyPreview);
+    const direction = directionFrom(ctx);
+    const amount = readPositive(preview.budget) ??
+        readPositive(meta.budget) ??
+        (direction === "sell"
+            ? readPositive(meta.sell_budget)
+            : readPositive(meta.buy_budget));
+    if (amount === null) {
+        return null;
+    }
+    const token = direction === "sell"
+        ? resolveSymbol(ctx.tokenService, meta.base_token ?? meta.base)
+        : resolveSymbol(ctx.tokenService, meta.quote_token ?? meta.quote);
+    return `${formatAmount(amount)} ${token}`;
+}
+function actionFromSummary(summary) {
+    const normalized = summary.trim().toLowerCase();
+    if (normalized.includes("limit order"))
+        return "limit";
+    if (normalized.includes("range order"))
+        return "range";
+    if (normalized.includes("recurring strategy"))
+        return "recurring";
+    if (normalized.includes("concentrated strategy"))
+        return "concentrated";
+    if (normalized.includes("full-range strategy"))
+        return "full-range";
+    if (normalized.includes("reprice strategy"))
+        return "reprice";
+    if (normalized.includes("edit strategy"))
+        return "edit";
+    if (normalized.includes("deposit budget"))
+        return "deposit";
+    if (normalized.includes("withdraw budget"))
+        return "withdraw";
+    if (normalized.includes("pause strategy"))
+        return "pause";
+    if (normalized.includes("resume strategy"))
+        return "resume";
+    if (normalized.includes("delete strategy"))
+        return "delete";
+    if (normalized.includes("taker swap"))
+        return "swap";
+    return null;
+}
+function actionFromPreview(preview) {
+    const type = String(preview.type ?? "").toLowerCase();
+    if (type.includes("limit"))
+        return "limit";
+    if (type.includes("range"))
+        return "range";
+    if (type.includes("recurring"))
+        return "recurring";
+    if (type.includes("concentrated"))
+        return "concentrated";
+    if (type.includes("full"))
+        return "full-range";
+    return null;
+}
+function createActionLabel(ctx) {
+    const preview = readRecord(ctx.strategyPreview);
+    const action = actionFromPreview(preview) ?? actionFromSummary(ctx.summary) ?? "strategy";
+    const direction = directionFrom(ctx);
+    const pair = pairLabel(ctx);
+    const budget = budgetLabel(ctx);
+    if (action === "swap") {
+        return "Swap via Carbon DeFi";
+    }
+    if (action === "reprice")
+        return "Reprice Carbon strategy";
+    if (action === "edit")
+        return "Edit Carbon strategy";
+    if (action === "deposit")
+        return "Deposit to Carbon strategy";
+    if (action === "withdraw")
+        return "Withdraw from Carbon strategy";
+    if (action === "pause")
+        return "Pause Carbon strategy";
+    if (action === "resume")
+        return "Resume Carbon strategy";
+    if (action === "delete")
+        return "Close Carbon strategy";
+    if (action === "recurring") {
+        return budget
+            ? `Create recurring strategy — ${budget} on ${pair}`
+            : `Create recurring strategy — ${pair}`;
+    }
+    if (action === "concentrated" || action === "full-range") {
+        const kind = action === "concentrated" ? "concentrated" : "full-range";
+        return budget
+            ? `Create ${kind} strategy — ${budget} on ${pair}`
+            : `Create ${kind} strategy — ${pair}`;
+    }
+    const side = action === "range" ? "range" : "limit";
+    const sideLabel = `${side} ${direction}`;
+    return budget
+        ? `Create ${sideLabel} — ${budget} on ${pair}`
+        : `Create ${sideLabel} on ${pair}`;
+}
+/** Human-readable label for a Carbon controller transaction step. */
+export function describeCarbonControllerStep(ctx, index, total) {
+    const base = createActionLabel(ctx);
+    if (total <= 1) {
+        return base;
+    }
+    return `${base} (step ${index + 1} of ${total})`;
+}
+function isApprovalStep(step) {
+    return (step.kind === "erc20" ||
+        step.description.startsWith("Approve "));
+}
+function isGenericCarbonStep(step) {
+    return GENERIC_CARBON_STEP.test(step.description);
+}
+/** Replace generic Carbon REST step descriptions with human-readable labels. */
+export function applyCarbonStepLabels(steps, ctx) {
+    const controllerIndexes = steps
+        .map((step, index) => ({ step, index }))
+        .filter(({ step }) => !isApprovalStep(step) && isGenericCarbonStep(step));
+    if (controllerIndexes.length === 0) {
+        return steps;
+    }
+    const total = controllerIndexes.length;
+    const labels = new Map();
+    controllerIndexes.forEach(({ index }, controllerIndex) => {
+        labels.set(index, describeCarbonControllerStep(ctx, controllerIndex, total));
+    });
+    return steps.map((step, index) => {
+        const label = labels.get(index);
+        if (!label) {
+            return step;
+        }
+        return { ...step, description: label };
+    });
+}
+//# sourceMappingURL=carbon-step-labels.js.map

package/build/utils/carbon-step-labels.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrewkimjoseph/celina-sdk",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Celina SDK — Celo mainnet reads and unsigned transaction preparation for frontend apps.",
   "type": "module",
   "sideEffects": false,