Skip to main content

Try it Live

Run TransactionStatus examples in the interactive playground

Overview

TransactionStatus is a discriminated union type representing the execution status of a transaction: pending, success, or failed.
import * as TransactionStatus from '@tevm/primitives/TransactionStatus'

const status = TransactionStatus.success(21000n as Uint256Type)

Type Definition

type TransactionStatusType =
  | { readonly type: "pending" }
  | { readonly type: "success"; readonly gasUsed: Uint256Type }
  | { readonly type: "failed"; readonly revertReason?: string }

Creating Status Values

pending

Transaction not yet mined.
const status = TransactionStatus.pending()

success

Transaction executed successfully.
import type { Uint256Type } from '@tevm/primitives/Uint'

const gasUsed = 21000n as Uint256Type
const status = TransactionStatus.success(gasUsed)

failed

Transaction reverted or failed.
// Without revert reason
const status1 = TransactionStatus.failed()

// With revert reason
const status2 = TransactionStatus.failed('insufficient funds')

Type Guards

isPending

Check if status is pending.
if (TransactionStatus.isPending(status)) {
  console.log('Transaction pending')
}

isSuccess

Check if status is success (narrows type).
if (TransactionStatus.isSuccess(status)) {
  console.log('Gas used:', status.gasUsed)
}

isFailed

Check if status is failed (narrows type).
if (TransactionStatus.isFailed(status)) {
  console.log('Revert reason:', status.revertReason)
}

Usage in Receipts

TransactionStatus appears in receipts to indicate execution outcome:
import * as Receipt from '@tevm/primitives/Receipt'
import * as TransactionStatus from '@tevm/primitives/TransactionStatus'

const receipt = Receipt.from({
  status: TransactionStatus.success(gasUsed),
  // ... other fields
})

// Check status
if (TransactionStatus.isSuccess(receipt.status)) {
  console.log('Transaction succeeded')
}

Handling Different States

function handleStatus(status: TransactionStatusType) {
  if (TransactionStatus.isPending(status)) {
    console.log('Waiting for confirmation...')
  } else if (TransactionStatus.isSuccess(status)) {
    console.log('Success! Gas used:', status.gasUsed)
  } else if (TransactionStatus.isFailed(status)) {
    console.error('Failed:', status.revertReason || 'Unknown error')
  }
}

See Also