@stridge/kit 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/flows/withdraw/dialog/WithdrawDialog.d.ts

@@ -1,8 +1,9 @@
 import { TxRef } from "../../../shared/driver/types.js";
-import { WithdrawalQuotePayload, WithdrawalSettlementFailurePayload, WithdrawalSettlementPendingPayload, WithdrawalSettlementSuccessPayload } from "../driver/payloads.js";
-import { SubmitWithdrawalInput } from "../driver/types.js";
 import { FailureInfo } from "../../../shared/orchestrator/types.js";
-import { WithdrawStateName } from "../orchestrator/types.js";
+import { WithdrawalQuotePayload, WithdrawalSettlementFailurePayload, WithdrawalSettlementPendingPayload, WithdrawalSettlementSuccessPayload } from "../driver/payloads.js";
+import { PrepareWithdrawalInput } from "../driver/types.js";
+import { WithdrawStateName, WithdrawSubmitCallback } from "../orchestrator/types.js";
+import { WithdrawBalanceInput, WithdrawSuggestedRecipient } from "../bindings/WithdrawBindings.js";
 import { WithdrawFormEventCallbacks } from "./WithdrawDialogEventsContext.js";
 import { ErrorInfo } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
@@ -25,7 +26,10 @@ declare function WithdrawDialog({
   onOpened,
   onClosed,
   onStepChanged,
-  events
+  events,
+  balance,
+  onSubmit,
+  suggestedRecipient
 }?: WithdrawDialog.Props): _$react_jsx_runtime0.JSX.Element;
 declare namespace WithdrawDialog {
   interface Props {
@@ -56,21 +60,56 @@ declare namespace WithdrawDialog {
      * valid for the named event.
      */
     events?: Events;
+    /**
+     * Withdrawable balance to display in the form. Two forms:
+     *
+     * - `number` — bare amount in display units (kit infers symbol from the provider's
+     *   `asset.symbol`; USD value is short-circuited to $1 for known stablecoins or
+     *   hidden otherwise).
+     * - `{ amount, amountUsd? }` — explicit amount plus an optional pre-computed USD
+     *   value.
+     *
+     * Pass `undefined` (or omit) while loading; the form renders a skeleton until a value
+     * arrives.
+     */
+    balance?: WithdrawBalanceInput;
+    /**
+     * Submit handler — fires once the kit has prepared a fresh UDA target for the
+     * withdrawal. The host's backend (treasury wallet, custodial signer, whatever fits their
+     * stack) is responsible for broadcasting a transfer of the brand currency to that UDA;
+     * the kit hands a `WithdrawSubmitActions` handle the host calls to advance the FSM at
+     * the point its backend reaches the matching state. Required when the dialog is used —
+     * a missing callback lands the user on the error screen instead of an infinite spinner.
+     */
+    onSubmit?: WithdrawSubmitCallback;
+    /**
+     * Trusted recipient address surfaced as a one-click prefill chip next to the recipient
+     * input. The kit no longer auto-derives this from `wagmi.address` (it misled users on
+     * embedded-wallet integrations where wagmi exposes a generated wallet, not the user's
+     * primary self-custodial wallet). Pass an explicit address you trust the user wants to
+     * fill with — a saved profile wallet, a KYC-bound payout destination, a whitelisted
+     * payout. When omitted, no chip renders.
+     */
+    suggestedRecipient?: WithdrawSuggestedRecipient;
   }
   /**
    * Operational lifecycle hooks. Splits cleanly into:
    *
    * - **Form-level inputs** (`onRecipientChanged` / `onAmountChanged` / `onReceiveTokenChanged`
    *   / `onReceiveChainChanged`) — fire on every change of the form's local state.
-   * - **User actions** (`onWithdrawalConfirmed`) — fire when the user submits the form.
+   * - **User actions** (`onWithdrawalConfirmed`) — fires when the user submits the form, just
+   *   before the kit hands control to the host's `<WithdrawDialog onSubmit>` callback.
    * - **Quote lifecycle** — track the form's quote entity through `loading → ready / error`.
-   * - **Submit lifecycle** — track the wagmi-driven broadcast through wagmi → receipt → terminal
-   *   verdict.
+   * - **Submit lifecycle** — track the host-driven progression. The host calls
+   *   `actions.beginProcessing(tx?)` from inside `onSubmit` to move the orchestrator into
+   *   `inProgress`; `onWithdrawalSubmitted` fires once a tx hash is surfaced (either via
+   *   `beginProcessing({ hash })` or a later `setTxHash`). `onSubmissionFailed` fires when
+   *   the host calls `actions.fail(failure)` or `onSubmit` throws.
    * - **Settlement entity** — track the gateway's settlement payload through pending / succeeded /
    *   failed.
    */
   interface Events extends WithdrawFormEventCallbacks {
-    /** User submitted the form (the SUBMIT action — wallet prompt is about to fire). */
+    /** User submitted the form — fires just before the host's `onSubmit` callback runs. */
     onWithdrawalConfirmed?: () => void;
     /** Quote entity reached `ready` with the formatted payload. */
     onQuoteResolved?: (quote: WithdrawalQuotePayload) => void;
@@ -79,14 +118,21 @@ declare namespace WithdrawDialog {
       reason: string;
       code?: string;
     }) => void;
-    /** Wagmi broadcast completed and the orchestrator transitioned into `inProgress`. */
+    /**
+     * Orchestrator transitioned into `inProgress` with a tx hash supplied by the host —
+     * either passed to `actions.beginProcessing({ hash })` or surfaced later via
+     * `actions.setTxHash`.
+     */
     onWithdrawalSubmitted?: (event: {
-      input: SubmitWithdrawalInput;
+      input: PrepareWithdrawalInput;
       tx: TxRef;
     }) => void;
-    /** User declined the wallet signature prompt; orchestrator transitioned into `error`. */
+    /**
+     * Host signaled a user-rejection-shaped failure from `onSubmit` (typically the user
+     * backed out of a wallet prompt); the orchestrator routed back to `form{notice}`.
+     */
     onSignatureDeclined?: () => void;
-    /** Submission failed for a non-rejection reason (network, bad input, etc). */
+    /** Host signaled a non-rejection submission failure (backend rejection, network, …). */
     onSubmissionFailed?: (failure: FailureInfo) => void;
     /** The driver's `settlement` entity emitted a progressive pending update. */
     onProcessingProgress?: (update: WithdrawalSettlementPendingPayload) => void;

package/dist/flows/withdraw/dialog/WithdrawDialog.js

@@ -1 +1 @@
-"use client";import{useDialogLifecycle as e}from"../../../shared/orchestrator/useDialogLifecycle.js";import"../../../shared/orchestrator/index.js";import{useWithdrawSnapshot as t}from"../driver/context.js";import{useWithdrawEffectiveState as n,useWithdrawState as r}from"../orchestrator/controller.js";import{useWithdraw as i}from"../orchestrator/useWithdraw.js";import"../orchestrator/index.js";import{Dialog as a}from"../../../shared/ui/Dialog/Dialog.js";import"../../../shared/ui/Dialog/index.js";import{StepTransition as o}from"../../../shared/dialog/StepTransition.js";import{GatewayKitBoundary as s}from"../../../shared/error-handling/components/GatewayKitBoundary.js";import"../../../shared/error-handling/index.js";import{WithdrawError as c}from"../widgets/withdraw-error/WithdrawError.js";import{WithdrawDialogEventsProvider as l}from"./WithdrawDialogEventsContext.js";import{WithdrawForm as u}from"../widgets/withdraw-form/WithdrawForm.js";import{WithdrawInProgress as d}from"../widgets/withdraw-in-progress/WithdrawInProgress.js";import{WithdrawSuccess as f}from"../widgets/withdraw-success/WithdrawSuccess.js";import"../../../_internal/withdraw/widgets/index.js";import{useRef as p}from"react";import{jsx as m,jsxs as h}from"react/jsx-runtime";function g({container:e,onError:p,onOpened:g,onClosed:v,onStepChanged:y,events:b}={}){let x=r(),S=n(),{close:C}=i(),w=t(),T=x.name!==`closed`;_(x,w.settlement,w.quote,{onOpened:g,onClosed:v,onStepChanged:y,events:b});let E=S.name===`submitting`?`form`:S.name;return m(a,{open:T,onOpenChange:e=>e?void 0:C(),children:m(a.Content,{container:e,children:m(s,{onError:p,onReset:C,children:m(l,{events:b??{},children:h(o,{stateKey:E,children:[S.name===`form`||S.name===`submitting`?m(u,{}):null,S.name===`inProgress`?m(d,{}):null,S.name===`success`?m(f,{}):null,S.name===`error`?m(c,{}):null]})})})})})}function _(t,n,r,i){let a=p(i);a.current=i,e({state:t,settlement:n,quote:r,fireFsm:(e,t)=>v(e,t,a.current),fireSettlement:(e,t)=>y(t,a.current),fireQuote:(e,t)=>{if(t.status===e)return;let n=a.current.events;t.status===`ready`&&n?.onQuoteResolved?.(t.payload),t.status===`error`&&n?.onQuoteFailed?.({reason:t.error.message||`Quote failed.`,...t.error.name?{code:t.error.name}:{}})}})}function v(e,t,n){let{onOpened:r,onClosed:i,onStepChanged:a,events:o}=n,s=e.name===`form`&&!!e.ctx?.notice;if(t.name===`form`&&t.ctx?.notice&&!s&&o?.onSignatureDeclined?.(),e.name!==t.name&&(e.name===`closed`&&t.name!==`closed`&&r?.(),e.name!==`closed`&&t.name===`closed`&&i?.(e.name),a?.({from:e.name,to:t.name}),e.name===`form`&&t.name===`submitting`&&o?.onWithdrawalConfirmed?.(),e.name===`submitting`&&t.name===`inProgress`&&o?.onWithdrawalSubmitted?.({input:t.ctx.input,tx:t.ctx.tx}),t.name===`error`)){let e=t.ctx.failure;e!==void 0&&t.ctx.tx===void 0&&e&&(o?.onSubmissionFailed?.(e),o?.onFailed?.(e))}}function y(e,t){if(e.status!==`ready`&&e.status!==`stale`)return;let n=e.payload,r=t.events;if(r){if(n.kind===`pending`){r.onProcessingProgress?.(n);return}if(n.kind===`succeeded`){r.onSucceeded?.(n);return}n.kind===`failed`&&r.onFailed?.(n)}}export{g as WithdrawDialog};
+"use client";import{useDialogLifecycle as e}from"../../../shared/orchestrator/useDialogLifecycle.js";import"../../../shared/orchestrator/index.js";import{useWithdrawBindings as t}from"../bindings/WithdrawBindings.js";import"../bindings/index.js";import{useWithdrawSnapshot as n}from"../driver/context.js";import{useWithdrawEffectiveState as r,useWithdrawState as i}from"../orchestrator/controller.js";import{useWithdraw as a}from"../orchestrator/useWithdraw.js";import"../orchestrator/index.js";import{useIntercomShutdownOnUnmount as o}from"../../../shared/support/useIntercomShutdownOnUnmount.js";import"../../../shared/support/index.js";import{Dialog as s}from"../../../shared/ui/Dialog/Dialog.js";import"../../../shared/ui/Dialog/index.js";import{StepTransition as c}from"../../../shared/dialog/StepTransition.js";import{GatewayKitBoundary as l}from"../../../shared/error-handling/components/GatewayKitBoundary.js";import"../../../shared/error-handling/index.js";import{WithdrawError as u}from"../widgets/withdraw-error/WithdrawError.js";import{WithdrawDialogEventsProvider as d}from"./WithdrawDialogEventsContext.js";import{WithdrawForm as f}from"../widgets/withdraw-form/WithdrawForm.js";import{WithdrawInProgress as p}from"../widgets/withdraw-in-progress/WithdrawInProgress.js";import{WithdrawSuccess as m}from"../widgets/withdraw-success/WithdrawSuccess.js";import"../../../_internal/withdraw/widgets/index.js";import{useRef as h}from"react";import{jsx as g,jsxs as _}from"react/jsx-runtime";function v({container:e,onError:h,onOpened:v,onClosed:b,onStepChanged:x,events:S,balance:C,onSubmit:w,suggestedRecipient:T}={}){let E=i(),D=r(),{close:O}=a(),k=n(),A=E.name!==`closed`;y(E,k.settlement,k.quote,{onOpened:v,onClosed:b,onStepChanged:x,events:S}),o(),t({...C===void 0?{}:{balance:C},...w?{onSubmit:w}:{},...T?{suggestedRecipient:T}:{}});let j=D.name===`submitting`?`form`:D.name;return g(s,{open:A,onOpenChange:e=>e?void 0:O(),children:g(s.Content,{container:e,children:g(l,{onError:h,onReset:O,children:g(d,{events:S??{},children:_(c,{stateKey:j,children:[D.name===`form`||D.name===`submitting`?g(f,{}):null,D.name===`inProgress`?g(p,{}):null,D.name===`success`?g(m,{}):null,D.name===`error`?g(u,{}):null]})})})})})}function y(t,n,r,i){let a=h(i);a.current=i,e({state:t,settlement:n,quote:r,fireFsm:(e,t)=>b(e,t,a.current),fireSettlement:(e,t)=>x(t,a.current),fireQuote:(e,t)=>{if(t.status===e)return;let n=a.current.events;t.status===`ready`&&n?.onQuoteResolved?.(t.payload),t.status===`error`&&n?.onQuoteFailed?.({reason:t.error.message||`Quote failed.`,...t.error.name?{code:t.error.name}:{}})}})}function b(e,t,n){let{onOpened:r,onClosed:i,onStepChanged:a,events:o}=n,s=e.name===`form`&&!!e.ctx?.notice;if(t.name===`form`&&t.ctx?.notice&&!s&&o?.onSignatureDeclined?.(),e.name!==t.name&&(e.name===`closed`&&t.name!==`closed`&&r?.(),e.name!==`closed`&&t.name===`closed`&&i?.(e.name),a?.({from:e.name,to:t.name}),e.name===`form`&&t.name===`submitting`&&o?.onWithdrawalConfirmed?.(),e.name===`submitting`&&t.name===`inProgress`&&t.ctx.tx&&o?.onWithdrawalSubmitted?.({input:t.ctx.input,tx:t.ctx.tx}),t.name===`error`)){let e=t.ctx.failure;e!==void 0&&t.ctx.tx===void 0&&e&&(o?.onSubmissionFailed?.(e),o?.onFailed?.(e))}}function x(e,t){if(e.status!==`ready`&&e.status!==`stale`)return;let n=e.payload,r=t.events;if(r){if(n.kind===`pending`){r.onProcessingProgress?.(n);return}if(n.kind===`succeeded`){r.onSucceeded?.(n);return}n.kind===`failed`&&r.onFailed?.(n)}}export{v as WithdrawDialog};

package/dist/flows/withdraw/driver/payloads.d.ts

@@ -1,5 +1,7 @@
 import { SettlementFailureKind } from "../../../shared/driver/types.js";
 import { FormattedField } from "../../../shared/format/types.js";
+import { ChainType } from "../../../shared/chains/index.js";
+
 //#region src/flows/withdraw/driver/payloads.d.ts
 /**
  * Per-asset balance available to withdraw — the brand-managed source the cash-out flow draws
@@ -108,6 +110,12 @@ interface WithdrawalSettlementPendingPayload {
   kind: "pending";
   receiveAsset: WithdrawalReceiveAssetPayload;
   receiveAmount: FormattedField<number>;
+  /**
+   * USD value of `receiveAmount` at the settlement leg's price snapshot. Sourced from the
+   * gateway leg's `amount_usd` (`to` preferred, `from` fallback). Omitted when neither leg
+   * carries a priced amount — the in-progress hero then falls back to the quote's USD figure.
+   */
+  receiveAmountUsd?: FormattedField<number>;
   /** Recipient address — the destination the user supplied on the form. */
   recipient: FormattedField<string>;
   /** Unix-ms timestamp when the withdrawal was submitted. */
@@ -191,8 +199,15 @@ interface ReceiveChainPayload {
   networkId: string;
   /** Human-readable network name (e.g. `"Polygon"`). */
   networkName: string;
-  /** EIP-155 chain id (numeric). */
+  /** EIP-155 chain id (numeric). Only meaningful when `chainType === "evm"`. */
   eip155Id: number;
+  /**
+   * Chain family this network belongs to — driver-populated from the gateway's `chain_type`
+   * tag. The withdraw form drives recipient-address validation off this so a non-EVM receive
+   * chain accepts its own address shape instead of the EVM `0x…` form. Drivers that can't
+   * determine the family tag it `"unknown"`, which keeps the address gate permissive.
+   */
+  chainType: ChainType;
   /** Resolved chain icon URL — derived from the chain's native_currency.logo. */
   chainLogoUrl?: string;
   /**

package/dist/flows/withdraw/driver/transformers/settlementToWithdrawalPayload.js

@@ -1 +1 @@
-import{classifyFailureKind as e,classifySettlementStatus as t}from"../../../shared/transformers/classifySettlementStatus.js";import{parseDecimalSafe as n,parseSmallestUnit as r}from"../../../shared/transformers/parseSmallestUnit.js";import{parseIsoMs as i}from"../../../shared/transformers/parseIsoMs.js";import{formatDurationCompact as a}from"../../../../shared/format/formatDurationCompact.js";import{formatTimestamp as o}from"../../../../shared/format/formatTimestamp.js";import{formatTokenAmount as s}from"../../../../shared/format/formatTokenAmount.js";import{shortenAddress as c}from"../../../../shared/format/shortenAddress.js";function l(e,n,r){let i=t(e.status);return i===`completed`?d(e,n,r):i===`failed`?f(e,n,r):u(e,n,r)}function u(e,t,n){let r=e.from,a=e.to,l=i(r?.confirmed_at)??i(e.created_at)??Date.now(),u=p(t,n),d=m(a,t.destination.asset_decimals)||m(r,r?.asset_decimals??t.destination.asset_decimals),f=t.destination.address,g=r?.tx_id,_=r?.eip155_id===void 0?void 0:Number(r.eip155_id);return{kind:`pending`,receiveAsset:u,receiveAmount:{value:d,formatted:s(d,n.i18n,{maxDecimals:t.destination.asset_decimals})},recipient:{value:f,formatted:c(f)},submittedAt:{value:l,formatted:o(l,n.i18n)},...g?{txHash:{value:g,formatted:c(g)},...h(n,_,g)?{txExplorerUrl:h(n,_,g)}:{}}:{}}}function d(e,t,n){let r=e.from,l=e.to,u=i(r?.confirmed_at)??i(e.created_at)??Date.now(),d=i(l?.settled_at)??i(e.updated_at)??Date.now(),f=Math.max(0,d-u),_=Math.round(f/1e3),v=p(t,n),y=m(l,t.destination.asset_decimals),b=t.destination.address,x=r?.tx_id??``,S=r?.eip155_id===void 0?void 0:Number(r.eip155_id),C=l?.tx_id,w=h(n,g(l?.eip155_id)??g(t.destination.eip155_id),C);return{kind:`succeeded`,receiveAsset:v,receiveAmount:{value:y,formatted:s(y,n.i18n,{maxDecimals:t.destination.asset_decimals})},recipient:{value:b,formatted:c(b)},submittedAt:{value:u,formatted:o(u,n.i18n)},filledAt:{value:d,formatted:o(d,n.i18n)},totalTime:{value:_,formatted:a(f,n.i18n)},txHash:{value:x,formatted:x?c(x):``},...h(n,S,x)?{txExplorerUrl:h(n,S,x)}:{},...C?{completionTx:{hash:{value:C,formatted:c(C)},...w?{explorerUrl:w}:{}}}:{}}}function f(t,n,r){let a=t.from,l=i(a?.confirmed_at)??i(t.created_at)??Date.now(),u=i(t.updated_at)??Date.now(),d=p(n,r),f=n.destination.address,m=a?.tx_id,g=a?.eip155_id===void 0?void 0:Number(a.eip155_id);return{kind:`failed`,failureKind:e(t.error),receiveAsset:d,receiveAmount:{value:0,formatted:s(0,r.i18n)},recipient:{value:f,formatted:c(f)},submittedAt:{value:l,formatted:o(l,r.i18n)},failedAt:{value:u,formatted:o(u,r.i18n)},...m?{txHash:{value:m,formatted:c(m)},...h(r,g,m)?{txExplorerUrl:h(r,g,m)}:{}}:{}}}function p(e,t){let n=t.receiveAssetEnrichment,r=Number(e.destination.eip155_id);return{symbol:e.destination.asset_symbol,decimals:e.destination.asset_decimals,address:e.destination.asset_address,isNative:!e.destination.asset_address,...n?.assetLogoUrl?{assetLogoUrl:n.assetLogoUrl}:{},networkId:e.destination.network_id,networkName:n?.networkName??e.destination.network_name,...Number.isFinite(r)?{eip155Id:e.destination.eip155_id}:{},...n?.chainLogoUrl?{chainLogoUrl:n.chainLogoUrl}:{}}}function m(e,t){if(!e)return 0;if(e.amount){let t=n(e.amount);if(t>0)return t}return e.raw_amount?r(e.raw_amount,t):0}function h(e,t,n){if(!n||t===void 0)return;let r=e.explorers?.[t];if(r)return`${r.replace(/\/+$/,``)}/tx/${n}`}function g(e){if(e==null||e===``)return;let t=Number(e);return Number.isFinite(t)?t:void 0}export{l as settlementToWithdrawalPayload};
+import{classifyFailureKind as e,classifySettlementStatus as t}from"../../../shared/transformers/classifySettlementStatus.js";import{parseDecimalSafe as n,parseSmallestUnit as r}from"../../../shared/transformers/parseSmallestUnit.js";import{parseIsoMs as i}from"../../../shared/transformers/parseIsoMs.js";import{formatDurationCompact as a}from"../../../../shared/format/formatDurationCompact.js";import{formatTimestamp as o}from"../../../../shared/format/formatTimestamp.js";import{formatTokenAmount as s}from"../../../../shared/format/formatTokenAmount.js";import{formatUsd as c}from"../../../../shared/format/formatUsd.js";import{shortenAddress as l}from"../../../../shared/format/shortenAddress.js";function u(e,n,r){let i=t(e.status);return i===`completed`?f(e,n,r):i===`failed`?p(e,n,r):d(e,n,r)}function d(e,t,r){let a=e.from,u=e.to,d=i(a?.confirmed_at)??i(e.created_at)??Date.now(),f=m(t,r),p=g(u,t,r),y=_(a,t,r),b=h(u,p)||h(a,y),x=n(u?.amount_usd)||n(a?.amount_usd),S=t.destination.address,C=a?.tx_id,w=a?.eip155_id===void 0?void 0:Number(a.eip155_id);return{kind:`pending`,receiveAsset:f,receiveAmount:{value:b,formatted:s(b,r.i18n,{maxDecimals:p})},...x>0?{receiveAmountUsd:{value:x,formatted:c(x,r.i18n)}}:{},recipient:{value:S,formatted:l(S)},submittedAt:{value:d,formatted:o(d,r.i18n)},...C?{txHash:{value:C,formatted:l(C)},...v(r,w,C)?{txExplorerUrl:v(r,w,C)}:{}}:{}}}function f(e,t,n){let r=e.from,c=e.to,u=i(r?.confirmed_at)??i(e.created_at)??Date.now(),d=i(c?.settled_at)??i(e.updated_at)??Date.now(),f=Math.max(0,d-u),p=Math.round(f/1e3),_=m(t,n),b=g(c,t,n),x=h(c,b),S=t.destination.address,C=r?.tx_id??``,w=r?.eip155_id===void 0?void 0:Number(r.eip155_id),T=c?.tx_id,E=v(n,y(c?.eip155_id)??y(t.destination.eip155_id),T);return{kind:`succeeded`,receiveAsset:_,receiveAmount:{value:x,formatted:s(x,n.i18n,{maxDecimals:b})},recipient:{value:S,formatted:l(S)},submittedAt:{value:u,formatted:o(u,n.i18n)},filledAt:{value:d,formatted:o(d,n.i18n)},totalTime:{value:p,formatted:a(f,n.i18n)},txHash:{value:C,formatted:C?l(C):``},...v(n,w,C)?{txExplorerUrl:v(n,w,C)}:{},...T?{completionTx:{hash:{value:T,formatted:l(T)},...E?{explorerUrl:E}:{}}}:{}}}function p(t,n,r){let a=t.from,c=i(a?.confirmed_at)??i(t.created_at)??Date.now(),u=i(t.updated_at)??Date.now(),d=m(n,r),f=n.destination.address,p=a?.tx_id,h=a?.eip155_id===void 0?void 0:Number(a.eip155_id);return{kind:`failed`,failureKind:e(t.error),receiveAsset:d,receiveAmount:{value:0,formatted:s(0,r.i18n)},recipient:{value:f,formatted:l(f)},submittedAt:{value:c,formatted:o(c,r.i18n)},failedAt:{value:u,formatted:o(u,r.i18n)},...p?{txHash:{value:p,formatted:l(p)},...v(r,h,p)?{txExplorerUrl:v(r,h,p)}:{}}:{}}}function m(e,t){let n=t.receiveAssetEnrichment,r=Number(e.destination.eip155_id);return{symbol:e.destination.asset_symbol,decimals:e.destination.asset_decimals,address:e.destination.asset_address,isNative:!e.destination.asset_address,...n?.assetLogoUrl?{assetLogoUrl:n.assetLogoUrl}:{},networkId:e.destination.network_id,networkName:n?.networkName??e.destination.network_name,...Number.isFinite(r)?{eip155Id:e.destination.eip155_id}:{},...n?.chainLogoUrl?{chainLogoUrl:n.chainLogoUrl}:{}}}function h(e,t){if(!e)return 0;if(e.amount){let t=n(e.amount);if(t>0)return t}return e.raw_amount?r(e.raw_amount,t):0}function g(e,t,n){return n.receiveAssetDecimals??e?.asset_decimals??t.destination.asset_decimals}function _(e,t,n){return n.sendAssetDecimals??e?.asset_decimals??t.destination.asset_decimals}function v(e,t,n){if(!n||t===void 0)return;let r=e.explorers?.[t];if(r)return`${r.replace(/\/+$/,``)}/tx/${n}`}function y(e){if(e==null||e===``)return;let t=Number(e);return Number.isFinite(t)?t:void 0}export{u as settlementToWithdrawalPayload};

package/dist/flows/withdraw/driver/transformers/supportedAssetsToReceiveOptionsPayload.js

@@ -1 +1 @@
-import{formatNetworkName as e}from"../../../../shared/format/formatNetworkName.js";function t(t,n={}){let r=n.excludedChainIds,i=[];for(let n of t.assets){if(r?.has(n.eip155_id))continue;let t=n.native_currency,a=new Set,o=(e,t)=>`${e.toUpperCase()}@${t.toLowerCase()}`,s=[];if(t?.symbol){let e={symbol:t.symbol,name:t.name??t.symbol,address:``,decimals:typeof t.decimals==`number`?t.decimals:18,isNative:!0,...t.logo?{assetLogoUrl:t.logo}:{}};s.push(e),a.add(o(e.symbol,e.address))}let c=t?.symbol?.toUpperCase();for(let e of n.assets){if(!e.symbol||!e.address||c&&e.symbol.toUpperCase()===c)continue;let t=o(e.symbol,e.address);a.has(t)||(a.add(t),s.push({symbol:e.symbol,name:e.name??e.symbol,address:e.address,decimals:e.decimals,isNative:!1,...e.logo?{assetLogoUrl:e.logo}:{}}))}s.length!==0&&i.push({networkId:n.network_id,networkName:e(n.network_name),eip155Id:n.eip155_id,...t?.logo?{chainLogoUrl:t.logo}:{},tokens:s})}return i.sort((e,t)=>e.eip155Id-t.eip155Id),i}export{t as supportedAssetsToReceiveOptionsPayload};
+import{toChainType as e}from"../../../../shared/chains/index.js";import{formatNetworkName as t}from"../../../../shared/format/formatNetworkName.js";function n(n,r={}){let i=r.excludedChainIds,a=[];for(let r of n.assets){if(i?.has(r.eip155_id))continue;let n=r.native_currency,o=new Set,s=(e,t)=>`${e.toUpperCase()}@${t.toLowerCase()}`,c=[];if(n?.symbol){let e={symbol:n.symbol,name:n.name??n.symbol,address:``,decimals:typeof n.decimals==`number`?n.decimals:18,isNative:!0,...n.logo?{assetLogoUrl:n.logo}:{}};c.push(e),o.add(s(e.symbol,e.address))}let l=n?.symbol?.toUpperCase();for(let e of r.assets){if(!e.symbol||!e.address||l&&e.symbol.toUpperCase()===l)continue;let t=s(e.symbol,e.address);o.has(t)||(o.add(t),c.push({symbol:e.symbol,name:e.name??e.symbol,address:e.address,decimals:e.decimals,isNative:!1,...e.logo?{assetLogoUrl:e.logo}:{}}))}c.length!==0&&a.push({networkId:r.network_id,networkName:t(r.network_name),eip155Id:r.eip155_id,chainType:e(r.chain_type),...n?.logo?{chainLogoUrl:n.logo}:{},tokens:c})}return a.sort((e,t)=>e.eip155Id-t.eip155Id),a}export{n as supportedAssetsToReceiveOptionsPayload};

package/dist/flows/withdraw/driver/types.d.ts

@@ -57,17 +57,57 @@ interface RequestWithdrawalQuoteInput {
   recipientAddress: string;
 }
 /**
- * Input to {@link WithdrawDriver.submitWithdrawal}. Identical to {@link RequestWithdrawalQuoteInput}
- * — the live driver re-uses the most recent quote for submit, so the same identifying fields
- * scope both calls.
+ * Input to {@link WithdrawDriver.prepareWithdrawal}. Identical to {@link RequestWithdrawalQuoteInput}
+ * — the live driver re-uses the most recent quote shape for the gateway/start call, so the same
+ * identifying fields scope both calls.
  */
-type SubmitWithdrawalInput = RequestWithdrawalQuoteInput;
+type PrepareWithdrawalInput = RequestWithdrawalQuoteInput;
 /**
- * Input to {@link WithdrawDriver.watchSettlement}. Carries the broadcast tx ref so the watcher
- * can scope its poll to the in-flight withdraw.
+ * Result of {@link WithdrawDriver.prepareWithdrawal}. Carries everything the host's `onSubmit`
+ * callback needs to broadcast a transfer to the Stridge UDA on the brand-currency chain — the
+ * UDA address, the chain, the token, the amount — plus the Stridge correlation fields the host
+ * may want to mirror into their own backend logs.
+ */
+interface WithdrawPreparation {
+  /**
+   * Where the host should send brand-currency funds. The kit has already provisioned a UDA
+   * (via `gateway/start`); the host's job is to broadcast a single on-chain transfer of
+   * `amount` of `tokenSymbol` from their treasury / custodial wallet to `address` on `chainId`.
+   * Stridge takes over from there to bridge into the user's chosen recipient/chain/token.
+   */
+  depositTarget: {
+    /** UDA deposit address on the brand-currency chain. */address: string; /** EIP-155 chain id of the brand-currency network. */
+    chainId: number; /** Brand-currency token symbol (e.g. `"USDC"`). */
+    tokenSymbol: string; /** ERC-20 contract address of the brand currency. Empty string for native gas tokens. */
+    tokenAddress: string; /** On-chain decimal precision (e.g. `6` for USDC on Ethereum, `18` for ETH). */
+    tokenDecimals: number; /** `true` when the brand currency is the chain's native gas token. */
+    isNative: boolean; /** Exact amount to transfer, in display units (kit-managed decimals already factored in). */
+    amount: number;
+  };
+  /**
+   * Stridge correlation slot the host can pass through to their own backend / logs. `owner`
+   * is the same value the kit threaded into `gateway/start.owner` for this UDA.
+   */
+  correlation: {
+    owner: string;
+  };
+}
+/**
+ * Input to {@link WithdrawDriver.watchSettlement}. `tx` is optional — when the host has
+ * surfaced a broadcast tx hash via the orchestrator's `setTxHash` action, the watcher anchors
+ * to it for precise matching. When omitted, the watcher falls back to a best-match heuristic
+ * (destination tuple + amount tolerance + submit-time window) so the kit can find the relevant
+ * settlement even if the host never surfaces a tx hash.
  */
 interface WatchWithdrawalSettlementInput {
-  tx: TxRef;
+  tx?: TxRef;
+  /**
+   * Form snapshot at submit time. The driver uses this in best-match mode to filter
+   * `gateway/{owner}` to settlements whose destination matches the user's selection.
+   */
+  form: RequestWithdrawalQuoteInput;
+  /** Unix-ms timestamp the host called `beginProcessing` — the start of the matching window. */
+  submittedAt: number;
 }
 /**
  * Input to {@link WithdrawDriver.watchWithdrawableBalances}. Optional listener — the form's
@@ -113,10 +153,12 @@ interface WithdrawDriver {
    */
   requestQuote(input: RequestWithdrawalQuoteInput, signal: AbortSignal): Promise<void>;
   /**
-   * Submits the confirmed withdrawal. Resolves with the broadcast tx ref. The settlement
-   * watcher takes over from there to populate the `settlement` entity.
+   * Provisions a fresh UDA for this withdrawal (via `gateway/start`) and returns the deposit
+   * target + Stridge correlation slot for the host's `onSubmit` callback to act on. The kit
+   * never signs the withdraw transfer itself — the host's backend (treasury wallet, custodial
+   * signer, hot-wallet service) does. See {@link WithdrawPreparation}.
    */
-  submitWithdrawal(input: SubmitWithdrawalInput, signal: AbortSignal): Promise<TxRef>;
+  prepareWithdrawal(input: PrepareWithdrawalInput, signal: AbortSignal): Promise<WithdrawPreparation>;
   /**
    * Watches the settlement entity through its lifecycle (pending → succeeded / failed). The
    * listener fires on every transition with the new envelope; the FSM consumes these via the
@@ -130,4 +172,4 @@ interface WithdrawDriver {
   watchWithdrawableBalances?(input: WatchWithdrawableBalancesInput, listener: (entity: WithdrawSnapshot["withdrawableBalances"]) => void, signal: AbortSignal): void;
 }
 //#endregion
-export { RequestWithdrawalQuoteInput, SubmitWithdrawalInput, WatchWithdrawableBalancesInput, WatchWithdrawalSettlementInput, WithdrawDriver, WithdrawSnapshot };
+export { PrepareWithdrawalInput, RequestWithdrawalQuoteInput, WatchWithdrawableBalancesInput, WatchWithdrawalSettlementInput, WithdrawDriver, WithdrawPreparation, WithdrawSnapshot };

package/dist/flows/withdraw/orchestrator/controller.js

@@ -1 +1 @@
-"use client";import{useLingui as e}from"../../../shared/i18n/useLingui.js";import"../../../i18n/index.js";import{toFailure as t}from"../../../shared/orchestrator/toFailure.js";import{useDriverSettlementListener as n}from"../../../shared/orchestrator/useDriverSettlementListener.js";import{useEffectiveState as r}from"../../../shared/orchestrator/useEffectiveState.js";import{useSettlementWatcher as i}from"../../../shared/orchestrator/useSettlementWatcher.js";import"../../../shared/orchestrator/index.js";import{useWithdrawDriverInstance as a}from"../driver/context.js";import{initialState as o,reducer as s}from"./reducer.js";import{createContext as c,use as l,useCallback as u,useMemo as d,useReducer as f,useRef as p}from"react";import{jsx as m}from"react/jsx-runtime";const h={id:`ldK3jJ`,message:`Failed to submit withdrawal.`},g={id:`kUFhUv`,message:`Withdrawal failed.`},_=c(null);_.displayName=`WithdrawControllerContext`;function v(){let e=l(_);if(!e)throw Error(`useWithdraw / WithdrawControllerProvider must be used inside <KitProvider withdraw={…} />. Mount KitProvider once at the host's app root with a withdraw driver.`);return e}function y(){return v().state}function b(){return v().effectiveState}function x(){return v().actions}function S({children:e}){let t=a(),[n,c]=f(s,o),l=w(n,c,t);i(t,n.name===`inProgress`?n.ctx.tx:void 0),T(n,c,t);let u=r(n),p=C(c,l);return m(_,{value:d(()=>({state:n,effectiveState:u,dispatch:c,controller:p,actions:l}),[n,u,p,l]),children:e})}function C(e,t){let n=u(()=>{e({type:`OPEN`})},[e]),r=u(()=>{e({type:`CLOSE`})},[e]);return d(()=>({open:n,close:r,actions:t}),[n,r,t])}function w(n,r,i){let a=p(n);a.current=n;let o=p(i);o.current=i;let s=p(r);s.current=r;let{i18n:c}=e(),l=p(c);l.current=c;let f=u(e=>{let n=o.current;s.current({type:`SUBMIT`,input:e});let r=new AbortController,i={sourceAssetSymbol:e.sourceAssetSymbol,sourceChainId:e.sourceChainId,amount:e.amount,receiveTokenSymbol:e.receiveTokenSymbol,receiveChainId:e.receiveChainId,recipientAddress:e.recipientAddress};n.submitWithdrawal(i,r.signal).then(e=>{r.signal.aborted||s.current({type:`SUBMIT_CONFIRMED`,tx:e})}).catch(n=>{r.signal.aborted||s.current({type:`SUBMIT_FAILED`,failure:t(n,l.current._(h)),input:e})})},[]),m=u(()=>{s.current({type:`CLOSE`})},[]),g=u(()=>{s.current({type:`RESET`})},[]),_=u(()=>{s.current({type:`CLEAR_NOTICE`})},[]);return d(()=>({submit:f,close:m,reset:g,clearNotice:_}),[f,m,g,_])}function T(t,r,i){let a=p(t);a.current=t;let{i18n:o}=e(),s=p(o);s.current=o,n(i,(e,t)=>{if(a.current.name===`inProgress`){if(e===`succeeded`){r({type:`SETTLEMENT_SUCCEEDED`});return}if(e===`failed`){let e=t.settlement,n=e.status===`ready`||e.status===`stale`?e.payload:null,i=n&&n.kind===`failed`?{reason:s.current._(g),code:n.failureKind}:void 0;r({type:`SETTLEMENT_FAILED`,...i?{failure:i}:{}})}}})}export{S as WithdrawControllerProvider,v as useControllerContext,x as useWithdrawActions,b as useWithdrawEffectiveState,y as useWithdrawState};
+"use client";import{useLingui as e}from"../../../shared/i18n/useLingui.js";import"../../../i18n/index.js";import{toFailure as t}from"../../../shared/orchestrator/toFailure.js";import{useDriverSettlementListener as n}from"../../../shared/orchestrator/useDriverSettlementListener.js";import{useEffectiveState as r}from"../../../shared/orchestrator/useEffectiveState.js";import{useSettlementWatcher as i}from"../../../shared/orchestrator/useSettlementWatcher.js";import"../../../shared/orchestrator/index.js";import{useWithdrawBindingsRef as a}from"../bindings/WithdrawBindings.js";import"../bindings/index.js";import{useWithdrawDriverInstance as o}from"../driver/context.js";import{initialState as s,reducer as c}from"./reducer.js";import{createContext as l,use as u,useCallback as d,useMemo as f,useReducer as p,useRef as m}from"react";import{jsx as h}from"react/jsx-runtime";const g={id:`ldK3jJ`,message:`Failed to submit withdrawal.`},_={id:`kUFhUv`,message:`Withdrawal failed.`},v=l(null);v.displayName=`WithdrawControllerContext`;function y(){let e=u(v);if(!e)throw Error(`useWithdraw / WithdrawControllerProvider must be used inside <KitProvider withdraw={…} />. Mount KitProvider once at the host's app root with a withdraw driver.`);return e}function b(){return u(v)}function x(){return y().state}function S(){return y().effectiveState}function C(){return y().actions}function w({children:e}){let t=o(),[n,a]=p(c,s),l=E(n,a,t),u=n.name===`inProgress`?{form:n.ctx.input,submittedAt:n.ctx.submittedAt,...n.ctx.tx?{tx:n.ctx.tx}:{}}:void 0;i(t,u,u?`${u.submittedAt}|${u.tx?.hash??``}`:void 0),D(n,a,t);let d=r(n),m=T(a,l);return h(v,{value:f(()=>({state:n,effectiveState:d,dispatch:a,controller:m,actions:l}),[n,d,m,l]),children:e})}function T(e,t){let n=d(()=>{e({type:`OPEN`})},[e]),r=d(()=>{e({type:`CLOSE`})},[e]);return f(()=>({open:n,close:r,actions:t}),[n,r,t])}function E(n,r,i){let o=m(n);o.current=n;let s=m(i);s.current=i;let c=m(r);c.current=r;let{i18n:l}=e(),u=m(l);u.current=l;let p=a(),h=d(e=>{let n=s.current;c.current({type:`SUBMIT`,input:e});let r=new AbortController,i={sourceAssetSymbol:e.sourceAssetSymbol,sourceChainId:e.sourceChainId,amount:e.amount,receiveTokenSymbol:e.receiveTokenSymbol,receiveChainId:e.receiveChainId,recipientAddress:e.recipientAddress},a={beginProcessing(e){c.current({type:`BEGIN_PROCESSING`,submittedAt:Date.now(),...e?{tx:e}:{}})},setTxHash(e){c.current({type:`SET_TX_HASH`,tx:e,submittedAt:Date.now()})},fail(e){c.current({type:`MARK_FAILED`,...e?{failure:e}:{}})},succeed(){c.current({type:`MARK_SUCCEEDED`})}};n.prepareWithdrawal(i,r.signal).then(i=>{if(r.signal.aborted)return;let o=p.current.onSubmit;if(!o){c.current({type:`SUBMIT_FAILED`,failure:t(Error(`WithdrawDialog onSubmit is missing.`),u.current._(g)),input:e});return}let s=n.getSnapshot().quote,l=s.status===`ready`||s.status===`stale`?s.payload:void 0;try{let n=o({form:e,depositTarget:i.depositTarget,correlation:i.correlation,...l?{quote:l}:{}},a,r.signal);n&&typeof n.catch==`function`&&n.catch(n=>{r.signal.aborted||c.current({type:`SUBMIT_FAILED`,failure:t(n,u.current._(g)),input:e})})}catch(n){if(r.signal.aborted)return;c.current({type:`SUBMIT_FAILED`,failure:t(n,u.current._(g)),input:e})}}).catch(n=>{r.signal.aborted||c.current({type:`SUBMIT_FAILED`,failure:t(n,u.current._(g)),input:e})})},[]),_=d(()=>{c.current({type:`CLOSE`})},[]),v=d(()=>{c.current({type:`RESET`})},[]),y=d(()=>{c.current({type:`CLEAR_NOTICE`})},[]);return f(()=>({submit:h,close:_,reset:v,clearNotice:y}),[h,_,v,y])}function D(t,r,i){let a=m(t);a.current=t;let{i18n:o}=e(),s=m(o);s.current=o,n(i,(e,t)=>{if(a.current.name===`inProgress`){if(e===`succeeded`){r({type:`SETTLEMENT_SUCCEEDED`});return}if(e===`failed`){let e=t.settlement,n=e.status===`ready`||e.status===`stale`?e.payload:null,i=n&&n.kind===`failed`?{reason:s.current._(_),code:n.failureKind}:void 0;r({type:`SETTLEMENT_FAILED`,...i?{failure:i}:{}})}}})}export{w as WithdrawControllerProvider,y as useControllerContext,b as useOptionalControllerContext,C as useWithdrawActions,S as useWithdrawEffectiveState,x as useWithdrawState};

package/dist/flows/withdraw/orchestrator/index.d.ts

@@ -1,4 +1,4 @@
 import { FailureInfo } from "../../../shared/orchestrator/types.js";
 import { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawalFormSnapshot } from "./types.js";
 import { useWithdrawState } from "./controller.js";
-import { useWithdraw } from "./useWithdraw.js";
+import { useOptionalWithdraw, useWithdraw } from "./useWithdraw.js";

package/dist/flows/withdraw/orchestrator/reducer.js

@@ -1 +1 @@
-import{isUserRejectionFailure as e}from"../../../shared/orchestrator/userRejection.js";import"../../../shared/orchestrator/index.js";const t={name:`closed`};function n(e,t){switch(e.name){case`closed`:return r(t);case`form`:return i(e,t);case`submitting`:return a(e,t);case`inProgress`:return o(e,t);case`success`:return s(e,t);case`error`:return c(e,t);default:return l(e)}}function r(e){return e.type===`OPEN`?{name:`form`}:{name:`closed`}}function i(e,t){switch(t.type){case`SUBMIT`:return{name:`submitting`,ctx:{input:t.input}};case`CLEAR_NOTICE`:return e.ctx?.notice?{name:`form`}:e;case`CLOSE`:return{name:`closed`};default:return e}}function a(t,n){switch(n.type){case`SUBMIT_CONFIRMED`:return{name:`inProgress`,ctx:{input:t.ctx.input,tx:n.tx}};case`SUBMIT_FAILED`:return e(n.failure)?{name:`form`,ctx:{notice:n.failure.reason}}:{name:`error`,ctx:{input:n.input,failure:n.failure}};case`CLOSE`:return{name:`closed`};default:return t}}function o(e,t){switch(t.type){case`SETTLEMENT_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,tx:e.ctx.tx}};case`SETTLEMENT_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,tx:e.ctx.tx,...t.failure?{failure:t.failure}:{}}};case`CLOSE`:return{name:`closed`};default:return e}}function s(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function c(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function l(e){throw Error(`Unhandled withdraw state: ${JSON.stringify(e)}`)}export{t as initialState,n as reducer};
+import{isUserRejectionFailure as e}from"../../../shared/orchestrator/userRejection.js";import"../../../shared/orchestrator/index.js";const t={name:`closed`};function n(e,t){switch(e.name){case`closed`:return r(t);case`form`:return i(e,t);case`submitting`:return a(e,t);case`inProgress`:return o(e,t);case`success`:return s(e,t);case`error`:return c(e,t);default:return l(e)}}function r(e){return e.type===`OPEN`?{name:`form`}:{name:`closed`}}function i(e,t){switch(t.type){case`SUBMIT`:return{name:`submitting`,ctx:{input:t.input}};case`CLEAR_NOTICE`:return e.ctx?.notice?{name:`form`}:e;case`CLOSE`:return{name:`closed`};default:return e}}function a(t,n){switch(n.type){case`BEGIN_PROCESSING`:return{name:`inProgress`,ctx:{input:t.ctx.input,submittedAt:n.submittedAt,...n.tx?{tx:n.tx}:{}}};case`SET_TX_HASH`:return{name:`inProgress`,ctx:{input:t.ctx.input,submittedAt:n.submittedAt,tx:n.tx}};case`MARK_SUCCEEDED`:return{name:`success`,ctx:{input:t.ctx.input}};case`MARK_FAILED`:return{name:`error`,ctx:{input:t.ctx.input,...n.failure?{failure:n.failure}:{}}};case`SUBMIT_FAILED`:return e(n.failure)?{name:`form`,ctx:{notice:n.failure.reason}}:{name:`error`,ctx:{input:n.input,failure:n.failure}};case`CLOSE`:return{name:`closed`};default:return t}}function o(e,t){switch(t.type){case`SET_TX_HASH`:return{name:`inProgress`,ctx:{...e.ctx,tx:t.tx}};case`BEGIN_PROCESSING`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:e.ctx.submittedAt,...e.ctx.tx?{tx:e.ctx.tx}:t.tx?{tx:t.tx}:{}}};case`MARK_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{}}};case`MARK_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{},...t.failure?{failure:t.failure}:{}}};case`SETTLEMENT_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{}}};case`SETTLEMENT_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...e.ctx.tx?{tx:e.ctx.tx}:{},...t.failure?{failure:t.failure}:{}}};case`CLOSE`:return{name:`closed`};default:return e}}function s(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function c(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function l(e){throw Error(`Unhandled withdraw state: ${JSON.stringify(e)}`)}export{t as initialState,n as reducer};

package/dist/flows/withdraw/orchestrator/types.d.ts

@@ -1,6 +1,7 @@
 import { TxRef } from "../../../shared/driver/types.js";
 import { FailureInfo } from "../../../shared/orchestrator/types.js";
-
+import { WithdrawalQuotePayload } from "../driver/payloads.js";
+import { WithdrawPreparation } from "../driver/types.js";
 //#region src/flows/withdraw/orchestrator/types.d.ts
 /**
  * Form values captured at submit time. The orchestrator carries this snapshot through every
@@ -22,22 +23,24 @@ interface WithdrawalFormSnapshot {
   receiveChainId: number;
 }
 /**
- * State machine state for the orchestrated withdraw dialog. Per-state discriminated `ctx` narrows
- * what data is available — illegal states (e.g. `inProgress` without a tx ref) are
- * unrepresentable.
+ * State machine state for the orchestrated withdraw dialog. Per-state discriminated `ctx`
+ * narrows what data is available.
  *
- * The reducer carries navigation intent only — entity-derived data (quote payload, settlement
- * payload, balances) lives on the driver and is read directly by widgets.
+ * **Host-paced lifecycle** (different from the old wagmi-signed model): the kit stays in
+ * `submitting` until the host's `onSubmit` callback calls one of the controller's actions
+ * (`beginProcessing`, `fail`, `succeed`). `inProgress` accepts an optional `tx` — the host may
+ * move the user into processing before a broadcast tx hash exists; the kit polls
+ * `gateway/{owner}` and best-matches the relevant settlement (destination tuple + amount +
+ * submit-time window) until the host supplies a tx hash via `setTxHash`. `success` / `error`
+ * similarly accept optional `tx` since the host may declare a terminal verdict directly.
  */
 type WithdrawState = {
   name: "closed";
 } | {
   name: "form";
   /**
-   * Optional notice rendered inline near the submit footer. Currently set when the user
-   * declines the wallet signature: the FSM lands the user back on the form (preserving
-   * recipient + amount + receive selection) with `notice = "Signature declined…"` so they
-   * can retry without losing context. Cleared on the next SUBMIT or CLOSE.
+   * Optional notice rendered inline near the submit footer. Cleared on the next SUBMIT
+   * or CLOSE.
    */
   ctx?: {
     notice?: string;
@@ -50,24 +53,28 @@ type WithdrawState = {
 } | {
   name: "inProgress";
   ctx: {
-    input: WithdrawalFormSnapshot;
-    tx: TxRef;
+    input: WithdrawalFormSnapshot; /** Unix-ms timestamp the host moved the FSM into processing (drives best-match windowing). */
+    submittedAt: number;
+    /**
+     * Source-chain broadcast hash, when the host has surfaced one via
+     * `actions.setTxHash`. Absent while the kit relies on the best-match heuristic.
+     */
+    tx?: TxRef;
   };
 } | {
   name: "success";
   ctx: {
     input: WithdrawalFormSnapshot;
-    tx: TxRef;
+    tx?: TxRef;
   };
 } | {
   name: "error";
   ctx: {
     /**
      * Form snapshot captured at submit time. Set when error follows a submit attempt;
-     * absent when the error path was reached without a known prior submit (currently
-     * unreachable in V2 — kept optional so resume-style entries can re-use the slot).
+     * absent when the error path was reached without a known prior submit.
      */
-    input?: WithdrawalFormSnapshot; /** Optional non-settlement failure (quote / submission rejection). */
+    input?: WithdrawalFormSnapshot; /** Optional non-settlement failure (quote / submission rejection, host-supplied failure). */
     failure?: FailureInfo; /** Source-chain broadcast tx hash when the error followed a successful broadcast. */
     tx?: TxRef;
   };
@@ -79,6 +86,16 @@ type WithdrawState = {
 type WithdrawStateName = WithdrawState["name"];
 /**
  * Reducer event union. Strict discriminated; no stringly-typed transitions.
+ *
+ * The host-paced lifecycle splits the old `SUBMIT_CONFIRMED { tx }` event into three pieces so
+ * the host can move the user forward at whichever step their backend actually completes:
+ *
+ * - `BEGIN_PROCESSING { tx?, submittedAt }` — host accepted the request; move to inProgress with
+ *   or without a tx hash.
+ * - `SET_TX_HASH { tx }` — host surfaced a broadcast hash later; upgrade best-match polling to
+ *   tx-anchored.
+ * - `MARK_SUCCEEDED` / `MARK_FAILED { failure? }` — host short-circuits to a terminal verdict
+ *   (e.g. their own settlement verification ran independently of Stridge's poll).
  */
 type WithdrawEvent = {
   type: "OPEN";
@@ -88,12 +105,22 @@ type WithdrawEvent = {
   type: "SUBMIT";
   input: WithdrawalFormSnapshot;
 } | {
-  type: "SUBMIT_CONFIRMED";
+  type: "BEGIN_PROCESSING";
+  submittedAt: number;
+  tx?: TxRef;
+} | {
+  type: "SET_TX_HASH";
   tx: TxRef;
+  submittedAt: number;
 } | {
   type: "SUBMIT_FAILED";
   failure: FailureInfo;
   input: WithdrawalFormSnapshot;
+} | {
+  type: "MARK_SUCCEEDED";
+} | {
+  type: "MARK_FAILED";
+  failure?: FailureInfo;
 } | {
   type: "SETTLEMENT_SUCCEEDED";
 } | {
@@ -101,15 +128,7 @@ type WithdrawEvent = {
   failure?: FailureInfo;
 } | {
   type: "RESET";
-}
-/**
- * Drops the inline notice on the `form` state. Dispatched by the form widget when the user
- * starts editing again after a wallet-rejection landed them back on `form{notice}`. Mirror of
- * deposit's `regenerating → ready` transition (where the notice clears as a side-effect of
- * the next quote resolving) — withdraw's form has no FSM-driven phase to ride on, so the
- * widget signals it explicitly.
- */
-| {
+} | {
   type: "CLEAR_NOTICE";
 };
 /**
@@ -134,9 +153,10 @@ interface WithdrawController {
  */
 interface WithdrawActions {
   /**
-   * Submits the withdrawal through the driver. Dispatches `SUBMIT` synchronously (so the form
-   * flips to the loading-button state) and then `SUBMIT_CONFIRMED` / `SUBMIT_FAILED` based on
-   * the driver's `submitWithdrawal` resolution.
+   * Submits the withdrawal. Dispatches `SUBMIT` synchronously (so the form flips to the
+   * loading-button state) and then fires the host's `<WithdrawDialog onSubmit>` callback with
+   * the prepared UDA target + a `WithdrawSubmitActions` handle. The kit stays in `submitting`
+   * until the host calls one of those actions (`beginProcessing`, `fail`, `succeed`).
    */
   submit(input: WithdrawalFormSnapshot): void;
   /** Close the dialog. Idempotent. */
@@ -147,10 +167,64 @@ interface WithdrawActions {
    */
   reset(): void;
   /**
-   * Clear the form's inline notice (typically the post-rejection "Signature declined." hint).
-   * No-op when there's no notice or the FSM isn't on `form`.
+   * Clear the form's inline notice. No-op when there's no notice or the FSM isn't on `form`.
    */
   clearNotice(): void;
 }
+/**
+ * Payload the kit hands to the host's `<WithdrawDialog onSubmit>` callback. Carries everything
+ * the host needs to broadcast the source-chain transfer to the UDA (or to validate the request
+ * server-side before broadcasting / queueing).
+ */
+interface WithdrawSubmitInput {
+  /** What the user picked on the form (recipient, amount, receive token + chain). */
+  form: WithdrawalFormSnapshot;
+  /** Where the host should send brand-currency funds to trigger the bridge. */
+  depositTarget: WithdrawPreparation["depositTarget"];
+  /** Stridge correlation slot — useful for backend logs / cross-system traces. */
+  correlation: WithdrawPreparation["correlation"];
+  /** Active quote payload at submit time, when one is available. */
+  quote?: WithdrawalQuotePayload;
+}
+/**
+ * Imperative handles the host's `onSubmit` callback receives. Each action advances the kit's
+ * FSM at the point the host's backend reaches the matching state. All actions are optional —
+ * the host calls only what fits their flow (e.g. backend pre-validates and accepts ⇒
+ * `beginProcessing()`; later the broadcast lands ⇒ `setTxHash({ hash })`; settlement watching
+ * via Stridge takes over from there). The kit also exposes a `signal` for cancellation when
+ * the user closes the dialog mid-submit.
+ */
+interface WithdrawSubmitActions {
+  /**
+   * Move the FSM into `inProgress`. Pass `tx` if a broadcast hash already exists at this point;
+   * otherwise omit — the kit polls `gateway/{owner}` with a best-match heuristic until you
+   * call {@link setTxHash}. Idempotent — calling more than once is a no-op.
+   */
+  beginProcessing(tx?: TxRef): void;
+  /**
+   * Surface a broadcast hash mid-processing. Upgrades the watcher from best-match to
+   * tx-anchored. Legal from `inProgress` or `submitting` (auto-promotes to `inProgress`).
+   */
+  setTxHash(tx: TxRef): void;
+  /**
+   * Mark the withdraw failed. Legal from `submitting` (pre-broadcast rejection) and
+   * `inProgress` (post-broadcast failure). The optional `failure` carries a localized
+   * reason + machine code for analytics; omit when the host has nothing meaningful to
+   * report and just needs to terminate the flow.
+   */
+  fail(failure?: FailureInfo): void;
+  /**
+   * Mark the withdraw succeeded directly. Useful when the host runs their own settlement
+   * verification independently of Stridge's poll. Legal from `submitting` and `inProgress`.
+   */
+  succeed(): void;
+}
+/**
+ * Host-supplied callback fired when the user submits the withdrawal form. The kit hands the
+ * callback the resolved {@link WithdrawSubmitInput} plus a {@link WithdrawSubmitActions} handle
+ * the host calls to advance the FSM. The kit does NOT await the callback's promise — the host
+ * is in control of pacing via the actions. The `signal` aborts when the user closes the dialog.
+ */
+type WithdrawSubmitCallback = (input: WithdrawSubmitInput, actions: WithdrawSubmitActions, signal: AbortSignal) => void | Promise<void>;
 //#endregion
-export { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawalFormSnapshot };
+export { WithdrawActions, WithdrawController, WithdrawEvent, WithdrawState, WithdrawStateName, WithdrawSubmitActions, WithdrawSubmitCallback, WithdrawSubmitInput, WithdrawalFormSnapshot };

package/dist/flows/withdraw/orchestrator/useWithdraw.d.ts

@@ -19,5 +19,22 @@ import { WithdrawController } from "./types.js";
  * ```
  */
 declare function useWithdraw(): WithdrawController;
+/**
+ * Non-throwing variant of {@link useWithdraw} — returns `null` when called outside a
+ * `<KitProvider withdraw={…} />`. Lets hosts mount `<StridgeProvider />` conditionally
+ * (e.g. only after a wallet is connected) without descendants crashing the moment they render
+ * before the provider exists.
+ *
+ * @example
+ * ```tsx
+ * const withdraw = useOptionalWithdraw();
+ * return (
+ *     <button onClick={() => withdraw?.open()} disabled={!withdraw}>
+ *         Withdraw
+ *     </button>
+ * );
+ * ```
+ */
+declare function useOptionalWithdraw(): WithdrawController | null;
 //#endregion
-export { useWithdraw };
+export { useOptionalWithdraw, useWithdraw };

package/dist/flows/withdraw/orchestrator/useWithdraw.js

@@ -1 +1 @@
-"use client";import{useControllerContext as e}from"./controller.js";function t(){return e().controller}export{t as useWithdraw};
+"use client";import{useControllerContext as e,useOptionalControllerContext as t}from"./controller.js";function n(){return e().controller}function r(){return t()?.controller??null}export{r as useOptionalWithdraw,n as useWithdraw};