@spicenet-io/spiceflow-ui 4.14.4-rc.4 → 4.14.4

package/README.md

@@ -78,8 +78,11 @@ host-configured RPC. Keep private credentials out of browser bundles.
 - 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.
+  A controlled ERC20 action can opt into `actionExecution: { wallet: "external", recoveryKey: "my-action" }`
+  when its contract requires the external caller. The SDK routes funds to that wallet,
+  verifies delivery, then submits the captured host calls. This also permits a matching
+  external source to execute directly while the app remains in Embedded mode.
+  `onPayExecute` and `onLockExecute` remain blocked. 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
@@ -87,7 +90,7 @@ host-configured RPC. Keep private credentials out of browser bundles.
 - 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 inclusive Supply controller and its fee hierarchy.
+  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.
@@ -283,12 +286,30 @@ mode to its own wallet, pass `includeExternalWalletAssets={false}` (Embedded mod
 token in both wallets sees one row per wallet; a host that preselects a source should
 match on `assetPositionId`, not on symbol or address alone.
 
+### Routed external callers
+
+The controlled hook supports positive ERC20 input, input-inclusive and fixed-output
+actions with an explicit external caller. Configure `rpcOverrides` for the destination
+and any wallet-source chain. Quotes bind the source spend cap, destination delivery,
+external caller and host calls before funding. The SDK checks the destination receipt,
+ERC20 transfer amount and caller balance before requesting the host transactions.
+Only the final external transaction hash reaches awaited application finalization.
+
+Below one destination transaction's native gas cost, the accepted route buys gas for
+the pending external calls plus three later transactions. At or above that threshold
+it adds no reserve; direct execution still pays its own native gas. Native destinations,
+zero-principal, proceeds-funded and explicit source-escrow caller actions remain
+unsupported capability gaps. This does not add a stock-component prop or a durable
+execution journal: after signing fails, delivered tokens remain ordinary wallet assets
+and retrying the original route can fund again. Use `retryFinalization()` to retry only
+a failed application callback after the external action has confirmed.
+
 ### 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 uses the shared input-inclusive Supply controller and its fee-only planner for local fees. Do not bypass its fee/readiness gates based on the label "withdraw".
+- 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.
 - `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.
@@ -390,7 +411,7 @@ during prewarming. The time available before typing determines how much work it
 - 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.
-- Account wallet withdrawals use this hierarchy automatically and display the chosen fee asset without a selector. Entered amounts and Max are total source-token budgets; applicable fees reduce the net received amount. Same-chain transfers retain the selected token. Choosing another supported chain routes through USDC escrow and delivers registered USDC, with the net output shown before submission. Withdraw discovers permitted embedded balances by default alongside escrow balances; `walletAssets` optionally supplies extra token metadata or an initial wallet selection. Custom `useSpiceSupply` actions that must preserve an exact principal can declare `feeFundingReserve: { asset, amount }` instead of offering that principal as `actionInput`.
+- Account wallet withdrawals use this hierarchy automatically and display the chosen fee asset without a selector. The exact withdrawal amount is reserved before ranking balances; only its remainder can pay fees. Custom `useSpiceSupply` actions that must preserve an exact principal can declare `feeFundingReserve: { asset, amount }` instead of offering that principal as `actionInput`.
 - `feeOnlyAction` alone declares the action: `amountDirection` defaults to `"output"` and `paymentAmount` to `"0"`. Explicit values still win.
 - `submit()` on the controller runs the executor that matches `amountDirection`. `submitSupply()` and `submitPay()` remain for existing callers.
 

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-CQoRAq7w.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-BPsKHzUu.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

@@ -21,7 +21,6 @@ export type ExecutorContext = {
     isInsufficientBalance: boolean;
     isPayMode: boolean;
     isFeeInclusiveInput?: boolean;
-    quotedInclusivePlatformFee?: boolean;
     feeOnlyAction?: boolean;
     actionProceeds?: Exclude<SpiceSupplyProps["actionProceeds"], "output">;
     validateFeeQuote?: () => void;

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

@@ -0,0 +1,24 @@
+import { type Address } from "viem";
+import type { Call, ChainBatch } from "../../../types/authorization";
+import type { BuildActionCallsContext } from "../../../types/supply";
+import type { ActionDefinition } from "../../../utils/actionDefinition";
+import type { SupplyFeeQuote } from "./feePreview";
+export declare function buildExternalAction(params: {
+    quote: SupplyFeeQuote;
+    recipient: Address;
+    beneficiary?: Address;
+    chainId: number;
+    token: Address;
+    feeExecutionMode: BuildActionCallsContext["feeExecutionMode"];
+    buildCalls: (amount: bigint, context: BuildActionCallsContext) => Call[] | Promise<Call[]>;
+}): Promise<ActionDefinition>;
+export declare function buildExternalDeliveryCalls(amount: bigint, context: BuildActionCallsContext, recipient: Address): Call[];
+export declare function externalDeliveryAmount(batches: ChainBatch[], token: Address, chainId: number, recipient: Address): bigint;
+export declare function verifyExternalDelivery(params: {
+    hash: string;
+    token: Address;
+    chainId: number;
+    recipient: Address;
+    sender: Address;
+    amount: bigint;
+}): Promise<void>;

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

@@ -0,0 +1,19 @@
+import type { Address } from "viem";
+import type { ChainBatch } from "../../../types/authorization";
+import type { FeePreviewContext, SupplyFeeQuote } from "./feePreview";
+export interface ExternalGasReserve {
+    chainId: number;
+    recipient: Address;
+    balance: bigint;
+    incoming: bigint;
+    transactionGas: bigint;
+    nativeAmount: bigint;
+    currentTransactions: number;
+    currentValue: bigint;
+    feeAmount: bigint;
+    calls: ChainBatch["calls"];
+}
+export declare function quoteExternalGasReserve(ctx: FeePreviewContext, plan: SupplyFeeQuote): Promise<ExternalGasReserve>;
+export declare function appendExternalGasReserve(batches: ChainBatch[], reserve?: ExternalGasReserve): ChainBatch[];
+export declare function assertExternalGasReserveCalls(reserve: ExternalGasReserve | undefined, batches: ChainBatch[]): void;
+export declare function validateExternalGasReserve(reserve?: ExternalGasReserve, batches?: ChainBatch[]): Promise<void>;

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

@@ -8,10 +8,12 @@ import type { DestinationTokenConfig, FeeFundingSource, PivotRoute, SpiceSupplyP
 import type { FeePreview } from "../../../types/ui";
 import type { ResolvedExactOutputSwap } from "../../../utils/swapQuotes";
 import { type FundingConversion } from "./feeConversion";
+import { type ExternalGasReserve } from "./externalGasReserve";
 type EstimateFn = (chainBatches: ChainBatch[], tokenAddress: string, tokenTransferAmount: bigint, options?: ExecutionOptions) => Promise<FeeEstimateSummary>;
 type BuildPayBatchesFn = (options?: SupplyBatchBuildOptions) => Promise<ChainBatch[]>;
 type BuildSupplyBatchesFn = (options?: SupplyBatchBuildOptions) => Promise<ChainBatch[]>;
 export type SupplyFeeQuote = {
+    externalGasReserve?: ExternalGasReserve;
     fundedFeeToken?: DestinationTokenConfig;
     actionDefinition?: Parameters<NonNullable<SupplyBatchBuildOptions["onActionCalls"]>>[0];
     fundingConversion?: FundingConversion;
@@ -85,6 +87,9 @@ export declare function estimateSupplyMaxAmount(ctx: {
     feeExecutionMode: SpiceSupplyProps["feeExecutionMode"];
 }): Promise<string | null>;
 export interface FeePreviewContext {
+    externalGasRecipient?: Address;
+    externalGasCalls?: (plan: SupplyFeeQuote) => Promise<ChainBatch["calls"]>;
+    externalGasReserve?: ExternalGasReserve;
     feeToleranceBps?: number;
     initialFeeEstimate?: FeeEstimateSummary;
     initialSourceGasSkim?: bigint;
@@ -104,7 +109,6 @@ export interface FeePreviewContext {
     selectedAsset: SelectedAsset | null;
     isPayMode: boolean;
     isFeeInclusiveInput?: boolean;
-    quotedInclusivePlatformFee?: boolean;
     parsedAmount: number;
     needsSwap: boolean;
     exactOutputSwap: ResolvedExactOutputSwap | null;
@@ -138,5 +142,5 @@ export declare class FeeShortfallError extends Error {
     readonly preview: FeePreview;
     constructor(preview: FeePreview);
 }
-export declare function supplyContextForFees(fees: FeePreview, amount: bigint, inclusive: boolean, mode: SpiceSupplyProps["feeExecutionMode"], quotedInclusivePlatformFee?: boolean): Required<Pick<import("../../../types/supply").BuildActionCallsContext, "grossAmount" | "netAmount" | "combinedFeeAmount" | "feeExecutionMode" | "feeBreakdown">>;
+export declare function supplyContextForFees(fees: FeePreview, amount: bigint, inclusive: boolean, mode: SpiceSupplyProps["feeExecutionMode"], reserveFee?: bigint): Required<Pick<import("../../../types/supply").BuildActionCallsContext, "grossAmount" | "netAmount" | "combinedFeeAmount" | "feeExecutionMode" | "feeBreakdown">>;
 export {};

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

@@ -5,12 +5,6 @@ export declare function useSpiceEmbeddedWithdraw(params: {
     enabled: boolean;
     asset: Asset | null;
     amount: bigint;
-    destination?: {
-        address: Address;
-        symbol: string;
-        decimals: number;
-        chainId: number;
-    } | null;
     recipient?: Address;
     owner?: Address;
     sourceChains?: number[];
@@ -119,6 +113,6 @@ export declare function useSpiceEmbeddedWithdraw(params: {
         resetAfterSuccess: () => void;
         resetPaymentState: () => void;
     };
-    source: Asset | null | undefined;
+    source: Asset | undefined;
     maximumFeeFunding: bigint | null | undefined;
 };

package/dist/hooks/useSpiceSupply.d.ts

@@ -6,7 +6,6 @@ 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"> {
-    quotedInclusivePlatformFee?: boolean;
     enabled?: boolean;
     destinationToken: DestinationTokenDeclaration | undefined;
     selectedAsset: SelectedAsset | null;