Skip to main content

​
Status Types

Types for tracking execution progress and transaction status.

​
StepStatusPayload

Enhanced status payload for individual step callbacks. 
interface StepStatusPayload {
  /** Step identifier */
  stepId: string;
  /** Type of step */
  step: StepType;
  /** Current status */
  status: 'pending' | 'active' | 'completed' | 'failed';
  /** Transaction hash (if submitted) */
  txHash: string | null;
  /** Error (if failed) */
  error: Error | null;
  /** Timestamp of last update */
  timestamp: number;
}

​
Properties

PropertyTypeDescription
stepIdstringUnique identifier for this step
stepStepTypeType of operation: 'approval', 'swap', 'bridge', or 'deposit'
statusstringCurrent status of the step
txHashstring | nullTransaction hash once submitted, null before submission
errorError | nullError object if step failed, null otherwise
timestampnumberUnix timestamp of the last status update

​
Step Status Values

StatusDescription
'pending'Step has not started yet
'active'Step is currently executing (also shown as 'in_progress')
'completed'Step finished successfully
'failed'Step encountered an error

​
Example

const result = await mina.execute({
  quote,
  signer,
  onStepChange: (payload: StepStatusPayload) => {
    console.log(`Step ${payload.stepId}: ${payload.status}`);

    if (payload.status === 'active') {
      console.log('Transaction submitted:', payload.txHash);
    }

    if (payload.status === 'failed') {
      console.error('Step failed:', payload.error?.message);
    }
  },
});

​
TransactionStatusPayload

Status payload for overall transaction progress tracking. 
interface TransactionStatusPayload {
  /** Overall status */
  status: 'pending' | 'in_progress' | 'completed' | 'failed';
  /** Substatus for detailed state */
  substatus: string;
  /** Current step index (1-based for UI display) */
  currentStep: number;
  /** Total number of steps */
  totalSteps: number;
  /** Input amount */
  fromAmount: string;
  /** Output amount (or expected) */
  toAmount: string | null;
  /** Bridge transaction hash */
  txHash: string;
  /** Receiving transaction hash on destination chain */
  receivingTxHash: string | null;
  /** Progress percentage (0-100) */
  progress: number;
  /** Estimated time remaining in seconds */
  estimatedTime: number;
}

​
Properties

PropertyTypeDescription
statusstringOverall execution status
substatusstringDetailed substatus message (e.g., “WAIT_SOURCE_CONFIRMATIONS”)
currentStepnumberCurrent step number (1-based for UI)
totalStepsnumberTotal number of steps in the execution
fromAmountstringInput amount being bridged
toAmountstring | nullOutput amount (may be null until confirmed)
txHashstringMain bridge transaction hash
receivingTxHashstring | nullTransaction hash on destination chain
progressnumberProgress percentage from 0 to 100
estimatedTimenumberEstimated seconds remaining

​
Example

const result = await mina.execute({
  quote,
  signer,
  onStatusChange: (payload: TransactionStatusPayload) => {
    // Update progress bar
    setProgress(payload.progress);

    // Show current step
    setStatusText(`Step ${payload.currentStep} of ${payload.totalSteps}`);

    // Display detailed status
    console.log('Substatus:', payload.substatus);

    if (payload.receivingTxHash) {
      console.log('Receiving tx:', payload.receivingTxHash);
    }
  },
});

​
ExecutionStatusType

Enum-like type for overall execution status. 
type ExecutionStatusType =
  | 'idle'
  | 'approving'
  | 'approved'
  | 'executing'
  | 'bridging'
  | 'completed'
  | 'failed';

​
Status Flow

idle -> approving -> approved -> executing -> bridging -> completed
                                    |            |
                                    v            v
                                 failed       failed

​
Values

ValueDescription
'idle'No execution in progress
'approving'Token approval transaction pending
'approved'Token approval confirmed
'executing'Main bridge transaction executing
'bridging'Cross-chain transfer in progress
'completed'Bridge completed successfully
'failed'Execution failed at some step

​
StepType

Type of execution step. 
type StepType = 'approval' | 'swap' | 'bridge' | 'deposit';

​
Values

ValueDescription
'approval'ERC20 token approval for spending
'swap'Token swap on source or destination chain
'bridge'Cross-chain bridge transfer
'deposit'Deposit to Hyperliquid L1 trading account

​
StepStatus (Internal)

Internal status tracking for individual steps. 
interface StepStatus {
  /** Step ID */
  stepId: string;
  /** Step type */
  stepType?: StepType;
  /** Current status */
  status: 'pending' | 'executing' | 'completed' | 'failed';
  /** Transaction hash (if submitted) */
  txHash?: string;
  /** Error message (if failed) */
  error?: string;
  /** Timestamp of last update */
  updatedAt: number;
}

​
Callback Types

Type definitions for status callbacks. 
/** Callback type for step changes */
type OnStepChange = (stepStatus: StepStatusPayload) => void;

/** Callback type for overall status changes */
type OnStatusChange = (status: TransactionStatusPayload) => void;

​
Example: Complete Status Handling

import type {
  OnStepChange,
  OnStatusChange,
  StepStatusPayload,
  TransactionStatusPayload
} from '@mina-bridge/sdk';

const handleStepChange: OnStepChange = (step: StepStatusPayload) => {
  switch (step.status) {
    case 'pending':
      console.log(`Waiting for ${step.step}...`);
      break;
    case 'active':
      console.log(`${step.step} in progress: ${step.txHash}`);
      break;
    case 'completed':
      console.log(`${step.step} completed`);
      break;
    case 'failed':
      console.error(`${step.step} failed: ${step.error?.message}`);
      break;
  }
};

const handleStatusChange: OnStatusChange = (status: TransactionStatusPayload) => {
  updateUI({
    progress: status.progress,
    currentStep: status.currentStep,
    totalSteps: status.totalSteps,
    message: status.substatus,
  });
};

await mina.execute({
  quote,
  signer,
  onStepChange: handleStepChange,
  onStatusChange: handleStatusChange,
});