useWorkflowLifecycle()

function useWorkflowLifecycle(workflow, options?): UseWorkflowLifecycleResult;

Beta

Runs a prepared workflow on mount and owns its lifecycle: phase, the operation snapshot, and the WorkflowSettlement it ends in.

This is the headless half of the SDK’s executor surfaces — WorkflowExecutor and TransactionWorkflowDialog render it and add nothing but presentation. Settlement is returned state rather than only a callback, so a consumer that renders this hook cannot silently ignore a failure the way an omitted callback used to.

Parameters

Parameter	Type	Description
workflow	WalletOperationWorkflow	Prepared workflow to run on mount.
options	UseWorkflowLifecycleOptions	Terminal operations from an earlier run, which suppress execution entirely, and an onSettled callback. See UseWorkflowLifecycleOptions.

Returns

UseWorkflowLifecycleResult

Where the run stands (phase), the advancing operations snapshot, and the WorkflowSettlement it ended in — undefined while running and for a run that settled nothing, such as a cancelled or interrupted one.

Remarks

Part of the SDK’s experimental React surface — may change or be removed without notice and is not part of the compatibility contract.

Throws

Error when rendered outside <AnvilProvider>, by way of useExecuteWorkflow. A workflow that fails settles rather than throwing, and a throwing onSettled callback is swallowed so it cannot rewrite the settlement.

Example

export function RunWorkflow({
  workflow,
}: {
  workflow: WalletOperationWorkflow;
}) {
  // Runs on mount. `settlement` is returned state, so a surface that
  // renders this hook cannot silently drop a failure.
  const { phase, settlement } = useWorkflowLifecycle(workflow);

  if (phase === 'preflighting') return <p>Checking current state…</p>;
  if (phase === 'executing') return <p>Waiting for wallet…</p>;
  if (phase === 'idle') return <p>Starting…</p>;
  return <p>{getWorkflowSettlementMessage(settlement) ?? 'Done.'}</p>;
}