Sinker - Sinker

Constructor

import { Sinker } from 'sinker-sdk';

const sinker = new Sinker(config: SinkerConfig);

ModelConfig

required

AI model configuration. The agent cannot run without a provider and API key.

{
  provider: 'anthropic',          // 'openai' | 'anthropic' | 'groq' | 'xai'
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-opus-4-5',       // optional — falls back to provider default
}

string

default:"http://localhost:7777"

URL of the running Rust sidecar. Change this if you’ve configured a non-default port or are connecting to a remote sidecar over a tunnel.

number

default:"10000"

HTTP request timeout in milliseconds. Does not apply to SSE streams (those reconnect automatically).

PolicyConfig

In-memory guardrails for the AI agent — tip caps, retry limits, escalation controls. All keys are optional; omitted keys fall back to built-in defaults. The constructor throws SinkerPolicyError if the policy has hard contradictions.

{
  maxTipLamports: 200_000,      // hard ceiling (lamports) — default 500_000
  maxTipRatioPct: 3,            // % of tx value — default 5.0
  tipPercentile: 'p75',         // target percentile — default 'p75'
  staleAfterMs: 2000,           // oracle max age (ms) — default 2000
  maxRetries: 4,                // re-submission attempts — default 3
  expirySlots: 150,             // drop after N slots — default 150
  escalationStepLamports: 5000, // max tip raise per retry — default 5000
  priority: 'auto',             // tier or 'auto' — default 'auto'
}

See the Policy reference for full documentation, validation rules, and the relationship to sinker.policy.json.

The constructor immediately opens a persistent SSE connection to /internal/events. All sinker.on() handlers receive events from this single connection.

Methods

sinker.enqueue()

Enqueue a pre-signed transaction and return a Transaction handle.

const handle = await sinker.enqueue(rawTxBase64, priority?);

string

required

Base64-encoded wire transaction bytes. The transaction must be fully signed before enqueueing — Sinker never handles keypairs.

'normal' | 'high' | 'critical'

default:"'normal'"

Scheduling hint used by the agent when selecting which transactions to bundle first.

Returns: Promise<Transaction> Example:

const tx = buildAndSign(); // your code
const raw = Buffer.from(tx.serialize()).toString('base64');

const handle = await sinker.enqueue(raw, 'high');
console.log(handle.txId);        // "346e5b0e-..."
console.log(handle.enqueuedSlot); // 423602204

sinker.enqueueBatch()

Enqueue multiple transactions in parallel. Useful for batching up to 4 txs into a single Jito bundle.

const handles = await sinker.enqueueBatch([
  { txBytes: rawA },
  { txBytes: rawB, priority: 'high' },
]);

Array<{ txBytes: string; priority?: TxPriority }>

required

Array of transactions to enqueue. Each is assigned an independent tx_id.

Returns: Promise<Transaction[]>

sinker.submit()

Manually trigger a bundle submission. Normally the AI agent calls this automatically — use this only when you’re running without the agent (or in bypass mode) and need direct control over tip and timing.

const result = await sinker.submit({
  tip_lamports: 75000,
  reason: 'manual submission at p75',
  tx_ids: ['346e5b0e-...'],
});

number

required

Tip amount in lamports. Use sinker.getTip() to get live percentile values.

string[]

required

One or more tx_id values from pending transactions. Get them via sinker.getPending().

string

Human-readable rationale string. Written to the lifecycle entry’s ai_decision_trace.

Returns: Promise<SubmitResult>

string

Bundle identifier assigned by Jito (or a synthetic ID on error/fault).

number

Slot at which the bundle was submitted.

boolean

Present and true when the submission was intercepted by the fault injector.

sinker.getMode() / sinker.setMode()

Read or flip the agent’s decision tier at runtime — no restart. cortex reasons on every submission (the default); reflex runs the deterministic fast-path and escalates to the LLM only on exceptions. See AI Agent → Two-tier router.

const { decision_mode } = await sinker.getMode(); // 'reflex' | 'cortex'

await sinker.setMode('reflex');   // fast-path, no model on the common case
await sinker.setMode('cortex');   // full reasoning every cycle

Returns: Promise<ModeState> — { supervised: boolean, decision_mode: 'reflex' | 'cortex' }

sinker.getTip()

Latest tip floor percentiles from the Jito oracle (refreshed every 10 seconds).

const tip = await sinker.getTip();

console.log(tip.p50_lamports);      // 9,500
console.log(tip.p75_lamports);      // 11,400
console.log(tip.p99_lamports);      // 1,000,000
console.log(tip.stale);             // true if >30s old

Returns: Promise<TipFloor>

sinker.getSlot()

Current slot and the validator identity scheduled to lead it.

const { slot, leader } = await sinker.getSlot();

Returns: Promise<ChainState>

sinker.getLifecycle()

Full lifecycle log for all bundle submissions in this sidecar session.

const { count, entries } = await sinker.getLifecycle();

const finalized = entries.filter(e => e.stage === 'finalized');
const failed    = entries.filter(e => e.stage === 'failed');

Returns: Promise<LifecycleLog>

sinker.getPending()

Current pending transaction queue snapshot.

const queue = await sinker.getPending();

console.log(queue.count);           // 2
console.log(queue.evicted_total);   // 0
for (const item of queue.items) {
  console.log(item.tx_id, item.age_slots);
}

Returns: Promise<PendingTxQueue>

sinker.on()

Subscribe to a specific SSE event type. See Events for the full list.

sinker.on('tx_status_changed', (e) => {
  console.log(e.tx_id, '→', e.state);
});

sinker.on('bundle_settled', (e) => {
  console.log('bundle', e.bundle_id, ':', e.stage);
});

Returns: this (chainable)

sinker.off()

Remove a previously registered handler.

const handler = (e: TxStatusChangedEvent) => console.log(e.state);

sinker.on('tx_status_changed', handler);
// ...
sinker.off('tx_status_changed', handler);

sinker.validatePolicy()

Check the current policy for contradictions and dangerous values without throwing. Returns { errors, warnings, valid }.

const result = sinker.validatePolicy();

if (!result.valid) {
  console.error(result.errors);
}
for (const w of result.warnings) {
  console.warn(w);
}

Returns: PolicyValidationResult See the Policy reference for the full list of checks.

sinker.destroy()

Disconnect the SSE stream and free resources. Call this when you’re done with the instance.

sinker.destroy();

Properties

sinker.model

The ModelConfig passed at construction. Read-only.

console.log(sinker.model.provider);  // 'anthropic'

sinker.policy

The fully resolved policy — all defaults filled in. Read-only.

console.log(sinker.policy.maxTipLamports);         // 200000  (your value)
console.log(sinker.policy.tipPercentile);           // 'p75'   (default)
console.log(sinker.policy.escalationStepLamports);  // 5000    (default)

Type: ResolvedPolicy — all 8 fields present, no optionals.

sinker.debug

Access to the DebugClient for fault injection.

await sinker.debug.injectFault('fee_too_low');

​Constructor

​Methods

​sinker.enqueue()

​sinker.enqueueBatch()

​sinker.submit()

​sinker.getMode() / sinker.setMode()

​sinker.getTip()

​sinker.getSlot()

​sinker.getLifecycle()

​sinker.getPending()

​sinker.on()

​sinker.off()

​sinker.validatePolicy()

​sinker.destroy()

​Properties

​sinker.model

​sinker.policy

​sinker.debug

Constructor

Methods

sinker.enqueue()

sinker.enqueueBatch()

sinker.submit()

sinker.getMode() / sinker.setMode()

sinker.getTip()

sinker.getSlot()

sinker.getLifecycle()

sinker.getPending()

sinker.on()

sinker.off()

sinker.validatePolicy()

sinker.destroy()

Properties

sinker.model

sinker.policy

sinker.debug