@spicenet-io/spiceflow-ui 4.10.0 → 4.11.0

package/README.md

@@ -4,23 +4,24 @@ A React component library for building DeFi swap interfaces with multi-chain sup
 
 ## Version and migration
 
-The shared inventory/action refactor merged in PR #103. As checked September 14, 2026,
-`4.9.6-consistency.16` is published under `consistency`; npm `latest` remains `4.9.5`.
-Check the actual registry tag and client pin before adopting it. See
-[CONSISTENCY-MIGRATION.md](CONSISTENCY-MIGRATION.md) for migration breaks and candidate-specific evidence.
-A merged source change does not publish npm or upgrade consuming apps.
+Release `4.11.0` includes quote prewarming, scoped fee-hint reuse, concurrent fee
+checks, configurable fee-estimate tolerance, and faster execution-status polling.
+It uses `@spicenet-io/spiceflow-core@0.7.3`. Source spend caps, destination minimums
+and required destination receipts remain enforced. See the fee-estimate tolerance
+section below for the default and configuration.
 
-The unified action controller in this source restores direct external execution for a wallet asset matching the destination token and chain. Clients keep one action definition across direct and routed execution. See [the migration guide](CONSISTENCY-MIGRATION.md#unreleased-direct-external-execution-in-the-unified-controller) for scope, gas, recovery and the unpublished release status.
+Check the actual registry tag and client pin before adopting it. See
+[CONSISTENCY-MIGRATION.md](CONSISTENCY-MIGRATION.md) for the earlier inventory/action
+migration. Publishing the SDK does not upgrade consuming apps automatically.
 
 ## Installation and provider setup
 
 Select an approved exact version, preserving the app's dependency-age and security policies:
 
 ```bash
-bun add --exact @spicenet-io/spiceflow-ui@4.9.6-consistency.16
+bun add --exact @spicenet-io/spiceflow-ui@4.11.0
 ```
 
-The example is a prerelease selection, not a stable recommendation or a policy bypass.
 Reuse compatible host-owned Privy, wagmi and QueryClient providers. Read the exact
 package's peer dependencies; do not replace the wallet stack as part of a version bump.
 
@@ -54,6 +55,10 @@ host-configured RPC. Keep private credentials out of browser bundles.
 
 - Use stock components when they fit the approved UI; use `useSpiceSupply` for custom
   action forms. `useSpiceLock` and legacy `useSpiceAction` delegate to that controller.
+- In this source (not yet published), `useSpiceSupply` defaults `enabled` to `true`.
+  Omit it for a mounted action form, or pass `enabled: isOpen` when a hidden form stays
+  mounted. Use `canExecute` for submit-button readiness; fee calculation does not
+  require toggling `enabled`. Published 4.10.0 still requires an explicit value.
 - Declare the destination token by chain and address:
   `destinationToken={{ chainId: 8453, address: USDC }}`. The SDK takes the symbol and
   decimals from the chain's token registry, then from the token contract, and holds the
@@ -275,6 +280,51 @@ match on `assetPositionId`, not on symbol or address alone.
 - `onSubmit` on `SpiceSupply`, `SpiceLock`, `SpiceDeposit` and the shared controller fires once when the user submits and the SDK accepts it, before any wallet prompt. Use it for "transaction in progress" feedback instead of listening for clicks on SDK buttons.
 - `max()` on the shared controller (`useSpiceSupply`, `useSpiceLock`) resolves the fee-aware Max for the selected source, or `null` when there is none or the action fixes its output. The host sets the result as the amount.
 
+### Supply fee-estimate tolerance
+
+In `4.11.0`, `SpiceFlowProvider` defaults `feeToleranceBps` to
+`4000` (40%). Clients can override it, for example:
+
+```tsx
+<SpiceFlowProvider {...config} feeToleranceBps={100}>
+  {children}
+</SpiceFlowProvider>
+```
+
+`100` is 1%; `0` disables the drift allowance. Existing conservative fixed-fee
+retention still applies when estimates fall. Values must be integers from `0` to
+`10000`. The allowance is relative to each accepted fee component: a fee of 100
+allows a fresh estimate up to 140 at the default. A zero fee cannot become positive.
+
+This setting covers fee convergence and pre-sign validation for user-transfer
+Supply plans, including stock/controlled Supply and input-mode Lock consumers.
+Within tolerance, the SDK keeps the quoted fee amounts and transaction calls;
+it does not add a 40% fee buffer, increase the source spend cap, or relax swap
+slippage/minimum outputs. Changing the setting invalidates prepared plans.
+Backend acceptance and funding checks still apply. Exact-output Pay, fee-only
+funding, deposits and backend-transfer convergence retain their separate rules.
+
+The open Supply controller retains fee construction hints for at most 30 seconds
+across amount edits in the same wallet, route and configuration scope. These hints
+do not enable submission: the SDK rebuilds the current calls, then checks source
+gas and destination fees concurrently. User-transfer source gas uses the same
+configured fee tolerance; accepted amounts and source caps stay unchanged. A hint
+that no longer fits falls back to full preparation. Closing the form clears hints.
+Servers advertising fee validation price the already constructed destination fee
+calls; older servers retain the estimate path. Cold preparation still sizes fees
+from scratch. Input route quotes debounce for 100 ms; routed fee preparation adds
+no second debounce. These optimizations do not establish a latency SLA.
+
+Fee-inclusive, user-transfer Supply also prewarms when an eligible source is
+selected with an empty/zero amount. It constructs a provisional quote for at most
+one token, capped by the available balance, and retains only fee hints. The amount,
+fee preview and executable plan remain empty. Typing can await in-flight prewarming
+before validating the real amount; closing or changing wallet/configuration
+cancels it. Failed provisional preparation leaves normal quoting available.
+This does not apply to direct external actions, exact-output Pay, fee-only actions
+or actions with explicit funding inputs/proceeds. No signature or submission occurs
+during prewarming. The time available before typing determines how much work it hides.
+
 ### Fee funding for fee-only actions
 
 - A fee-only action (`feeOnlyAction`) runs on what the executing wallet already holds; the SDK funds only the Spicenet fees, in the chain's fee token (`destinationToken`).

package/dist/auth-privy.cjs.js

@@ -1,3 +1,3 @@
 "use client";
 (function(){if(typeof document==="undefined"||document.getElementById("spiceflow-styles"))return;var s=document.createElement("style");s.id="spiceflow-styles";s.textContent="@keyframes spiceflow-spin{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}@keyframes spin{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}@media (prefers-reduced-motion:reduce){*,:after,:before{animation-duration:.001ms!important;animation-iteration-count:1!important;scroll-behavior:auto!important;transition-duration:.001ms!important}}.spiceflow-focus-ring:focus-visible,[data-spiceflow-focus]:focus-visible{border-radius:4px;outline:2px solid currentColor;outline-offset:2px}@media (forced-colors:active){.spiceflow-focus-ring:focus-visible,[data-spiceflow-focus]:focus-visible{outline:2px solid Highlight}}.ibm-plex-mono-thin{font-weight:100}.ibm-plex-mono-extralight,.ibm-plex-mono-thin{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-extralight{font-weight:200}.ibm-plex-mono-light{font-weight:300}.ibm-plex-mono-light,.ibm-plex-mono-regular{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-regular{font-weight:400}.ibm-plex-mono-medium{font-weight:500}.ibm-plex-mono-medium,.ibm-plex-mono-semibold{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-semibold{font-weight:600}.ibm-plex-mono-bold{font-family:IBM Plex Mono,monospace!important;font-style:normal;font-weight:700}#privy-modal-content button{border-radius:6px;font-family:IBM Plex Mono,monospace!important;font-size:small;letter-spacing:-.5px;text-transform:uppercase}#privy-modal-content input{background:#fff;border-radius:6px;padding-top:5px!important}#privy-dialog-title{display:none!important;font-size:18px;padding-bottom:10px;padding-top:10px}.AppLogoContainer-sc-a206bd44-0{display:none}#privy-modal-content{background:var(--Neutral-0,#fafafa);border:6px solid var(--Neutral-1,#e9e9e9);box-shadow:inset 0 0 0 1px rgba(0,0,0,.15),0 330px 92px transparent,0 211px 84px rgba(0,0,0,.01),0 119px 71px rgba(0,0,0,.05),0 53px 53px rgba(0,0,0,.09),0 13px 29px rgba(0,0,0,.1);height:auto!important;padding-bottom:10px}.Subtitle-sc-ddbf22b4-4{font-size:12px;margin-top:-14px;opacity:.5}.StyledLink-sc-1c6127e5-0{background:none!important}.StyledLink-sc-c8577138-0,.login-method-button{font-family:IBM Plex Mono,monospace!important}.StyledLink-sc-c8577138-0{font-style:uppercase}#protected-by-privy{color:#000!important}";document.head.appendChild(s)})();
-"use strict";const r=require("./privy-BG9UqWrL.js");require("react/jsx-runtime"),require("react"),require("@spicenet-io/spiceflow-core"),require("@tanstack/react-query"),require("viem"),require("@privy-io/react-auth"),require("wagmi"),require("viem/actions"),exports.PrivyLogin=r.PrivyLogin;
+"use strict";const r=require("./privy-DvCweNRl.js");require("react/jsx-runtime"),require("react"),require("@spicenet-io/spiceflow-core"),require("@tanstack/react-query"),require("viem"),require("@privy-io/react-auth"),require("wagmi"),require("viem/actions"),exports.PrivyLogin=r.PrivyLogin;

package/dist/auth-privy.js

@@ -1,3 +1,3 @@
 "use client";
 (function(){if(typeof document==="undefined"||document.getElementById("spiceflow-styles"))return;var s=document.createElement("style");s.id="spiceflow-styles";s.textContent="@keyframes spiceflow-spin{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}@keyframes spin{0%{transform:rotate(0deg)}to{transform:rotate(1turn)}}@media (prefers-reduced-motion:reduce){*,:after,:before{animation-duration:.001ms!important;animation-iteration-count:1!important;scroll-behavior:auto!important;transition-duration:.001ms!important}}.spiceflow-focus-ring:focus-visible,[data-spiceflow-focus]:focus-visible{border-radius:4px;outline:2px solid currentColor;outline-offset:2px}@media (forced-colors:active){.spiceflow-focus-ring:focus-visible,[data-spiceflow-focus]:focus-visible{outline:2px solid Highlight}}.ibm-plex-mono-thin{font-weight:100}.ibm-plex-mono-extralight,.ibm-plex-mono-thin{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-extralight{font-weight:200}.ibm-plex-mono-light{font-weight:300}.ibm-plex-mono-light,.ibm-plex-mono-regular{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-regular{font-weight:400}.ibm-plex-mono-medium{font-weight:500}.ibm-plex-mono-medium,.ibm-plex-mono-semibold{font-family:IBM Plex Mono,monospace!important;font-style:normal}.ibm-plex-mono-semibold{font-weight:600}.ibm-plex-mono-bold{font-family:IBM Plex Mono,monospace!important;font-style:normal;font-weight:700}#privy-modal-content button{border-radius:6px;font-family:IBM Plex Mono,monospace!important;font-size:small;letter-spacing:-.5px;text-transform:uppercase}#privy-modal-content input{background:#fff;border-radius:6px;padding-top:5px!important}#privy-dialog-title{display:none!important;font-size:18px;padding-bottom:10px;padding-top:10px}.AppLogoContainer-sc-a206bd44-0{display:none}#privy-modal-content{background:var(--Neutral-0,#fafafa);border:6px solid var(--Neutral-1,#e9e9e9);box-shadow:inset 0 0 0 1px rgba(0,0,0,.15),0 330px 92px transparent,0 211px 84px rgba(0,0,0,.01),0 119px 71px rgba(0,0,0,.05),0 53px 53px rgba(0,0,0,.09),0 13px 29px rgba(0,0,0,.1);height:auto!important;padding-bottom:10px}.Subtitle-sc-ddbf22b4-4{font-size:12px;margin-top:-14px;opacity:.5}.StyledLink-sc-1c6127e5-0{background:none!important}.StyledLink-sc-c8577138-0,.login-method-button{font-family:IBM Plex Mono,monospace!important}.StyledLink-sc-c8577138-0{font-style:uppercase}#protected-by-privy{color:#000!important}";document.head.appendChild(s)})();
-import{P as g}from"./privy-D-vEVQff.js";import"react/jsx-runtime";import"react";import"@spicenet-io/spiceflow-core";import"@tanstack/react-query";import"viem";import"@privy-io/react-auth";import"wagmi";import"viem/actions";export{g as PrivyLogin};
+import{P as g}from"./privy-De1a_NkQ.js";import"react/jsx-runtime";import"react";import"@spicenet-io/spiceflow-core";import"@tanstack/react-query";import"viem";import"@privy-io/react-auth";import"wagmi";import"viem/actions";export{g as PrivyLogin};

package/dist/components/SpiceSupply/lib/executors.d.ts

@@ -14,6 +14,7 @@ export type PaymentResult = {
     error?: string;
 };
 export type ExecutorContext = {
+    feeToleranceBps?: number;
     selectedAsset: SelectedAsset | null;
     parsedAmount: number;
     currentPaymentAmount: string;

package/dist/components/SpiceSupply/lib/feePreview.d.ts

@@ -45,6 +45,7 @@ export declare function sizePivotSourceGasSkim(params: {
     buildSupplyChainBatches: BuildSupplyBatchesFn;
     signal?: AbortSignal;
 }): Promise<bigint>;
+export declare function retainQuotedFixedFees(estimate: FeeEstimateSummary, previous: FeeEstimateSummary): FeeEstimateSummary;
 export declare function solveGrossFunding(fees: Pick<FeePreview, "grossAmount" | "gasFee" | "spicenetFee" | "bridgeFee">, requiredNetFunding: bigint): bigint;
 export declare function estimatePayFunding(args: {
     requiredNetFunding: bigint;
@@ -83,6 +84,9 @@ export declare function estimateSupplyMaxAmount(ctx: {
     feeExecutionMode: SpiceSupplyProps["feeExecutionMode"];
 }): Promise<string | null>;
 export interface FeePreviewContext {
+    feeToleranceBps?: number;
+    initialFeeEstimate?: FeeEstimateSummary;
+    initialSourceGasSkim?: bigint;
     liquidityVenues?: import("../../../utils/crossChainRouter/venueConfig").LiquidityVenuesConfig;
     maxSlippage?: number;
     resolveExactOutputSwap?: SpiceSupplyProps["resolveExactOutputSwap"];

package/dist/components/SpiceWithdraw/lib/useEmbeddedWithdraw.d.ts

@@ -43,21 +43,21 @@ export declare function useSpiceEmbeddedWithdraw(params: {
                 decimals: number;
                 amount: bigint;
             } | null;
-            inputDecimals?: number | null;
             quoteKey: string | null;
             quoteExpiresAt: number | null;
-            refreshQuote: () => void;
-            isQuoting: boolean;
             quoteError: string | null;
+            isQuoting: boolean;
             estimatedInput: string | null;
-            exactOutputSwap: import("../../..").ResolvedExactOutputSwap | null;
             quoteAmountOut: bigint | null;
+            sourceSwap: import("@spicenet-io/spiceflow-core").ResolvedSwap | null;
+            exactOutputSwap: import("../../..").ResolvedExactOutputSwap | null;
+            sourceExactOutputSwap: import("../../..").ResolvedExactOutputSwap | null;
+            inputDecimals?: number | null;
+            refreshQuote: () => void;
             resolvedTokenIn: Address | null;
             isDirect: boolean;
             needsSwap: boolean;
             selectedIsEquivalent: boolean;
-            sourceSwap: import("@spicenet-io/spiceflow-core").ResolvedSwap | null;
-            sourceExactOutputSwap: import("../../..").ResolvedExactOutputSwap | null;
             pivot: import("../../../types/supply").PivotRoute | null;
         };
         fees: {

package/dist/execution/intentSigning.d.ts

@@ -10,4 +10,5 @@ export declare function getChainAuthorizations(params: {
     cache?: Map<string, ChainAuthorization>;
     signal?: AbortSignal;
     onSignatureRequested?: () => void;
+    beforeSign?: () => Promise<void>;
 }): Promise<ChainAuthorization[]>;

package/dist/hooks/useSpiceExecution.d.ts

@@ -36,6 +36,7 @@ export interface ExecutionOptions {
     skipPreSubmitFeeEstimate?: boolean;
     submittedFeeEstimate?: FeeEstimateSummary;
     skipUserFundingPreflight?: boolean;
+    validateFeeCalls?: boolean;
     signal?: AbortSignal;
 }
 export declare function validateUserFundingCapacity(chainBatches: ChainBatch[], userAddress: Address, options?: {

package/dist/hooks/useSpiceLock.d.ts

@@ -18,20 +18,20 @@ export declare function useSpiceLock(params: UseSpiceLockParams): {
             decimals: number;
             amount: bigint;
         } | null;
-        inputDecimals?: number | null;
         quoteKey: string | null;
         quoteExpiresAt: number | null;
-        isQuoting: boolean;
         quoteError: string | null;
+        isQuoting: boolean;
         estimatedInput: string | null;
-        exactOutputSwap: import("..").ResolvedExactOutputSwap | null;
         quoteAmountOut: bigint | null;
+        sourceSwap: import("@spicenet-io/spiceflow-core").ResolvedSwap | null;
+        exactOutputSwap: import("..").ResolvedExactOutputSwap | null;
+        sourceExactOutputSwap: import("..").ResolvedExactOutputSwap | null;
+        inputDecimals?: number | null;
         resolvedTokenIn: import("viem").Address | null;
         isDirect: boolean;
         needsSwap: boolean;
         selectedIsEquivalent: boolean;
-        sourceSwap: import("@spicenet-io/spiceflow-core").ResolvedSwap | null;
-        sourceExactOutputSwap: import("..").ResolvedExactOutputSwap | null;
         pivot: import("../types/supply").PivotRoute | null;
     };
     destination: {

package/dist/hooks/useSpiceSupply.d.ts

@@ -5,7 +5,7 @@ import type { Asset, SelectedAsset } from "../types/assets";
 import type { DestinationTokenDeclaration, SpiceSupplyProps } from "../types/supply";
 import type { FeePreview } from "../types/ui";
 export interface UseSpiceSupplyParams extends Pick<SpiceSupplyProps, "sourceChains" | "supportedSourceAssets" | "buildActionCalls" | "feeExecutionMode" | "buildSpicenetBatch" | "onPayExecute" | "resolveExactOutputSwap" | "amountDirection" | "onSubmit" | "onSuccess" | "onError" | "additionalSourceTokens" | "includeExternalWalletAssets" | "includeCrossChainEmbeddedAssets" | "feeOnlyAction" | "actionInput" | "actionProceeds" | "feeFunding" | "maxSlippage" | "resolveInputSwap"> {
-    enabled: boolean;
+    enabled?: boolean;
     destinationToken: DestinationTokenDeclaration | undefined;
     selectedAsset: SelectedAsset | null;
     paymentAmount?: string;
@@ -48,21 +48,21 @@ export declare function useSpiceSupply(params: UseSpiceSupplyParams): {
             decimals: number;
             amount: bigint;
         } | null;
-        inputDecimals?: number | null;
         quoteKey: string | null;
         quoteExpiresAt: number | null;
-        refreshQuote: () => void;
-        isQuoting: boolean;
         quoteError: string | null;
+        isQuoting: boolean;
         estimatedInput: string | null;
-        exactOutputSwap: import("..").ResolvedExactOutputSwap | null;
         quoteAmountOut: bigint | null;
+        sourceSwap: ResolvedSwap | null;
+        exactOutputSwap: import("..").ResolvedExactOutputSwap | null;
+        sourceExactOutputSwap: import("..").ResolvedExactOutputSwap | null;
+        inputDecimals?: number | null;
+        refreshQuote: () => void;
         resolvedTokenIn: Address | null;
         isDirect: boolean;
         needsSwap: boolean;
         selectedIsEquivalent: boolean;
-        sourceSwap: ResolvedSwap | null;
-        sourceExactOutputSwap: import("..").ResolvedExactOutputSwap | null;
         pivot: import("../types/supply").PivotRoute | null;
     };
     fees: {