Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// MEV-aware execution engine — the single protected broadcast path for every
// agent-signed trade on three.ws (the sniper worker + both discretionary trade
// endpoints).
//
// submitProtected({ network, connection, payer, instructions, opts })
// → { signature, slot, route, tipLamports, priorityFeeMicroLamports, attempts, landedMs }
//
// What it does, all with REAL on-chain / Jito calls (never a simulated landing
// or a fabricated fee):
//
// 1. Dynamic compute budget. Prepends ComputeBudgetProgram.setComputeUnitLimit
// from a REAL simulateTransaction unit estimate (not a guess) and
// setComputeUnitPrice from a REAL priority-fee estimate — Helius
// getPriorityFeeEstimate when HELIUS_API_KEY is set, falling back to the
// getRecentPrioritizationFees 75th-percentile. Both estimates are cached
// briefly so the hot snipe path doesn't re-pay for them every tick.
//
// 2. Jito bundle route. When tipMode is 'economy'|'turbo' AND a Jito Block
// Engine is reachable on mainnet, it fetches the live tip-floor, appends a
// REAL SOL tip transfer to a Jito tip account as the last instruction, and
// submits the signed tx as a single-tx bundle via sendBundle. It then polls
// getBundleStatuses for a real landing. Tip sizing is adaptive: it scales
// with the mode and the live tip-floor and escalates on retry.
//
// 3. Transparent fallback. Devnet, tipMode 'off', no Jito, or a Jito error all
// fall back to the protected single-tx route (sendRawTransaction + confirm)
// and SAY SO in the returned `route`/`fallbackReason`. A bundle that doesn't
// land within the poll window is reported as not-landed and retried on the
// protected route — never claimed as landed.
//
// 4. Adaptive retry. Simulate first (skippable for a pre-simulated caller); on
// blockhash expiry or a not-landed bundle, refresh the blockhash, escalate
// the priority fee + tip, and re-submit up to a bounded count. Honest
// landing telemetry (route, attempts, tip, fee, landedMs) is returned.
//
// Idempotency / double-spend safety is the CALLER's responsibility (the sniper's
// per-(agent,mint) lock + DB claim, the endpoints' idempotency key). Re-sending
// the same signed tx to a second RPC or a bundle is safe — Solana dedupes by
// signature, and a landed tx confirms regardless of which lane carried it.
import {
ComputeBudgetProgram,
PublicKey,
SystemProgram,
TransactionMessage,
VersionedTransaction,
} from '@solana/web3.js';
import { pollConfirmation } from './solana/confirm.js';
import { fetchUpstream } from './upstream-fetch.js';
import { resolveLandingProviders } from './landing-providers.js';
import { getLandingStats, raceLanes, rpcLane, rpcProbe } from './landing-race.js';
import { tipAccountAt } from '../../packages/avatar-agent-mcp/src/lib/jito-tip-accounts.js';
// A bundle's tip must transfer SOL to one of Jito's tip accounts. The shared
// module serves the engine's live getTipAccounts list (cached, refreshed in the
// background so the snipe path never waits on it) with a pinned fallback. We
// rotate per-attempt to spread load and avoid a hot account.
const DEFAULT_JITO_URL = 'https://mainnet.block-engine.jito.wtf';
// Jito's public regional block engines. Every region serves the same bundle API
// at the same path, so the configured (or default) engine leads and the others
// are the alternates a network error or 5xx on the send fails over to. A bundle
// is only ever re-sent when the first engine gave NO answer about it: a JSON-RPC
// rejection or a 4xx is an answer and is never retried on another host.
const JITO_REGION_URLS = [
DEFAULT_JITO_URL,
'https://ny.mainnet.block-engine.jito.wtf',
'https://amsterdam.mainnet.block-engine.jito.wtf',
'https://frankfurt.mainnet.block-engine.jito.wtf',
'https://tokyo.mainnet.block-engine.jito.wtf',
'https://slc.mainnet.block-engine.jito.wtf',
];
// Deadlines. The fee + tip-floor reads sit on the hot snipe path and have safe
// fallbacks (the connection's own fee sample, the mode floor), so they get a
// short budget; the bundle send is the one that matters and gets 10s.
const HELIUS_FEE_TIMEOUT_MS = 4_000;
const JITO_TIP_FLOOR_TIMEOUT_MS = 4_000;
const JITO_SEND_TIMEOUT_MS = 10_000;
const JITO_STATUS_TIMEOUT_MS = 4_000;
const LAMPORTS_PER_SOL = 1_000_000_000;
// ── adaptive tip sizing (lamports) ────────────────────────────────────────────
// A tip is real SOL leaving the wallet, so the floors are deliberately modest and
// the ceiling hard-caps any single tip. 'economy' rides near the live tip-floor;
// 'turbo' pays a multiple for first-block inclusion under contention. Each retry
// escalates the chosen tip toward the ceiling.
const TIP_PROFILE = {
economy: { floor: 10_000n, multiplier: 1.5, ceiling: 1_000_000n },
turbo: { floor: 100_000n, multiplier: 4, ceiling: 5_000_000n },
};
// Compute-unit price floors per mode (microLamports/CU) — a lower bound so the tx
// is never priced below what the network currently demands even if the estimate
// reads abnormally low. Turbo bids the network fee up alongside the bundle tip.
const CU_PRICE_FLOOR = { off: 1_000, economy: 5_000, turbo: 25_000 };
const CU_PRICE_CEILING = 5_000_000; // hard cap on microLamports/CU
const MAX_ATTEMPTS = 3;
const BUNDLE_POLL_MS = 700; // between getBundleStatuses polls
const BUNDLE_POLL_TIMEOUT_MS = 12_000; // give a bundle this long to land before falling back
// ── brief estimate caches (per lambda instance) ──────────────────────────────
// Keyed by network. The hot snipe path calls submitProtected on every fill; these
// keep the priority-fee + tip-floor reads off the critical path for a few seconds
// without ever serving a stale-enough value to misprice a tx.
const PRIORITY_FEE_TTL_MS = 4_000;
const TIP_FLOOR_TTL_MS = 4_000;
const _priorityFeeCache = new Map(); // network → { at, microLamports }
const _tipFloorCache = new Map(); // jitoUrl → { at, lamports }
function jitoBlockEngineUrl() {
const u = (process.env.JITO_BLOCK_ENGINE_URL || DEFAULT_JITO_URL).trim();
return u.replace(/\/+$/, '');
}
/** The configured engine first, then every other public region, deduplicated. */
function jitoBlockEngineUrls() {
const primary = jitoBlockEngineUrl();
return [primary, ...JITO_REGION_URLS.filter((u) => u !== primary)];
}
/** A Jito bundle route is only attempted on mainnet with a non-'off' tip mode. */
function jitoEligible(network, tipMode) {
return network !== 'devnet' && (tipMode === 'economy' || tipMode === 'turbo');
}
function pickTipAccount(attempt) {
return tipAccountAt(attempt, { baseUrl: jitoBlockEngineUrl() });
}
function clampBig(v, min, max) {
if (v < min) return min;
if (v > max) return max;
return v;
}
// ── priority fee estimate (microLamports per CU) ──────────────────────────────
// Helius getPriorityFeeEstimate first (it reads the global fee market, not just
// this node's recent blocks); falls back to the connection's
// getRecentPrioritizationFees 75th percentile. Cached briefly per network.
async function estimatePriorityFeeMicroLamports(connection, network) {
const cached = _priorityFeeCache.get(network);
if (cached && Date.now() - cached.at < PRIORITY_FEE_TTL_MS) return cached.microLamports;
let micro = null;
const heliusKey = process.env.HELIUS_API_KEY;
if (heliusKey) {
micro = await heliusPriorityFee(heliusKey, network).catch(() => null);
}
if (micro == null) {
micro = await recentPrioritizationFee(connection).catch(() => null);
}
if (micro == null) micro = 5_000; // last-resort floor; never zero-priced
const value = Math.max(0, Math.round(micro));
_priorityFeeCache.set(network, { at: Date.now(), microLamports: value });
return value;
}
async function heliusPriorityFee(heliusKey, network) {
const host = network === 'devnet' ? 'devnet.helius-rpc.com' : 'mainnet.helius-rpc.com';
const url = `https://${host}/?api-key=${heliusKey}`;
const resp = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 'three-ws-mev',
method: 'getPriorityFeeEstimate',
// account-less, options-only form: Helius returns the global recommended
// microLamports/CU. We escalate from this in turbo, so 'Medium'/recommended
// is the right anchor.
params: [{ options: { recommended: true } }],
}),
signal: AbortSignal.timeout(HELIUS_FEE_TIMEOUT_MS),
});
if (!resp.ok) throw new Error(`helius pf ${resp.status}`);
const body = await resp.json();
const est = body?.result?.priorityFeeEstimate;
if (typeof est !== 'number' || !Number.isFinite(est)) throw new Error('helius pf shape');
return est;
}
async function recentPrioritizationFee(connection) {
const fees = await connection.getRecentPrioritizationFees();
if (!Array.isArray(fees) || fees.length === 0) return 1_000;
const sorted = fees.map((f) => f.prioritizationFee).filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
if (!sorted.length) return 1_000;
return sorted[Math.floor(sorted.length * 0.75)] ?? sorted[sorted.length - 1];
}
// ── compute-unit estimate ─────────────────────────────────────────────────────
// A REAL simulateTransaction of the trade instructions to read unitsConsumed,
// padded 15% for the runtime drift between sim and land. Not cached (it depends on
// the exact instruction set), but it's a single RPC call on the hot path.
async function estimateComputeUnits(connection, payer, instructions, lookupTables = []) {
const { blockhash } = await connection.getLatestBlockhash('confirmed');
const msg = new TransactionMessage({
payerKey: payer.publicKey,
recentBlockhash: blockhash,
instructions,
}).compileToV0Message(lookupTables);
const sim = await connection.simulateTransaction(new VersionedTransaction(msg), {
sigVerify: false,
replaceRecentBlockhash: true,
commitment: 'confirmed',
});
if (sim.value?.err) {
const err = new Error(`pre-broadcast simulation failed: ${JSON.stringify(sim.value.err)}`);
err.code = 'SIM_FAILED';
err.simLogs = sim.value.logs || [];
throw err;
}
const units = sim.value?.unitsConsumed;
if (!units || units <= 0) {
// No unit count returned — fall back to a conservative bound by instruction
// count rather than the chain default 200k (which under-budgets a multi-CPI
// pump.fun buy that opens an ATA).
return Math.min(1_400_000, 60_000 + instructions.length * 40_000);
}
// +15% headroom plus a flat allowance for the instructions the simulation did
// not contain: the two ComputeBudget instructions and a possible tip transfer
// each cost ~150 CU of their own, which a 15% margin alone does not cover on a
// tiny transaction. Clamped to the per-tx max (1.4M CU).
return Math.min(1_400_000, Math.ceil(units * 1.15) + 3 * 150);
}
// ── Jito Block Engine REST ────────────────────────────────────────────────────
async function jitoRpc(method, params, { baseUrl = jitoBlockEngineUrl(), timeoutMs = JITO_STATUS_TIMEOUT_MS } = {}) {
const url = `${baseUrl}/api/v1/bundles`;
const resp = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
signal: AbortSignal.timeout(timeoutMs),
});
if (!resp.ok) {
const text = await resp.text().catch(() => '');
const err = new Error(`jito ${method} ${resp.status}: ${text.slice(0, 160)}`);
err.code = 'JITO_HTTP';
err.status = resp.status;
throw err;
}
const body = await resp.json();
if (body.error) {
const err = new Error(`jito ${method}: ${body.error.message || JSON.stringify(body.error)}`);
err.code = 'JITO_RPC';
throw err;
}
return body.result;
}
// A failure that says nothing about the bundle itself: the engine never
// answered (network error, deadline) or answered with a 5xx. Only these move
// the send to another region; a JSON-RPC rejection or a 4xx is final.
function isJitoFailoverError(err) {
if (err?.code === 'JITO_RPC') return false;
if (err?.code === 'JITO_HTTP') return Number(err.status) >= 500;
return true;
}
// sendBundle against the primary engine, then exactly one alternate region when
// the primary gave no answer. Returns the engine that accepted the bundle so the
// status polls ask the same one.
async function jitoSendBundle(params) {
const urls = jitoBlockEngineUrls().slice(0, 2);
let lastErr;
for (const baseUrl of urls) {
try {
const bundleId = await jitoRpc('sendBundle', params, { baseUrl, timeoutMs: JITO_SEND_TIMEOUT_MS });
return { bundleId, baseUrl };
} catch (err) {
lastErr = err;
if (!isJitoFailoverError(err)) throw err;
}
}
throw lastErr;
}
// Live Jito tip-floor (lamports). Reads the tip-floor endpoint and uses the 50th
// percentile of recent landed-tips as the baseline. Cached briefly. Returns null
// when no engine answers; the caller then uses the mode floor. The primary
// engine and one alternate region are asked, each on a short deadline.
async function fetchJitoTipFloorLamports() {
const url = jitoBlockEngineUrl();
const cached = _tipFloorCache.get(url);
if (cached && Date.now() - cached.at < TIP_FLOOR_TTL_MS) return cached.lamports;
for (const baseUrl of jitoBlockEngineUrls().slice(0, 2)) {
try {
const resp = await fetch(`${baseUrl}/api/v1/bundles/tip_floor`, {
method: 'GET',
signal: AbortSignal.timeout(JITO_TIP_FLOOR_TIMEOUT_MS),
});
if (!resp.ok) continue;
const body = await resp.json();
const row = Array.isArray(body) ? body[0] : body;
// The endpoint reports tips in SOL; prefer the 50th percentile, fall back to
// the EMA of landed tips.
const sol = row?.landed_tips_50th_percentile ?? row?.ema_landed_tips_50th_percentile ?? null;
if (sol == null || !Number.isFinite(Number(sol))) continue;
const lamports = BigInt(Math.max(0, Math.round(Number(sol) * LAMPORTS_PER_SOL)));
_tipFloorCache.set(url, { at: Date.now(), lamports });
return lamports;
} catch {
continue;
}
}
return null;
}
// Resolve the tip for this attempt: max(mode floor, live tip-floor) scaled by the
// mode multiplier and the attempt index, hard-capped by the mode ceiling.
export function resolveTipLamports(tipMode, tipFloorLamports, attempt, maxTipLamports = null) {
const profile = TIP_PROFILE[tipMode];
if (!profile) return 0n;
const base = tipFloorLamports != null && tipFloorLamports > profile.floor ? tipFloorLamports : profile.floor;
// Escalate with both the mode multiplier and the retry index (attempt 0 = base).
const scaled = BigInt(Math.ceil(Number(base) * profile.multiplier * (1 + attempt * 0.5)));
const tip = clampBig(scaled, profile.floor, profile.ceiling);
return maxTipLamports != null && tip > maxTipLamports ? maxTipLamports : tip;
}
// The smallest tip Jito's block engine accepts on a bundle. A per-trade tip
// ceiling below it means the trade cannot ride a tipped lane at all.
const MIN_BUNDLE_TIP_LAMPORTS = 1_000n;
// The per-trade tip ceiling, honored by every tip-bearing provider because the tip
// is one instruction inside the one signed tx. opts.maxTipLamports wins, then the
// LANDING_MAX_TIP_LAMPORTS env default; null means only the mode ceiling applies.
function resolveMaxTip(opts) {
const raw = opts.maxTipLamports ?? process.env.LANDING_MAX_TIP_LAMPORTS;
if (raw == null || raw === '') return null;
try {
const v = BigInt(raw);
return v >= 0n ? v : null;
} catch {
return null;
}
}
// Submit a signed v0 tx as a single-tx Jito bundle and poll for a real landing.
// Returns { landed, slot, bundleId } — landed:false means the poll window lapsed
// without an on-chain landing (the caller falls back to the protected route).
async function sendJitoBundle(signedTx, signature, connection) {
const b64 = Buffer.from(signedTx.serialize()).toString('base64');
const { bundleId, baseUrl } = await jitoSendBundle([[b64], { encoding: 'base64' }]);
const deadline = Date.now() + BUNDLE_POLL_TIMEOUT_MS;
while (Date.now() < deadline) {
await sleep(BUNDLE_POLL_MS);
// Prefer the chain's own view of the signature — it's authoritative and avoids
// trusting Jito's status alone for a landing claim.
const status = await connection
.getSignatureStatus(signature, { searchTransactionHistory: true })
.catch(() => null);
const conf = status?.value?.confirmationStatus;
if (status?.value?.err) {
return { landed: false, slot: null, bundleId, error: status.value.err };
}
if (conf === 'confirmed' || conf === 'finalized') {
return { landed: true, slot: status.value.slot ?? null, bundleId };
}
// Cross-check Jito's bundle status: a 'Failed'/'Dropped' verdict ends the wait
// early so we fall back without burning the full timeout.
const jitoStatus = await jitoRpc('getBundleStatuses', [[bundleId]], { baseUrl }).catch(() => null);
const st = jitoStatus?.value?.[0]?.confirmation_status || jitoStatus?.value?.[0]?.status;
if (st === 'failed' || st === 'Failed' || st === 'dropped' || st === 'Dropped') {
return { landed: false, slot: null, bundleId };
}
}
return { landed: false, slot: null, bundleId };
}
function sleep(ms) {
return new Promise((r) => setTimeout(r, ms));
}
// ── protected single-tx route ─────────────────────────────────────────────────
// sendRawTransaction with preflight, then a bounded confirm with an ambiguous-
// timeout re-check (a landed tx is never reported as failed). Returns the slot on
// landing.
async function sendProtected(signedTx, signature, connection, blockhashCtx, confirmTimeoutMs) {
await connection.sendRawTransaction(signedTx.serialize(), { skipPreflight: false, maxRetries: 3 });
// HTTP-polling confirm (no WebSocket) — bounded by confirmTimeoutMs and re-checked
// on the ambiguous-timeout path below, so a throttled RPC can't spin web3.js's WS
// 429 reconnect loop. Returns the confirmTransaction result shape this code reads.
const confirmPromise = pollConfirmation(
connection,
{ signature, blockhash: blockhashCtx.blockhash, lastValidBlockHeight: blockhashCtx.lastValidBlockHeight },
'confirmed',
{ timeoutMs: confirmTimeoutMs },
);
const timeout = new Promise((_, rej) =>
setTimeout(() => rej(Object.assign(new Error('confirm timeout'), { code: 'CONFIRM_TIMEOUT' })), confirmTimeoutMs),
);
let landed = false;
let slot = null;
try {
const result = await Promise.race([confirmPromise, timeout]);
if (result?.value?.err) {
throw Object.assign(new Error(`tx failed on-chain: ${JSON.stringify(result.value.err)}`), { code: 'TX_ERR' });
}
landed = true;
slot = result?.context?.slot ?? null;
} catch (err) {
if (err?.code === 'TX_ERR') throw err;
// Ambiguous confirm (timeout / RPC blip): re-check the chain before giving up
// so a tx that actually landed isn't retried or reported as not-landed.
const status = await connection.getSignatureStatus(signature, { searchTransactionHistory: true }).catch(() => null);
if (status?.value?.err) {
throw Object.assign(new Error(`tx failed on-chain: ${JSON.stringify(status.value.err)}`), { code: 'TX_ERR' });
}
const conf = status?.value?.confirmationStatus;
landed = conf === 'confirmed' || conf === 'finalized';
slot = status?.value?.slot ?? null;
if (!landed) {
const e = new Error('not landed within confirm window');
e.code = 'NOT_LANDED';
throw e;
}
}
return { landed, slot };
}
/**
* Submit a protected, MEV-aware transaction.
*
* @param {object} o
* @param {'mainnet'|'devnet'} o.network
* @param {import('@solana/web3.js').Connection} o.connection failover-wrapped Connection
* @param {import('@solana/web3.js').Keypair} o.payer the agent keypair (signs)
* @param {import('@solana/web3.js').TransactionInstruction[]} o.instructions the trade ixs
* @param {object} [o.opts]
* @param {'off'|'economy'|'turbo'} [o.opts.tipMode='off'] per-strategy Jito tip policy
* @param {import('@solana/web3.js').Keypair[]} [o.opts.extraSigners=[]] co-signers
* beyond the fee-payer (e.g. a new mint Keypair on a launch)
* @param {number} [o.opts.confirmTimeoutMs=45000] protected-route confirm bound
* @param {import('@solana/web3.js').AddressLookupTableAccount[]} [o.opts.addressLookupTables=[]]
* tables to compile the v0 message against (a launch needs pump.fun's to fit)
* @param {boolean} [o.opts.preSimulated=false] caller already simulated (firewall) — still estimates CU
* @param {(tipLamports: bigint, route: string) => Promise<void>} [o.opts.onTip]
* Spend-guard hook invoked BEFORE a tip is appended. Throw to veto the
* tip (engine then falls back to the protected route, no tip paid).
* @returns {Promise<{ signature: string, slot: number|null, route: string,
* tipLamports: number, priorityFeeMicroLamports: number, attempts: number,
* landedMs: number, fallbackReason: string|null }>}
*/
export async function submitProtected({ network, connection, payer, instructions, opts = {} }) {
const tipMode = ['economy', 'turbo'].includes(opts.tipMode) ? opts.tipMode : 'off';
const confirmTimeoutMs = Number.isFinite(opts.confirmTimeoutMs) ? opts.confirmTimeoutMs : 45_000;
// Co-signers beyond the fee-payer — e.g. a freshly generated mint Keypair on a
// token launch. The fee payer is always `payer`; these are added to the
// signature set. (Sim uses sigVerify:false, so it needs only the account metas
// the instructions already carry, not these keypairs.)
const extraSigners = Array.isArray(opts.extraSigners) ? opts.extraSigners : [];
const lookupTables = Array.isArray(opts.addressLookupTables) ? opts.addressLookupTables : [];
// Strip any caller-supplied ComputeBudget instructions: this engine sets its own
// data-driven CU limit + escalating priority fee, and a SECOND ComputeBudget
// instruction of the same kind makes the runtime reject the whole transaction.
// No-op for the trade path (passes none); lets migrated send paths hand us their
// raw instructions untouched without each having to remember to drop their own.
const computeBudgetId = ComputeBudgetProgram.programId.toBase58();
const userIxs = instructions.filter((ix) => {
const pid = ix?.programId;
const id = typeof pid?.toBase58 === 'function' ? pid.toBase58() : String(pid ?? '');
return id !== computeBudgetId;
});
const t0 = Date.now();
// 1. Data-driven compute budget. Estimate the priority fee and the CU limit in
// parallel — both are real RPC reads (fee cached, CU is a fresh simulate).
const [priorityFeeBase, cuLimit] = await Promise.all([
estimatePriorityFeeMicroLamports(connection, network),
estimateComputeUnits(connection, payer, userIxs, lookupTables),
]);
const canJito = jitoEligible(network, tipMode);
const tipFloor = canJito ? await fetchJitoTipFloorLamports() : null;
// Landing providers: who this trade is raced through, ordered by recent success.
// A provider on a failure streak sits out until a health probe passes; the probe
// runs off the hot path, so skipping costs the trade nothing.
const stats = getLandingStats(network);
await stats.hydrate();
const maxTip = resolveMaxTip(opts);
const optionalProviders = resolveLandingProviders(network).filter((p) => p.enabled && p.kind !== 'primary');
const probeIfDue = (p) => {
if (!stats.probeDue(p.name)) return;
const fn = p.kind === 'bundle' ? () => jitoRpc('getTipAccounts', []) : rpcProbe(p.endpoint);
void stats.probe(p.name, fn).then(() => stats.flush());
};
for (const p of optionalProviders) if (stats.isSkipped(p.name)) probeIfDue(p);
const jitoSkipped = canJito && stats.isSkipped('jito');
const rpcProviders = optionalProviders.filter((p) => p.kind === 'rpc' && !stats.isSkipped(p.name));
// A tip-bearing rpc provider (sender) only joins when this trade carries its tip.
const senderProvider = rpcProviders.find((p) => p.tip.rule === 'sender' && p.tip.account);
const plainRpcProviders = rpcProviders.filter((p) => p.tip.rule === 'none');
let attempts = 0;
let lastErr = null;
let fallbackReason = canJito
? (jitoSkipped ? 'jito_failure_streak' : null)
: (network === 'devnet' ? 'devnet_no_jito' : (tipMode === 'off' ? 'tip_mode_off' : null));
for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
attempts = attempt + 1;
// Escalate the priority fee on each retry; floor + ceiling clamp it. The
// ramp is steep on purpose (1x, 3x, 5x): a retry means the network outbid
// us during a congested launch window, and re-bidding 60% higher was losing
// the same auction again (EXEC_EXHAUSTED clusters in peak hours). The
// ceiling caps the worst case at CU_PRICE_CEILING x cuLimit, well under a
// position's size.
const feeFloor = CU_PRICE_FLOOR[tipMode] || CU_PRICE_FLOOR.off;
const priorityFeeMicroLamports = Math.min(
CU_PRICE_CEILING,
Math.max(feeFloor, Math.round(priorityFeeBase * (1 + attempt * 2))),
);
// Decide whether THIS attempt rides the Jito bundle. The first attempt(s) try
// Jito; a bundle that doesn't land falls the NEXT attempt back to protected.
const tryJito = canJito && fallbackReason == null;
// Tip target for this attempt: the Jito bundle tip, else the sender tip when
// that provider is enabled and the mode asks for one. One tip per tx.
const trySender = !tryJito && !!senderProvider && tipMode !== 'off';
let tipLamports = 0n;
let tipAccount = null;
const budgetIxs = [
ComputeBudgetProgram.setComputeUnitLimit({ units: cuLimit }),
ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFeeMicroLamports }),
];
const txIxs = [...budgetIxs, ...userIxs];
if (tryJito || trySender) {
tipLamports = tryJito
? resolveTipLamports(tipMode, tipFloor, attempt, maxTip)
: resolveTipLamports(tipMode, 0n, 0, maxTip);
if (tipLamports < MIN_BUNDLE_TIP_LAMPORTS) {
// The per-trade ceiling leaves no room for a tip any provider accepts:
// ride the plain lanes untipped rather than overspend.
tipLamports = 0n;
if (tryJito) {
fallbackReason = 'tip_over_budget';
attempt--;
continue;
}
}
}
if ((tryJito || trySender) && tipLamports > 0n) {
const route = tryJito ? (tipMode === 'turbo' ? 'jito_turbo' : 'jito_economy') : 'helius_sender';
// Spend-guard the tip BEFORE it's appended. The hook counts it against the
// daily budget + kill switch; a veto drops us to the protected route with no
// tip ever leaving the wallet.
let tipVetoed = false;
if (typeof opts.onTip === 'function') {
try {
await opts.onTip(tipLamports, route);
} catch (e) {
tipVetoed = true;
fallbackReason = e?.code === 'spend_guard' ? 'tip_spend_guarded' : 'tip_vetoed';
tipLamports = 0n;
}
}
if (tipVetoed) {
if (tryJito) {
// Re-loop on the same attempt index via protected route (don't consume a
// retry just to drop the tip).
attempt--;
continue;
}
} else {
tipAccount = tryJito ? pickTipAccount(attempt) : senderProvider.tip.account;
txIxs.push(
SystemProgram.transfer({
fromPubkey: payer.publicKey,
toPubkey: new PublicKey(tipAccount),
lamports: tipLamports,
}),
);
}
}
const senderLaneOn = trySender && tipAccount != null;
// Build, sign.
let blockhashCtx;
try {
blockhashCtx = await connection.getLatestBlockhash('confirmed');
} catch (e) {
lastErr = e;
continue;
}
const msg = new TransactionMessage({
payerKey: payer.publicKey,
recentBlockhash: blockhashCtx.blockhash,
instructions: txIxs,
}).compileToV0Message(lookupTables);
const tx = new VersionedTransaction(msg);
tx.sign([payer, ...extraSigners]);
const signature = bs58Sig(tx);
try {
const lanes = [
{ name: 'rpc', run: () => sendProtected(tx, signature, connection, blockhashCtx, confirmTimeoutMs) },
];
if (tryJito && tipAccount) {
lanes.push({
name: 'jito',
run: () =>
sendJitoBundle(tx, signature, connection).catch((e) => {
// Jito unreachable / rejected: recorded honestly. We do NOT claim a
// landing; the other lanes are racing the same tx.
fallbackReason = `jito_unavailable:${e?.code || 'error'}`;
throw e;
}),
});
}
const rawTx = tx.serialize();
for (const p of plainRpcProviders) {
lanes.push(rpcLane({ name: p.name, url: p.endpoint, rawTx, signature, confirmTimeoutMs }));
}
if (senderLaneOn) {
lanes.push(rpcLane({ name: senderProvider.name, url: senderProvider.endpoint, rawTx, signature, confirmTimeoutMs }));
}
// Send order follows recent success; every lane carries the SAME signed tx,
// so Solana dedupes by signature and at most one landing exists.
const order = stats.rank(lanes.map((l) => l.name));
lanes.sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
let race;
try {
race = await raceLanes({ lanes, stats });
} finally {
void stats.flush();
}
if (race.winner) {
const w = race.winner.name;
return {
signature,
slot: race.winner.slot,
// Route label reflects the lane that actually reported the landing.
route: w === 'jito' ? (tipMode === 'turbo' ? 'jito_turbo' : 'jito_economy') : w === 'helius_sender' ? 'helius_sender' : 'protected',
tipLamports: Number(tipLamports),
priorityFeeMicroLamports,
attempts,
landedMs: Date.now() - t0,
fallbackReason: w === 'jito' ? null : tryJito ? (fallbackReason || 'jito_not_landed') : fallbackReason,
landedBy: w,
lanes: race.lanes,
};
}
if (tryJito && fallbackReason == null) fallbackReason = 'jito_not_landed';
const primaryLoss = race.lanes.find((l) => l.name === 'rpc')?.error;
lastErr = Object.assign(new Error(`not landed: ${primaryLoss || 'no lane confirmed'}`), {
code: /^[A-Z_]+$/.test(primaryLoss || '') ? primaryLoss : 'NOT_LANDED',
});
// Nothing landed: refresh the blockhash and retry with a higher fee/tip.
} catch (e) {
lastErr = e;
// A hard on-chain failure (TX_ERR) is terminal — the instructions reverted,
// retrying the same trade would just revert again.
if (e?.code === 'TX_ERR' || e?.code === 'SIM_FAILED') throw e;
// Blockhash expiry / not-landed: refresh and retry.
}
}
const err = lastErr || new Error('execution engine exhausted retries without landing');
if (!err.code) err.code = 'EXEC_EXHAUSTED';
throw err;
}
// Recover the base58 signature string from a signed VersionedTransaction without
// re-importing bs58 (web3.js bundles it; the signature is the first signature).
function bs58Sig(tx) {
const sig = tx.signatures?.[0];
if (!sig) throw new Error('transaction is not signed');
// @solana/web3.js exposes bs58 via its own export; encode the 64-byte sig.
return encodeBase58(sig);
}
// Minimal, dependency-free base58 encode (Bitcoin alphabet) for a 64-byte sig.
const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
function encodeBase58(bytes) {
const digits = [0];
for (let i = 0; i < bytes.length; i++) {
let carry = bytes[i];
for (let j = 0; j < digits.length; j++) {
carry += digits[j] << 8;
digits[j] = carry % 58;
carry = (carry / 58) | 0;
}
while (carry > 0) {
digits.push(carry % 58);
carry = (carry / 58) | 0;
}
}
let out = '';
for (let k = 0; k < bytes.length && bytes[k] === 0; k++) out += '1';
for (let q = digits.length - 1; q >= 0; q--) out += B58_ALPHABET[digits[q]];
return out;
}