@avail-project/widgets 0.0.1

package/dist/common/hooks/useTransactionFlow.js

@@ -0,0 +1,435 @@
+import {} from "@avail-project/nexus-core";
+import { useEffect, useMemo, useCallback, useRef, useState, useReducer, } from "react";
+import { isAddress, parseUnits } from "viem";
+import { CHAIN_METADATA } from "../utils/constant";
+import { useNexusError } from "./useNexusError";
+import { useTransactionExecution } from "./useTransactionExecution";
+import { usePolling } from "./usePolling";
+import { useStopwatch } from "./useStopwatch";
+import { useDebouncedCallback } from "./useDebouncedCallback";
+import {} from "../tx/types";
+import { useTransactionSteps } from "../tx/useTransactionSteps";
+import {} from "../types/transaction-flow";
+import { MAX_AMOUNT_DEBOUNCE_MS, buildInitialInputs, clampAmountToMax, formatAmountForDisplay, getCoverageDecimals, normalizeMaxAmount, } from "../utils/transaction-flow";
+export function useTransactionFlow(props) {
+    const { type, network, nexusSDK, intent, bridgableBalance, prefill, onComplete, onStart, onError, fetchBalance, allowance, maxAmount, isSourceMenuOpen = false, notifyHistoryRefresh, executeTransaction, } = props;
+    const connectedAddress = props.connectedAddress;
+    const operationName = type === "bridge" ? "bridge" : "transfer";
+    const handleNexusError = useNexusError();
+    const initialState = {
+        inputs: buildInitialInputs({ type, network, connectedAddress, prefill }),
+        status: "idle",
+    };
+    function reducer(state, action) {
+        switch (action.type) {
+            case "setInputs":
+                return { ...state, inputs: { ...state.inputs, ...action.payload } };
+            case "resetInputs":
+                return {
+                    ...state,
+                    inputs: buildInitialInputs({
+                        type,
+                        network,
+                        connectedAddress,
+                        prefill,
+                    }),
+                };
+            case "setStatus":
+                return { ...state, status: action.payload };
+            default:
+                return state;
+        }
+    }
+    const [state, dispatch] = useReducer(reducer, initialState);
+    const inputs = state.inputs;
+    const setInputs = (next) => {
+        dispatch({
+            type: "setInputs",
+            payload: next,
+        });
+    };
+    const loading = state.status === "executing";
+    const [refreshing, setRefreshing] = useState(false);
+    const [isDialogOpen, setIsDialogOpen] = useState(false);
+    const [txError, setTxError] = useState(null);
+    const [lastExplorerUrl, setLastExplorerUrl] = useState("");
+    const previousConnectedAddressRef = useRef(connectedAddress);
+    const maxAmountRequestIdRef = useRef(0);
+    const [selectedSourceChains, setSelectedSourceChains] = useState(null);
+    const [selectedSourcesMaxAmount, setSelectedSourcesMaxAmount] = useState(null);
+    const [appliedSourceSelectionKey, setAppliedSourceSelectionKey] = useState("ALL");
+    const { steps, onStepsList, onStepComplete, reset: resetSteps, } = useTransactionSteps();
+    const configuredMaxAmount = useMemo(() => normalizeMaxAmount(maxAmount), [maxAmount]);
+    const areInputsValid = useMemo(() => {
+        const hasToken = inputs?.token !== undefined && inputs?.token !== null;
+        const hasChain = inputs?.chain !== undefined && inputs?.chain !== null;
+        const hasAmount = Boolean(inputs?.amount) && Number(inputs?.amount) > 0;
+        const hasValidRecipient = Boolean(inputs?.recipient) && isAddress(inputs.recipient);
+        return hasToken && hasChain && hasAmount && hasValidRecipient;
+    }, [inputs]);
+    const filteredBridgableBalance = useMemo(() => {
+        const found = bridgableBalance?.find((bal) => inputs?.token === "USDM"
+            ? bal?.symbol === "USDC"
+            : bal?.symbol === inputs?.token);
+        if (!found)
+            return undefined;
+        const breakdown = found.chainBalances?.map((cb) => ({
+            balance: cb.balance,
+            balanceInFiat: Number.parseFloat(cb.value),
+            chain: cb.chain,
+        })) ?? found.breakdown ?? [];
+        return {
+            ...found,
+            breakdown,
+        };
+    }, [bridgableBalance, inputs?.token]);
+    const availableSources = useMemo(() => {
+        const breakdown = filteredBridgableBalance?.breakdown ?? [];
+        const destinationChainId = inputs?.chain;
+        const nonZero = breakdown.filter((source) => {
+            if (Number.parseFloat(source.balance ?? "0") <= 0)
+                return false;
+            if (typeof destinationChainId === "number") {
+                return source.chain.id !== destinationChainId;
+            }
+            return true;
+        });
+        const decimals = filteredBridgableBalance?.decimals;
+        if (!nexusSDK || typeof decimals !== "number") {
+            return nonZero.sort((a, b) => Number.parseFloat(b.balance) - Number.parseFloat(a.balance));
+        }
+        return nonZero.sort((a, b) => {
+            try {
+                const aRaw = parseUnits(a.balance ?? "0", decimals);
+                const bRaw = parseUnits(b.balance ?? "0", decimals);
+                if (aRaw === bRaw)
+                    return 0;
+                return aRaw > bRaw ? -1 : 1;
+            }
+            catch {
+                return Number.parseFloat(b.balance) - Number.parseFloat(a.balance);
+            }
+        });
+    }, [
+        inputs?.chain,
+        filteredBridgableBalance?.breakdown,
+        filteredBridgableBalance?.decimals,
+        nexusSDK,
+    ]);
+    const allAvailableSourceChainIds = useMemo(() => availableSources.map((source) => source.chain.id), [availableSources]);
+    const effectiveSelectedSourceChains = useMemo(() => {
+        if (selectedSourceChains && selectedSourceChains.length > 0) {
+            const availableSet = new Set(allAvailableSourceChainIds);
+            const filteredSelection = selectedSourceChains.filter((id) => availableSet.has(id));
+            if (filteredSelection.length > 0) {
+                return filteredSelection;
+            }
+        }
+        return allAvailableSourceChainIds;
+    }, [selectedSourceChains, allAvailableSourceChainIds]);
+    const sourceChainsForSdk = effectiveSelectedSourceChains.length > 0
+        ? effectiveSelectedSourceChains
+        : undefined;
+    const sourceSelectionKey = useMemo(() => {
+        if (allAvailableSourceChainIds.length === 0)
+            return "NONE";
+        if (!selectedSourceChains || selectedSourceChains.length === 0) {
+            return "ALL";
+        }
+        return [...effectiveSelectedSourceChains].sort((a, b) => a - b).join("|");
+    }, [
+        allAvailableSourceChainIds.length,
+        effectiveSelectedSourceChains,
+        selectedSourceChains,
+    ]);
+    const hasPendingSourceSelectionChanges = sourceSelectionKey !== appliedSourceSelectionKey;
+    const intentSourceSpendAmount = intent.current?.intent?.sourcesTotal;
+    const getMaxForCurrentSelection = useCallback(async () => {
+        if (!nexusSDK || !inputs?.token || !inputs?.chain)
+            return undefined;
+        let totalMax = 0;
+        const selectedChainSet = new Set(sourceChainsForSdk ?? allAvailableSourceChainIds);
+        for (const source of availableSources) {
+            if (!selectedChainSet.has(source.chain.id))
+                continue;
+            const balVal = Number.parseFloat(source.balance ?? "0");
+            if (balVal <= 0)
+                continue;
+            let chainMax = balVal;
+            const chainMeta = CHAIN_METADATA[source.chain.id];
+            const nativeSymbol = chainMeta?.nativeCurrency?.symbol;
+            if (nativeSymbol && inputs.token === nativeSymbol) {
+                chainMax = Math.max(0, chainMax - 0.003);
+            }
+            totalMax += chainMax;
+        }
+        const amountStr = totalMax.toString();
+        return clampAmountToMax({
+            amount: amountStr,
+            maxAmount: configuredMaxAmount,
+            nexusSDK,
+            token: inputs.token,
+            chainId: inputs.chain,
+        });
+    }, [
+        configuredMaxAmount,
+        inputs?.chain,
+        inputs?.token,
+        nexusSDK,
+        sourceChainsForSdk,
+        allAvailableSourceChainIds,
+        availableSources,
+    ]);
+    const toggleSourceChain = useCallback((chainId) => {
+        setSelectedSourceChains((prev) => {
+            if (allAvailableSourceChainIds.length === 0)
+                return prev;
+            const current = prev && prev.length > 0 ? prev : allAvailableSourceChainIds;
+            const next = current.includes(chainId)
+                ? current.filter((id) => id !== chainId)
+                : [...current, chainId];
+            if (next.length === 0) {
+                return current;
+            }
+            const isAllSelected = next.length === allAvailableSourceChainIds.length &&
+                allAvailableSourceChainIds.every((id) => next.includes(id));
+            return isAllSelected ? null : next;
+        });
+    }, [allAvailableSourceChainIds]);
+    const sourceSelection = useMemo(() => {
+        const amount = intentSourceSpendAmount?.trim() ?? inputs?.amount?.trim() ?? "";
+        const decimals = getCoverageDecimals({
+            type,
+            token: inputs?.token,
+            chainId: inputs?.chain,
+            fallback: filteredBridgableBalance?.decimals,
+        });
+        const selectedChainSet = new Set(effectiveSelectedSourceChains);
+        const selectedTotalRaw = !nexusSDK || typeof decimals !== "number"
+            ? BigInt(0)
+            : availableSources.reduce((sum, source) => {
+                if (!selectedChainSet.has(source.chain.id))
+                    return sum;
+                try {
+                    return sum + parseUnits(source.balance ?? "0", decimals);
+                }
+                catch {
+                    return sum;
+                }
+            }, BigInt(0));
+        const selectedTotal = !nexusSDK || typeof decimals !== "number"
+            ? "0"
+            : formatAmountForDisplay(selectedTotalRaw, decimals, nexusSDK);
+        const baseSelection = {
+            selectedTotal,
+            requiredTotal: amount || "0",
+            requiredSafetyTotal: amount || "0",
+            missingToProceed: "0",
+            missingToSafety: "0",
+            coverageState: "healthy",
+            coverageToSafetyPercent: 100,
+            isBelowRequired: false,
+            isBelowSafetyBuffer: false,
+        };
+        if (!nexusSDK || !inputs?.token || !inputs?.chain || !amount) {
+            return baseSelection;
+        }
+        try {
+            const requiredRaw = nexusSDK.convertTokenReadableAmountToBigInt(amount, inputs.token, inputs.chain);
+            if (requiredRaw <= BigInt(0)) {
+                return baseSelection;
+            }
+            const missingToProceedRaw = selectedTotalRaw >= requiredRaw
+                ? BigInt(0)
+                : requiredRaw - selectedTotalRaw;
+            const missingToSafetyRaw = missingToProceedRaw;
+            const coverageState = selectedTotalRaw < requiredRaw ? "error" : "healthy";
+            const coverageBasisPoints = requiredRaw === BigInt(0)
+                ? 10_000
+                : selectedTotalRaw >= requiredRaw
+                    ? 10_000
+                    : Number((selectedTotalRaw * BigInt(10_000)) / requiredRaw);
+            return {
+                selectedTotal,
+                requiredTotal: amount,
+                requiredSafetyTotal: amount,
+                missingToProceed: formatAmountForDisplay(missingToProceedRaw, decimals, nexusSDK),
+                missingToSafety: formatAmountForDisplay(missingToSafetyRaw, decimals, nexusSDK),
+                coverageState,
+                coverageToSafetyPercent: coverageBasisPoints / 100,
+                isBelowRequired: coverageState === "error",
+                isBelowSafetyBuffer: coverageState === "error",
+            };
+        }
+        catch {
+            return baseSelection;
+        }
+    }, [
+        type,
+        filteredBridgableBalance?.decimals,
+        nexusSDK,
+        inputs?.chain,
+        inputs?.amount,
+        inputs?.token,
+        intentSourceSpendAmount,
+        availableSources,
+        effectiveSelectedSourceChains,
+    ]);
+    const stopwatch = useStopwatch({ intervalMs: 100 });
+    const setStatus = useCallback((status) => dispatch({ type: "setStatus", payload: status }), []);
+    const resetInputs = useCallback(() => {
+        dispatch({ type: "resetInputs" });
+    }, []);
+    const { refreshIntent, handleTransaction, startTransaction, commitAmount, reset, invalidatePendingExecution, } = useTransactionExecution({
+        operationName,
+        nexusSDK,
+        intent,
+        allowance,
+        inputs,
+        configuredMaxAmount,
+        allAvailableSourceChainIds,
+        sourceChainsForSdk,
+        sourceSelectionKey,
+        sourceSelection,
+        loading,
+        txError,
+        areInputsValid,
+        executeTransaction,
+        getMaxForCurrentSelection,
+        onStepsList,
+        onStepComplete,
+        resetSteps,
+        setStatus,
+        resetInputs,
+        setRefreshing,
+        setIsDialogOpen,
+        setTxError,
+        setLastExplorerUrl,
+        setSelectedSourceChains,
+        setAppliedSourceSelectionKey,
+        stopwatch,
+        handleNexusError,
+        onStart,
+        onComplete,
+        onError,
+        fetchBalance,
+        notifyHistoryRefresh,
+    });
+    usePolling(Boolean(intent.current) &&
+        !isDialogOpen &&
+        !isSourceMenuOpen &&
+        !hasPendingSourceSelectionChanges, async () => {
+        await refreshIntent();
+    }, 15000);
+    const debouncedRefreshMaxForSelection = useDebouncedCallback(async (requestId) => {
+        try {
+            const maxForCurrentSelection = await getMaxForCurrentSelection();
+            if (requestId !== maxAmountRequestIdRef.current)
+                return;
+            setSelectedSourcesMaxAmount(maxForCurrentSelection ?? "0");
+        }
+        catch (error) {
+            if (requestId !== maxAmountRequestIdRef.current)
+                return;
+            console.error("Unable to calculate max for selected sources:", error);
+            setSelectedSourcesMaxAmount("0");
+        }
+    }, MAX_AMOUNT_DEBOUNCE_MS);
+    useEffect(() => {
+        debouncedRefreshMaxForSelection.cancel();
+        if (!nexusSDK || !inputs?.token || !inputs?.chain) {
+            maxAmountRequestIdRef.current += 1;
+            setSelectedSourcesMaxAmount(null);
+            return;
+        }
+        if (allAvailableSourceChainIds.length === 0) {
+            maxAmountRequestIdRef.current += 1;
+            setSelectedSourcesMaxAmount("0");
+            return;
+        }
+        const requestId = ++maxAmountRequestIdRef.current;
+        debouncedRefreshMaxForSelection(requestId);
+    }, [
+        allAvailableSourceChainIds.length,
+        configuredMaxAmount,
+        debouncedRefreshMaxForSelection,
+        inputs?.recipient,
+        sourceSelectionKey,
+        inputs?.chain,
+        inputs?.token,
+        nexusSDK,
+    ]);
+    useEffect(() => {
+        if (type !== "bridge" || !connectedAddress)
+            return;
+        const previousConnectedAddress = previousConnectedAddressRef.current;
+        if (!previousConnectedAddress) {
+            previousConnectedAddressRef.current = connectedAddress;
+            return;
+        }
+        if (connectedAddress === previousConnectedAddress)
+            return;
+        previousConnectedAddressRef.current = connectedAddress;
+        if (prefill?.recipient)
+            return;
+        if (!inputs?.recipient || inputs.recipient === previousConnectedAddress) {
+            dispatch({ type: "setInputs", payload: { recipient: connectedAddress } });
+        }
+    }, [type, connectedAddress, inputs?.recipient, prefill?.recipient]);
+    useEffect(() => {
+        invalidatePendingExecution();
+    }, [inputs, invalidatePendingExecution]);
+    useEffect(() => {
+        setSelectedSourceChains(null);
+    }, [inputs?.token]);
+    useEffect(() => {
+        if (isDialogOpen)
+            return;
+        stopwatch.stop();
+        stopwatch.reset();
+        if (state.status === "success" || state.status === "error") {
+            resetSteps();
+            setLastExplorerUrl("");
+            setStatus("idle");
+        }
+    }, [isDialogOpen, resetSteps, setStatus, state.status, stopwatch]);
+    useEffect(() => {
+        if (txError) {
+            setTxError(null);
+        }
+    }, [inputs, txError]);
+    return {
+        inputs,
+        setInputs,
+        timer: stopwatch.seconds,
+        setIsDialogOpen,
+        setTxError,
+        loading,
+        refreshing,
+        isDialogOpen,
+        txError,
+        handleTransaction,
+        reset,
+        filteredBridgableBalance,
+        startTransaction,
+        commitAmount,
+        lastExplorerUrl,
+        steps,
+        status: state.status,
+        availableSources,
+        selectedSourceChains: effectiveSelectedSourceChains,
+        toggleSourceChain,
+        isSourceSelectionInsufficient: sourceSelection.isBelowRequired,
+        isSourceSelectionBelowSafetyBuffer: sourceSelection.isBelowSafetyBuffer,
+        isSourceSelectionReadyForAccept: sourceSelection.coverageState === "healthy",
+        sourceCoverageState: sourceSelection.coverageState,
+        sourceCoveragePercent: sourceSelection.coverageToSafetyPercent,
+        missingToProceed: sourceSelection.missingToProceed,
+        missingToSafety: sourceSelection.missingToSafety,
+        selectedTotal: sourceSelection.selectedTotal,
+        requiredTotal: sourceSelection.requiredTotal,
+        requiredSafetyTotal: sourceSelection.requiredSafetyTotal,
+        maxAvailableAmount: selectedSourcesMaxAmount ?? undefined,
+        isInputsValid: areInputsValid,
+    };
+}

package/dist/common/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./hooks/useStopwatch";
+export * from "./hooks/usePolling";
+export * from "./hooks/useInterval";
+export * from "./hooks/useStableCallback";
+export * from "./hooks/useLatest";
+export * from "./hooks/useDebouncedValue";
+export * from "./hooks/useDebouncedCallback";
+export * from "./hooks/useNexusError";
+export * from "./hooks/useTransactionFlow";
+export * from "./types/transaction-flow";
+export * from "./tx/types";
+export * from "./tx/steps";
+export * from "./tx/useTransactionSteps";
+export * from "./utils/constant";
+export * from "./utils/token-pricing";
+export * from "./components/ErrorBoundary";
+//# sourceMappingURL=index.d.ts.map

package/dist/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../.build-src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/common/index.js

@@ -0,0 +1,16 @@
+export * from "./hooks/useStopwatch";
+export * from "./hooks/usePolling";
+export * from "./hooks/useInterval";
+export * from "./hooks/useStableCallback";
+export * from "./hooks/useLatest";
+export * from "./hooks/useDebouncedValue";
+export * from "./hooks/useDebouncedCallback";
+export * from "./hooks/useNexusError";
+export * from "./hooks/useTransactionFlow";
+export * from "./types/transaction-flow";
+export * from "./tx/types";
+export * from "./tx/steps";
+export * from "./tx/useTransactionSteps";
+export * from "./utils/constant";
+export * from "./utils/token-pricing";
+export * from "./components/ErrorBoundary";

package/dist/common/tx/steps.d.ts

@@ -0,0 +1,19 @@
+import type { SwapStepType } from "../types/transaction-flow";
+import type { GenericStep } from "./types";
+/**
+ * Predefined expected steps for swaps to seed UI before events arrive.
+ * Kept here to avoid duplication across exact-in and exact-out hooks.
+ */
+export declare const SWAP_EXPECTED_STEPS: SwapStepType[];
+export declare function seedSteps<T>(expected: T[]): Array<GenericStep<T>>;
+export declare function computeAllCompleted<T>(steps: Array<GenericStep<T>>): boolean;
+/**
+ * Replace the current list of steps with a new list, preserving completion
+ * for any steps that were already marked completed (matched by key).
+ */
+export declare function mergeStepsList<T>(prev: Array<GenericStep<T>>, list: T[]): Array<GenericStep<T>>;
+/**
+ * Mark a step complete in-place; if the step doesn't yet exist, append it.
+ */
+export declare function mergeStepComplete<T>(prev: Array<GenericStep<T>>, step: T): Array<GenericStep<T>>;
+//# sourceMappingURL=steps.d.ts.map

package/dist/common/tx/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../.build-src/common/tx/steps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAAY,EA0B7C,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMjE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAE5E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EAAE,GACR,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAkBvB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,GACN,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBvB"}

package/dist/common/tx/steps.js

@@ -0,0 +1,89 @@
+import { getStepKey } from "./types";
+/**
+ * Predefined expected steps for swaps to seed UI before events arrive.
+ * Kept here to avoid duplication across exact-in and exact-out hooks.
+ */
+export const SWAP_EXPECTED_STEPS = [
+    { type: "SWAP_START", typeID: "SWAP_START" },
+    { type: "DETERMINING_SWAP", typeID: "DETERMINING_SWAP" },
+    {
+        type: "CREATE_PERMIT_FOR_SOURCE_SWAP",
+        typeID: "CREATE_PERMIT_FOR_SOURCE_SWAP",
+    },
+    {
+        type: "SOURCE_SWAP_BATCH_TX",
+        typeID: "SOURCE_SWAP_BATCH_TX",
+    },
+    {
+        type: "SOURCE_SWAP_HASH",
+        typeID: "SOURCE_SWAP_HASH",
+    },
+    { type: "RFF_ID", typeID: "RFF_ID" },
+    {
+        type: "DESTINATION_SWAP_BATCH_TX",
+        typeID: "DESTINATION_SWAP_BATCH_TX",
+    },
+    {
+        type: "DESTINATION_SWAP_HASH",
+        typeID: "DESTINATION_SWAP_HASH",
+    },
+    { type: "SWAP_COMPLETE", typeID: "SWAP_COMPLETE" },
+];
+export function seedSteps(expected) {
+    return expected.map((st, index) => ({
+        id: index,
+        completed: false,
+        step: st,
+    }));
+}
+export function computeAllCompleted(steps) {
+    return steps.length > 0 && steps.every((s) => s.completed);
+}
+/**
+ * Replace the current list of steps with a new list, preserving completion
+ * for any steps that were already marked completed (matched by key).
+ */
+export function mergeStepsList(prev, list) {
+    const completedKeys = new Set();
+    for (const prevStep of prev) {
+        if (prevStep.completed) {
+            completedKeys.add(getStepKey(prevStep.step));
+        }
+    }
+    const next = [];
+    for (let index = 0; index < list.length; index++) {
+        const step = list[index];
+        const key = getStepKey(step);
+        next.push({
+            id: index,
+            completed: completedKeys.has(key),
+            step,
+        });
+    }
+    return next;
+}
+/**
+ * Mark a step complete in-place; if the step doesn't yet exist, append it.
+ */
+export function mergeStepComplete(prev, step) {
+    const key = getStepKey(step);
+    const updated = [];
+    let found = false;
+    for (const s of prev) {
+        if (getStepKey(s.step) === key) {
+            updated.push({ ...s, completed: true, step: { ...s.step, ...step } });
+            found = true;
+        }
+        else {
+            updated.push(s);
+        }
+    }
+    if (!found) {
+        updated.push({
+            id: updated.length,
+            completed: true,
+            step,
+        });
+    }
+    return updated;
+}

package/dist/common/tx/types.d.ts

@@ -0,0 +1,11 @@
+export type TransactionStatus = "idle" | "preview" | "awaiting-approval" | "executing" | "success" | "error";
+export type GenericStep<TStep> = {
+    id: number;
+    completed: boolean;
+    step: TStep;
+};
+/**
+ * Normalizes a step to a stable key. Prefers typeID, then type, otherwise JSON.
+ */
+export declare function getStepKey(step: any): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/common/tx/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../.build-src/common/tx/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,SAAS,GACT,mBAAmB,GACnB,WAAW,GACX,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAa5C"}

package/dist/common/tx/types.js

@@ -0,0 +1,19 @@
+/**
+ * Normalizes a step to a stable key. Prefers typeID, then type, otherwise JSON.
+ */
+export function getStepKey(step) {
+    if (!step)
+        return "";
+    if (typeof step.typeID === "string" && step.typeID.length > 0) {
+        return step.typeID;
+    }
+    if (typeof step.type === "string" && step.type.length > 0) {
+        return step.type;
+    }
+    try {
+        return JSON.stringify(step);
+    }
+    catch {
+        return String(step);
+    }
+}

package/dist/common/tx/useTransactionSteps.d.ts

@@ -0,0 +1,21 @@
+import type { GenericStep } from "./types";
+interface UseTransactionStepsOptions<T> {
+    expected?: T[];
+}
+/**
+ * Manages transaction steps with utilities to seed from expected steps,
+ * replace the list on "steps list" events, and mark individual steps complete.
+ */
+export declare function useTransactionSteps<T extends {
+    typeID?: string;
+    type?: string;
+}>(options?: UseTransactionStepsOptions<T>): {
+    steps: GenericStep<T>[];
+    allCompleted: boolean;
+    onStepsList: (list: T[]) => void;
+    onStepComplete: (step: T) => void;
+    seed: (expectedSteps: T[]) => void;
+    reset: () => void;
+};
+export {};
+//# sourceMappingURL=useTransactionSteps.d.ts.map

package/dist/common/tx/useTransactionSteps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTransactionSteps.d.ts","sourceRoot":"","sources":["../../../.build-src/common/tx/useTransactionSteps.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAS3C,UAAU,0BAA0B,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,SAAS;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAO,GAAE,0BAA0B,CAAC,CAAC,CAAM;;;wBAOhB,CAAC,EAAE;2BAUA,CAAC;0BAIF,CAAC,EAAE;;EAmBjC"}