@circle-fin/app-kit 1.6.1 → 1.7.0

package/index.cjs

@@ -2308,7 +2308,8 @@ const DEFAULT_RETRYABLE_ERROR_CODES = [
  *
  * @remarks
  * Check order for KitError instances:
- * 1. If `recoverability === 'RETRYABLE'`, return `true` immediately (priority check).
+ * 1. If `recoverability === 'RETRYABLE'` or `recoverability === 'RESUMABLE'`,
+ *    return `true` immediately (priority check).
  * 2. Otherwise, check if `error.code` is in `DEFAULT_RETRYABLE_ERROR_CODES` (fallback check).
  * 3. Non-KitError instances always return `false`.
  *
@@ -2319,6 +2320,12 @@ const DEFAULT_RETRYABLE_ERROR_CODES = [
  * subsequent attempts, such as network timeouts or temporary service
  * unavailability. These errors are safe to retry after a delay.
  *
+ * RESUMABLE errors indicate a multi-phase operation that completed some phases
+ * before failing (for example, a token approval landed but the execution
+ * transaction failed). They are also retryable — re-running the operation is
+ * safe — but callers that have a kit-level `retry()` should prefer it so that
+ * already-completed phases are skipped.
+ *
  * @param error - Unknown error to check
  * @returns True if error is retryable
  *
@@ -2364,16 +2371,29 @@ const DEFAULT_RETRYABLE_ERROR_CODES = [
  * })
  * isRetryableError(error3) // false
  *
+ * // KitError with RESUMABLE recoverability (partially-completed operation)
+ * const error4 = new KitError({
+ *   code: 8101,
+ *   name: 'EARN_EXECUTION_FAILED',
+ *   type: 'SERVICE',
+ *   recoverability: 'RESUMABLE',
+ *   message: 'Execution failed after approval',
+ * })
+ * isRetryableError(error4) // true
+ *
  * // Non-KitError
- * const error4 = new Error('Standard error')
- * isRetryableError(error4) // false
+ * const error5 = new Error('Standard error')
+ * isRetryableError(error5) // false
  * ```
  */
 function isRetryableError$1(error) {
     // Use proper type guard to check if it's a KitError
     if (isKitError(error)) {
-        // Priority check: explicit recoverability
-        if (error.recoverability === 'RETRYABLE') {
+        // Priority check: explicit recoverability. RESUMABLE errors are a subset of
+        // retryable errors — re-running the operation is safe, but a kit-level
+        // retry() can resume from the failed phase instead.
+        if (error.recoverability === 'RETRYABLE' ||
+            error.recoverability === 'RESUMABLE') {
             return true;
         }
         // Fallback check: error code against default retryable codes
@@ -11046,7 +11066,7 @@ function emitResultStepErrorTelemetry(failedStep, stepEventMap, fallbackEventTyp
 }
 
 var name$3 = "@circle-fin/bridge-kit";
-var version$4 = "1.10.1";
+var version$4 = "1.10.2";
 var pkg$4 = {
 	name: name$3,
 	version: version$4};
@@ -11537,60 +11557,6 @@ const validateBalanceForTransaction = async (params) => {
     }
 };
 
-/**
- * Validate that the adapter has sufficient native token balance for transaction fees.
- *
- * This function checks if the adapter's current native token balance (ETH, SOL, etc.)
- * is greater than zero. It throws a KitError with code 9002 (BALANCE_INSUFFICIENT_GAS)
- * if the balance is zero, indicating the wallet cannot pay for transaction fees.
- *
- * @param params - The validation parameters containing adapter and operation context.
- * @returns A promise that resolves to void if validation passes.
- * @throws {KitError} When the adapter's native balance is zero (code: 9002).
- *
- * @example
- * ```typescript
- * import { validateNativeBalanceForTransaction } from '@core/adapter'
- * import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
- * import { isKitError, ERROR_TYPES } from '@core/errors'
- *
- * const adapter = createViemAdapterFromPrivateKey({
- *   privateKey: '0x...',
- *   chain: 'Ethereum',
- * })
- *
- * try {
- *   await validateNativeBalanceForTransaction({
- *     adapter,
- *     operationContext: { chain: 'Ethereum' },
- *   })
- *   console.log('Native balance validation passed')
- * } catch (error) {
- *   if (isKitError(error) && error.type === ERROR_TYPES.BALANCE) {
- *     console.error('Insufficient gas funds:', error.message)
- *   }
- * }
- * ```
- */
-const validateNativeBalanceForTransaction = async (params) => {
-    const { adapter, operationContext } = params;
-    const balancePrepared = await adapter.prepareAction('native.balanceOf', {
-        walletAddress: operationContext.address,
-    }, operationContext);
-    const balance = await balancePrepared.execute();
-    if (BigInt(balance) === 0n) {
-        const { chain } = operationContext;
-        const chainName = extractChainInfo(chain).name;
-        const nativeSymbol = typeof chain === 'object' && chain !== null && 'nativeCurrency' in chain
-            ? chain.nativeCurrency.symbol
-            : undefined;
-        throw createInsufficientGasError(chainName, nativeSymbol, {
-            balance: '0',
-            walletAddress: operationContext.address,
-        });
-    }
-};
-
 /**
  * Permit signature standards for gasless token approvals.
  *
@@ -16022,7 +15988,7 @@ async function buildBatchedStep(name, receipt, batchId, adapter, chain, statusCo
     return step;
 }
 
-var version$3 = "1.8.2";
+var version$3 = "1.8.3";
 var pkg$3 = {
 	version: version$3};
 
@@ -16840,7 +16806,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
     async bridge(params) {
         // CCTP-specific bridge params validation (includes base validation)
         assertCCTPv2BridgeParams(params);
-        const { source, destination, amount, token } = params;
+        const { source, amount, token } = params;
         // Extract operation context from source wallet context for balance validation
         const sourceOperationContext = this.extractOperationContext(source);
         // Validate USDC balance for transaction on source chain
@@ -16851,24 +16817,6 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             tokenAddress: source.chain.usdcAddress,
             operationContext: sourceOperationContext,
         });
-        // Validate native balance > 0 for gas fees on source chain
-        await validateNativeBalanceForTransaction({
-            adapter: source.adapter,
-            operationContext: sourceOperationContext,
-        });
-        // Only validate destination native balance if there's an adapter
-        // and forwarder is not being used (forwarder handles mint, no gas needed)
-        if ('adapter' in destination &&
-            destination.adapter &&
-            !destination.useForwarder) {
-            // Extract operation context from destination wallet context
-            const destinationOperationContext = this.extractOperationContext(destination);
-            // Validate native balance > 0 for gas fees on destination chain
-            await validateNativeBalanceForTransaction({
-                adapter: destination.adapter,
-                operationContext: destinationOperationContext,
-            });
-        }
         return bridge$1(params, this);
     }
     /**
@@ -18421,7 +18369,7 @@ const createBridgeKit = (context) => {
 };
 
 var name$2 = "@circle-fin/swap-kit";
-var version$2 = "1.2.2";
+var version$2 = "1.2.3";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -29584,7 +29532,7 @@ const createSwapKit = (context) => {
 };
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.0.1";
+var version$1 = "1.1.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -29994,6 +29942,253 @@ function validateExecutionDeadline(executionParams) {
     }
 }
 
+/** Base discriminators shared by every earn action payload. */
+const EARN_ACTION_BASE = {
+    protocol: 'earn',
+    service: 'earn-service',
+};
+/**
+ * Dispatch a step event for an earn operation through the kit's action
+ * dispatcher.
+ *
+ * Builds the action payload for the given action/operation/step combination
+ * and forwards it to any registered listeners (including wildcard `'*'`
+ * listeners). The call is a no-op when no dispatcher has been registered, so
+ * callers can invoke it unconditionally.
+ *
+ * The `approve` action only fires for `deposit` and `withdraw` operations and
+ * only carries `approve` steps; the `deposit`, `withdraw`, and `claimRewards`
+ * actions carry only `fetchParams` and `execute` steps. Mismatched
+ * combinations are ignored defensively.
+ *
+ * @param dispatcher - The action dispatcher, or `undefined` if none registered.
+ * @param action - The action name to dispatch under.
+ * @param operation - The earn operation the step belongs to.
+ * @param step - The step to deliver as the event payload.
+ *
+ * @example
+ * ```typescript
+ * dispatchEarnEvent(dispatcher, 'deposit', 'deposit', {
+ *   name: 'execute',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ * })
+ * ```
+ */
+function dispatchEarnEvent(dispatcher, action, operation, step) {
+    if (dispatcher === undefined) {
+        return;
+    }
+    // Listener errors must never abort the financial operation flow. A throwing
+    // listener on a 'success' event after a transaction has landed on-chain
+    // would otherwise propagate to the caller as a RESUMABLE error and trigger
+    // a retry that re-submits the same transaction (double-spend risk).
+    try {
+        if (action === 'approve') {
+            // The approve action only applies to deposit/withdraw approval steps.
+            if (step.name !== 'approve' || operation === 'claimRewards') {
+                return;
+            }
+            dispatcher.dispatch('approve', {
+                ...EARN_ACTION_BASE,
+                operation,
+                method: 'approve',
+                values: step,
+            });
+            return;
+        }
+        // deposit / withdraw / claimRewards actions carry fetchParams + execute steps.
+        if (step.name === 'approve') {
+            return;
+        }
+        const payload = { ...EARN_ACTION_BASE, method: step.name, values: step };
+        if (action === 'deposit') {
+            dispatcher.dispatch('deposit', { ...payload, operation: 'deposit' });
+            return;
+        }
+        if (action === 'withdraw') {
+            dispatcher.dispatch('withdraw', { ...payload, operation: 'withdraw' });
+            return;
+        }
+        if (action === 'claimRewards') {
+            dispatcher.dispatch('claimRewards', {
+                ...payload,
+                operation: 'claimRewards',
+            });
+            return;
+        }
+    }
+    catch {
+        // Swallow listener errors. Observability of the failure is the listener's
+        // responsibility; the operation flow continues unaffected.
+        return;
+    }
+    // Reached only when `action` is not a known earn action. Thrown outside the
+    // try/catch so a missing case surfaces as a developer error instead of being
+    // silently swallowed alongside listener failures.
+    const exhaustive = action;
+    throw new Error(`Unhandled earn action: ${String(exhaustive)}`);
+}
+
+const EARN_OPERATIONS = new Set([
+    'deposit',
+    'withdraw',
+    'claimRewards',
+]);
+/**
+ * Operations whose service params carry a top-level `amount` input field
+ * (`deposit` and `withdraw`); `claimRewards` params have no `amount`. This
+ * refers to the request input — distinct from the reward `amount` that appears
+ * inside a claimRewards *result*.
+ */
+const OPERATIONS_WITH_AMOUNT = new Set([
+    'deposit',
+    'withdraw',
+]);
+/**
+ * Validate that `params` carries the minimum shape `retry()` needs to resume
+ * the given operation: an adapter context (`from`) and a `vaultAddress`, plus
+ * an `amount` for `deposit`/`withdraw`. This is a structural sanity check, not
+ * a full schema validation — operations re-validate their inputs when re-run —
+ * but it lets a mismatched or forged trace fail the {@link isEarnErrorTrace}
+ * guard cleanly instead of crashing deep inside the resume path.
+ */
+function hasEarnServiceParamsShape(operation, params) {
+    if (params['from'] === null || typeof params['from'] !== 'object') {
+        return false;
+    }
+    if (typeof params['vaultAddress'] !== 'string') {
+        return false;
+    }
+    if (OPERATIONS_WITH_AMOUNT.has(operation) &&
+        typeof params['amount'] !== 'string') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Wrap an error thrown during a multi-phase earn operation with step-tracking
+ * and resume context.
+ *
+ * Produces a new {@link KitError} that preserves the original error's code,
+ * name, type, and message, merges any existing `cause.trace`, and adds an
+ * {@link EarnErrorTrace} (`provider`, `operation`, `steps`, `params`). When a
+ * prior phase had already committed work (a successful step exists) and the
+ * underlying error is retryable, the recoverability is upgraded to
+ * `RESUMABLE` so callers know `retry()` can resume from the failed phase. A
+ * fatal underlying error stays fatal — it cannot be resumed.
+ *
+ * Non-{@link KitError} inputs (which should not occur on provider code paths)
+ * are normalized to a retryable {@link ServiceError.INTERNAL_ERROR}.
+ *
+ * @param error - The error caught from a phase of the operation.
+ * @param context - The operation context used to build the trace.
+ * @returns A new {@link KitError} carrying the {@link EarnErrorTrace}.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await executeEarnAction(...)
+ * } catch (error) {
+ *   throw augmentEarnError(error, {
+ *     providerName: 'EarnService',
+ *     operation: 'deposit',
+ *     steps,
+ *     params,
+ *   })
+ * }
+ * ```
+ */
+function augmentEarnError(error, context) {
+    const base = isKitError(error)
+        ? error
+        : new KitError({
+            ...ServiceError.INTERNAL_ERROR,
+            recoverability: 'RETRYABLE',
+            message: getErrorMessage(error),
+        });
+    // Only upgrade to RESUMABLE when a prior *on-chain* phase succeeded. The
+    // RESUMABLE label promises retry() can skip already-committed work — true
+    // for a landed `approve` or `execute`, but a successful `fetchParams` saves
+    // nothing (retry() re-fetches it anyway, since execution params/deadlines
+    // expire), so it stays a plain RETRYABLE.
+    const priorOnChainPhaseSucceeded = context.steps.some((step) => step.state === 'success' &&
+        (step.name === 'approve' || step.name === 'execute'));
+    const recoverability = priorOnChainPhaseSucceeded && base.recoverability === 'RETRYABLE'
+        ? 'RESUMABLE'
+        : base.recoverability;
+    const existingTrace = base.cause?.trace !== undefined &&
+        base.cause.trace !== null &&
+        typeof base.cause.trace === 'object'
+        ? base.cause.trace
+        : {};
+    // Snapshot the steps so the trace `retry()` reads can't be mutated by a
+    // future code path that retains the live `EarnRunContext.steps` array.
+    const trace = {
+        ...existingTrace,
+        provider: context.providerName,
+        operation: context.operation,
+        steps: [...context.steps],
+    };
+    // Store the original service params non-enumerably. `retry()` reads them by
+    // direct property access (`trace.params`), but JSON.stringify, console.log,
+    // and telemetry serializers skip non-enumerable properties — so a
+    // permissioned call's `config.kitKey` (a `KIT_KEY:<id>:<secret>` value) and
+    // the in-memory adapter never leak through a logged error. defineProperty
+    // also redefines any enumerable `params` an upstream trace may have carried.
+    Object.defineProperty(trace, 'params', {
+        value: context.params,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return new KitError({
+        code: base.code,
+        name: base.name,
+        type: base.type,
+        recoverability,
+        message: base.message,
+        cause: { trace },
+    });
+}
+/**
+ * Runtime type guard for {@link EarnErrorTrace}.
+ *
+ * Verifies the value carries the fields `retry()` needs to resume an earn
+ * operation: a provider name, a known operation, a steps array, and a `params`
+ * object whose shape matches that operation (an adapter context and vault
+ * address, plus an amount for `deposit`/`withdraw`). Used to validate
+ * `KitError.cause.trace` before resuming so a mismatched or forged trace is
+ * rejected cleanly rather than crashing inside the resume path.
+ *
+ * @param value - The candidate value (typically `error.cause?.trace`).
+ * @returns `true` if `value` is a usable {@link EarnErrorTrace}.
+ *
+ * @example
+ * ```typescript
+ * const trace = error.cause?.trace
+ * if (isEarnErrorTrace(trace)) {
+ *   console.log(trace.operation, trace.steps.length)
+ * }
+ * ```
+ */
+function isEarnErrorTrace(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    const operation = candidate['operation'];
+    if (typeof candidate['provider'] !== 'string' ||
+        typeof operation !== 'string' ||
+        !EARN_OPERATIONS.has(operation) ||
+        !Array.isArray(candidate['steps']) ||
+        candidate['params'] === null ||
+        typeof candidate['params'] !== 'object') {
+        return false;
+    }
+    return hasEarnServiceParamsShape(operation, candidate['params']);
+}
+
 // ---------------------------------------------------------------------------
 // Shared primitives
 // ---------------------------------------------------------------------------
@@ -30981,12 +31176,63 @@ async function fetchClaimRewardsQuote(params) {
     }
 }
 
+/**
+ * Build the `pending` {@link EarnStep} for a phase about to start,
+ * discriminating on `stepName` so the result is a typed union member rather
+ * than an unsafe `as EarnStep` cast.
+ *
+ * @param stepName - The name of the phase about to start.
+ * @returns The typed pending step for the phase.
+ */
+function buildPendingStep(stepName) {
+    if (stepName === 'fetchParams') {
+        return { name: 'fetchParams', state: 'pending' };
+    }
+    return { name: stepName, state: 'pending' };
+}
+/**
+ * Build the `success` {@link EarnStep} for a completed phase, discriminating
+ * on `stepName` so the `fetchParams` variant (which has no `txHash` in its
+ * type) cannot accidentally carry a transaction hash.
+ *
+ * @param stepName - The name of the completed phase.
+ * @param txHash - The on-chain transaction hash, if any.
+ * @returns The typed success step for the phase.
+ */
+function buildSuccessStep(stepName, txHash) {
+    if (stepName === 'fetchParams') {
+        return { name: 'fetchParams', state: 'success' };
+    }
+    if (txHash === undefined) {
+        return { name: stepName, state: 'success' };
+    }
+    return { name: stepName, state: 'success', txHash };
+}
+/**
+ * Build the `error` {@link EarnStep} for a failed phase, discriminating on
+ * `stepName` so the result is a typed union member rather than an unsafe
+ * `as EarnStep` cast.
+ *
+ * @param stepName - The name of the failed phase.
+ * @param errorMessage - The human-readable failure message.
+ * @param error - The raw error that caused the phase to fail.
+ * @returns The typed error step for the phase.
+ */
+function buildErrorStep(stepName, errorMessage, error) {
+    if (stepName === 'fetchParams') {
+        return { name: 'fetchParams', state: 'error', errorMessage, error };
+    }
+    return { name: stepName, state: 'error', errorMessage, error };
+}
 /**
  * Earn Service provider for the Circle earn service API.
  *
  * Implement the {@link EarningProvider} interface for yield-bearing vault
  * operations including vault discovery, position queries, deposits,
- * withdrawals, and reward claiming.
+ * withdrawals, and reward claiming. Multi-phase operations (deposit,
+ * withdraw, claimRewards) emit step-level events through the kit's action
+ * dispatcher and attach step progress to thrown errors so callers can resume
+ * via {@link EarnServiceProvider.retry}.
  *
  * @example
  * ```typescript
@@ -31017,6 +31263,8 @@ class EarnServiceProvider {
     name = 'EarnService';
     /** {@inheritdoc} */
     supportedChains = Object.keys(CHAIN_TO_API).map((chain) => resolveChainIdentifier(chain));
+    /** {@inheritdoc} */
+    actionDispatcher = undefined;
     defaultConfig;
     /**
      * Create a new EarnServiceProvider.
@@ -31027,12 +31275,49 @@ class EarnServiceProvider {
     constructor(config) {
         this.defaultConfig = config;
     }
+    /** {@inheritdoc} */
+    registerDispatcher(dispatcher) {
+        this.actionDispatcher = dispatcher;
+    }
     resolveConfig(config) {
         const resolvedConfig = this.defaultConfig === undefined
             ? config
             : { ...this.defaultConfig, ...config };
         return resolvedConfig;
     }
+    /**
+     * Run one phase of a multi-phase earn operation: dispatch a `pending` event,
+     * execute it, then dispatch a `success` event (recording the resulting step)
+     * or — on failure — dispatch an `error` event, record the failed step, and
+     * re-throw the original error for the caller to wrap with full step context.
+     *
+     * @typeParam R - The phase's result type.
+     * @param ctx - The operation context (dispatcher, operation, steps, params).
+     * @param action - The action name to dispatch the events under.
+     * @param stepName - The phase name.
+     * @param run - The phase work to execute.
+     * @param txHashOf - Extracts the on-chain transaction hash from the result, if any.
+     * @returns The phase result.
+     */
+    async runPhase(ctx, action, stepName, run, txHashOf) {
+        dispatchEarnEvent(ctx.dispatcher, action, ctx.operation, buildPendingStep(stepName));
+        let result;
+        try {
+            result = await run();
+        }
+        catch (error) {
+            const failedStep = buildErrorStep(stepName, getErrorMessage(error), error);
+            ctx.steps.push(failedStep);
+            dispatchEarnEvent(ctx.dispatcher, action, ctx.operation, failedStep);
+            throw error;
+        }
+        // Discriminate on stepName so the `fetchParams` variant (which has no
+        // `txHash` field in its type) cannot accidentally pick up a tx hash.
+        const successStep = buildSuccessStep(stepName, txHashOf(result));
+        ctx.steps.push(successStep);
+        dispatchEarnEvent(ctx.dispatcher, action, ctx.operation, successStep);
+        return result;
+    }
     /** {@inheritdoc} */
     async getVaults(params) {
         const config = this.resolveConfig(params.config);
@@ -31054,146 +31339,246 @@ class EarnServiceProvider {
     }
     /** {@inheritdoc} */
     async deposit(params) {
-        const config = this.resolveConfig(params.config);
-        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
-        const adapterContractAddress = requireAdapterContract(chain);
-        const rawUsdcAddress = chain.usdcAddress;
-        if (rawUsdcAddress === null) {
-            throw createUnsupportedTokenError('USDC', chain.name);
-        }
-        const usdcAddress = assertHexAddress('chain.usdcAddress', rawUsdcAddress, `USDC address for chain ${chain.name} must be a 0x-prefixed 20-byte hex address.`);
-        const { executionParams, signature } = await fetchDeposit({
-            vaultAddress: params.vaultAddress,
-            amount: params.amount,
-            address,
-            chain: apiChain,
-            config,
-        });
-        validateExecutionDeadline(executionParams);
-        const { adapter } = params.from;
-        const tokenInputs = buildEarnTokenInputs(executionParams, usdcAddress);
-        const approvalToken = tokenInputs[0]?.token;
-        if (approvalToken !== undefined) {
-            await approveMaxIfNeeded({
+        return this.runDepositFlow(params, { skipApprove: false });
+    }
+    async runDepositFlow(params, options) {
+        const ctx = {
+            dispatcher: this.actionDispatcher,
+            operation: 'deposit',
+            steps: [],
+            params,
+        };
+        try {
+            const config = this.resolveConfig(params.config);
+            const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+            const adapterContractAddress = requireAdapterContract(chain);
+            const rawUsdcAddress = chain.usdcAddress;
+            if (rawUsdcAddress === null) {
+                throw createUnsupportedTokenError('USDC', chain.name);
+            }
+            const usdcAddress = assertHexAddress('chain.usdcAddress', rawUsdcAddress, `USDC address for chain ${chain.name} must be a 0x-prefixed 20-byte hex address.`);
+            const { adapter } = params.from;
+            const { executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async () => fetchDeposit({
+                vaultAddress: params.vaultAddress,
+                amount: params.amount,
+                address,
+                chain: apiChain,
+                config,
+            }), () => undefined);
+            validateExecutionDeadline(executionParams);
+            const tokenInputs = buildEarnTokenInputs(executionParams, usdcAddress);
+            const approvalToken = tokenInputs[0]?.token;
+            if (!options.skipApprove && approvalToken !== undefined) {
+                await this.runPhase(ctx, 'approve', 'approve', async () => approveMaxIfNeeded({
+                    adapter,
+                    chain,
+                    tokenAddress: approvalToken,
+                    delegate: adapterContractAddress,
+                    address,
+                    revertMessage: 'USDC approval reverted on-chain',
+                }), (txHash) => txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async () => executeEarnAction({
                 adapter,
                 chain,
-                tokenAddress: approvalToken,
-                delegate: adapterContractAddress,
                 address,
-                revertMessage: 'USDC approval reverted on-chain',
+                actionKey: 'earn.deposit',
+                actionParams: {
+                    executeParams: executionParams,
+                    tokenInputs,
+                    signature,
+                },
+                revertMessage: 'Earn deposit reverted on-chain',
+            }), ({ txHash }) => txHash);
+            return {
+                txHash,
+                explorerUrl,
+                vaultAddress: params.vaultAddress,
+                amount: params.amount,
+            };
+        }
+        catch (error) {
+            throw augmentEarnError(error, {
+                providerName: this.name,
+                operation: ctx.operation,
+                steps: ctx.steps,
+                params: ctx.params,
             });
         }
-        const { txHash, explorerUrl } = await executeEarnAction({
-            adapter,
-            chain,
-            address,
-            actionKey: 'earn.deposit',
-            actionParams: {
-                executeParams: executionParams,
-                tokenInputs,
-                signature,
-            },
-            revertMessage: 'Earn deposit reverted on-chain',
-        });
-        return {
-            txHash,
-            explorerUrl,
-            vaultAddress: params.vaultAddress,
-            amount: params.amount,
-        };
     }
     /** {@inheritdoc} */
     async withdraw(params) {
-        const config = this.resolveConfig(params.config);
-        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
-        const adapterContractAddress = requireAdapterContract(chain);
-        const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-        const { executionParams, signature } = await fetchWithdraw({
-            vaultAddress,
-            amount: params.amount,
-            address,
-            chain: apiChain,
-            config,
-        });
-        validateExecutionDeadline(executionParams);
-        const { adapter } = params.from;
-        const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
-        const approvalToken = tokenInputs[0]?.token;
-        if (approvalToken !== undefined) {
-            await approveMaxIfNeeded({
+        return this.runWithdrawFlow(params, { skipApprove: false });
+    }
+    async runWithdrawFlow(params, options) {
+        const ctx = {
+            dispatcher: this.actionDispatcher,
+            operation: 'withdraw',
+            steps: [],
+            params,
+        };
+        try {
+            const config = this.resolveConfig(params.config);
+            const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+            const adapterContractAddress = requireAdapterContract(chain);
+            const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
+            const { adapter } = params.from;
+            const { executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async () => fetchWithdraw({
+                vaultAddress,
+                amount: params.amount,
+                address,
+                chain: apiChain,
+                config,
+            }), () => undefined);
+            validateExecutionDeadline(executionParams);
+            const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
+            const approvalToken = tokenInputs[0]?.token;
+            if (!options.skipApprove && approvalToken !== undefined) {
+                await this.runPhase(ctx, 'approve', 'approve', async () => approveMaxIfNeeded({
+                    adapter,
+                    chain,
+                    tokenAddress: approvalToken,
+                    delegate: adapterContractAddress,
+                    address,
+                    revertMessage: 'Vault share token approval reverted on-chain',
+                }), (txHash) => txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async () => executeEarnAction({
                 adapter,
                 chain,
-                tokenAddress: approvalToken,
-                delegate: adapterContractAddress,
                 address,
-                revertMessage: 'Vault share token approval reverted on-chain',
+                actionKey: 'earn.withdraw',
+                actionParams: {
+                    executeParams: executionParams,
+                    tokenInputs,
+                    signature,
+                },
+                revertMessage: 'Earn withdraw reverted on-chain',
+            }), ({ txHash }) => txHash);
+            return {
+                txHash,
+                explorerUrl,
+                vaultAddress,
+                amount: params.amount,
+            };
+        }
+        catch (error) {
+            throw augmentEarnError(error, {
+                providerName: this.name,
+                operation: ctx.operation,
+                steps: ctx.steps,
+                params: ctx.params,
             });
         }
-        const { txHash, explorerUrl } = await executeEarnAction({
-            adapter,
-            chain,
-            address,
-            actionKey: 'earn.withdraw',
-            actionParams: {
-                executeParams: executionParams,
-                tokenInputs,
-                signature,
-            },
-            revertMessage: 'Earn withdraw reverted on-chain',
-        });
-        return {
-            txHash,
-            explorerUrl,
-            vaultAddress,
-            amount: params.amount,
-        };
     }
     /** {@inheritdoc} */
     async claimRewards(params) {
-        const config = this.resolveConfig(params.config);
-        const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
-        // Claim rewards has no approval step, but still requires adapter support.
-        requireAdapterContract(chain);
-        const { rewards, executionParams, signature } = await fetchClaimRewards({
-            address,
-            chain: apiChain,
-            vaultAddress: params.vaultAddress,
-            config,
-        });
-        const nothingToClaim = rewards.length === 0;
-        if (nothingToClaim) {
-            return { status: 'no_rewards', rewards: [] };
-        }
-        const missingExecutionParams = executionParams === undefined;
-        const missingSignature = signature === undefined;
-        if (missingExecutionParams || missingSignature) {
-            throw new KitError({
-                ...EarnError.INTERNAL_ERROR,
-                recoverability: 'RETRYABLE',
-                message: 'Claim rewards response must include executionParams and signature when rewards are claimable',
-                cause: {
-                    trace: {
-                        rewardsCount: rewards.length,
-                        missingExecutionParams,
-                        missingSignature,
+        return this.runClaimRewardsFlow(params);
+    }
+    async runClaimRewardsFlow(params) {
+        const ctx = {
+            dispatcher: this.actionDispatcher,
+            operation: 'claimRewards',
+            steps: [],
+            params,
+        };
+        try {
+            const config = this.resolveConfig(params.config);
+            const { address, chain: apiChain, chainDefinition: chain, } = await resolveAdapterContext(params.from);
+            // Claim rewards has no approval step, but still requires adapter support.
+            requireAdapterContract(chain);
+            const { rewards, executionParams, signature } = await this.runPhase(ctx, 'claimRewards', 'fetchParams', async () => fetchClaimRewards({
+                address,
+                chain: apiChain,
+                vaultAddress: params.vaultAddress,
+                config,
+            }), () => undefined);
+            const nothingToClaim = rewards.length === 0;
+            if (nothingToClaim) {
+                return { status: 'no_rewards', rewards: [] };
+            }
+            const missingExecutionParams = executionParams === undefined;
+            const missingSignature = signature === undefined;
+            if (missingExecutionParams || missingSignature) {
+                throw new KitError({
+                    ...EarnError.INTERNAL_ERROR,
+                    recoverability: 'RETRYABLE',
+                    message: 'Claim rewards response must include executionParams and signature when rewards are claimable',
+                    cause: {
+                        trace: {
+                            rewardsCount: rewards.length,
+                            missingExecutionParams,
+                            missingSignature,
+                        },
                     },
+                });
+            }
+            validateExecutionDeadline(executionParams);
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'claimRewards', 'execute', async () => executeEarnAction({
+                adapter: params.from.adapter,
+                chain,
+                address,
+                actionKey: 'earn.claimRewards',
+                actionParams: {
+                    executeParams: executionParams,
+                    tokenInputs: [],
+                    signature,
                 },
+                revertMessage: 'Earn claim rewards reverted on-chain',
+            }), ({ txHash }) => txHash);
+            return { status: 'claimed', rewards, txHash, explorerUrl };
+        }
+        catch (error) {
+            throw augmentEarnError(error, {
+                providerName: this.name,
+                operation: ctx.operation,
+                steps: ctx.steps,
+                params: ctx.params,
             });
         }
-        validateExecutionDeadline(executionParams);
-        const { txHash, explorerUrl } = await executeEarnAction({
-            adapter: params.from.adapter,
-            chain,
-            address,
-            actionKey: 'earn.claimRewards',
-            actionParams: {
-                executeParams: executionParams,
-                tokenInputs: [],
-                signature,
-            },
-            revertMessage: 'Earn claim rewards reverted on-chain',
-        });
-        return { status: 'claimed', rewards, txHash, explorerUrl };
+    }
+    /** {@inheritdoc} */
+    supportsRetry(error) {
+        return (isKitError(error) &&
+            isRetryableError$1(error) &&
+            isEarnErrorTrace(error.cause?.trace) &&
+            error.cause.trace.provider === this.name);
+    }
+    /** {@inheritdoc} */
+    async retry(error) {
+        // Validation order mirrors EarnKit.retry().
+        if (!isKitError(error)) {
+            throw createValidationFailedError$1('error', error, 'retry() requires a KitError thrown by a previous earn operation');
+        }
+        if (!isRetryableError$1(error)) {
+            throw createValidationFailedError$1('error.recoverability', error.recoverability, 'retry() requires a retryable or resumable error — check isRetryableError(error) first');
+        }
+        const trace = error.cause?.trace;
+        if (!isEarnErrorTrace(trace)) {
+            throw createValidationFailedError$1('error.cause.trace', trace, 'retry() requires a KitError carrying earn retry context (operation, steps, provider, params)');
+        }
+        if (trace.provider !== this.name) {
+            throw createValidationFailedError$1('error.cause.trace.provider', trace.provider, `Cannot retry: error was produced by provider "${trace.provider}", not "${this.name}"`);
+        }
+        const approveCompleted = trace.steps.some((step) => step.name === 'approve' && step.state === 'success');
+        // `trace` is a discriminated union on `operation`, so each branch narrows
+        // `trace.params` to the matching service-params type — no cast needed.
+        switch (trace.operation) {
+            case 'deposit':
+                return this.runDepositFlow(trace.params, {
+                    skipApprove: approveCompleted,
+                });
+            case 'withdraw':
+                return this.runWithdrawFlow(trace.params, {
+                    skipApprove: approveCompleted,
+                });
+            case 'claimRewards':
+                return this.runClaimRewardsFlow(trace.params);
+            default: {
+                const exhaustive = trace;
+                throw createValidationFailedError$1('error.cause.trace.operation', exhaustive, 'retry() does not support this earn operation');
+            }
+        }
     }
     /** {@inheritdoc} */
     async getDepositQuote(params) {
@@ -31277,54 +31662,6 @@ function createEarnKitContext(config = {}) {
     return context;
 }
 
-/**
- * Symbol used to track that assertEarnParams has validated an object.
- * @internal
- */
-const ASSERT_EARN_PARAMS_SYMBOL = Symbol('assertEarnParams');
-/**
- * Assert that the provided value conforms to the given earn params schema.
- *
- * Validate earn parameters using the provided Zod schema and track
- * validation state to avoid duplicate checks. Throw a structured
- * error with detailed validation messages if any parameter is invalid.
- *
- * @typeParam T - The expected type after validation
- * @param params - The earn parameters to validate
- * @param schema - The Zod schema to validate against
- * @throws {@link KitError} If the parameters fail validation
- *
- * @example
- * ```typescript
- * import { assertEarnParams, depositParamsSchema } from '@circle-fin/earn-kit'
- *
- * assertEarnParams(params, depositParamsSchema)
- * ```
- */
-function assertEarnParams(params, schema) {
-    validateWithStateTracking(params, schema, 'earn parameters', ASSERT_EARN_PARAMS_SYMBOL);
-}
-
-function findProvider(context, chain, operation = 'earn') {
-    let fallback;
-    for (const provider of context.providers) {
-        fallback ??= provider;
-        if (provider.supportedChains.length === 0)
-            continue;
-        if (chain === undefined ||
-            provider.supportedChains.some((c) => c.chain === chain.chain)) {
-            return provider;
-        }
-    }
-    if (fallback === undefined) {
-        throw createValidationFailedError$1('context.providers', [], 'No earn providers configured');
-    }
-    if (chain !== undefined) {
-        throw createUnsupportedEarnRouteError(operation, chain.name);
-    }
-    return fallback;
-}
-
 /**
  * Format a provider amount object as a human-readable decimal string.
  *
@@ -31467,6 +31804,54 @@ function formatClaimRewardsResult(result) {
     };
 }
 
+/**
+ * Symbol used to track that assertEarnParams has validated an object.
+ * @internal
+ */
+const ASSERT_EARN_PARAMS_SYMBOL = Symbol('assertEarnParams');
+/**
+ * Assert that the provided value conforms to the given earn params schema.
+ *
+ * Validate earn parameters using the provided Zod schema and track
+ * validation state to avoid duplicate checks. Throw a structured
+ * error with detailed validation messages if any parameter is invalid.
+ *
+ * @typeParam T - The expected type after validation
+ * @param params - The earn parameters to validate
+ * @param schema - The Zod schema to validate against
+ * @throws {@link KitError} If the parameters fail validation
+ *
+ * @example
+ * ```typescript
+ * import { assertEarnParams, depositParamsSchema } from '@circle-fin/earn-kit'
+ *
+ * assertEarnParams(params, depositParamsSchema)
+ * ```
+ */
+function assertEarnParams(params, schema) {
+    validateWithStateTracking(params, schema, 'earn parameters', ASSERT_EARN_PARAMS_SYMBOL);
+}
+
+function findProvider(context, chain, operation = 'earn') {
+    let fallback;
+    for (const provider of context.providers) {
+        fallback ??= provider;
+        if (provider.supportedChains.length === 0)
+            continue;
+        if (chain === undefined ||
+            provider.supportedChains.some((c) => c.chain === chain.chain)) {
+            return provider;
+        }
+    }
+    if (fallback === undefined) {
+        throw createValidationFailedError$1('context.providers', [], 'No earn providers configured');
+    }
+    if (chain !== undefined) {
+        throw createUnsupportedEarnRouteError(operation, chain.name);
+    }
+    return fallback;
+}
+
 /**
  * Schema for the adapter context within earn operations.
  *
@@ -32116,6 +32501,19 @@ async function getClaimRewardsQuote$1(context, params) {
     return formatClaimRewardsQuoteInfo(result);
 }
 
+function formatRetryResult(operation, result) {
+    switch (operation) {
+        case 'deposit':
+        case 'withdraw':
+            return result;
+        case 'claimRewards':
+            return formatClaimRewardsResult(result);
+        default: {
+            const exhaustive = operation;
+            throw createValidationFailedError$1('error.cause.trace.operation', exhaustive, 'EarnKit.retry() does not support this earn operation');
+        }
+    }
+}
 /**
  * A high-level class-based interface for DeFi lending vault operations.
  *
@@ -32173,6 +32571,12 @@ async function getClaimRewardsQuote$1(context, params) {
  */
 class EarnKit {
     context;
+    /**
+     * Event dispatcher for step-level events emitted during multi-phase earn
+     * operations. Prefer {@link EarnKit.on} / {@link EarnKit.off} over using
+     * this directly.
+     */
+    actionDispatcher;
     /**
      * Create a new EarnKit instance.
      *
@@ -32192,6 +32596,89 @@ class EarnKit {
      */
     constructor(config = {}) {
         this.context = createEarnKitContext(config);
+        this.actionDispatcher = new Actionable();
+        for (const provider of this.context.providers) {
+            provider.registerDispatcher(this.actionDispatcher);
+        }
+    }
+    on(action, handler) {
+        if (action === '*') {
+            this.actionDispatcher.on('*', handler);
+        }
+        else {
+            this.actionDispatcher.on(action, handler);
+        }
+    }
+    off(action, handler) {
+        if (action === '*') {
+            this.actionDispatcher.off('*', handler);
+        }
+        else {
+            this.actionDispatcher.off(action, handler);
+        }
+    }
+    /**
+     * Resume a multi-phase earn operation that previously failed.
+     *
+     * Pass the {@link KitError} caught from a `deposit`, `withdraw`, or
+     * `claimRewards` call. The error carries the original operation, inputs,
+     * and step progress, so the operation can be re-run while skipping phases
+     * that already completed (for example a successful token approval). Use
+     * `isRetryableError(error)` to check whether retrying is worthwhile before
+     * calling this.
+     *
+     * @remarks
+     * Resuming re-fetches execution params and re-submits the `execute`
+     * transaction; the earn service deduplicates execution server-side, which
+     * makes this safe in the common case. But if a prior attempt broadcast the
+     * `execute` transaction and then failed before its receipt was observed,
+     * that transaction may still be in flight when `retry()` re-broadcasts.
+     * Treat `retry()` as best-effort recovery, not an atomic operation.
+     *
+     * @param error - The error caught from a previous multi-phase earn operation.
+     * @returns A promise resolving to the result of the resumed operation.
+     * @throws {@link KitError} If `error` is not a retryable {@link KitError}
+     *   carrying earn retry context, names an unknown provider, or the resumed
+     *   operation itself fails.
+     *
+     * @example
+     * ```typescript
+     * import { isRetryableError } from '@circle-fin/earn-kit'
+     *
+     * try {
+     *   await kit.deposit(params)
+     * } catch (error) {
+     *   if (isRetryableError(error)) {
+     *     const result = await kit.retry(error)
+     *     console.log('recovered, tx:', 'txHash' in result ? result.txHash : undefined)
+     *   }
+     * }
+     * ```
+     */
+    async retry(error) {
+        if (!isKitError(error)) {
+            throw createValidationFailedError$1('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
+        }
+        if (!isRetryableError$1(error)) {
+            throw createValidationFailedError$1('error.recoverability', error.recoverability, 'EarnKit.retry() requires a retryable or resumable error — check isRetryableError(error) first');
+        }
+        const trace = error.cause?.trace;
+        if (!isEarnErrorTrace(trace)) {
+            throw createValidationFailedError$1('error.cause.trace', trace, 'EarnKit.retry() requires a KitError carrying earn retry context (operation, steps, provider, params)');
+        }
+        const provider = this.context.providers.find((candidate) => candidate.name === trace.provider);
+        if (provider === undefined) {
+            throw createValidationFailedError$1('error.cause.trace.provider', trace.provider, `No earn provider named "${trace.provider}" is registered with this kit`);
+        }
+        const result = await provider.retry(error);
+        // `provider.retry` returns a flat result union with no compile-time link to
+        // `trace.operation`, so narrow the operation here to select the matching
+        // overload. The result cast in each branch is sound: the provider always
+        // returns the result type corresponding to the resumed operation.
+        if (trace.operation === 'claimRewards') {
+            return formatRetryResult(trace.operation, result);
+        }
+        return formatRetryResult(trace.operation, result);
     }
     /**
      * Return the chains supported by configured earn providers.
@@ -33534,7 +34021,7 @@ async function getClaimRewardsQuote(context, params) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.1.2";
+var version = "1.1.3";
 var pkg = {
 	name: name,
 	version: version};
@@ -34007,10 +34494,6 @@ async function deposit$1(params) {
     const signerAddress = await resolveSignerAddress(params.from, chain);
     const resolvedContext = { ...operationContext, address: signerAddress };
     await validateDepositBalance(params.from.adapter, chain, valueBigInt, resolvedContext, params.token);
-    await validateNativeBalanceForTransaction({
-        adapter: params.from.adapter,
-        operationContext: { ...resolvedContext, chain },
-    });
     const tokenAddress = getTokenAddress(chain, params.token);
     const strategy = params.allowanceStrategy ?? 'authorize';
     let txHash;
@@ -34055,10 +34538,6 @@ async function depositFor$1(params) {
     const signerAddress = await resolveSignerAddress(params.from, chain);
     const resolvedContext = { ...operationContext, address: signerAddress };
     await validateDepositBalance(params.from.adapter, chain, valueBigInt, resolvedContext, params.token);
-    await validateNativeBalanceForTransaction({
-        adapter: params.from.adapter,
-        operationContext: { ...resolvedContext, chain },
-    });
     const tokenAddress = getTokenAddress(chain, params.token);
     let txHash;
     if (chain.type === 'solana') {
@@ -37342,10 +37821,6 @@ async function updateDelegate(params, action, state) {
     const tokenAddress = getTokenAddress(chain, params.token);
     assertValidAddress(delegateAddress, chain, 'delegate');
     assertNotSelfDelegation(chain, signerAddress, delegateAddress, action);
-    await validateNativeBalanceForTransaction({
-        adapter,
-        operationContext: { ...operationContext, chain, address: signerAddress },
-    });
     const request = await adapter.prepareAction(action, { token: tokenAddress, delegate: delegateAddress, chain }, operationContext);
     const txHash = await executeAndWait(adapter, request, chain);
     return {
@@ -37548,10 +38023,6 @@ async function initiateRemoveFund$1(params) {
     const signerAddress = await resolveSignerAddress(from, chain);
     const tokenAddress = getTokenAddress(chain, params.token);
     const value = parseAmountSafe(amount);
-    await validateNativeBalanceForTransaction({
-        adapter,
-        operationContext: { ...operationContext, chain, address: signerAddress },
-    });
     const request = await adapter.prepareAction('gateway.v1.initiateWithdrawal', { token: tokenAddress, value, chain }, operationContext);
     let txHash;
     try {
@@ -37610,10 +38081,6 @@ async function removeFund$1(params) {
     const operationContext = extractOperationContext(from);
     const signerAddress = await resolveSignerAddress(from, chain);
     const tokenAddress = getTokenAddress(chain, params.token);
-    await validateNativeBalanceForTransaction({
-        adapter,
-        operationContext: { ...operationContext, chain, address: signerAddress },
-    });
     // Read the pending balance before withdrawing — the contract resets it to 0
     // after withdraw() executes, so this is the only way to capture the amount.
     const withdrawingBalanceReq = await adapter.prepareAction('gateway.v1.withdrawingBalance', { token: tokenAddress, depositor: signerAddress, chain }, operationContext);