@turtleclub/opportunities 0.1.0-beta.0

package/src/transaction-status/components/TransactionStatusSection.tsx

@@ -0,0 +1,81 @@
+import { TxStatus } from "@turtleclub/ui";
+import { useMemo } from "react";
+import type { TransactionStep } from "../types";
+import { formatNumber } from "@turtleclub/utils";
+
+interface TransactionStatusSectionProps {
+  steps: TransactionStep[];
+  currentStep: TransactionStep;
+  allCompleted: boolean;
+  cancelled: boolean;
+  tokenSymbol: string;
+  amount: string;
+  resetQueue: () => void;
+  resetForm: () => void;
+  refetchBalances?: () => void;
+}
+
+// Transaction Status Section - Shows TxStatus in the info area
+export function TransactionStatusSection({
+  steps,
+  currentStep,
+  allCompleted,
+  cancelled,
+  tokenSymbol,
+  amount,
+  resetQueue,
+  resetForm,
+  refetchBalances,
+}: TransactionStatusSectionProps) {
+  // For completed transactions, use the last completed transaction hash
+  // For ongoing transactions, use the current step hash
+  const lastCompletedStep = steps
+    .filter((step) => step.status === "completed" && step.txHash)
+    .pop();
+  const currentStepWithHash = currentStep?.txHash ? currentStep : null;
+  const displayTxHash = allCompleted
+    ? lastCompletedStep?.txHash
+    : currentStepWithHash?.txHash || lastCompletedStep?.txHash;
+
+  const txStatusProps = useMemo(
+    () => ({
+      title: cancelled
+        ? "Transaction Cancelled"
+        : allCompleted
+          ? "Transaction Completed!"
+          : "Processing Transaction",
+      description: cancelled
+        ? "Transaction was cancelled by user"
+        : allCompleted
+          ? "Your deposit has been successfully processed."
+          : "Please wait while your transaction is being confirmed...",
+      txHash: displayTxHash,
+      explorerUrl: "https://etherscan.io", // TODO: Get from config
+      estimatedTime: undefined,
+      amount: `${amount ? formatNumber(amount, 5, false, false) : "0"}`,
+      token: tokenSymbol,
+      protocol: "Turtle Protocol",
+      completed: allCompleted,
+      cancelled,
+      onViewDetails: undefined, // Don't show View Details button for now
+      onClose: () => {
+        resetQueue();
+        resetForm();
+        refetchBalances?.();
+      },
+      steps: steps.map((step) => ({
+        label: step.label,
+        completed: step.status === "completed",
+        current: step.status === "executing",
+        txHash: step.txHash,
+      })),
+    }),
+    [steps, allCompleted, cancelled, tokenSymbol, amount, resetQueue, resetForm, refetchBalances, displayTxHash]
+  );
+
+  return (
+    <div className="h-full overflow-hidden">
+      <TxStatus {...txStatusProps} className="bg-background border-border text-foreground h-full" />
+    </div>
+  );
+}

package/src/transaction-status/hooks/useTransactionQueue.ts

@@ -0,0 +1,322 @@
+import { useCallback, useEffect, useMemo, useReducer } from "react";
+import type { EarnRouteResponse, RouterStep, StepTx } from "@turtleclub/hooks";
+import {
+  TransactionStep,
+  TransactionQueueState,
+  TransactionStepStatus,
+  QueueStatus,
+} from "../types";
+import { getStepLabel, getStepDescription, isUserRejection, shouldAutoExecuteNextStep } from "../utils";
+
+/**
+ * useTransactionQueue Hook
+ *
+ * Manages the execution of multiple blockchain transactions in sequence.
+ * Key features:
+ * - Maintains a queue of transaction steps from an EarnRoute
+ * - Executes transactions one by one with proper state management
+ * - Auto-triggers the next transaction after the previous one completes
+ * - Handles errors, user cancellations, and retry logic
+ *
+ * Auto-trigger logic:
+ * 1. After a transaction completes, the hook updates currentIndex to point to the next step
+ * 2. A useEffect monitors state changes and checks if conditions are met for auto-execution
+ * 3. If conditions are met, it automatically triggers the next transaction after a 1s delay
+ * 4. This continues until all transactions in the queue are completed
+ */
+
+// Constants
+const AUTO_EXECUTE_DELAY = 1000; // ms
+
+interface UseTransactionQueueProps {
+  earnRoute: EarnRouteResponse | null;
+  userAddress?: string;
+  chainId?: number;
+  sendTransaction: (transaction: StepTx) => Promise<`0x${string}` | undefined>;
+  onError?: (error: Error) => void;
+  onSuccess?: () => void;
+}
+
+// Reducer action types
+type QueueAction =
+  | { type: "INITIALIZE_QUEUE"; steps: TransactionStep[] }
+  | { type: "START_EXECUTION"; index: number }
+  | { type: "COMPLETE_STEP"; index: number; txHash: string }
+  | { type: "FAIL_STEP"; index: number; error: string; isCancellation: boolean }
+  | { type: "RESET_QUEUE"; steps: TransactionStep[] };
+
+// Helper functions
+function createTransactionStep(step: RouterStep, index: number): TransactionStep | null {
+  // Only process steps that have transaction data
+  if (!step.tx) {
+    return null;
+  }
+
+  const newStep: TransactionStep = {
+    id: index,
+    label: getStepLabel(step),
+    description: getStepDescription(step, index),
+    txData: step.tx,
+    status: "pending",
+  };
+  return newStep;
+}
+
+// Reducer function
+function queueReducer(state: TransactionQueueState, action: QueueAction): TransactionQueueState {
+  switch (action.type) {
+    case "INITIALIZE_QUEUE":
+      return {
+        steps: action.steps,
+        currentIndex: 0,
+        queueStatus: "idle" satisfies QueueStatus,
+        lastError: undefined,
+      };
+
+    case "START_EXECUTION":
+      return {
+        ...state,
+        steps: state.steps.map((step, idx) => {
+          if (idx === action.index) {
+            const updatedStep: TransactionStep = { ...step, status: "executing" };
+            return updatedStep;
+          }
+          return step;
+        }),
+        queueStatus: "executing" satisfies QueueStatus,
+        lastError: undefined,
+      };
+
+    case "COMPLETE_STEP": {
+      const updatedSteps = state.steps.map((step, idx) => {
+        if (idx === action.index) {
+          const completedStep: TransactionStep = { ...step, status: "completed", txHash: action.txHash };
+          return completedStep;
+        }
+        return step;
+      });
+      const nextIndex = action.index + 1;
+      const allCompleted = nextIndex >= updatedSteps.length;
+
+      return {
+        ...state,
+        steps: updatedSteps,
+        currentIndex: allCompleted ? state.currentIndex : nextIndex,
+        queueStatus: (allCompleted ? "completed" : "idle") satisfies QueueStatus,
+      };
+    }
+
+    case "FAIL_STEP":
+      return {
+        ...state,
+        steps: state.steps.map((step, idx) => {
+          if (idx === action.index) {
+            const failedStep: TransactionStep = { ...step, status: "failed", error: action.error };
+            return failedStep;
+          }
+          return step;
+        }),
+        queueStatus: (action.isCancellation ? "cancelled" : "error") satisfies QueueStatus,
+        lastError: action.error,
+      };
+
+    case "RESET_QUEUE":
+      return {
+        steps: action.steps,
+        currentIndex: 0,
+        queueStatus: "idle" satisfies QueueStatus,
+        lastError: undefined,
+      };
+
+    default:
+      return state;
+  }
+}
+
+export function useTransactionQueue({
+  earnRoute,
+  userAddress,
+  chainId,
+  sendTransaction,
+  onError = () => {},
+  onSuccess = () => {},
+}: UseTransactionQueueProps) {
+  // Initialize state with reducer
+  const initialState: TransactionQueueState = {
+    steps: [],
+    currentIndex: 0,
+    queueStatus: "idle",
+  };
+  const [state, dispatch] = useReducer(queueReducer, initialState);
+
+  // Initialize queue when earnRoute changes
+  useEffect(() => {
+    if (!earnRoute?.steps?.length) {
+      dispatch({ type: "INITIALIZE_QUEUE", steps: [] });
+      return;
+    }
+
+    const steps = earnRoute.steps
+      .map((step: RouterStep, index: number) => createTransactionStep(step, index))
+      .filter((step): step is TransactionStep => step !== null);
+
+    dispatch({ type: "INITIALIZE_QUEUE", steps });
+  }, [earnRoute]);
+
+  // Execute current transaction
+  const executeCurrentTransaction = useCallback(async () => {
+    // Validation checks
+    if (!userAddress || !chainId || !sendTransaction || state.queueStatus === "executing") {
+      return;
+    }
+
+    const currentStep = state.steps[state.currentIndex];
+    if (!currentStep || (currentStep.status !== "pending" && currentStep.status !== "failed")) {
+      return;
+    }
+
+    // Security validation: verify transaction 'from' matches connected wallet
+    const txFrom = currentStep.txData.from as `0x${string}`;
+    if (txFrom.toLowerCase() !== userAddress.toLowerCase()) {
+      const error = new Error("Transaction 'from' address doesn't match connected wallet");
+      dispatch({
+        type: "FAIL_STEP",
+        index: state.currentIndex,
+        error: error.message,
+        isCancellation: false,
+      });
+      if (onError) {
+        onError(error);
+      }
+      return;
+    }
+
+    // Start execution
+    dispatch({ type: "START_EXECUTION", index: state.currentIndex });
+
+    try {
+      // Send transaction with chainId
+      const txHash = await sendTransaction({
+        ...currentStep.txData,
+        chainId,
+      });
+
+      // Transaction is already confirmed at this point because executeTransaction waits for confirmation
+      // Mark as completed
+      dispatch({ type: "COMPLETE_STEP", index: state.currentIndex, txHash: txHash ?? "" });
+
+      // Check if all completed and trigger success callback
+      const isLastStep = state.currentIndex + 1 >= state.steps.length;
+      if (isLastStep && onSuccess) {
+        onSuccess();
+      }
+    } catch (error) {
+      // Handle error
+      const errorMessage = error instanceof Error ? error.message : "Transaction failed";
+      const isCancellation = isUserRejection(error);
+
+      dispatch({
+        type: "FAIL_STEP",
+        index: state.currentIndex,
+        error: isCancellation ? "Transaction cancelled by user" : errorMessage,
+        isCancellation,
+      });
+
+      // Call error callback if not a cancellation
+      if (!isCancellation && onError) {
+        onError(error instanceof Error ? error : new Error(errorMessage));
+      }
+    }
+  }, [
+    userAddress,
+    chainId,
+    sendTransaction,
+    state.queueStatus,
+    state.steps,
+    state.currentIndex,
+    onSuccess,
+    onError,
+  ]);
+
+  // Reset queue to initial state
+  const resetQueue = useCallback(() => {
+    if (!earnRoute?.steps?.length) {
+      return;
+    }
+
+    const steps = earnRoute.steps
+      .map((step: RouterStep, index: number) => createTransactionStep(step, index))
+      .filter((step): step is TransactionStep => step !== null);
+
+    dispatch({ type: "RESET_QUEUE", steps });
+  }, [earnRoute]);
+
+  // Computed values
+  const currentStep = state.steps[state.currentIndex] || null;
+  const isExecuting = state.queueStatus === "executing";
+  const allCompleted = state.queueStatus === "completed";
+  const hasError = state.queueStatus === "error";
+  const cancelled = state.queueStatus === "cancelled";
+  const completedSteps = state.steps.filter((step) => step.status === "completed").length;
+  const totalSteps = state.steps.length;
+  const progress = totalSteps > 0 ? (completedSteps / totalSteps) * 100 : 0;
+
+  const showTxStatus = useMemo(() => {
+    if (!currentStep) return false;
+    if (allCompleted) return true;
+    if (isExecuting && currentStep.id === 0) return true;
+    if (currentStep.id > 0) return true;
+    return false;
+  }, [currentStep, allCompleted, isExecuting]);
+
+  // Check if ready to execute
+  const canExecute = !!(
+    userAddress &&
+    chainId &&
+    state.steps.length > 0 &&
+    state.queueStatus !== "executing" &&
+    state.queueStatus !== "completed"
+  );
+
+  // Auto-execute next transaction when current one completes (only for multi-step transactions)
+  useEffect(() => {
+    if (shouldAutoExecuteNextStep(state)) {
+      // Delay execution to allow UI to update
+      const timer = setTimeout(() => {
+        executeCurrentTransaction();
+      }, AUTO_EXECUTE_DELAY);
+
+      // Cleanup timeout on unmount or dependency change
+      return () => clearTimeout(timer);
+    }
+  }, [state, executeCurrentTransaction]);
+
+  // Return value maintaining the same signature
+  return {
+    steps: state.steps.map((step, index) => ({
+      ...step,
+      completed: step.status === "completed",
+      current: index === state.currentIndex,
+    })),
+    currentIndex: state.currentIndex,
+    isExecuting,
+    allCompleted,
+    hasError,
+    cancelled,
+    error: state.lastError,
+    currentStep: currentStep
+      ? {
+          ...currentStep,
+          completed: currentStep.status === "completed",
+          current: true,
+        }
+      : null,
+    canExecute,
+    executeCurrentTransaction,
+    resetQueue,
+    totalSteps,
+    completedSteps,
+    progress,
+    showTxStatus,
+  };
+}

package/src/transaction-status/index.ts

@@ -0,0 +1,8 @@
+export { TransactionStatusSection } from "./components/TransactionStatusSection";
+export { useTransactionQueue } from "./hooks/useTransactionQueue";
+export type {
+  TransactionStep,
+  TransactionQueueState,
+  TransactionStepStatus,
+  QueueStatus,
+} from "./types";

package/src/transaction-status/types/index.ts

@@ -0,0 +1,22 @@
+import type { StepTx } from "@turtleclub/hooks";
+
+export type TransactionStepStatus = "pending" | "executing" | "completed" | "failed";
+
+export interface TransactionStep {
+  id: number;
+  label: string;
+  description: string;
+  txData: StepTx;
+  status: TransactionStepStatus;
+  txHash?: string;
+  error?: string;
+}
+
+export type QueueStatus = "idle" | "executing" | "completed" | "cancelled" | "error";
+
+export interface TransactionQueueState {
+  steps: TransactionStep[];
+  currentIndex: number;
+  queueStatus: QueueStatus;
+  lastError?: string;
+}

package/src/transaction-status/utils/index.ts

@@ -0,0 +1,80 @@
+import type { RouterStep } from "@turtleclub/hooks";
+import type { TransactionQueueState } from "../types";
+
+/**
+ * Generate a user-friendly label for a transaction step
+ * @param step - The router step from the API
+ * @returns A formatted label string
+ */
+export function getStepLabel(step: RouterStep): string {
+  if (step.kind === "approve" && step.token) {
+    return `Approve ${step.token.symbol}`;
+  }
+  if (step.kind === "enso") {
+    return `Execute Deposit`;
+  }
+  return `Execute ${step.kind}`;
+}
+
+/**
+ * Generate a user-friendly description for a transaction step
+ * @param step - The router step from the API
+ * @param index - The step index in the queue
+ * @returns A formatted description string
+ */
+export function getStepDescription(step: RouterStep, index: number): string {
+  if (step.kind === "approve" && step.token) {
+    return `Allow contract to spend ${step.token.symbol}`;
+  }
+  return `Transaction step ${index + 1}`;
+}
+
+/**
+ * Check if an error is a user rejection (e.g., cancelled transaction in wallet)
+ * @param error - The error to check
+ * @returns True if the error indicates user rejection
+ */
+export function isUserRejection(error: Error | unknown): boolean {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const rejectionPatterns = [
+    "user rejected",
+    "user denied",
+    "user cancelled",
+    "cancelled by user",
+    "transaction rejected",
+    "4001", // MetaMask user rejection code
+  ];
+
+  return rejectionPatterns.some((pattern) =>
+    errorMessage.toLowerCase().includes(pattern.toLowerCase())
+  );
+}
+
+/**
+ * Determine if the next transaction step should be auto-executed
+ * This is used for multi-step transaction flows where steps need to be executed sequentially
+ *
+ * @param state - The current transaction queue state
+ * @returns True if the next step should be automatically executed
+ */
+export function shouldAutoExecuteNextStep(state: TransactionQueueState): boolean {
+  // No auto-execute for single step transactions
+  if (state.steps.length <= 1 || state.queueStatus !== "idle") {
+    return false;
+  }
+
+  const previousStep = state.steps[state.currentIndex - 1];
+  const currentStep = state.steps[state.currentIndex];
+
+  // Auto-execute if:
+  // - We've already executed at least one transaction
+  // - Previous step is completed
+  // - Current step is pending
+  // - There are more steps to execute
+  return (
+    state.currentIndex > 0 &&
+    state.currentIndex < state.steps.length &&
+    previousStep?.status === "completed" &&
+    currentStep?.status === "pending"
+  );
+}

package/src/transaction-status/utils/selectors.ts

@@ -0,0 +1,66 @@
+import type { TransactionQueueState } from "../types";
+
+/**
+ * Selectors for computed values from transaction queue state
+ * These are pure functions that derive values from state
+ */
+
+export interface QueueMetrics {
+  completedSteps: number;
+  totalSteps: number;
+  progress: number;
+  isExecuting: boolean;
+  allCompleted: boolean;
+  hasError: boolean;
+  cancelled: boolean;
+  canExecute: boolean;
+}
+
+export function selectQueueMetrics(
+  state: TransactionQueueState,
+  hasRequiredProps: { userAddress?: string; chainId?: number }
+): QueueMetrics {
+  const completedSteps = state.steps.filter((step) => step.status === "completed").length;
+  const totalSteps = state.steps.length;
+  const progress = totalSteps > 0 ? (completedSteps / totalSteps) * 100 : 0;
+
+  const isExecuting = state.queueStatus === "executing";
+  const allCompleted = state.queueStatus === "completed";
+  const hasError = state.queueStatus === "error";
+  const cancelled = state.queueStatus === "cancelled";
+
+  const canExecute = !!(
+    hasRequiredProps.userAddress &&
+    hasRequiredProps.chainId &&
+    state.steps.length > 0 &&
+    state.queueStatus !== "executing" &&
+    state.queueStatus !== "completed"
+  );
+
+  return {
+    completedSteps,
+    totalSteps,
+    progress,
+    isExecuting,
+    allCompleted,
+    hasError,
+    cancelled,
+    canExecute,
+  };
+}
+
+export function selectCurrentStep(state: TransactionQueueState) {
+  return state.steps[state.currentIndex] || null;
+}
+
+export function selectShouldShowTxStatus(state: TransactionQueueState): boolean {
+  const currentStep = selectCurrentStep(state);
+  const isExecuting = state.queueStatus === "executing";
+  const allCompleted = state.queueStatus === "completed";
+
+  if (!currentStep) return false;
+  if (allCompleted) return true;
+  if (isExecuting && currentStep.id === 0) return true;
+  if (currentStep.id > 0) return true;
+  return false;
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}