@spicenet-io/spiceflow-ui 4.14.5-limit-orders.0 → 4.15.0

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
@@ -283,6 +286,24 @@ 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.

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;
@@ -137,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"]): 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 {};