@spicenet-io/spiceflow-ui 4.10.0-next.3 → 4.10.0-rc.0

package/README.md

@@ -2,39 +2,75 @@
 
 A React component library for building DeFi swap interfaces with multi-chain support.
 
-## Installation
+## 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.
+
+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.
+
+## Installation and provider setup
+
+Select an approved exact version, preserving the app's dependency-age and security policies:
 
 ```bash
-npm install @spicenet-io/spiceflow-ui
+bun add --exact @spicenet-io/spiceflow-ui@4.9.6-consistency.16
 ```
 
-## Usage
+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.
 
 ```tsx
-import { SwapWidget, SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";
+import { SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";
 import "@spicenet-io/spiceflow-ui/styles.css";
 
-function App() {
-  return (
-    <SpiceFlowProvider
-      provider="privy"
-      privyAppId="your-privy-app-id"
-      dynamicEnvironmentId="your-env-id"
-      paraApiKey="your-para-api-key"
-      paraAppName="your-app-name"
-    >
-      <SwapWidget
-        swapBatches={swapBatches}
-        supportedChains={[1, 137, 42161]}
-        showSlippageSettings={true}
-        enableFlipSwap={true}
-        theme="dark"
-      />
-    </SpiceFlowProvider>
-  );
-}
+// Inside the host's existing WagmiProvider → QueryClientProvider → PrivyProvider stack.
+<SpiceFlowProvider
+  provider="privy"
+  network="mainnet"
+  nativeChainId={8453}
+  rpcOverrides={clientRpcUrls}
+>
+  {children}
+</SpiceFlowProvider>;
 ```
 
+Configure Privy credentials/policy on the host's `PrivyProvider`. Supply client RPCs
+for every enabled source, conversion and destination chain, and keep the SDK/wallet
+chain sets aligned. Wallet-library transports alone do not configure SDK reads;
+there is no internal RPC fallback. Keep private credentials out of browser bundles.
+
+## Integration ownership
+
+- Use stock components when they fit the approved UI; use `useSpiceSupply` for custom
+  action forms. `useSpiceLock` and legacy `useSpiceAction` delegate to that controller.
+- Supply destination metadata, protocol `buildActionCalls` or destination-only
+  `lockBatches`, beneficiary semantics, and awaited application updates. The SDK owns
+  inventory, routing, Max, fees, accepted plans, funding, execution and recovery.
+- For custom holdings, use `useSpiceInventory` and `assetPositionId`. Keep raw balance,
+  default visibility and spend eligibility separate. Preserve rows during refresh;
+  stale/failed balances cannot authorize spending, and confirmed zero wins.
+- In this unreleased source, eligible External-mode actions with a matching wallet token
+  and destination chain execute directly from the external signer, without embedded funding.
+  Other assets/chains still use embedded funding and the shared routed executor.
+  `onPayExecute` and `onLockExecute` remain blocked; the deprecated external-caller hint
+  supports only the direct case. Verify contract caller/beneficiary and NFT receiver behavior.
+  Published `.16` does not contain this restoration.
+- Supply `input` adds fees to principal; `input-inclusive` uses a total budget; Pay
+  `output` fixes the destination amount. Use controller readiness/Max/status instead of
+  constructing an executor context or duplicating fee arithmetic in the host.
+- Use controller recovery for uncertain funding and `retryFinalization()` for failed
+  application updates after settlement. Preserve original host terms across reload.
+- Deposit and rollup Withdraw retain distinct execution semantics while sharing
+  inventory/policy. Account wallet withdrawal uses the fee-only Supply path.
+
+Inventory isolation does not establish support for simultaneous differently configured
+providers: underlying quote/execution transports still have global state.
+
 ## Liquidity venues
 
 When a flow has to swap on the destination chain, the SDK quotes every liquidity
@@ -108,12 +144,93 @@ it becomes a `protocol` everyone can name.
 
 ## Development
 
-### Fee-Charging Intent Flows
+### Rollup balance pricing
+
+Rollup USD values use the host-configured RPC provider's pricing capability when the balance API has no valid value. The built-in account panel and withdrawal modal enable this while open; custom `useSpiceAssets` consumers can opt in with `priceEnabled`. Quantities arrive independently. Lookups follow receipt mappings, prefer `nativeChainId`, and fall back to other supported chains with a configured Alchemy endpoint. Explicit account `tokenPrices` overrides still take precedence over provider quotes.
+
+Wallet discovery and rollup balances share a one-minute quote cache. Pricing polls only while the view is open and the page is visible. A failed refresh can retain a marked stale quote for up to five minutes; an unavailable quote displays `—`. No extra key, internal RPC, or symbol-based ERC-20 price fallback is used.
+
+### Host-supplied token logos
+
+`AccountDisplay.tokenLogos` maps a token symbol to a logo URL, the same key
+shape `tokenPrices` uses. A discovered embedded-wallet balance falls back to
+it when the RPC provider returns no logo, which is what happens for a token
+that is not in the chain's configured token list. Provider metadata still
+wins when it has a logo.
+
+```tsx
+<AccountDisplay tokenLogos={{ TOKEN: tokenLogoUrl }} />
+```
+
+### Withdraw from an account balance
+
+`AccountDisplay.onWithdrawClick` receives the rollup receipt-token ID when a
+user clicks Withdraw on an idle rollup balance. The main Withdraw button calls
+it without an ID. Pass the ID to `SpiceWithdraw.initialSourceAssetId` to open
+the existing modal with that asset selected; the user chooses the destination
+network inside the modal. Existing callbacks that take no arguments continue
+to work.
+
+```tsx
+const [withdrawOpen, setWithdrawOpen] = useState(false);
+const [withdrawAssetId, setWithdrawAssetId] = useState<string>();
+
+<AccountDisplay
+  onWithdrawClick={(receiptTokenId) => {
+    setWithdrawAssetId(receiptTokenId);
+    setWithdrawOpen(true);
+  }}
+/>
+<SpiceWithdraw
+  isOpen={withdrawOpen}
+  onClose={() => setWithdrawOpen(false)}
+  initialSourceAssetId={withdrawAssetId}
+  buildSpicenetBatch={buildSpicenetWithdrawalBatch}
+/>
+```
+
+Keep the integration's existing withdrawal batch builder and callbacks.
+`initialSourceAssetId` selects a current balance by ID; it does not supply a
+cached balance or change the receipt's supported withdrawal routes.
+
+### Action Fee Readiness
+
+- Routed Supply, Pay and Lock actions must surface fee estimation before enabling submission.
+- Eligible direct external actions still require an accepted plan but charge no Spicenet fee. Network gas remains payable in the external wallet; native Max reserves gas.
+- Deposit gas and rollup withdrawal semantics remain distinct from action intent fees. Preserve their existing quote/readiness requirements.
+- Account wallet withdrawal is a fee-only Supply action. Do not bypass its fee/readiness gates based on the label "withdraw".
+- Custom actions use the shared controller's `canExecute`; an available balance or old quote alone is insufficient.
+
+### 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`).
+- With no `selectedAsset`, the SDK picks the fee source and the user is never asked. The action's input (`actionInput`) comes first, then its proceeds (`actionProceeds`), so the fee stays inside the action the user submitted; then other balances: same-chain embedded wallet before rollup, and within each, balances already in the fee token before balances that swap into it. The first source that simulates and covers the fee wins and is reported as `fees.fundingSource`; a source whose swap has no route, or that cannot cover the fee within slippage, is skipped for the next.
+- Declare `actionInput` for every token the action consumes and honour the amount passed to `buildActionCalls`: when fees come from an input, the action is built for the remainder. Declare `actionProceeds` for a token the action leaves in the wallet. Both are optional; with neither, only balances can pay. Omit `actionProceeds` when the output is delivered to another owner.
+- `feeFunding` overrides the level order per transaction, for example `["proceeds", "input", "balance"]`; the order inside the balance level is fixed. An empty list leaves the choice to the host's `selectedAsset`.
+- A `selectedAsset` on a fee-only action is an explicit host choice and funds the fee from that balance as before.
+
+### Updating and releasing
+
+Change the shared inventory/policy/controller owner and audit affected stock and custom
+consumers. Use the central team's `workflow`, `ui-quality` and `shared/sdk.md` guidance;
+keep skills in the skills repo rather than copying them here.
+
+Read the central `shared/client-design-decisions.md` register before an upgrade. Map
+applicable decision IDs to affected consumers and regression scenarios, and report each
+result with exact candidate evidence. Preserve agreed behavior and ownership even when
+types compile; a deliberate change needs an explicit product decision and migration plan.
+
+Run focused regressions, `bun test`, `bun run typecheck` and `bun run build`, then validate
+affected consumer builds and rendered/financial behavior on the exact candidate. Record
+package identity, configuration, acceptance coverage and untested cases. Earlier candidate
+results do not automatically apply to newer main or a new client.
 
-- `SpiceSupply` and `SpicePay` are fee-charging intent-execution flows and must surface fee estimation before enabling submission.
-- `SpiceLockModal` is also a fee-charging intent-execution flow and must surface fee estimation before enabling submission.
-- `SpiceDeposit` and `SpiceWithdraw` are treated as non-fee actions and should not use the fee-estimation gating UX.
-- Rule of thumb: every intent-execution flow other than deposit/withdraw should assume fees apply and should gate CTA enablement on successful fee estimation.
+If core/API changes are needed, resolve those dependencies before their UI/app consumers.
+An inventory/controller-only change does not inherently require a core release. After
+explicit release authorization, publish a prerelease with a non-`latest` tag, verify its
+registry artifact, and pin/test that exact version in each adopting app. Stable promotion,
+client deployment and docs targeting are separate release decisions. This refactor adds
+no automatic npm publishing.
 
 ### Building the Library
 

package/dist/auth-privy.cjs.js

@@ -1,2 +1,2 @@
 "use client";
-"use strict";const r=require("./privy-XbtFily9.js");require("react/jsx-runtime"),require("react"),require("@spicenet-io/spiceflow-core"),require("viem"),require("viem/actions"),require("@privy-io/react-auth"),require("wagmi"),require("@tanstack/react-query"),exports.PrivyLogin=r.PrivyLogin;
+"use strict";const r=require("./privy-DgLAdE7U.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,2 +1,2 @@
 "use client";
-import{P as g}from"./privy-C4NTw6Dl.js";import"react/jsx-runtime";import"react";import"@spicenet-io/spiceflow-core";import"viem";import"viem/actions";import"@privy-io/react-auth";import"wagmi";import"@tanstack/react-query";export{g as PrivyLogin};
+import{P as g}from"./privy-TGSRGTFo.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/AccountDisplay/parts/AccountCustomSection.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
-import { CustomSection } from "../types";
 import type { ResolvedDarkPalette } from "../../../utils/theme";
+import { CustomSection } from "../types";
 interface AccountCustomSectionProps {
     section: CustomSection;
     dk: ResolvedDarkPalette;

package/dist/components/AccountDisplay/parts/AccountHeader.d.ts

@@ -5,7 +5,6 @@ interface AccountHeaderProps {
     status: "active" | "inactive";
     statusLabel?: string;
     totalUsdValue: number;
-    hasUnpricedAssets?: boolean;
     breakdownSubtitle: string;
     showUsdSummary?: boolean;
     address?: string;

package/dist/components/AccountDisplay/parts/AccountIdleBalances.d.ts

@@ -1,11 +1,7 @@
 import React from "react";
-import { SpiceAsset } from "../types";
 import type { ResolvedDarkPalette } from "../../../utils/theme";
-export interface DirectWithdrawState {
-    key: string;
-    step: "pending" | "error";
-    message?: string;
-}
+import type { DirectWithdrawState } from "../types";
+import { SpiceAsset } from "../types";
 interface AccountIdleBalancesProps {
     spiceAssets: SpiceAsset[];
     loading: boolean;
@@ -14,6 +10,8 @@ interface AccountIdleBalancesProps {
     canDirectWithdraw?: boolean;
     onDirectWithdraw?: (asset: SpiceAsset) => void;
     directWithdrawState?: DirectWithdrawState | null;
+    onWithdrawClick?: (receiptTokenId?: string) => void;
+    limit?: number;
 }
 export declare const AccountIdleBalances: React.NamedExoticComponent<AccountIdleBalancesProps>;
 export {};

package/dist/components/AccountDisplay/parts/AccountPanel.d.ts

@@ -1,14 +1,13 @@
 import React from "react";
-import { SpiceAsset, CustomSection, AccountNotice } from "../types";
 import { VerifiedPendingDeposit } from "../../../hooks/usePendingDeposit";
 import type { ResolvedDarkPalette } from "../../../utils/theme";
-import { type DirectWithdrawState } from "./AccountIdleBalances";
+import type { DirectWithdrawState } from "../types";
+import { AccountNotice, CustomSection, SpiceAsset } from "../types";
 interface AccountPanelProps {
     appName: string;
     status: "active" | "inactive";
     statusLabel?: string;
     totalUsdValue: number;
-    hasUnpricedAssets?: boolean;
     breakdownSubtitle: string;
     showUsdSummary?: boolean;
     address?: string;
@@ -18,7 +17,7 @@ interface AccountPanelProps {
     customSections: CustomSection[];
     notice?: AccountNotice | null;
     onDepositClick?: () => void;
-    onWithdrawClick?: () => void;
+    onWithdrawClick?: (receiptTokenId?: string) => void;
     depositDisabled?: boolean;
     onCompleteDeposit?: (deposit: VerifiedPendingDeposit) => void;
     primaryColor?: string;
@@ -34,6 +33,7 @@ interface AccountPanelProps {
     canDirectWithdraw?: boolean;
     onDirectWithdraw?: (asset: SpiceAsset) => void;
     directWithdrawState?: DirectWithdrawState | null;
+    idleBalancesLimit?: number;
 }
 export declare const AccountPanel: React.NamedExoticComponent<AccountPanelProps>;
 export {};

package/dist/components/AccountDisplay/types.d.ts

@@ -1,12 +1,13 @@
-import type { CustomStyles } from "../../types/theme";
-import { VerifiedPendingDeposit } from "../../hooks/usePendingDeposit";
 import type React from "react";
+import { VerifiedPendingDeposit } from "../../hooks/usePendingDeposit";
+import type { CustomStyles } from "../../types/theme";
 export interface CustomSectionItem {
     tokenSymbol: string;
     tokenLogoURI?: string;
     label: React.ReactNode;
     displayValue: string;
     valueColor?: "green" | "red" | "default";
+    onClick?: () => void;
 }
 export interface CustomSection {
     title: string;
@@ -14,6 +15,9 @@ export interface CustomSection {
     totalValue?: number;
 }
 export interface SpiceAsset {
+    owner?: string;
+    location?: "external" | "embedded" | "rollup";
+    positionId?: string;
     tokenAddress: string;
     tokenSymbol: string;
     tokenDisplaySymbol?: string;
@@ -24,7 +28,9 @@ export interface SpiceAsset {
     balance: string;
     balanceFormatted: number;
     usdValue: number;
+    priceStatus?: "fresh" | "stale" | "unavailable";
     logoURI?: string;
+    receiptTokenId?: string;
     directWithdraw?: boolean;
 }
 export interface BreakdownLabel {
@@ -42,15 +48,24 @@ export interface AccountDisplayProps {
     customSections?: CustomSection[];
     extraAssets?: SpiceAsset[];
     tokenPrices?: Record<string, number>;
+    tokenLogos?: Record<string, string>;
     breakdownLabels?: BreakdownLabel[];
     notice?: AccountNotice | null;
     styles?: CustomStyles;
     dark?: boolean;
     onDepositSuccess?: () => void;
     onDepositClick?: () => void;
-    onWithdrawClick?: () => void;
+    onWithdrawClick?: (receiptTokenId?: string) => void;
     onCompleteDeposit?: (deposit: VerifiedPendingDeposit) => void;
     showModeToggle?: boolean;
     defaultMode?: "7702" | "non7702";
     showUsdSummary?: boolean;
+    alwaysShowEmbeddedIdle?: boolean;
+    idleBalancesLimit?: number;
+    showDisconnect?: boolean;
+}
+export interface DirectWithdrawState {
+    key: string;
+    step: "pending" | "error";
+    message?: string;
 }

package/dist/components/SpiceDeposit/lib/escrowCredit.d.ts

@@ -0,0 +1,2 @@
+import type { Asset } from "../../../types/assets";
+export declare function isEscrowCreditable(asset: Pick<Asset, "address" | "chainId" | "isNative">): boolean;

package/dist/components/SpiceLock/lib/helpers.d.ts

@@ -3,6 +3,7 @@ import { type FeeEstimateSummary, type ResolvedSwap } from "@spicenet-io/spicefl
 import type { ChainAuthorization, ChainBatch } from "../../../types/authorization";
 import type { Asset } from "../../../types/assets";
 export declare function isDirectLockSource(asset: Asset, lockChainId: number): boolean;
+export declare function isInPlaceLockSource(asset: Asset, lockChainId: number): boolean;
 export declare function composeLockSwapBatches(batches: ChainBatch[], params: {
     chainId: number;
     recipient: Address;

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

@@ -1,7 +1,12 @@
 import { type Address } from "viem";
 import type { ChainBatch } from "../../../types/authorization";
-import type { SpiceSupplyProps } from "../../../types/supply";
+import type { SpiceSupplyProps, SupplyBatchBuildOptions } from "../../../types/supply";
 import type { SupplyFeeQuote } from "./feePreview";
+export declare class InsufficientFeeFundingBalanceError extends Error {
+    readonly requiredAmount: bigint;
+    readonly balance: bigint;
+    constructor(requiredAmount: bigint, balance: bigint);
+}
 export declare function appendProceedsFees(batches: ChainBatch[], owner: Address, token: Address, gas: bigint, platform: bigint): ChainBatch[];
 export declare function simulateProceedsBatch(batches: ChainBatch[], owner: Address, token: Address, signal?: AbortSignal, platformFeeMaximum?: bigint): Promise<bigint>;
 export declare function estimateProceedsFunding(args: {
@@ -10,5 +15,7 @@ export declare function estimateProceedsFunding(args: {
     token: Address;
     signal?: AbortSignal;
     baseline: () => Promise<SupplyFeeQuote | null>;
-    buildBatches: (amount: bigint) => Promise<ChainBatch[]>;
+    buildBatches: (amount: bigint, options?: SupplyBatchBuildOptions) => Promise<ChainBatch[]>;
+    fundShortfall?: boolean;
+    actionAmountFor?: (fee: bigint) => bigint;
 }): Promise<SupplyFeeQuote>;

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

@@ -1,29 +1,27 @@
+import type { FeeEstimateSummary, ResolvedSwap } from "@spicenet-io/spiceflow-core";
 import { type Address } from "viem";
-import type { ResolvedSwap } from "@spicenet-io/spiceflow-core";
-import type { ChainBatch } from "../../../types/authorization";
+import type { ExecutionOptions } from "../../../hooks/useSpiceExecution";
 import type { SelectedAsset } from "../../../types/assets";
-import type { SpiceSupplyProps, SupplyBatchBuildOptions } from "../../../types/supply";
+import type { ChainBatch } from "../../../types/authorization";
+import type { PivotRoute, SpiceSupplyProps, SupplyBatchBuildOptions } from "../../../types/supply";
 import type { ResolvedExactOutputSwap } from "../../../utils/swapQuotes";
-import type { ExecutionOptions } from "../../../hooks/useSpiceExecution";
-import type { FeeEstimateSummary } from "@spicenet-io/spiceflow-core";
 type EstimateFn = (chainBatches: ChainBatch[], tokenAddress: string, tokenTransferAmount: bigint, options?: ExecutionOptions) => Promise<FeeEstimateSummary>;
-export declare function buildEmbeddedEscrowDepositBatch(token: Address, amount: bigint, chainId: number): ChainBatch;
-export declare function isExternalSource(asset: SelectedAsset["asset"] | null | undefined, isNon7702: boolean): boolean;
+export declare function getPivotEscrowAmount(sourceSwap: Pick<ResolvedSwap, "amountOutMinimum">, gasSkim: bigint): bigint;
 export declare function stripSpicenetFundingBatches(batches: ChainBatch[]): ChainBatch[];
 export declare function scaleTokenAmount(amount: bigint, fromDecimals: number, toDecimals: number): bigint;
-export declare function resolveSupplyTokenDecimals(asset: SelectedAsset["asset"], destination: SpiceSupplyProps["destinationToken"], token: Address): Promise<number>;
 export interface BatchBuilderContext {
     currentPaymentAmount: string;
+    isFeeInclusiveInput?: boolean;
+    feeOnlyAction?: boolean;
+    swapInputAmount?: bigint | null;
     destinationToken: SpiceSupplyProps["destinationToken"];
     embeddedWalletAddress: string | null | undefined;
     providerEmbeddedAddress: string | null | undefined;
     externalWalletAddress: string | null | undefined;
     address: string | null | undefined;
     recipient?: Address;
-    swapOutputRecipient?: Address;
     isNon7702: boolean;
     isPayMode: boolean;
-    feeOnlyAction?: boolean;
     resolvedChainId: number;
     buildActionCalls: SpiceSupplyProps["buildActionCalls"];
     feeExecutionMode: SpiceSupplyProps["feeExecutionMode"];
@@ -31,12 +29,24 @@ export interface BatchBuilderContext {
     selectedAsset: SelectedAsset | null;
     needsSwap: boolean;
     resolvedSwap: ResolvedSwap | null;
+    resolveInputSwap?: (amountIn: bigint, selectedSwap?: ResolvedSwap) => Promise<ResolvedSwap>;
     exactOutputSwap: ResolvedExactOutputSwap | null;
     quoteAmountOut: bigint | null;
     resolvedTokenIn: Address | null;
+    sourceSwap?: ResolvedSwap | null;
+    sourceExactOutputSwap?: ResolvedExactOutputSwap | null;
+    resolveSourceExactOutputSwap?: (amountOut: bigint) => Promise<ResolvedExactOutputSwap>;
+    pivot?: PivotRoute | null;
     requestTimestampMs?: number;
 }
-export declare function buildPayChainBatches(ctx: BatchBuilderContext, options?: SupplyBatchBuildOptions): Promise<ChainBatch[]>;
-export declare function buildSupplyChainBatches(ctx: BatchBuilderContext, options?: SupplyBatchBuildOptions): Promise<ChainBatch[]>;
+export declare function isPivotPay(ctx: Pick<BatchBuilderContext, "isPayMode" | "selectedAsset" | "resolvedChainId" | "pivot">): ctx is typeof ctx & {
+    pivot: PivotRoute;
+};
+export declare function isPivotSupply(ctx: Pick<BatchBuilderContext, "isPayMode" | "selectedAsset" | "resolvedChainId" | "sourceSwap" | "pivot">): ctx is typeof ctx & {
+    sourceSwap: ResolvedSwap;
+    pivot: PivotRoute;
+};
+export declare const buildPayChainBatches: (ctx: BatchBuilderContext, options?: SupplyBatchBuildOptions) => Promise<ChainBatch[]>;
+export declare const buildSupplyChainBatches: (ctx: BatchBuilderContext, options?: SupplyBatchBuildOptions) => Promise<ChainBatch[]>;
 export declare function estimateRequiredGrossFunding(requiredNetFunding: bigint, buildBatches: (grossFundingAmount: bigint) => ChainBatch[] | Promise<ChainBatch[]>, fundingToken: Address, estimate: EstimateFn, executionOptions?: Pick<ExecutionOptions, "useCustomTransfers" | "userOverride">): Promise<bigint>;
 export {};

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

@@ -1,23 +1,19 @@
-import { type SourceConversionExecution } from "./sourceConversion";
+import type { ResolvedSwap } from "@spicenet-io/spiceflow-core";
 import type { Dispatch, MutableRefObject, SetStateAction } from "react";
 import { type Address } from "viem";
-import { type TransactionObserver } from "../../../execution/externalWalletClient";
-import { type SourceFundingState } from "../../../execution/sourceFunding";
+import type { ExecutionRunner } from "../../../execution/runner";
+import type { ExecutionProgress } from "../../../hooks/useSpiceExecution";
 import type { SelectedAsset } from "../../../types/assets";
-import type { BuildPayBatchesFn, BuildSupplyBatchesFn, SpiceSupplyProps } from "../../../types/supply";
-import { type SupplyFeeQuote } from "./feePreview";
+import type { BuildPayBatchesFn, BuildSupplyBatchesFn, PivotRoute, SpiceSupplyProps } from "../../../types/supply";
 import type { ResolvedExactOutputSwap } from "../../../utils/swapQuotes";
-import type { ExecutionProgress } from "../../../hooks/useSpiceExecution";
-import type { ExecutionRunner } from "../../../execution/runner";
-export type SupplyStep = "idle" | "signing-delegation" | "signing-intent" | "submitting" | "executing" | "success" | "error";
+import { type SupplyFeeQuote } from "./feePreview";
+export type SupplyStep = "idle" | "building" | "signing-delegation" | "signing-intent" | "submitting" | "executing" | "success" | "error";
 export type PaymentResult = {
     status: "processing" | "success" | "failed";
     txHash?: string;
     error?: string;
 };
-export { isExternalSource } from "./buildBatches";
 export type ExecutorContext = {
-    signal?: AbortSignal;
     selectedAsset: SelectedAsset | null;
     parsedAmount: number;
     currentPaymentAmount: string;
@@ -27,12 +23,18 @@ export type ExecutorContext = {
     feeOnlyAction?: boolean;
     actionProceeds?: SpiceSupplyProps["actionProceeds"];
     validateFeeQuote?: () => void;
+    executionTokenDecimals?: number;
+    signal?: AbortSignal;
     isNon7702: boolean;
+    directExternalAction?: boolean;
     isSourceDestToken: boolean;
     needsSwap: boolean;
     exactOutputSwap: ResolvedExactOutputSwap | null;
     selectedIsEquivalent: boolean;
     resolvedTokenIn: Address | null;
+    sourceSwap: ResolvedSwap | null;
+    sourceExactOutputSwap: ResolvedExactOutputSwap | null;
+    pivot: PivotRoute | null;
     embeddedWalletAddress: string | null | undefined;
     providerEmbeddedAddress: string | null | undefined;
     recipient?: Address;
@@ -51,14 +53,7 @@ export type ExecutorContext = {
     provider: string | null | undefined;
     resolvedChainId: number;
     executionTokenAddress: Address;
-    executionTokenDecimals?: number;
     feeQuote: SupplyFeeQuote | null;
-    fundingObserver?: TransactionObserver;
-    sourceFunding?: SourceFundingState;
-    sourceFundingRecoveryKey?: string;
-    sourceConversion?: SourceConversionExecution;
-    sourceConversionRequired?: boolean;
-    onSourceFundingChange?: (state: SourceFundingState) => void;
     execution: ExecutionRunner & {
         buildPayChainBatches: BuildPayBatchesFn;
         buildSupplyChainBatches: BuildSupplyBatchesFn;
@@ -78,7 +73,5 @@ export type ExecutorContext = {
         abortControllerRef: MutableRefObject<AbortController | null>;
     };
 } & Pick<SpiceSupplyProps, "destinationToken" | "buildActionCalls" | "feeExecutionMode" | "buildSpicenetBatch" | "onPayExecute" | "onSuccess">;
-export declare function sourceFundingSelection(ctx: ExecutorContext): SelectedAsset | null;
-export declare function sourceFundingIdentity(ctx: ExecutorContext): string;
 export declare function executeSupply(ctx: ExecutorContext): Promise<void>;
 export declare function executePay(ctx: ExecutorContext): Promise<void>;

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

@@ -1,4 +1,6 @@
-import type { Address } from "viem";
+import { type Address } from "viem";
+import type { ChainBatch } from "../../../types/authorization";
+export { InsufficientFeeFundingBalanceError } from "./actionProceeds";
 import type { FeePreviewContext, SupplyFeeQuote } from "./feePreview";
 export declare function resolveFeeFundingToken(asset: NonNullable<FeePreviewContext["selectedAsset"]>["asset"], chainId: number, feeToken: Address): Address | null;
 export interface FundingConversion {
@@ -7,5 +9,16 @@ export interface FundingConversion {
     amountInMax: bigint;
     amountOut: bigint;
     sourceAmountMax: bigint;
+    fromProceeds?: boolean;
+    fromInput?: boolean;
 }
-export declare function quoteConvertedFees(ctx: FeePreviewContext): Promise<SupplyFeeQuote>;
+export declare function simulateInPlaceFees(ctx: FeePreviewContext, owner: Address, tokenOut: Address, batches: ChainBatch[]): Promise<{
+    gasFee: bigint;
+    gasQuoteSource: string;
+    simulationVerified?: boolean;
+    platformFee?: bigint;
+}>;
+export declare function quoteConvertedFees(ctx: FeePreviewContext, input?: {
+    token: Address;
+    amount: bigint;
+}): Promise<SupplyFeeQuote>;

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

@@ -0,0 +1,21 @@
+import type { Address } from "viem";
+import type { Asset } from "../../../types/assets";
+import type { FeeFundingLevel, FeeFundingSource, SpiceSupplyProps } from "../../../types/supply";
+import type { FeePreviewContext, SupplyFeeQuote } from "./feePreview";
+export declare const DEFAULT_FEE_FUNDING: FeeFundingLevel[];
+type Candidate = FeeFundingSource & {
+    swap: boolean;
+};
+export declare function rankFeeFundingCandidates(args: {
+    feeToken: Address;
+    chainId: number;
+    inputs?: SpiceSupplyProps["actionInput"];
+    proceeds?: {
+        token: Address;
+        amount: bigint;
+    };
+    balances: Asset[];
+    order?: FeeFundingLevel[];
+}): Candidate[];
+export declare function quoteFeeFunding(ctx: FeePreviewContext, estimateFeePreview: (ctx: FeePreviewContext) => Promise<SupplyFeeQuote | null>): Promise<SupplyFeeQuote | null>;
+export {};

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

@@ -1,6 +1,6 @@
 import { type Address } from "viem";
-import type { ChainBatch } from "../../../types/authorization";
 import type { ExecutionOptions } from "../../../hooks/useSpiceExecution";
+import type { ChainBatch } from "../../../types/authorization";
 import type { ExecutorContext } from "./executors";
 export declare function stripFeeOnlyCalls(batches: ChainBatch[], chainId: number, token: Address): ChainBatch[];
 export declare function feeOnlyExecutionOptions(ctx: ExecutorContext, token: Address, fundingCap: bigint): Pick<ExecutionOptions, "prepareForSigning" | "validateBeforeSubmit" | "resolveActionOutputCredits">;