@stridge/kit 0.1.0-alpha.6 → 0.1.0-alpha.61

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

@@ -1,4 +1,5 @@
 import { Entity, SettlementFailureKind, TxRef } from "../../../shared/driver/types.js";
+import { FormattedField } from "../../../shared/format/types.js";
 import { ReceiveOptionDto, ReceiveOptionsResponse, WithdrawableBalanceDto, WithdrawableBalancesResponse, WithdrawalQuoteDto, WithdrawalQuoteResponse, WithdrawalSettlementDto, WithdrawalSettlementResponse } from "./dto.js";
 import { ReceiveChainPayload, ReceiveTokenOptionPayload, WithdrawableBalanceItemPayload, WithdrawalQuoteBreakdownPayload, WithdrawalQuotePayload, WithdrawalReceiveAssetPayload, WithdrawalSettlementFailurePayload, WithdrawalSettlementPayload, WithdrawalSettlementPendingPayload, WithdrawalSettlementSuccessPayload } from "./payloads.js";
 
@@ -8,8 +9,9 @@ import { ReceiveChainPayload, ReceiveTokenOptionPayload, WithdrawableBalanceItem
  * {@link WithdrawDriver.getSnapshot} and consumed by `useSyncExternalStore`. The kit's
  * `useWithdrawSnapshot()` hook returns this shape.
  *
- * Each field is an {@link Entity} envelope — components switch on `status` and read `payload` on
- * the `ready` / `stale` variants.
+ * Most fields are {@link Entity} envelopes — components switch on `status` and read `payload` on
+ * the `ready` / `stale` variants. The optional `minAmountUsd` / `maxAmountUsd` carry static
+ * config-derived USD bounds (set once at driver construction) and stay outside the entity model.
  */
 interface WithdrawSnapshot {
   /**
@@ -23,7 +25,7 @@ interface WithdrawSnapshot {
   withdrawableBalances: Entity<ReadonlyArray<WithdrawableBalanceItemPayload>, WithdrawableBalancesResponse, WithdrawableBalancesResponse>;
   /**
    * Per-chain catalog of routable receive destinations. Drives the form's "Receive chain" /
-   * "Receive token" pickers. Derived from `Uda.supportedAssets()`.
+   * "Receive token" pickers. Derived from `Gateway.assets()`.
    */
   receiveOptions: Entity<ReadonlyArray<ReceiveChainPayload>, ReadonlyArray<ReceiveOptionDto>, ReceiveOptionsResponse>;
   /**
@@ -37,6 +39,18 @@ interface WithdrawSnapshot {
    * error state screen renders.
    */
   settlement: Entity<WithdrawalSettlementPayload, WithdrawalSettlementDto, WithdrawalSettlementResponse>;
+  /**
+   * Optional lower USD bound on the withdraw amount. The withdraw form blocks submit with a
+   * localized "Min $X" CTA when the typed amount sits below `value`. Set from
+   * `<StridgeProvider flows.withdraw.minAmountUsd>` and constant across the driver's lifetime.
+   */
+  minAmountUsd?: FormattedField<number>;
+  /**
+   * Optional upper USD bound on the withdraw amount. The withdraw form blocks submit with a
+   * localized "Max $X" CTA when the typed amount sits above `value`. Set from
+   * `<StridgeProvider flows.withdraw.maxAmountUsd>` and constant across the driver's lifetime.
+   */
+  maxAmountUsd?: FormattedField<number>;
 }
 /**
  * Input to {@link WithdrawDriver.requestQuote}. The form widget builds this from current field
@@ -57,17 +71,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
@@ -107,16 +161,25 @@ interface WithdrawDriver {
   getSnapshot(): WithdrawSnapshot;
   /** Subscribe to entity transitions outside React (analytics, headless integrations). */
   subscribe(listener: () => void): () => void;
+  /**
+   * Idempotent bootstrap trigger. The kit calls this from `useWithdraw().open()` and the
+   * headless `usePrefetchWithdraw()` hook. First call kicks off any deferred network work
+   * (e.g. `supportedAssets` + the initial `balance/onchain` fetch); subsequent calls are
+   * no-ops while bootstrap is in flight or completed.
+   */
+  arm(): void;
   /**
    * Fetches a fresh quote for `input` and updates the `quote` entity through its lifecycle
    * (`idle | loading → ready | error`). The `signal` cancels in-flight work.
    */
   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 +193,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{useOptionalActivityDriverInstance as e}from"../../activity/driver/context.js";import{useLingui as t}from"../../../shared/i18n/useLingui.js";import"../../../i18n/index.js";import{toFailure as n}from"../../../shared/orchestrator/toFailure.js";import{useDriverSettlementListener as r}from"../../../shared/orchestrator/useDriverSettlementListener.js";import{useEffectiveState as i}from"../../../shared/orchestrator/useEffectiveState.js";import{useSettlementWatcher as a}from"../../../shared/orchestrator/useSettlementWatcher.js";import"../../../shared/orchestrator/index.js";import{useWithdrawBindingsRef as o}from"../bindings/WithdrawBindings.js";import"../bindings/index.js";import{useWithdrawDriverInstance as s}from"../driver/context.js";import{initialState as c,reducer as l}from"./reducer.js";import{createContext as u,use as d,useCallback as f,useEffect as p,useMemo as m,useReducer as h,useRef as g}from"react";import{jsx as _}from"react/jsx-runtime";const v={id:`ldK3jJ`,message:`Failed to submit withdrawal.`},y={id:`kUFhUv`,message:`Withdrawal failed.`},b={id:`srsA0x`,message:`Withdrawal declined.`},x=u(null);x.displayName=`WithdrawControllerContext`;function S(){let e=d(x);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 C(){return d(x)}function w(){return S().state}function T(){return S().effectiveState}function E(){return S().actions}function D({children:t}){let n=s(),r=e(),[o,u]=h(l,c),d=k(o,u,n,r),f=o.name===`inProgress`?{form:o.ctx.input,submittedAt:o.ctx.submittedAt,...o.ctx.tx?{tx:o.ctx.tx}:{}}:void 0;a(n,f,f?`${f.submittedAt}|${f.tx?.hash??``}`:void 0),A(r,o.name===`activityList`||o.name===`activityDetail`),j(o,u,n);let p=i(o),g=O(u,d,n);return _(x,{value:m(()=>({state:o,effectiveState:p,dispatch:u,controller:g,actions:d}),[o,p,g,d]),children:t})}function O(e,t,n){let r=g(n);r.current=n;let i=f(t=>(r.current.arm(),e({type:`OPEN`}),!0),[e]),a=f(()=>{e({type:`CLOSE`})},[e]);return m(()=>({open:i,close:a,actions:t}),[i,a,t])}function k(e,r,i,a){let s=g(e);s.current=e;let c=g(i);c.current=i;let l=g(a);l.current=a;let u=g(r);u.current=r;let{i18n:d}=t(),p=g(d);p.current=d;let h=o(),_=f(e=>{let t=c.current;u.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){u.current({type:`BEGIN_PROCESSING`,submittedAt:Date.now(),...e?{tx:e}:{}});try{l.current?.invalidateActivity?.()}catch{}},setTxHash(e){u.current({type:`SET_TX_HASH`,tx:e,submittedAt:Date.now()})},fail(e){u.current({type:`MARK_FAILED`,...e?{failure:e}:{}})},decline(){u.current({type:`SUBMIT_FAILED`,failure:{reason:p.current._(b),code:`UserRejectedRequestError`},input:e})},succeed(){u.current({type:`MARK_SUCCEEDED`})}};t.prepareWithdrawal(i,r.signal).then(i=>{if(r.signal.aborted)return;let o=h.current.onSubmit;if(!o){u.current({type:`SUBMIT_FAILED`,failure:n(Error(`WithdrawDialog onSubmit is missing.`),p.current._(v)),input:e});return}let s=t.getSnapshot().quote,c=s.status===`ready`||s.status===`stale`?s.payload:void 0;try{let t=o({form:e,depositTarget:i.depositTarget,correlation:i.correlation,...c?{quote:c}:{}},a,r.signal);t&&typeof t.catch==`function`&&t.catch(t=>{r.signal.aborted||u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})})}catch(t){if(r.signal.aborted)return;u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})}}).catch(t=>{r.signal.aborted||u.current({type:`SUBMIT_FAILED`,failure:n(t,p.current._(v)),input:e})})},[]),y=f(()=>{u.current({type:`CLOSE`})},[]),x=f(()=>{u.current({type:`RESET`})},[]),S=f(()=>{u.current({type:`CLEAR_NOTICE`})},[]),C=f(()=>{u.current({type:`BACK`})},[]),w=f(()=>{if(l.current==null){process.env.NODE_ENV!==`production`&&console.warn("[@stridge/kit] useWithdrawActions().openActivity() was called but no activity driver is mounted. Wrap the host with `<KitProvider activity={…}>` (or `<StridgeProvider>` with any flow enabled) to enable the activity surface.");return}s.current.name===`form`&&u.current({type:`OPEN_ACTIVITY`})},[]),T=f(e=>{u.current({type:`SELECT_SETTLEMENT`,settlementId:e})},[]);return m(()=>({submit:_,close:y,reset:x,clearNotice:S,back:C,openActivity:w,selectSettlement:T}),[_,y,x,S,C,w,T])}function A(e,t){p(()=>{if(!t||!e)return;let n=new AbortController;return e.watchActivity(n.signal),()=>n.abort()},[t,e])}function j(e,n,i){let a=g(e);a.current=e;let{i18n:o}=t(),s=g(o);s.current=o,r(i,(e,t)=>{if(a.current.name===`inProgress`){if(e===`succeeded`){n({type:`SETTLEMENT_SUCCEEDED`});return}if(e===`failed`){let e=t.settlement,r=e.status===`ready`||e.status===`stale`?e.payload:null,i=r&&r.kind===`failed`?{reason:s.current._(y),code:r.failureKind}:void 0;n({type:`SETTLEMENT_FAILED`,...i?{failure:i}:{}})}}})}export{D as WithdrawControllerProvider,S as useControllerContext,C as useOptionalControllerContext,E as useWithdrawActions,T as useWithdrawEffectiveState,w 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, usePrefetchWithdraw, 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{createActivityReducers as e}from"../../../shared/orchestrator/createActivityReducers.js";import{isUserRejectionFailure as t}from"../../../shared/orchestrator/userRejection.js";import"../../../shared/orchestrator/index.js";import{assertNever as n}from"../../../shared/utils/assertNever.js";const r={name:`closed`},{reduceFromActivityList:i,reduceFromActivityDetail:a}=e({activityList:e=>({name:`activityList`,ctx:{backTarget:e}}),activityDetail:(e,t,n)=>({name:`activityDetail`,ctx:{settlementId:e,backTarget:t,viaList:n}}),closed:()=>({name:`closed`}),restoreFromBackTarget:e=>p(e)});function o(e,t){switch(e.name){case`closed`:return s(t);case`form`:return c(e,t);case`submitting`:return l(e,t);case`inProgress`:return u(e,t);case`success`:return d(e,t);case`error`:return f(e,t);case`activityList`:return i(e,t);case`activityDetail`:return a(e,t);default:return n(e)}}function s(e){return e.type===`OPEN`?{name:`form`}:{name:`closed`}}function c(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`OPEN_ACTIVITY`:return{name:`activityList`,ctx:{backTarget:{kind:`form`,...e.ctx?.notice?{notice:e.ctx.notice}:{}}}};case`CLOSE`:return{name:`closed`};default:return e}}function l(e,n){switch(n.type){case`BEGIN_PROCESSING`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:n.submittedAt,...n.tx?{tx:n.tx}:{}}};case`SET_TX_HASH`:return{name:`inProgress`,ctx:{input:e.ctx.input,submittedAt:n.submittedAt,tx:n.tx}};case`MARK_SUCCEEDED`:return{name:`success`,ctx:{input:e.ctx.input}};case`MARK_FAILED`:return{name:`error`,ctx:{input:e.ctx.input,...n.failure?{failure:n.failure}:{}}};case`SUBMIT_FAILED`:return t(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 e}}function u(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 d(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function f(e,t){switch(t.type){case`RESET`:return{name:`form`};case`CLOSE`:return{name:`closed`};default:return e}}function p(e){return e.notice?{name:`form`,ctx:{notice:e.notice}}:{name:`form`}}export{r as initialState,o 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
@@ -20,24 +21,43 @@ interface WithdrawalFormSnapshot {
   receiveTokenSymbol: string;
   /** Receive-side chain id (EIP-155 numeric). */
   receiveChainId: number;
+  /**
+   * Pre-formatted USD figure the form displayed under the amount input at submit time. Carried
+   * through the FSM so the in-progress / success heroes can render the same dollar value the
+   * user just saw on the form, before the indexer prices the settlement legs. Optional because
+   * the form's USD computation already returns `undefined` for invalid amounts; the snapshot
+   * mirrors that. Pre-formatted (locale-aware) — the orchestrator does not re-format.
+   */
+  amountUsd?: string;
+}
+/**
+ * Where `BACK` lands when the user exits the activity surface. Encoded once at `OPEN_ACTIVITY`
+ * time — the in-flow header icon is the only way into withdraw activity now (direct-entry
+ * migrated to `useActivity()`), so the form is always the source step.
+ */
+interface ActivityBackTarget {
+  kind: "form";
+  notice?: string;
 }
 /**
- * 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,27 +70,56 @@ 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;
   };
+} | {
+  /**
+   * Activity list — reachable from `form` via the header icon. `backTarget`
+   * snapshots the source state (including any inline notice) at `OPEN_ACTIVITY` time so
+   * the back chevron can restore it lossless.
+   */
+  name: "activityList";
+  ctx: {
+    backTarget: ActivityBackTarget;
+  };
+} | {
+  /**
+   * Activity per-settlement detail — reached from `activityList` via
+   * `SELECT_SETTLEMENT`. Carries the selected row's id, the same `backTarget` so `BACK`
+   * collapses through `activityList` to the original source step, and a `viaList` flag
+   * that disambiguates "reached via the list" from "reached imperatively"; the latter
+   * skips the list interlude on `BACK`. For direct-entry into the activity surface,
+   * see {@link useActivity}.
+   */
+  name: "activityDetail";
+  ctx: {
+    settlementId: string;
+    backTarget: ActivityBackTarget;
+    viaList: boolean;
+  };
 };
 /**
  * Public state-name discriminator — useful for analytics and React-side gating without unwrapping
@@ -79,21 +128,41 @@ 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";
+  /** Lifecycle entry. Always lands the FSM on `form`. */type: "OPEN";
 } | {
   type: "CLOSE";
 } | {
   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,24 +170,48 @@ 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";
+} | {
+  /**
+   * User tapped the back chevron. Legal only from `activityList` / `activityDetail` today —
+   * the form step has no source to return to (closing the dialog is `CLOSE`). Two-step
+   * collapse: `activityDetail → activityList → source`.
+   */
+  type: "BACK";
+} | {
+  /**
+   * User tapped the header activity icon. Legal from `form`; ignored elsewhere. Snapshots
+   * the source state into a {@link ActivityBackTarget} so the back chevron can restore it
+   * lossless (including any inline notice surfaced after a recent submit failure).
+   */
+  type: "OPEN_ACTIVITY";
+} | {
+  /**
+   * User tapped a row in the activity list. Legal only from `activityList`; transitions
+   * to `activityDetail` carrying the selected `settlementId`.
+   */
+  type: "SELECT_SETTLEMENT";
+  settlementId: string;
 };
+/**
+ * Public open-input variant accepted by `useWithdraw().open()`. Today the withdraw flow has no
+ * `{ method }` arm — opening always lands on `form`.
+ *
+ * For direct-entry into the activity surface, see {@link useActivity}.
+ */
+type WithdrawOpenInput = undefined;
 /**
  * Imperative controller returned by `useWithdraw()`. Mirrors {@link import("#/flows/deposit/orchestrator").DepositController}'s
  * surface so hosts can drive both flows symmetrically. Stable across re-renders.
  */
 interface WithdrawController {
-  /** Open the withdraw dialog. Idempotent. */
-  open(): void;
+  /**
+   * Open the withdraw dialog on `form`. Returns `true` whenever the open() call advanced the
+   * dialog past its guards — there is no per-method disable lever on withdraw, so the only
+   * `false` path is reserved for forward compatibility. Idempotent.
+   */
+  open(input?: WithdrawOpenInput): boolean;
   /** Close the withdraw dialog. Idempotent. */
   close(): void;
   /**
@@ -134,9 +227,11 @@ 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`, `setTxHash`, `decline`,
+   * `fail`, `succeed`).
    */
   submit(input: WithdrawalFormSnapshot): void;
   /** Close the dialog. Idempotent. */
@@ -147,10 +242,98 @@ 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;
+  /**
+   * Back-chevron action. Today the chevron is only rendered on the activity step
+   * (detail → list → source); other steps either render no chevron or close directly via
+   * {@link close}.
+   */
+  back(): void;
+  /**
+   * Header-icon entry into the activity surface. Legal from `form`; ignored elsewhere.
+   * Snapshots the current state into a {@link ActivityBackTarget} so `back()` can restore it
+   * lossless. No-ops with a dev-mode warning when no activity driver is mounted (host wired the
+   * action without `<KitProvider activity={…}>`).
+   */
+  openActivity(): void;
+  /**
+   * Open the detail view for a settlement listed on the activity surface. Legal only from
+   * `activityList`; transitions the FSM to `activityDetail`.
+   */
+  selectSettlement(settlementId: string): 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.
+   *
+   * For user-rejection (the user said no in their wallet), prefer {@link decline} so the
+   * kit can emit `withdraw.submission.declined` instead of `withdraw.submission.failed`.
+   */
+  fail(failure?: FailureInfo): void;
+  /**
+   * Mark the withdraw as user-declined. Use when the user explicitly refused a wallet
+   * prompt or backed out of a host-side confirmation step. The kit routes the FSM back to
+   * `form{notice}` (same as the wallet-rejection heuristic) and emits
+   * `withdraw.submission.declined` on the unified bus — distinct from `*.failed` because
+   * declining is a user choice, not an error. Analytics that count `.failed` events stay
+   * accurate.
+   *
+   * Legal from `submitting`. When the host doesn't call this explicitly, the kit's
+   * built-in rejection heuristic still classifies wallet-rejection-shaped errors as
+   * declines automatically.
+   */
+  decline(): 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,40 @@ 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;
+/**
+ * Headless prefetch handle for the withdraw driver. Returns a stable function that arms the
+ * driver — kicks off the deferred `supportedAssets` + initial `balance/onchain` bootstrap.
+ * Calling it before the user opens the dialog warms the cache so the subsequent
+ * `useWithdraw().open()` lands on populated data without a perceptible loading window.
+ *
+ * Fire-and-forget: returns `void`. Observe bootstrap state via
+ * `useWithdrawSnapshot().receiveOptions.status` if needed.
+ *
+ * ```tsx
+ * const withdraw = useWithdraw();
+ * const prefetchWithdraw = usePrefetchWithdraw();
+ * <button onMouseEnter={prefetchWithdraw} onClick={() => withdraw.open()}>Withdraw</button>;
+ * ```
+ *
+ * Idempotent — subsequent calls are no-ops while the driver is already armed.
+ */
+declare function usePrefetchWithdraw(): () => void;
 //#endregion
-export { useWithdraw };
+export { useOptionalWithdraw, usePrefetchWithdraw, 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{useWithdrawDriverInstance as e}from"../driver/context.js";import{useControllerContext as t,useOptionalControllerContext as n}from"./controller.js";import{useCallback as r}from"react";function i(){return t().controller}function a(){return n()?.controller??null}function o(){let t=e();return r(()=>{t.arm()},[t])}export{a as useOptionalWithdraw,o as usePrefetchWithdraw,i as useWithdraw};

package/dist/flows/withdraw/widgets/activity/WithdrawActivityDetail.d.ts

@@ -0,0 +1,39 @@
+import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/flows/withdraw/widgets/activity/WithdrawActivityDetail.d.ts
+interface WithdrawActivityDetailOwnProps {
+  /**
+   * Optional custom composition forwarded to the underlying `<ActivityDetail>`
+   * compound. Defaults to mounting all three per-kind parts.
+   */
+  children?: ReactNode;
+}
+/**
+ * Orchestrated activity detail wrapper for the withdraw dialog. Mirrors
+ * {@link import("#/flows/deposit/widgets/activity").DepositActivityDetail}. Renders
+ * `null` while the FSM is not on `activityDetail`.
+ */
+declare function WithdrawActivityDetail({
+  children
+}: WithdrawActivityDetailOwnProps): _$react_jsx_runtime0.JSX.Element | null;
+declare namespace WithdrawActivityDetail {
+  type Props = WithdrawActivityDetailOwnProps;
+  const Processing: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+  const Succeeded: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+  const Failed: ({
+    children
+  }: {
+    children?: ReactNode;
+  }) => _$react_jsx_runtime0.JSX.Element | null;
+}
+//#endregion
+export { WithdrawActivityDetail };

package/dist/flows/withdraw/widgets/activity/WithdrawActivityDetail.js

@@ -0,0 +1 @@
+"use client";import{ActivitySourceProvider as e}from"../../../../shared/widgets/activity/compound/context.js";import{ActivityDetail as t}from"../../../../shared/widgets/activity/compound/ActivityDetail.js";import"../../../../shared/widgets/activity/compound/index.js";import{useWithdrawActivitySource as n}from"./useWithdrawActivitySource.js";import{jsx as r}from"react/jsx-runtime";function i({children:i}){let{sourceValue:a,step:o}=n();return o!==`activityDetail`||!a?null:r(e,{value:a,children:r(t,{children:i})})}(function(e){e.Processing=t.Processing,e.Succeeded=t.Succeeded,e.Failed=t.Failed})(i||={});export{i as WithdrawActivityDetail};