---
title: "Querying a Transaction"
description: "Read, track, and interpret GenLayer transaction state with the v2 lifecycle APIs."
source: https://docs.genlayer.com/developers/decentralized-applications/querying-a-transaction
last_updated: 2026-09-03
---

# Querying a Transaction

GenLayerJS exposes a simple stored transaction view for applications, wait helpers for common completion points, and an advanced lifecycle projection for protocol operators.

## Read stored state

```typescript
import { createClient, isSuccessful } from 'genlayer-js';
import { localnet } from 'genlayer-js/chains';

const client = createClient({ chain: localnet });
const transaction = await client.getTransaction({ hash: txId });

console.log({
  status: transaction.statusName,
  execution: transaction.txExecutionResultName,
  lifecycle: transaction.lifecycle,
  queuePosition: transaction.queuePosition,
  successful: isSuccessful(transaction),
});
```

`getTransaction` reports the persisted transaction and derives `lifecycle` only from that stored state. It does not silently project timeouts or claim that a transaction has finalized before the corresponding state change is stored.

Common fields include:

| Field | Meaning |
|:--|:--|
| `hash` / `txId` | GenLayer transaction identifier. |
| `statusName` | Exact persisted consensus status. |
| `txExecutionResultName` | Contract execution outcome, such as `FINISHED_WITH_RETURN` or `FINISHED_WITH_ERROR`. |
| `lifecycle` | Normalized `processing`, `decided`, `finalized`, or `canceled` view derived from stored state. |
| `queuePosition` | Position while waiting in the recipient contract's queue, when available. |
| `txDataDecoded` | Decoded deploy or call payload. |
| `recipient` | Target contract; for a deployment, the created contract address. |

## Wait for a decision or finalization

```typescript
const decided = await client.waitForDecision({ hash: txId });
const finalized = await client.waitForFinalization({ hash: txId });
```

Use `waitForDecision` when the UI can continue after the transaction has a materialized decision. Use `waitForFinalization` when you need final fee consumption, refunds, or durable completion.

The generic helper is equivalent:

```typescript
const transaction = await client.waitForTransactionReceipt({
  hash: txId,
  waitUntil: 'finalized',
  interval: 5_000,
  retries: 100,
});
```

The older `status` option is deprecated. More importantly, reaching an accepted or finalized status does not by itself prove successful execution; call `isSuccessful(transaction)` as well.

## Read the protocol projection

Keepers, debuggers, and other protocol-aware tools can ask for the action implied by the current deadlines and active decision:

```typescript
const lifecycle = await client.advanced.getTransactionLifecycle({ hash: txId });

console.log({
  stored: lifecycle.storedStatus,
  projected: lifecycle.projectedStatus,
  action: lifecycle.resolutionAction,
  source: lifecycle.resolutionSource,
  decisionId: lifecycle.decisionId,
  decisionActive: lifecycle.decisionActive,
});
```

`resolutionAction === 'Finalize'` is a protocol action, not another transaction status or an independent boolean readiness flag. On an older Studio backend without the lifecycle RPC, the SDK degrades to the stored state it can prove instead of inventing a projected transition.

## Child transactions and traces

```typescript
const children = await client.getTriggeredTransactionIds({ hash: txId });
const trace = await client.debugTraceTransaction({ hash: txId, round: 0 });
```

Use triggered transaction IDs to follow messages emitted by an Intelligent Contract. Use the trace for return data, stdout, stderr, GenVM logs, and round-level execution debugging.

## Polling and process restarts

Persist the transaction ID as soon as submission succeeds. If the application process restarts or a wait times out, resume `getTransaction` / `waitForFinalization` for that ID. Do not infer that the write was never submitted and send it again.

## Related

- [Writing to Intelligent Contracts](./writing-data)
- [Fee Outcomes and Debugging](./fee-outcomes-and-debugging)
- [Transaction and lifecycle API reference](/api-references/genlayer-js/transactions)
- [Transaction Statuses](/understand-genlayer-protocol/core-concepts/transactions/transaction-statuses)