Debug - Sinker

Debug methods are intended for testing only. Do not call injectFault() in production — it will cause the next real submission to return a synthetic failure.

Overview

The sinker.debug object provides access to the fault injection system. Register a fault before enqueueing a transaction to simulate any failure class on demand.

// Register a fee_too_low fault
await sinker.debug.injectFault('fee_too_low');

// Enqueue a real transaction — the next submit will be faulted
const handle = await sinker.enqueue(rawTxBase64);

// The agent retries automatically
const result = await handle.waitFor('finalized');

Methods

debug.injectFault()

const result = await sinker.debug.injectFault(failureClass, rawError?);

FaultClass

required

The failure class to inject. One of:

'fee_too_low'
'expired_blockhash'
'bundle_failed'
'compute_exceeded'
'slot_skip'

string

Optional custom error string stored in the lifecycle entry’s raw_error field. Defaults to "Injected fault: {failureClass} (demo)".

Returns: Promise<FaultInjectResult>

boolean

true when the fault was registered successfully.

FaultClass

The failure class that was registered (echoed back for confirmation).

Example — test each failure class:

const faultClasses = [
  'fee_too_low',
  'expired_blockhash',
  'slot_skip',
] as const;

for (const fc of faultClasses) {
  await sinker.debug.injectFault(fc);
  const handle = await sinker.enqueue(rawTxBase64);

  const entries = await handle.lifecycle();
  const faulted = entries.find(e => e.stage === 'failed');
  console.log(fc, '→', faulted?.failure?.type);
}

debug.runFaultDemo()

const { faultRegistered, tx_id } = await sinker.debug.runFaultDemo(
  'fee_too_low',
  rawTxBase64,
);

console.log('Fault registered:', faultRegistered);
console.log('Transaction ID:', tx_id);

FaultClass

required

The failure class to inject.

string

required

Base64-encoded pre-signed transaction bytes.

Returns: Promise<{ faultRegistered: boolean; tx_id: string }>

What the sidecar does on a faulted submit

When a fault is registered and POST /internal/submit is called:

The tx queue is drained normally and bytes are retained for retry
The fault spec is consumed (cleared from next_fault)
A lifecycle entry is written with stage: "failed" and the specified failure_class
TxStatusChanged SSE events are emitted for each tx_id
A BundleSettled SSE event fires with stage: "failed" and failure_type
HTTP 200 is returned with a structured result — no Jito call is made

The agent receives the SSE events and executes its normal retry policy, including fetching raw bytes via GET /tx/raw/:tx_id and re-enqueueing.

Fault coverage

All five failure classes have been validated against the full agent retry cycle on mainnet-beta:

Class	Fault injected	Agent retry	Result
`fee_too_low`	✅	Escalate tip to p95	✅ PASS
`expired_blockhash`	✅	Re-enqueue (fresh blockhash)	✅ PASS
`bundle_failed`	✅	Inspect error → retry	✅ PASS
`compute_exceeded`	✅	Hold (instruction broken)	✅ PASS
`slot_skip`	✅	Re-enqueue (same tip)	✅ PASS

​Overview

​Methods

​debug.injectFault()

​debug.runFaultDemo()

​What the sidecar does on a faulted submit

​Fault coverage

Overview

Methods

debug.injectFault()

debug.runFaultDemo()

What the sidecar does on a faulted submit

Fault coverage