Skip to main content
This guide describes the stable @spicenet-io/spiceflow-ui@4.10.0 release. The refactor shares asset inventory, source policy, quotes and execution between stock components and custom UIs. It does not require replacing your app’s layout or wallet-provider stack.

​
What the Client Configures

For a basic Supply action, declare the destination chain ID, token address, and protocol calls. The action builder still needs your protocol’s contract address and ABI. Choose amount semantics when the default input-plus-fees behavior is not appropriate. Keep product policy, beneficiary selection, lock duration and success-side application updates in your app. These counts compare the previous 4.9.6 Custom UI guide with the 4.10.0 Supply example; they measure that example’s wiring, not every possible integration or a change in required wallet dependencies. The eight previous hooks/helpers were useWallet, useSpiceExecution, useSupplyAssets, useSupplyQuote, buildSupplyChainBatches, buildPayChainBatches, estimateFeePreview, and executeSupply. The 4.10.0 controller has four top-level inputs in the basic example: enabled, destinationToken, selectedAsset, and buildActionCalls. Optional callbacks, styling, restrictions and protocol-specific parameters are excluded from these minimum counts. An upcoming SDK change makes enabled optional with a true default, reducing the basic example to three inputs. That default is not in published 4.10.0. enabled controls whether the form is active; canExecute controls submit readiness after quotes, fees and other checks. An existing Privy/wagmi/Query setup is still required. network still defaults to testnet; production apps must set network="mainnet". nativeChainId remains the app-chain setting for account deposit and withdrawal flows. Custom RPCs remain recommended for production, not mandatory for every chain.

​
Migration Map

Legacy lower-level exports remain available; replacing a working integration with the controller is not a prerequisite for every upgrade. Review the blocked execution overrides and changed defaults below even if TypeScript reports no errors. Deposit/Withdraw callback semantics are separate and remain available; do not apply the Pay/Lock override removal to them.

​
Defaults That Reduce Configuration

  • Destination metadata: pass chainId and address; symbol, decimals and logo are optional overrides. Missing required metadata keeps the action unavailable.
  • Funding sources: both connected wallets are eligible by default, subject to balances, policy and routes. Account mode and funding-wallet selection are distinct. Preserve owner/location in custom selectors.
  • RPCs: a rpcOverrides entry wins; otherwise the SDK uses that chain’s built-in endpoint. Wagmi transports alone do not configure SDK reads. Rollup price lookups require a host RPC.
  • Venues: Uniswap v3 defaults now cover Ethereum, Arbitrum, Polygon, BSC and Monad, alongside the existing chain-specific venues. The default route no longer depends on keyless 1inch. See Liquidity Venues; supported chain does not mean every token pair has liquidity.
  • Styling: automatic browser stylesheet injection and provider-theme inheritance. Existing CSS imports remain supported. Per-component styling overrides are optional.
  • Fee and funding batches: SDK-owned by default; new apps need no fee-collection mode or escrow builder.
  • Account controls: SpiceAccount owns deposit/withdraw modal state. AccountDisplay remains available for apps that already own those modals.

​
Amounts, Caller and Completion

Use "input" for principal plus fees, "input-inclusive" for a total source budget, and "output" for a fixed destination payment. Lock uses input-inclusive. Builder amounts are destination-token bigints, not source-token units. Display the SDK’s fee currency and maximum source debit. External matching-token, same-chain actions execute directly. Routed sources execute through the embedded wallet; use beneficiary-capable protocol calls when the intended owner differs. Fee-only, proceeds-funded and zero-amount payment actions do not use the matching-token direct path. onSubmit() lets the app observe an accepted submission. Await onSuccess / onLockSuccess for required app updates and use retryFinalization() if only that update fails. This retry does not resubmit the financial action. The SDK has no durable action journal or timed accepted-plan expiry; changed inputs or invalid funding still require a new valid plan. A host can impose its own quote policy.

​
Upgrade Checks

  1. Install the stable release and build your app against its declarations.
  2. Remove Pay/Lock execution overrides, if present, and verify beneficiary/caller behavior for your contract.
  3. Check source selectors with the same token held in external, embedded and Spice balances; key by assetPositionId, not symbol or chain/address alone. Render both initial loading and background refresh correctly.
  4. Check all three amount modes you use, Max, fee currency, insufficient funds and application-update failure.
  5. Verify matching-token direct execution and every routed wallet/chain combination your app supports. Existing successful tests on another app do not prove your contract or deployment.
See Custom UI Integration, Hooks, and Components for current examples.