> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# TransactionStatus

> Transaction execution status

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/transaction-status.ts">
  Run TransactionStatus examples in the interactive playground
</Card>

## Overview

TransactionStatus is a discriminated union type representing the execution status of a transaction: pending, success, or failed.

```typescript theme={null}
import * as TransactionStatus from '@tevm/primitives/TransactionStatus'

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

## Type Definition

```typescript theme={null}
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.

```typescript theme={null}
const status = TransactionStatus.pending()
```

### success

Transaction executed successfully.

```typescript theme={null}
import type { Uint256Type } from '@tevm/primitives/Uint'

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

### failed

Transaction reverted or failed.

```typescript theme={null}
// Without revert reason
const status1 = TransactionStatus.failed()

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

## Type Guards

### isPending

Check if status is pending.

```typescript theme={null}
if (TransactionStatus.isPending(status)) {
  console.log('Transaction pending')
}
```

### isSuccess

Check if status is success (narrows type).

```typescript theme={null}
if (TransactionStatus.isSuccess(status)) {
  console.log('Gas used:', status.gasUsed)
}
```

### isFailed

Check if status is failed (narrows type).

```typescript theme={null}
if (TransactionStatus.isFailed(status)) {
  console.log('Revert reason:', status.revertReason)
}
```

## Usage in Receipts

TransactionStatus appears in receipts to indicate execution outcome:

```typescript theme={null}
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

```typescript theme={null}
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

* [Receipt](/primitives/receipt) - Transaction receipts
* [TransactionHash](/primitives/transaction-hash) - Transaction identifier
* [Uint](/primitives/uint) - Gas amounts