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

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

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:

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:

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

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.

GenLayer JS Reading Data from Intelligent Contracts