Transaction - Sinker

Overview

sinker.enqueue() returns a Transaction handle — a lightweight object tied to a specific tx_id. Use it to wait for confirmation, inspect status, or retrieve lifecycle history without managing raw HTTP calls.

const handle = await sinker.enqueue(rawTxBase64);

// Wait for on-chain confirmation
const result = await handle.waitFor('finalized');

Properties

string

The tx_id assigned by the sidecar on enqueue. Use this to reference the transaction in other API calls.

number

The slot at which the transaction was enqueued. Blockhashes are valid for 150 slots from their reference slot — monitor age_slots in the pending queue to detect near-expiry transactions.

Methods

handle.waitFor()

Wait until this transaction reaches the specified commitment state. Subscribes to the per-transaction filtered SSE stream at GET /tx/events/:tx_id. Resolves as soon as the target state (or any terminal state) is observed.

const result = await handle.waitFor('finalized', timeoutMs?);

TxState

required

The commitment level to wait for:

'confirmed' — supermajority vote. Fast (~6–8s). Safe for most use cases.
'finalized' — irreversible. Slower (~9–14s). Required for settlement finality.

number

default:"120000"

Maximum wait time in milliseconds before the Promise rejects with a timeout error.

Returns: Promise<WaitResult>

TxState

The actual state that triggered resolution (may be 'finalized' even if you waited for 'confirmed').

string | null

The bundle ID that landed this transaction.

string[]

On-chain signatures. Use these to look up the transaction on Solscan or the Jito explorer.

Throws:

Error if the transaction reaches 'failed' before the target state
Error on timeout

Example:

try {
  const { state, tx_signatures } = await handle.waitFor('finalized');
  console.log('Finalized:', tx_signatures[0]);
} catch (err) {
  if (err.message.includes('failed')) {
    console.log('Transaction failed — check handle.lifecycle() for failure class');
  }
}

handle.status()

Fetch the current status of this transaction from the sidecar. Uses a 3-tier lookup: memory cache → lifecycle log → 404.

const status = await handle.status();

console.log(status.state);          // 'confirmed'
console.log(status.bundle_id);      // 'b9e8b294...'
console.log(status.tx_signatures);  // ['3b9QQcUQ...']
console.log(status.failure);        // null (or 'fee_too_low')
console.log(status.explorer_links); // { solscan: [...], jito: '...' }

Returns: Promise<TxStatus>

handle.lifecycle()

Fetch all lifecycle entries (bundle attempts) for this tx_id. A transaction that was retried after a failure will appear in multiple entries — one per bundle attempt. Inspect the failure and ai_decision_trace fields to understand what happened.

const entries = await handle.lifecycle();

for (const entry of entries) {
  console.log('Attempt:', entry.bundle_id);
  console.log('Stage:',   entry.stage);
  console.log('Failure:', entry.failure?.type ?? 'none');
  console.log('Agent reasoning:', entry.ai_decision_trace);
}

Returns: Promise<LifecycleEntry[]>

handle.rawBytes()

Retrieve the retained base64 transaction bytes for manual retry or inspection. Bytes are captured by the sidecar at submit time and stored in memory for the lifetime of the process. They’re independent of the original signing infrastructure — no keypair needed.

const bytes = await handle.rawBytes();
// bytes is the original base64 wire tx you passed to sinker.enqueue()

Returns: Promise<string>

rawBytes() returns 404 (as a SinkerError) if the transaction has never been submitted — i.e., it’s still in the pending queue. Wait for at least one submit attempt before calling this.

​Overview

​Properties

​Methods

​handle.waitFor()

​handle.status()

​handle.lifecycle()

​handle.rawBytes()

Overview

Properties

Methods

handle.waitFor()

handle.status()

handle.lifecycle()

handle.rawBytes()