@circle-fin/app-kit 1.6.0 → 1.7.0

package/earn.mjs

@@ -988,6 +988,151 @@ function createTransactionRevertedError(chain, reason, trace, txHash, explorerUr
     });
 }
 
+/**
+ * Type guard to check if an error is a KitError instance.
+ *
+ * This guard enables TypeScript to narrow the type from `unknown` to
+ * `KitError`, providing access to structured error properties like
+ * code, name, and recoverability.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * import { isKitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isKitError(error)) {
+ *     // TypeScript knows this is KitError
+ *     console.log(`Structured error: ${error.name} (${error.code})`)
+ *   } else {
+ *     console.log('Regular error:', error)
+ *   }
+ * }
+ * ```
+ */
+function isKitError(error) {
+    return error instanceof KitError;
+}
+/**
+ * Error codes that are considered retryable by default.
+ *
+ * @remarks
+ * These are typically transient errors that may succeed on retry:
+ * - Network connectivity issues (3001, 3002)
+ * - Provider unavailability (4001, 4002)
+ * - RPC nonce errors (4003)
+ */
+const DEFAULT_RETRYABLE_ERROR_CODES = [
+    // Network errors
+    3001, // NETWORK_CONNECTION_FAILED
+    3002, // NETWORK_TIMEOUT
+    // Provider errors
+    4001, // PROVIDER_UNAVAILABLE
+    4002, // PROVIDER_TIMEOUT
+    4003, // RPC_NONCE_ERROR
+];
+/**
+ * Checks if an error is retryable.
+ *
+ * @remarks
+ * Check order for KitError instances:
+ * 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`.
+ *
+ * This two-tier approach allows both explicit recoverability control and
+ * backward-compatible code-based retry logic.
+ *
+ * RETRYABLE errors indicate transient failures that may succeed on
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Implement retry logic with exponential backoff
+ *     setTimeout(() => retryOperation(), 5000)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError, createNetworkConnectionError, KitError } from '@core/errors'
+ *
+ * // KitError with RETRYABLE recoverability (priority check)
+ * const error1 = createNetworkConnectionError('Ethereum')
+ * isRetryableError(error1) // true
+ *
+ * // KitError with default retryable code (fallback check)
+ * const error2 = new KitError({
+ *   code: 3002, // NETWORK_TIMEOUT - in DEFAULT_RETRYABLE_ERROR_CODES
+ *   name: 'NETWORK_TIMEOUT',
+ *   type: 'NETWORK',
+ *   recoverability: 'FATAL', // Not RETRYABLE
+ *   message: 'Timeout',
+ * })
+ * isRetryableError(error2) // true (code 3002 is in default list)
+ *
+ * // KitError with non-retryable code and FATAL recoverability
+ * const error3 = new KitError({
+ *   code: 1001,
+ *   name: 'INPUT_NETWORK_MISMATCH',
+ *   type: 'INPUT',
+ *   recoverability: 'FATAL',
+ *   message: 'Invalid input',
+ * })
+ * 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 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. 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
+        return DEFAULT_RETRYABLE_ERROR_CODES.includes(error.code);
+    }
+    return false;
+}
 /**
  * Safely extracts error message from any error type.
  *
@@ -6510,6 +6655,120 @@ function validateOrThrow(value, schema, message) {
     }
 }
 
+/**
+ * A type-safe event emitter for managing action-based event subscriptions.
+ *
+ * Actionable provides a strongly-typed publish/subscribe pattern for events,
+ * where each event (action) has its own specific payload type. Handlers can
+ * subscribe to specific events or use a wildcard to receive all events.
+ *
+ * @typeParam AllActions - A record mapping action names to their payload types.
+ *
+ * @example
+ * ```typescript
+ * import { Actionable } from '@circle-fin/bridge-kit/utils';
+ *
+ * // Define your action types
+ * type TransferActions = {
+ *   started: { txHash: string; amount: string };
+ *   completed: { txHash: string; destinationTxHash: string };
+ *   failed: { error: Error };
+ * };
+ *
+ * // Create an actionable instance
+ * const transferEvents = new Actionable<TransferActions>();
+ *
+ * // Subscribe to a specific event
+ * transferEvents.on('completed', (payload) => {
+ *   console.log(`Transfer completed with hash: ${payload.destinationTxHash}`);
+ * });
+ *
+ * // Subscribe to all events
+ * transferEvents.on('*', (payload) => {
+ *   console.log('Event received:', payload);
+ * });
+ *
+ * // Dispatch an event
+ * transferEvents.dispatch('completed', {
+ *   txHash: '0x123',
+ *   destinationTxHash: '0xabc'
+ * });
+ * ```
+ */
+class Actionable {
+    // Store event handlers by action key
+    handlers = {};
+    // Store wildcard handlers that receive all events
+    wildcard = [];
+    // Implementation that handles both overloads
+    on(action, handler) {
+        if (action === '*') {
+            // Add to wildcard handlers array
+            this.wildcard.push(handler);
+        }
+        else {
+            // Initialize the action's handler array if it doesn't exist
+            if (!this.handlers[action]) {
+                this.handlers[action] = [];
+            }
+            // Add the handler to the specific action's array
+            this.handlers[action].push(handler);
+        }
+    }
+    // Implementation that handles both overloads
+    off(action, handler) {
+        if (action === '*') {
+            // Find and remove the handler from wildcard array
+            const index = this.wildcard.indexOf(handler);
+            if (index !== -1) {
+                this.wildcard.splice(index, 1);
+            }
+        }
+        else if (this.handlers[action]) {
+            // Check if there are handlers for this action
+            // Find and remove the specific handler
+            const index = this.handlers[action].indexOf(handler);
+            if (index !== -1) {
+                this.handlers[action].splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Dispatch an action with its payload to all registered handlers.
+     *
+     * This method notifies both:
+     * - Handlers registered specifically for this action
+     * - Wildcard handlers registered for all actions
+     *
+     * @param action - The action key identifying the event type.
+     * @param payload - The data associated with the action.
+     *
+     * @example
+     * ```typescript
+     * type Actions = {
+     *   transferStarted: { amount: string; destination: string };
+     *   transferComplete: { txHash: string };
+     * };
+     *
+     * const events = new Actionable<Actions>();
+     *
+     * // Dispatch an event
+     * events.dispatch('transferStarted', {
+     *   amount: '100',
+     *   destination: '0xABC123'
+     * });
+     * ```
+     */
+    dispatch(action, payload) {
+        // Execute all handlers registered for this specific action
+        for (const h of this.handlers[action] ?? [])
+            h(payload);
+        // Execute all wildcard handlers
+        for (const h of this.wildcard)
+            h(payload);
+    }
+}
+
 /**
  * Convert a value from its smallest unit representation to a human-readable decimal string.
  *
@@ -7380,7 +7639,7 @@ function resolveKitSdkName(pkgName) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.10.1";
+var version$2 = "1.10.2";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -8293,7 +8552,7 @@ resolveKitSdkName(pkg$2.name);
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.2.2";
+var version$1 = "1.2.3";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -11770,7 +12029,7 @@ resolveKitSdkName(pkg$1.name);
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.0.0";
+var version = "1.1.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -12180,6 +12439,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
 // ---------------------------------------------------------------------------
@@ -13167,12 +13673,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
@@ -13203,6 +13760,8 @@ class EarnServiceProvider {
     name = 'EarnService';
     /** {@inheritdoc} */
     supportedChains = Object.keys(CHAIN_TO_API).map((chain) => resolveChainIdentifier(chain));
+    /** {@inheritdoc} */
+    actionDispatcher = undefined;
     defaultConfig;
     /**
      * Create a new EarnServiceProvider.
@@ -13213,12 +13772,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);
@@ -13240,146 +13836,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('error', error, 'retry() requires a KitError thrown by a previous earn operation');
+        }
+        if (!isRetryableError$1(error)) {
+            throw createValidationFailedError('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('error.cause.trace', trace, 'retry() requires a KitError carrying earn retry context (operation, steps, provider, params)');
+        }
+        if (trace.provider !== this.name) {
+            throw createValidationFailedError('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('error.cause.trace.operation', exhaustive, 'retry() does not support this earn operation');
+            }
+        }
     }
     /** {@inheritdoc} */
     async getDepositQuote(params) {
@@ -13463,54 +14159,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('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.
  *
@@ -13653,6 +14301,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('context.providers', [], 'No earn providers configured');
+    }
+    if (chain !== undefined) {
+        throw createUnsupportedEarnRouteError(operation, chain.name);
+    }
+    return fallback;
+}
+
 /**
  * Schema for the adapter context within earn operations.
  *
@@ -14302,6 +14998,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('error.cause.trace.operation', exhaustive, 'EarnKit.retry() does not support this earn operation');
+        }
+    }
+}
 /**
  * A high-level class-based interface for DeFi lending vault operations.
  *
@@ -14359,6 +15068,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.
      *
@@ -14378,6 +15093,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('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
+        }
+        if (!isRetryableError$1(error)) {
+            throw createValidationFailedError('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('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('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.