@circle-fin/app-kit 1.9.0 → 1.10.0

package/earn.mjs

@@ -18,6 +18,9 @@
 
 import { z } from 'zod';
 import 'pino';
+import '@ethersproject/bytes';
+import '@ethersproject/abi';
+import '@ethersproject/address';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
@@ -1759,14 +1762,14 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error definitions for Earn/Zenith operations.
+ * Standardized error definitions for Earn operations.
  *
  * These error codes provide fine-grained categorization of failures
- * from the Zenith earn service, enabling SDK consumers to distinguish
+ * from the Earn service, enabling SDK consumers to distinguish
  * between input errors (fix your request) and service errors (retry later).
  *
  * Error code ranges:
- * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
+ * - 1100-1106: INPUT errors — invalid, unsupported, or stale request state
  * - 8100-8105: SERVICE errors — retryable backend/provider failures
  *
  * @example
@@ -1819,6 +1822,14 @@ class KitError extends Error {
         name: 'EARN_UNSUPPORTED_BRIDGE_ROUTE',
         type: 'INPUT'
     },
+    /**
+   * The bridge quote expired. This is an INPUT error because the prepared
+   * request is stale and must be replaced instead of retried.
+   */ BRIDGE_QUOTE_EXPIRED: {
+        code: 1106,
+        name: 'EARN_BRIDGE_QUOTE_EXPIRED',
+        type: 'INPUT'
+    },
     /** The proxy signing call failed — retryable. */ SIGNING_FAILED: {
         code: 8100,
         name: 'EARN_SIGNING_FAILED',
@@ -1878,6 +1889,9 @@ function getOptionalString(value) {
  *   internal-error, vault-refresh-busy, off-chain-paused, position-PnL-pending,
  *   bridge failures/status lookup failures
  *
+ * Quote expiry is INPUT/FATAL because callers must start a fresh bridge prepare
+ * flow rather than retry the stale prepared bundle.
+ *
  * Unrecognized codes fall through to `parseApiError` for HTTP-status-based
  * handling.
  *
@@ -2111,6 +2125,13 @@ function getOptionalString(value) {
             errorDef: EarnError.PROVIDER_ERROR,
             recoverability: 'FATAL'
         }
+    ],
+    [
+        380506,
+        {
+            errorDef: EarnError.BRIDGE_QUOTE_EXPIRED,
+            recoverability: 'FATAL'
+        }
     ]
 ]);
 /**
@@ -2834,7 +2855,10 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
+                // deposit into the GatewayWallet above.
+                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
             }
         },
         forwarderSupported: {
@@ -5902,7 +5926,10 @@ var Chains = /*#__PURE__*/Object.freeze({
     minter: z.string({
         required_error: 'Gateway minter address is required. Please provide a valid contract address.',
         invalid_type_error: 'Gateway minter address must be a string.'
-    }).min(1, 'Gateway minter address cannot be empty.')
+    }).min(1, 'Gateway minter address cannot be empty.'),
+    depositForHandler: z.string({
+        invalid_type_error: 'Gateway depositForHandler address must be a string.'
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -8014,6 +8041,13 @@ const swapTokenEnumSchema = z.enum([
     return explorerUrl;
 }
 
+/**
+ * CCTP forwarding magic bytes prefix.
+ *
+ * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
+ * This prefix is right-padded to 24 bytes in the final hookData.
+ */ const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
+
 /**
  * Strip the `@circle-fin/` scope from a kit package name to produce the
  * short SDK name used in telemetry payloads.
@@ -8033,7 +8067,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$3 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.0";
+var version$3 = "1.12.1";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -8858,6 +8892,11 @@ var TransferSpeed;
     clock: z.any().optional()
 }).passthrough();
 
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ */ Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -8890,7 +8929,7 @@ var TransferSpeed;
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
 var name$2 = "@circle-fin/swap-kit";
-var version$2 = "1.3.2";
+var version$2 = "1.4.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -8955,7 +8994,10 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     }).min(1, 'kitKey must be a non-empty string').optional(),
     provider: z.string({
         invalid_type_error: 'provider must be a string'
-    }).min(1, 'provider must be a non-empty string').optional()
+    }).min(1, 'provider must be a non-empty string').optional(),
+    batchTransactions: z.boolean({
+        invalid_type_error: 'batchTransactions must be a boolean'
+    }).optional()
 });
 /**
  * Zod schema for adapter context.
@@ -9394,7 +9436,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
      * Circle Stablecoin Service API Key.
      * Must be a valid API key format.
-     */ apiKey: apiKeySchema
+     */ apiKey: apiKeySchema.optional()
 }).superRefine(requireCrossChainQuoteToAddress);
 /**
  * Zod schema for validating CreateSwapRequest parameters.
@@ -9452,7 +9494,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
    * Circle Stablecoin Service API Key.
    * Must be a valid API key format.
-   */ apiKey: apiKeySchema
+   */ apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetSwapStatusResponse data.
@@ -9488,7 +9530,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     toChain: z.string({
         invalid_type_error: 'toChain must be a string'
     }).min(1, 'toChain must be a non-empty string if provided').optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating CreateSwapResponse payloads.
@@ -9497,13 +9539,15 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'fee token is required',
         invalid_type_error: 'fee token must be a string'
     }).min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema
+    amount: feeAmountSchema,
+    decimals: z.number().int('fee token decimals must be an integer').nonnegative('fee token decimals must be a non-negative integer').optional(),
+    symbol: z.string({
+        invalid_type_error: 'fee token symbol must be a string'
+    }).min(1, 'fee token symbol must be a non-empty string').optional()
 });
 /**
  * Developer fee item schema with basis field.
- */ const createSwapDeveloperFeeItemSchema = z.object({
-    token: z.string().min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema,
+ */ const createSwapDeveloperFeeItemSchema = createSwapFeeItemSchema.extend({
     basis: z.enum([
         'inputAmount',
         'estimatedAmount'
@@ -9595,7 +9639,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     addresses: z.array(z.string({
         invalid_type_error: 'addresses entries must be strings'
     }).min(1, 'addresses entries must be non-empty strings')).min(1, 'addresses must contain at least one entry when provided').max(MAX_RATE_ADDRESSES_PER_REQUEST, `addresses supports at most ${String(MAX_RATE_ADDRESSES_PER_REQUEST)} values per request`).optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetTokenRatesResponse payloads.
@@ -12184,7 +12228,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.2.2";
+var version$1 = "1.3.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -12651,7 +12695,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @param params - Adapter, chain, token/delegate/wallet addresses, the required
  *   allowance for the signed payload, and a revert message for on-chain failure.
- * @returns The approval transaction hash when an approval was submitted, or
+ * @returns The approval transaction result when an approval was submitted, or
  *   `undefined` when the existing allowance already covers `requiredAllowance`
  *   (or `requiredAllowance` is zero).
  * @throws {@link KitError} If the `token.allowance` response is malformed.
@@ -12659,7 +12703,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @example
  * ```typescript
- * const txHash = await approveAllowanceIfNeeded({
+ * const approval = await approveAllowanceIfNeeded({
  *   adapter,
  *   chain,
  *   tokenAddress: usdcAddress,
@@ -12721,7 +12765,15 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
         maxAttempts: params.allowancePropagation?.maxAttempts ?? DEFAULT_PROPAGATION_ATTEMPTS,
         delayMs: params.allowancePropagation?.delayMs ?? DEFAULT_PROPAGATION_DELAY_MS
     });
-    return approvalTxHash;
+    return {
+        txHash: approvalTxHash,
+        ...approvalReceipt.gasUsed !== undefined && {
+            gasUsed: approvalReceipt.gasUsed
+        },
+        ...approvalReceipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: approvalReceipt.effectiveGasPrice
+        }
+    };
 }
 
 /** @internal */ function isSameAddress(actual, expected) {
@@ -12869,7 +12921,13 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     }
     return {
         txHash,
-        explorerUrl
+        explorerUrl,
+        ...receipt.gasUsed !== undefined && {
+            gasUsed: receipt.gasUsed
+        },
+        ...receipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: receipt.effectiveGasPrice
+        }
     };
 }
 
@@ -13181,112 +13239,6 @@ const EARN_OPERATIONS = new Set([
     return hasEarnServiceParamsShape(operation, candidate['params']);
 }
 
-function buildGasFeeBase(name, chain) {
-    return {
-        name,
-        token: chain.nativeCurrency.symbol,
-        blockchain: chain.chain
-    };
-}
-function buildGasFeeSuccess(name, chain, fees) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees
-    };
-}
-function buildGasFeeFailure(name, chain, error) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees: null,
-        error: getErrorMessage(error)
-    };
-}
-async function estimatePreparedGasFee(name, chain, prepared) {
-    try {
-        const estimate = bufferEstimatedGas(await prepared.estimate());
-        if (estimate.gas <= 0n) {
-            throw createValidationFailedError('estimate.gas', estimate.gas.toString(), 'gas estimate must be greater than zero');
-        }
-        return buildGasFeeSuccess(name, chain, estimate);
-    } catch (error) {
-        return buildGasFeeFailure(name, chain, error);
-    }
-}
-async function estimateApprovalGasFeeIfNeeded(params) {
-    const { adapter, chain, address, tokenAddress, delegate, requiredAllowance } = params;
-    if (requiredAllowance <= 0n) {
-        return undefined;
-    }
-    try {
-        const allowancePrepared = await adapter.prepareAction('token.allowance', {
-            tokenAddress,
-            delegate
-        }, {
-            chain,
-            address
-        });
-        const allowanceRaw = await allowancePrepared.execute();
-        const currentAllowance = parseAllowanceResponse(allowanceRaw);
-        if (currentAllowance >= requiredAllowance) {
-            return undefined;
-        }
-        // Reuse the execute path's approval builder so the estimate simulates the
-        // exact approval (action, amount, and WARM_SLOT_RESIDUAL) that
-        // approveAllowanceIfNeeded later submits.
-        const approvalPrepared = await prepareApprovalAction({
-            adapter,
-            chain,
-            address,
-            tokenAddress,
-            delegate,
-            currentAllowance,
-            requiredAllowance
-        });
-        return await estimatePreparedGasFee('Approve', chain, approvalPrepared);
-    } catch (error) {
-        return buildGasFeeFailure('Approve', chain, error);
-    }
-}
-/**
- * Estimate gas fee entries for an earn quote without submitting transactions.
- *
- * Each entry is produced by simulating the prepared transaction against
- * current chain state. When an approval is required (allowance below the
- * signed payload's required amount), the subsequent action simulation runs
- * without that approval in place and is expected to revert — the action entry
- * then carries `fees: null` with the revert message while the approval entry
- * still estimates normally. Quote consumers must treat that as "estimate
- * pending approval", not a hard failure.
- *
- * @internal
- */ async function estimateEarnQuoteGasFees(params) {
-    const { adapter, chain, address, actionName, actionKey, actionParams, approval } = params;
-    const gasFees = [];
-    if (approval !== undefined) {
-        const approvalEstimate = await estimateApprovalGasFeeIfNeeded({
-            adapter,
-            chain,
-            address,
-            tokenAddress: approval.token,
-            delegate: approval.delegate,
-            requiredAllowance: approval.requiredAllowance
-        });
-        if (approvalEstimate !== undefined) {
-            gasFees.push(approvalEstimate);
-        }
-    }
-    try {
-        const actionPrepared = await adapter.prepareAction(actionKey, actionParams, {
-            chain,
-            address
-        });
-        gasFees.push(await estimatePreparedGasFee(actionName, chain, actionPrepared));
-    } catch (error) {
-        gasFees.push(buildGasFeeFailure(actionName, chain, error));
-    }
-    return gasFees;
-}
-
 // ---------------------------------------------------------------------------
 // Shared primitives
 // ---------------------------------------------------------------------------
@@ -13364,7 +13316,11 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     asset: z.string(),
     assetAddress: z.string(),
     lltv: z.number(),
-    supplyUsd: z.number()
+    supplyUsd: z.number(),
+    // Optional during the expand/contract window (a backend that predates the
+    // field omits the key), mirroring the `.optional()` facets on the base
+    // schema; `null` when the product exposes no per-market allocation (V2).
+    allocationPct: z.number().nullable().optional()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -13378,7 +13334,74 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     ])
 });
 /**
- * Zod schema for a single vault info object in the API response.
+ * Zod schema for the manager (curator) facet in the API response.
+ *
+ * @internal
+ */ const managerSchema = z.object({
+    name: z.string(),
+    address: z.string().optional(),
+    // Only 'curator' is emitted today (Morpho V1/V2). Additional manager roles
+    // are added here as the providers that emit them land, rather than shipped
+    // speculatively.
+    type: z.enum([
+        'curator'
+    ])
+});
+/**
+ * Zod schema for the APY profile facet in the API response.
+ *
+ * @internal
+ */ const apyProfileSchema = z.object({
+    current: z.number(),
+    native: z.number().nullable(),
+    d7: z.number().nullable(),
+    d30: z.number().nullable(),
+    d90: z.number().nullable(),
+    rewardShare: z.number().nullable(),
+    source: z.string().optional(),
+    asOf: z.string().optional()
+});
+/**
+ * Zod schema for the fee split facet in the API response.
+ *
+ * @internal
+ */ const feeInfoSchema = z.object({
+    performance: z.number().nullable(),
+    management: z.number().nullable()
+});
+/**
+ * Zod schema for the liquidity profile facet in the API response.
+ *
+ * `totalSupply` is the outstanding vault share tokens (ERC4626 totalSupply);
+ * it is validated as a raw JSON amount, like `totalDeposits`/`available`.
+ *
+ * @internal
+ */ const liquidityProfileSchema = z.object({
+    totalDeposits: amountJsonSchema,
+    available: amountJsonSchema,
+    totalSupply: amountJsonSchema,
+    status: z.enum([
+        'active',
+        'low_liquidity'
+    ])
+});
+/**
+ * Zod schema for the risk signals facet in the API response.
+ *
+ * @internal
+ */ const riskSignalsSchema = z.object({
+    circleSentinel: z.boolean(),
+    warnings: z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: z.array(z.string()).optional()
+});
+/**
+ * Zod schema for the universal earn-opportunity base in the API response.
+ *
+ * Retains every existing deprecated flat field (kept validated through the
+ * expand/contract window so default-strip does not drop them) and adds the
+ * new nested facets. The nested facets are `.optional()` during the
+ * transition so the SDK still validates against a not-yet-fully-deployed
+ * backend; they become required after Expand ships.
  *
  * @internal
  */ const vaultInfoResponseSchema = z.object({
@@ -13403,6 +13426,96 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     warnings: z.array(vaultWarningSchema).optional(),
     earnKitWarnings: z.array(z.string()).optional()
 });
+/**
+ * Shared base schema: existing flat fields (kept) plus the new nested
+ * facets and neutral identity. Facets are `.optional()` during the
+ * transition; flip to required once the backend is confirmed emitting.
+ *
+ * @internal
+ */ const earnBaseSchema = vaultInfoResponseSchema.extend({
+    address: z.string().optional(),
+    asOf: z.string().optional(),
+    manager: managerSchema.nullable().optional(),
+    apyProfile: apyProfileSchema.optional(),
+    fee: feeInfoSchema.optional(),
+    liquidityProfile: liquidityProfileSchema.optional(),
+    riskSignals: riskSignalsSchema.optional()
+});
+/**
+ * Zod schema for the `vault` opportunity variant.
+ *
+ * @internal
+ */ const vaultOpportunitySchema = earnBaseSchema.extend({
+    productType: z.literal('vault'),
+    collateral: z.array(collateralSchema)
+});
+/**
+ * Discriminated union over `productType`. Add union members here as new
+ * product types (e.g. `lending_market`, `rwa_token`) land.
+ *
+ * @internal
+ */ const earnOpportunityVariants = [
+    vaultOpportunitySchema
+];
+/** @internal */ const earnOpportunitySchema = z.discriminatedUnion('productType', earnOpportunityVariants);
+/** Product types this SDK version knows how to parse. */ const knownProductTypes = new Set(earnOpportunityVariants.map((variant)=>variant.shape.productType.value));
+/**
+ * Tolerant list parser for earn opportunities.
+ *
+ * `z.discriminatedUnion` throws on an unrecognized discriminant and
+ * `z.array` fails the whole array if any element fails. Two migration-window
+ * cases are smoothed over here so neither breaks an already-shipped SDK:
+ *
+ * - A backend that predates `productType` omits it entirely. `'vault'` was the
+ *   only opportunity type then, so default a missing discriminant to `'vault'`
+ *   rather than dropping every vault the backend returns.
+ * - A future backend adds a *second* `productType` this SDK version does not
+ *   know. Drop those elements (a present-but-unrecognized discriminant) instead
+ *   of rejecting the whole list.
+ *
+ * Only the drop above is a *tolerant* case. Anything that is not a plain object
+ * with a present-but-unknown string `productType` — `null`, `undefined`,
+ * primitives, or an object whose `productType` is malformed — is passed through
+ * untouched so `z.array(earnOpportunitySchema)` reports it as a normal
+ * validation failure. It is deliberately not silently dropped (which would hide
+ * malformed backend data) and never throws here (an unguarded property read on
+ * a non-object would escape `safeParse` as a raw `TypeError` instead of a
+ * `ZodError`).
+ *
+ * @internal
+ */ const earnOpportunityListSchema = z.preprocess((raw)=>{
+    if (!Array.isArray(raw)) {
+        return raw;
+    }
+    // Array.isArray narrows `raw` to `any[]`; view it as `unknown[]` so the
+    // map/filter chain stays type-safe and no `any` leaks into the return.
+    const entries = raw;
+    return entries.map((entry)=>{
+        // Only touch plain objects; non-objects fall through to fail validation.
+        if (typeof entry !== 'object' || entry === null) {
+            return entry;
+        }
+        const record = entry;
+        // Older backend predating productType: default to the only type then.
+        return record.productType === undefined ? {
+            ...record,
+            productType: 'vault'
+        } : record;
+    }).filter((entry)=>{
+        // Drop ONLY a present-but-unknown string discriminant (a future
+        // productType this SDK version doesn't know). Everything else —
+        // non-objects, a non-string productType — flows through to
+        // z.array(earnOpportunitySchema) and fails/passes validation normally.
+        if (typeof entry !== 'object' || entry === null) {
+            return true;
+        }
+        const productType = entry.productType;
+        if (typeof productType !== 'string') {
+            return true;
+        }
+        return knownProductTypes.has(productType);
+    });
+}, z.array(earnOpportunitySchema));
 // ---------------------------------------------------------------------------
 // Position response schema
 // ---------------------------------------------------------------------------
@@ -13532,6 +13645,7 @@ const positionPnlSchema = z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -13623,6 +13737,21 @@ const bridgeDepositPrepareReviewSchema = z.object({
     amount: amountJsonSchema,
     vaultAddress: hexAddressSchema
 }).passthrough();
+/** @internal */ const bridgeQuoteExpirySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expiresAt: z.string().datetime({
+            offset: true
+        })
+    }),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: z.number().int(),
+        blockEstimatedAt: z.string().datetime({
+            offset: true
+        }).optional()
+    })
+]).optional().catch(undefined);
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -13634,6 +13763,10 @@ const bridgeDepositPrepareReviewSchema = z.object({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: z.string().datetime(),
+    quoteIssuedAt: z.string().datetime({
+        offset: true
+    }).optional().catch(undefined),
+    quoteExpiry: bridgeQuoteExpirySchema,
     review: bridgeDepositPrepareReviewSchema
 });
 /**
@@ -13699,6 +13832,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -13712,6 +13846,27 @@ const bridgeDepositPrepareReviewSchema = z.object({
     data: withdrawPayloadSchema
 });
 // ---------------------------------------------------------------------------
+// Transaction report response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the transaction report payload inside the API `data` envelope.
+ *
+ * The Earn Service returns an empty payload (`{"data":{}}`) on success, so the
+ * schema accepts any object shape and does not require specific fields.
+ *
+ * @internal
+ */ const transactionReportPayloadSchema = z.object({}).passthrough();
+/**
+ * Zod schema for the `POST /v1/earnKit/transactions/report` API response.
+ *
+ * The Earn Service API wraps the transaction report payload in a `data`
+ * envelope.
+ *
+ * @internal
+ */ const transactionReportResponseSchema = z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -13772,6 +13927,30 @@ const bridgeDepositPrepareReviewSchema = z.object({
     token: z.string(),
     amount: amountJsonSchema
 });
+/**
+ * Zod schema for a native gas-fee entry in an EarnKit quote response.
+ *
+ * The Earn Service backend estimates gas server-side and returns one entry per
+ * action (`Approve`, `Deposit`, `Withdraw`). A successful estimate carries
+ * `fees` in the SDK `EstimatedGas` shape (`{ gas, gasPrice, fee }`), each a raw
+ * integer string in the chain's native base units. When the backend cannot
+ * estimate an action it returns `fees: null` with an `error` message instead.
+ *
+ * The schema deliberately validates almost nothing beyond the envelope: `name`
+ * is optional and `fees` is entirely unvalidated (`unknown`). ALL validation
+ * of `fees` — that it is an object at all, and that `gas`, `gasPrice`, and
+ * `fee` are parseable integer strings — is deferred to {@link toQuoteGasFees},
+ * which degrades a malformed entry to a `fees: null` soft failure. This is
+ * intentional: gas is best-effort, so a single unparseable gas entry (a wrong
+ * type such as `fees: 123` or `fees: 'bad'`, a missing field, or a non-numeric
+ * `fee`) must never fail Zod validation and reject the entire quote.
+ *
+ * @internal
+ */ const quoteGasFeeSchema = z.object({
+    name: z.string().optional(),
+    fees: z.unknown(),
+    error: z.string().optional()
+}).passthrough();
 /**
  * Zod schema for the inner deposit quote payload.
  *
@@ -13787,7 +13966,8 @@ const bridgeDepositPrepareReviewSchema = z.object({
     expectedShares: amountJsonSchema,
     sharePrice: z.string(),
     currentApy: z.number(),
-    fees: z.array(feeSchema).optional()
+    fees: z.array(feeSchema).optional(),
+    gasFees: z.array(quoteGasFeeSchema).optional()
 });
 /**
  * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
@@ -13814,6 +13994,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
     sharePrice: z.string(),
     maxWithdrawable: amountJsonSchema,
     fees: z.array(feeSchema),
+    gasFees: z.array(quoteGasFeeSchema).optional(),
     warnings: z.array(z.string()).optional()
 });
 /**
@@ -13871,7 +14052,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: z.array(vaultErrorSchema)
 });
 /**
@@ -13901,7 +14082,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**
@@ -13994,6 +14175,16 @@ const bridgeDepositPrepareReviewSchema = z.object({
  */ function isWithdrawResponse(value) {
     return withdrawResponseSchema.safeParse(value).success;
 }
+/**
+ * Type guard for the transaction report API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the transaction report response shape
+ *
+ * @internal
+ */ function isTransactionReportResponse(value) {
+    return transactionReportResponseSchema.safeParse(value).success;
+}
 /**
  * Type guard for the claim rewards API response.
  *
@@ -14036,7 +14227,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.2.2";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -14156,7 +14347,7 @@ var pkg = {
 }
 
 /**
- * Convert an API vault info object into the SDK {@link VaultInfo} shape.
+ * Convert an API vault info object into the SDK {@link EarnOpportunity} shape.
  *
  * Map the API chain code back to the SDK chain identifier and hydrate the
  * amount payloads into {@link Amount} instances.
@@ -14167,16 +14358,29 @@ var pkg = {
  *
  * @internal
  */ function toVaultInfo(data) {
-    const { totalDeposits, liquidity, ...vault } = data;
+    const { totalDeposits, liquidity, liquidityProfile, ...vault } = data;
     const chain = toSdkChain(vault.chain);
     if (chain === undefined) {
         throw createInvalidChainError(vault.chain, 'Chain returned by the Earn Service is not supported by the SDK');
     }
+    // The nested facets are `.optional()` in the schema (a backend that predates
+    // them omits them) and are typed optional on `EarnOpportunity` to match.
+    // Convert the nested liquidity amounts when present and pass the remaining
+    // facets straight through; each absent facet stays absent rather than being
+    // asserted present by a cast.
     return {
         ...vault,
         chain,
         totalDeposits: Amount.fromJSON(totalDeposits),
-        liquidity: Amount.fromJSON(liquidity)
+        liquidity: Amount.fromJSON(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: Amount.fromJSON(liquidityProfile.totalDeposits),
+                available: Amount.fromJSON(liquidityProfile.available),
+                totalSupply: Amount.fromJSON(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 
@@ -14211,8 +14415,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isGetVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             errors: response.data.errors.map(toVaultError)
         };
     } catch (error) {
@@ -14261,8 +14468,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isExploreVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             pagination: response.data.pagination
         };
     } catch (error) {
@@ -14426,6 +14636,12 @@ function toPositionInfo(data) {
             execId: response.data.execId,
             preparedBundle,
             expiresAt: response.data.expiresAt,
+            ...response.data.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: response.data.quoteIssuedAt
+            },
+            ...response.data.quoteExpiry !== undefined && {
+                quoteExpiry: response.data.quoteExpiry
+            },
             review: response.data.review
         };
     } catch (error) {
@@ -14767,7 +14983,110 @@ function toClaimedAmount(reward) {
     }
 }
 
-function toDepositQuoteInfo(data) {
+/**
+ * Map the Earn Service's server-side quote gas estimates into the SDK
+ * {@link EarnGasFeeEstimate} shape.
+ *
+ * The Earn Service estimates gas for each action (`Approve`, `Deposit`,
+ * `Withdraw`) and returns `{ name, fees: { gas, gasPrice, fee } }` with raw
+ * integer strings.
+ * The SDK type additionally carries `token` (the chain's native currency
+ * symbol) and `blockchain`, which are filled in here from the chain
+ * definition.
+ *
+ * Gas reporting is best-effort: a malformed entry (e.g. a non-integer string
+ * that fails `BigInt` parsing) degrades to a `{ fees: null, error }` estimate
+ * rather than throwing, so one bad entry never fails the whole quote.
+ *
+ * @param gasFees - Backend gas-fee entries from the quote response, if any.
+ * @param chain - Chain definition, used for the native token symbol and
+ *   blockchain identifier.
+ * @returns One {@link EarnGasFeeEstimate} per backend entry (empty when the
+ *   backend returned none).
+ *
+ * @example
+ * ```typescript
+ * toQuoteGasFees(
+ *   [{ name: 'Deposit', fees: { gas: '364142', gasPrice: '21000000000', fee: '7646982000000000' } }],
+ *   arcTestnet,
+ * )
+ * // [{ name: 'Deposit', token: 'USDC', blockchain: 'Arc_Testnet',
+ * //    fees: { gas: 364142n, gasPrice: 21000000000n, fee: '7646982000000000' } }]
+ * ```
+ *
+ * @internal
+ */ function toQuoteGasFees(gasFees, chain) {
+    if (gasFees === undefined) {
+        return [];
+    }
+    return gasFees.map((entry)=>{
+        const base = {
+            // `name` is optional on the wire; label an unnamed entry rather than
+            // emitting `name: undefined`.
+            name: entry.name ?? 'Unknown',
+            token: chain.nativeCurrency.symbol,
+            blockchain: chain.chain
+        };
+        // The Earn Service itself reports a failed estimate as `fees: null` with
+        // an error; propagate that soft failure verbatim.
+        if (entry.fees === null || entry.fees === undefined) {
+            return {
+                ...base,
+                fees: null,
+                error: entry.error ?? 'gas estimate unavailable'
+            };
+        }
+        // `fees` is `unknown` at the schema layer, so ALL validation happens here:
+        // that it is an object at all, and that `gas`, `gasPrice`, and `fee` are
+        // each parseable integer strings (including `fee`, which the SDK contract
+        // requires be a numeric base-unit string). Any failure — a wrong type
+        // (`fees: 123`), a missing field, or a non-numeric value — degrades the
+        // whole entry to a `fees: null` soft failure rather than surfacing a
+        // malformed "successful" estimate or rejecting the quote.
+        try {
+            if (typeof entry.fees !== 'object') {
+                throw new TypeError(`gas fees must be an object (got ${typeof entry.fees})`);
+            }
+            const { gas, gasPrice, fee } = entry.fees;
+            return {
+                ...base,
+                fees: {
+                    gas: toBigInt('gas', gas),
+                    gasPrice: toBigInt('gasPrice', gasPrice),
+                    fee: toBigInt('fee', fee).toString()
+                }
+            };
+        } catch (error) {
+            return {
+                ...base,
+                fees: null,
+                error: getErrorMessage(error)
+            };
+        }
+    });
+}
+/**
+ * Parse an unknown value into a `bigint`, rejecting anything that is not a
+ * non-empty integer string. `BigInt` alone is too permissive for this path —
+ * it accepts numbers, booleans, and empty strings — so guard the type first.
+ *
+ * @param field - Field name, used in the thrown error message.
+ * @param value - Raw value from the backend gas entry.
+ * @returns The parsed `bigint`.
+ * @throws {TypeError} When `value` is not a non-empty integer string.
+ */ function toBigInt(field, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`gas fee field "${field}" must be an integer string`);
+    }
+    try {
+        // BigInt throws on non-integer strings (e.g. "1.5", "not-a-number").
+        return BigInt(value);
+    } catch  {
+        throw new Error(`gas fee field "${field}" is not a valid integer string: ${value}`);
+    }
+}
+
+function toDepositQuoteInfo(data, chain) {
     const fees = (data.fees ?? []).map(({ token: feeTokenSymbol, ...fee })=>{
         // Earn Service returns fee.token as a display symbol, for example "USDC".
         return {
@@ -14796,7 +15115,10 @@ function toDepositQuoteInfo(data) {
         sharePrice: data.sharePrice,
         currentApy: data.currentApy,
         fees,
-        gasFees: []
+        // The Earn Service estimates gas server-side; the chain fills token/blockchain.
+        // Cross-chain quotes resolve no local chain definition, so gasFees stays
+        // empty there (unchanged behavior).
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain)
     };
 }
 /**
@@ -14831,7 +15153,7 @@ function toDepositQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isDepositQuoteResponse, pollingConfig);
-        return toDepositQuoteInfo(response.data);
+        return toDepositQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getDepositQuote'
@@ -14839,7 +15161,7 @@ function toDepositQuoteInfo(data) {
     }
 }
 
-function toWithdrawalQuoteInfo(data) {
+function toWithdrawalQuoteInfo(data, chain) {
     return {
         vaultAddress: data.vaultAddress,
         vaultName: data.vaultName,
@@ -14867,7 +15189,7 @@ function toWithdrawalQuoteInfo(data) {
                     status
                 }
             })),
-        gasFees: [],
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain),
         // Wire format uses `warnings`, but the SDK surface uses
         // `earnKitWarnings` to match the precedent set by `VaultInfo` —
         // `warnings` is reserved for the structured `VaultWarning` shape.
@@ -14899,7 +15221,7 @@ function toWithdrawalQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isWithdrawalQuoteResponse, pollingConfig);
-        return toWithdrawalQuoteInfo(response.data);
+        return toWithdrawalQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getWithdrawalQuote'
@@ -14935,6 +15257,8 @@ function toWithdrawalQuoteInfo(data) {
                     amount: Amount.fromJSON(r.amount),
                     address: r.token
                 })),
+            // The claimRewards/quote response does not carry a gas estimate (unlike
+            // deposit/withdrawal quotes), so there is nothing to surface here.
             gasFees: []
         };
     } catch (error) {
@@ -14944,6 +15268,83 @@ function toWithdrawalQuoteInfo(data) {
     }
 }
 
+/**
+ * Build the native gas triple the backend expects for `gasUsed`.
+ *
+ * Returns `undefined` unless both receipt components are present, so the
+ * caller can omit the field entirely — the Earn Service treats a missing
+ * triple as "skip the gas cache write, still return 200".
+ *
+ * @param gasUsed - Receipt gas units used.
+ * @param effectiveGasPrice - Receipt effective gas price.
+ * @returns The `{ gas, gasPrice, fee }` triple, or `undefined` when either
+ *   component is missing.
+ *
+ * @example
+ * ```typescript
+ * buildReportedGasUsed(362454n, 29466364605n)
+ * // { gas: '362454', gasPrice: '29466364605', fee: '10680201716540670' }
+ * ```
+ *
+ * @internal
+ */ function buildReportedGasUsed(gasUsed, effectiveGasPrice) {
+    if (gasUsed === undefined || effectiveGasPrice === undefined) {
+        return undefined;
+    }
+    return {
+        gas: gasUsed.toString(),
+        gasPrice: effectiveGasPrice.toString(),
+        fee: (gasUsed * effectiveGasPrice).toString()
+    };
+}
+/**
+ * Report the outcome of an SDK-submitted same-chain Earn transaction.
+ *
+ * @param params - Transaction report parameters.
+ * @throws {@link KitError} When the API call fails.
+ *
+ * @internal
+ */ async function reportEarnTransaction(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/transactions/report`, baseUrl);
+    // The report endpoint is not idempotent: success reports refresh the gas
+    // cache and failure reports increment counts. If the first request succeeds
+    // server-side but the client times out or sees a transient 5xx, retrying
+    // would duplicate the report (double-writing an outcome or inflating failure
+    // counts). Reporting is best-effort (see the fire-and-forget caller), so
+    // make exactly one attempt and never retry — a single dropped report is
+    // preferable to a duplicated one. `maxRetries` here is the total attempt
+    // count in pollApiWithValidation (loop runs `attempt <= maxRetries`), so 1
+    // means one request with no retry; 0 would skip the request entirely.
+    const reportConfig = {
+        ...pollingConfig,
+        maxRetries: 1
+    };
+    const gasUsed = buildReportedGasUsed(params.gasUsed, params.effectiveGasPrice);
+    const requestBody = {
+        execId: params.execId,
+        chain: params.chain,
+        status: params.status,
+        action: params.action,
+        ...params.txHash !== undefined && {
+            txHash: params.txHash
+        },
+        ...gasUsed !== undefined && {
+            gasUsed
+        },
+        ...params.errorCode !== undefined && {
+            errorCode: params.errorCode
+        }
+    };
+    try {
+        await pollApiPost(url.toString(), requestBody, isTransactionReportResponse, reportConfig);
+    } catch (error) {
+        throw parseEarnApiError(error, {
+            operation: 'transactionReport'
+        });
+    }
+}
+
 /**
  * Sum the amounts across every token input to size the allowance approval.
  *
@@ -15054,6 +15455,59 @@ function toWithdrawalQuoteInfo(data) {
 // Intentionally built-ins-only: Earn bridge support is limited to SDK-known
 // token contracts plus the explicit ERC-3009 domain allowlist below.
 const TOKEN_REGISTRY = createTokenRegistry();
+function submitTransactionReport(reportContext, action, status, details) {
+    void reportEarnTransaction({
+        execId: reportContext.execId,
+        chain: reportContext.chain,
+        config: reportContext.config,
+        action,
+        status,
+        ...details
+    }).catch(()=>undefined);
+}
+function reportTransactionSuccess(reportContext, action, result) {
+    if (result === undefined) {
+        return;
+    }
+    submitTransactionReport(reportContext, action, 'success', {
+        txHash: result.txHash,
+        gasUsed: result.gasUsed,
+        effectiveGasPrice: result.effectiveGasPrice
+    });
+}
+function reportTransactionFailure(reportContext, action, error) {
+    submitTransactionReport(reportContext, action, 'failure', {
+        txHash: transactionReportTxHash(error),
+        errorCode: transactionReportErrorCode(error)
+    });
+}
+function transactionReportErrorCode(error) {
+    if (isKitError(error)) {
+        return error.name;
+    }
+    const message = getErrorMessage(error);
+    if (/user (rejected|denied)|rejected by user/i.test(message)) {
+        return 'USER_REJECTED';
+    }
+    if (/insufficient funds/i.test(message)) {
+        return 'INSUFFICIENT_FUNDS';
+    }
+    if (/timeout|timed out/i.test(message)) {
+        return 'TIMEOUT';
+    }
+    return 'UNKNOWN_ERROR';
+}
+function transactionReportTxHash(error) {
+    if (!isKitError(error)) {
+        return undefined;
+    }
+    const trace = error.cause?.trace;
+    if (typeof trace !== 'object' || trace === null) {
+        return undefined;
+    }
+    const txHash = trace['txHash'];
+    return typeof txHash === 'string' && txHash !== '' ? txHash : undefined;
+}
 /**
  * Build the typed error raised when a cross-chain wait is cancelled via its
  * `AbortSignal`. Mirrors `@core/adapter-base`'s `createAbortError` (same
@@ -15375,7 +15829,7 @@ function finishElapsedWait(lastStatus, lastError) {
             const adapterContractAddress = requireAdapterContract(chain);
             const { adapter } = params.from;
             const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -15383,32 +15837,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const approvalToken = resolveEarnApprovalToken(executionParams);
             const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Earn deposit token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Earn deposit token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.deposit',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn deposit reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.deposit',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn deposit reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Deposit', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Deposit', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 kind: 'same-chain',
                 txHash,
@@ -15488,7 +15965,13 @@ function finishElapsedWait(lastStatus, lastError) {
             amount: params.amount,
             sourceChain: sourceChain.chain,
             destinationChain: destinationChain.chain,
-            expiresAt: prepared.expiresAt
+            expiresAt: prepared.expiresAt,
+            ...prepared.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: prepared.quoteIssuedAt
+            },
+            ...prepared.quoteExpiry !== undefined && {
+                quoteExpiry: prepared.quoteExpiry
+            }
         };
     }
     /** {@inheritdoc} */ async withdraw(params) {
@@ -15509,7 +15992,7 @@ function finishElapsedWait(lastStatus, lastError) {
             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({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async ()=>fetchWithdraw({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -15517,32 +16000,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
             const approvalToken = tokenInputs[0]?.token;
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Vault share token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Vault share token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.withdraw',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn withdraw reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.withdraw',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn withdraw reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Withdraw', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 txHash,
                 explorerUrl,
@@ -15676,141 +16182,6 @@ function finishElapsedWait(lastStatus, lastError) {
                 }
         }
     }
-    gasEstimateFailure(name, chain, error) {
-        return {
-            name,
-            token: chain.nativeCurrency.symbol,
-            blockchain: chain.chain,
-            fees: null,
-            error: getErrorMessage(error)
-        };
-    }
-    async estimateDepositQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchDeposit({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const approvalToken = resolveEarnApprovalToken(executionParams);
-            const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Deposit',
-                actionKey: 'earn.deposit',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined && requiredAllowance > 0n ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Deposit', chain, error)
-            ];
-        }
-    }
-    async estimateWithdrawalQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchWithdraw({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const tokenInputs = buildEarnTokenInputs(executionParams, normalizedVaultAddress);
-            const approvalToken = tokenInputs[0]?.token;
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Withdraw',
-                actionKey: 'earn.withdraw',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Withdraw', chain, error)
-            ];
-        }
-    }
-    async estimateClaimRewardsQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, config } = params;
-        try {
-            requireAdapterContract(chain);
-            const { rewards, executionParams, signature } = await fetchClaimRewards({
-                address,
-                chain: apiChain,
-                vaultAddress,
-                config
-            });
-            if (rewards.length === 0) {
-                return [];
-            }
-            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);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Claim Rewards',
-                actionKey: 'earn.claimRewards',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs: [],
-                    signature
-                }
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Claim Rewards', chain, error)
-            ];
-        }
-    }
     /** {@inheritdoc} */ async getDepositQuote(params) {
         const config = this.resolveConfig(params.config);
         if (hasQuoteDestinationChain(params)) {
@@ -15833,96 +16204,43 @@ function finishElapsedWait(lastStatus, lastError) {
             throw createValidationFailedError('chain', destinationChain.chain, 'chain is only supported for cross-chain Earn deposit quotes; omit chain/address when quoting on the source chain');
         }
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchDepositQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateDepositQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote, so the
+        // SDK no longer simulates it locally. `chainDefinition` lets the fetch fill
+        // the native token symbol / blockchain on each gas entry.
+        return fetchDepositQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getWithdrawalQuote(params) {
         const config = this.resolveConfig(params.config);
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchWithdrawalQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateWithdrawalQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote.
+        return fetchWithdrawalQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getClaimRewardsQuote(params) {
         const config = this.resolveConfig(params.config);
-        const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        const quote = await fetchClaimRewardsQuote({
+        const { address, chain } = await resolveAdapterContext(params.from);
+        // The claimRewards/quote response carries no gas estimate (unlike
+        // deposit/withdrawal quotes), and the SDK no longer estimates gas locally,
+        // so gasFees is always empty for claim rewards.
+        return fetchClaimRewardsQuote({
             vaultAddress: params.vaultAddress,
             address,
             chain,
             config
         });
-        // No claimable rewards means there is nothing to execute, so there is no
-        // gas to estimate. Short-circuit on the already-fetched quote rather than
-        // calling the (heavier) claim execution endpoint again — this also keeps
-        // `gasFees` empty as documented, instead of risking a `{ fees: null }`
-        // estimation-error entry when the adapter/RPC is unavailable. This
-        // short-circuit is why the claim path stays sequential instead of using
-        // the Promise.all pattern of the deposit/withdrawal quotes: estimating in
-        // parallel would hit the signing endpoint even when nothing is claimable.
-        if (quote.rewards.length === 0) {
-            return {
-                ...quote,
-                gasFees: []
-            };
-        }
-        const gasFees = await this.estimateClaimRewardsQuoteGasFees({
-            adapter: params.from.adapter,
-            chain: chainDefinition,
-            apiChain: chain,
-            address,
-            vaultAddress: params.vaultAddress,
-            config
-        });
-        return {
-            ...quote,
-            gasFees
-        };
     }
 }
 function hasDepositDestination(params) {
@@ -16160,11 +16478,27 @@ function formatPositionPnL(pnl) {
  * @param vault - Provider vault info with raw amount objects
  * @returns Vault info with total deposits and liquidity formatted as strings
  */ function formatVaultInfo(vault) {
-    const { totalDeposits, liquidity, ...rest } = vault;
+    // The flat `totalDeposits`/`liquidity` are deprecated aliases that are
+    // intentionally dual-read through the migration window so existing
+    // consumers keep receiving them until Contract.
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    const { totalDeposits, liquidity, liquidityProfile, ...rest } = vault;
+    // `liquidityProfile` is `.optional()` in the response schema during the
+    // expand/contract window (an old backend that predates the nested facets
+    // omits it), so only format and re-attach it when present — matching the
+    // provider-side `toVaultInfo` mapper.
     return {
         ...rest,
         totalDeposits: formatAmount(totalDeposits),
-        liquidity: formatAmount(liquidity)
+        liquidity: formatAmount(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: formatAmount(liquidityProfile.totalDeposits),
+                available: formatAmount(liquidityProfile.available),
+                totalSupply: formatAmount(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 /**
@@ -18076,27 +18410,95 @@ function formatRetryResult(operation, result) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
+/**
+ * Register event handlers from a context actions map to a kit instance.
+ *
+ * This utility function registers event handlers stored in a context actions map
+ * with a kit instance that supports event handling via an `on` method. It handles
+ * wildcard handlers ('*') and prefixed action handlers, stripping the prefix
+ * before registration.
+ *
+ * The function is designed to be reusable across different operation types
+ * (bridge, swap, stake, etc.) by accepting a configurable prefix parameter.
+ *
+ * @param kit - The kit instance to register handlers with (must have an `on` method)
+ * @param handlers - Map of action names to arrays of handler functions
+ * @param prefix - Optional prefix to strip from action names (e.g., 'bridge.')
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ * const handlers = {
+ *   '*': [(payload) => console.log('All actions:', payload)],
+ *   'bridge.approve': [(payload) => console.log('Approved:', payload)],
+ *   'bridge.burn': [(payload) => console.log('Burned:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'bridge.')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { SwapKit } from '@circle-fin/swap-kit'
+ *
+ * const kit = new SwapKit()
+ * const handlers = {
+ *   'swap.initiate': [(payload) => console.log('Swap initiated:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'swap.')
+ * ```
+ */ const registerActionHandlers = (kit, handlers, prefix = '')=>{
+    for (const [action, handlerArray] of Object.entries(handlers)){
+        // Register all handlers for this action
+        for (const handler of handlerArray){
+            if (action === '*') {
+                // Wildcard handlers are registered as-is
+                kit.on('*', handler);
+            } else if (prefix && action.startsWith(prefix)) {
+                // Remove prefix to get the actual kit action name
+                const kitAction = action.split('.').at(1);
+                if (kitAction) {
+                    kit.on(kitAction, handler);
+                }
+            } else if (!prefix) {
+                // No prefix configured, register action as-is
+                kit.on(action, handler);
+            }
+        // Actions that don't match the prefix are silently ignored
+        }
+    }
+};
+
 /**
  * Create an EarnKit instance for AppKit earn operations.
  *
- * @remarks The context parameter is reserved for future EarnKit wiring.
- * EarnKit does not currently support AppKit developer fee hooks, so the
- * factory does not read fee callbacks from the context. Earn custom fees remain
- * reserved until EarnKit fee support ships.
+ * Attaches any earn event handlers previously registered on the AppKit
+ * context (via `kit.on('earn.*', …)` or `kit.on('*', …)`) so step events
+ * fire during the returned kit's earn operations.
  *
- * When EarnKit supports developer fee hooks, this factory can wire AppKit context through.
+ * @remarks Developer fee hooks from the AppKit context are not applied.
+ * EarnKit does not yet support custom fee policies.
  *
- * @param context - AppKit context reserved for future EarnKit wiring
- * @returns A new EarnKit instance
+ * @param context - AppKit context with earn event handlers and kit options
+ * @returns An EarnKit instance ready for AppKit earn operations
  *
  * @example
  * ```typescript
  * const earnKit = createEarnKit(context)
  * ```
- */ const createEarnKit = ()=>new EarnKit();
+ */ const createEarnKit = (context)=>{
+    const kit = new EarnKit();
+    registerActionHandlers(kit, context.actions.earn, 'earn');
+    return kit;
+};
 
 async function deposit(context, params) {
-    return createEarnKit().deposit(params);
+    return createEarnKit(context).deposit(params);
 }
 /**
  * Execute an earn withdrawal operation.
@@ -18120,7 +18522,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function withdraw(context, params) {
-    return createEarnKit().withdraw(params);
+    return createEarnKit(context).withdraw(params);
 }
 /**
  * Claim earn rewards.
@@ -18143,7 +18545,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function claimRewards(context, params) {
-    return createEarnKit().claimRewards(params);
+    return createEarnKit(context).claimRewards(params);
 }
 /**
  * Fetch vault information.
@@ -18165,7 +18567,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getVaults(context, params) {
-    return createEarnKit().getVaults(params);
+    return createEarnKit(context).getVaults(params);
 }
 /**
  * Discover vaults available on a chain.
@@ -18189,7 +18591,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function exploreVaults(context, params) {
-    return createEarnKit().exploreVaults(params);
+    return createEarnKit(context).exploreVaults(params);
 }
 /**
  * Lazily iterate every vault available on a chain.
@@ -18213,7 +18615,7 @@ async function deposit(context, params) {
  * }
  * ```
  */ function exploreVaultsIterator(context, params) {
-    return createEarnKit().exploreVaultsIterator(params);
+    return createEarnKit(context).exploreVaultsIterator(params);
 }
 /**
  * Fetch a wallet position in a vault.
@@ -18236,7 +18638,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getPosition(context, params) {
-    return createEarnKit().getPosition(params);
+    return createEarnKit(context).getPosition(params);
 }
 /**
  * Fetch the current status of a cross-chain Earn deposit.
@@ -18258,7 +18660,7 @@ async function deposit(context, params) {
  * console.log(status.status)
  * ```
  */ async function getCrossChainDepositStatus(context, params) {
-    return createEarnKit().getCrossChainDepositStatus(params);
+    return createEarnKit(context).getCrossChainDepositStatus(params);
 }
 /**
  * Poll a cross-chain Earn deposit until it reaches a terminal bridge state.
@@ -18281,7 +18683,7 @@ async function deposit(context, params) {
  * console.log(result.outcome)
  * ```
  */ async function waitForCrossChainDeposit(context, params) {
-    return createEarnKit().waitForCrossChainDeposit(params);
+    return createEarnKit(context).waitForCrossChainDeposit(params);
 }
 /**
  * Fetch a deposit quote.
@@ -18305,7 +18707,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getDepositQuote(context, params) {
-    return createEarnKit().getDepositQuote(params);
+    return createEarnKit(context).getDepositQuote(params);
 }
 /**
  * Fetch a withdrawal quote.
@@ -18329,7 +18731,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getWithdrawalQuote(context, params) {
-    return createEarnKit().getWithdrawalQuote(params);
+    return createEarnKit(context).getWithdrawalQuote(params);
 }
 /**
  * Fetch a claim rewards quote.
@@ -18352,8 +18754,44 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getClaimRewardsQuote(context, params) {
-    return createEarnKit().getClaimRewardsQuote(params);
+    return createEarnKit(context).getClaimRewardsQuote(params);
+}
+/**
+ * Resume a multi-phase earn operation that previously failed.
+ *
+ * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
+ * `claimRewards`. Completed phases can be skipped when the error carries
+ * earn retry context. Call `isRetryableError(error)` first.
+ *
+ * @remarks
+ * Retry re-fetches execution params and may re-submit the execute
+ * transaction. Treat this as best-effort recovery if a prior execute
+ * broadcast may still be in flight.
+ *
+ * @param context - AppKit context
+ * @param error - The error caught from a previous multi-phase earn operation
+ * @returns Promise resolving to the result of the resumed operation
+ * @throws If the error is not retryable or lacks earn retry context
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { retry } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ *
+ * try {
+ *   await deposit(context, params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     const result = await retry(context, error)
+ *   }
+ * }
+ * ```
+ */ async function retry(context, error) {
+    return createEarnKit(context).retry(error);
 }
 
-export { claimRewards, deposit, exploreVaults, exploreVaultsIterator, getClaimRewardsQuote, getCrossChainDepositStatus, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, waitForCrossChainDeposit, withdraw };
+export { claimRewards, deposit, exploreVaults, exploreVaultsIterator, getClaimRewardsQuote, getCrossChainDepositStatus, getDepositQuote, getPosition, getVaults, getWithdrawalQuote, retry, waitForCrossChainDeposit, withdraw };
 //# sourceMappingURL=earn.mjs.map