Skill

Solana Transaction Reliability Skill

Extends: solana-dev-skill — Core Solana development (programs, frontend, testing, security)

Landing a transaction is the single most common operational failure on Solana: dropped transactions, blockhash expiry, under-budgeted compute, mis-bid priority fees, and silent preflight failures. This skill encodes the full "make it land, then prove it landed" lifecycle so an agent writes a robust send path the first time instead of a flaky one.

What This Skill Is For

Use this skill when the user asks about:

Sending & Landing

• "My transactions keep dropping / timing out / never confirm"
• Building a production transaction-sending function
• Retry logic, confirmation, lastValidBlockHeight handling
• skipPreflight, maxRetries, commitment levels

Fees & Compute

• Priority fees: how much to pay, how to estimate dynamically
• Compute unit right-sizing (stop hardcoding 200k / 1.4M)
• Fee estimation via Helius / Triton / QuickNode / native RPC
• Cutting overpayment without hurting landing rate

Atomicity & MEV

• Jito bundles (atomic multi-tx, front-run resistance)
• Revert protection (bundleOnly)
• Tip sizing from the Jito tip floor

Transaction Shape

• Versioned (v0) transactions + Address Lookup Tables (size limits)
• Durable nonces (offline / delayed signing, no blockhash expiry)
• Simulation-driven transaction construction

Diagnosis

• "Why didn't this signature land?" — post-mortem on a failed/dropped tx

Program Authoring (Delegate to Core Skill)

• Writing the Anchor/Pinocchio program itself → programs-anchor.md
• Client/wallet framework setup → frontend-framework-kit.md
• Security review of program logic → security.md

Default Stack Decisions (Opinionated, June 2026)

1. SDK: @solana/kit (the renamed web3.js v2). Functional, tree-shakeable, factory-based. Use gill when you want a lighter convenience wrapper over Kit. Legacy @solana/web3.js v1 (Connection, Transaction) only when an existing codebase mandates it — see sending-and-confirming.md for the interop note.
2. Compute budget is mandatory, not optional. Every production transaction sets both a CU limit (from simulation + headroom) and a CU price. Never ship a transaction that relies on the implicit 200k-per-instruction default.
3. Estimate, don't guess, both numbers. CU limit comes from getComputeUnitEstimateForTransactionMessageFactory (simulation). CU price comes from a fee oracle (Helius getPriorityFeeEstimate or native getRecentPrioritizationFees), scoped to the writable accounts your tx touches — local fee markets are per-account.
4. Confirmation is blockhash-bounded. A transaction is alive only until its blockhash's lastValidBlockHeight. Retries re-send the same signed transaction within that window; they do not rebuild it. After expiry, rebuild with a fresh blockhash.
5. Reach for Jito when atomicity or ordering matters (multi-leg arb, liquidations, competitive mints) or when native priority fees stop landing during contention. Otherwise a well-budgeted native transaction is simpler and cheaper.
6. Always simulate before sending in any non-trivial path. Simulation gives you the CU estimate and surfaces program errors before you spend a fee.

Operating Procedure

1. Classify the Task

Goal	Skill File(s)
Understand the fee model / why a tx costs what it does	fundamentals.md
Right-size compute units	compute-budget.md
Decide / estimate the priority fee	priority-fees.md
Build a robust send + confirm + retry path	sending-and-confirming.md
Need atomicity / MEV protection / contention bypass	jito-bundles.md
Tx too big / many accounts	versioned-tx-luts.md
Offline or delayed signing	durable-nonces.md
Validate a tx before sending / decode an error	simulation.md
"Why didn't it land?"	checklist.md → tx-debugger agent
Build/audit a complete sending pipeline	checklist.md → tx-optimizer agent

2. Apply the Standard Send Pipeline

The reliable path, in order (details in the linked files):

1. Build the instruction list (your program calls).
2. Simulate to get a CU estimate → simulation.md, compute-budget.md.
3. Prepend compute budget: setComputeUnitLimit(estimate × 1.1) then setComputeUnitPrice(fee) → compute-budget.md.
4. Estimate the priority fee scoped to writable accounts → priority-fees.md.
5. Set fee payer + a fresh blockhash lifetime → sending-and-confirming.md.
6. Sign.
7. Send + confirm with sendAndConfirmTransactionFactory, or a manual re-send loop bounded by lastValidBlockHeight → sending-and-confirming.md.
8. On expiry: rebuild from a fresh blockhash and retry. On program error: stop and surface it (don't burn fees retrying a deterministic failure).

For atomic/competitive flows, swap steps 6–8 for the Jito bundle path → jito-bundles.md.

3. Verify

• Confirm the signature reached your target commitment (confirmed/finalized).
• Check requested-vs-used CU to catch overpayment (the doc's optimization metric).
• Two-strike rule: if a send fails twice for the same reason, STOP and diagnose with checklist.md, don't loop.

---

Progressive Disclosure (Read When Needed)

Transaction Reliability (This Skill)

File	Read when…
fundamentals.md	You need the fee model: base fee, CU, priority-fee formula, local fee markets, limits
compute-budget.md	Right-sizing CU limit/price (Kit + legacy)
priority-fees.md	Estimating the fee dynamically (Helius / Triton / QuickNode / native)
sending-and-confirming.md	Send, confirm, retry, blockhash lifetime, commitment, preflight
jito-bundles.md	Atomic bundles, tips, revert protection, statuses
versioned-tx-luts.md	v0 transactions + Address Lookup Tables, size limits
durable-nonces.md	Offline/delayed signing without blockhash expiry
simulation.md	Pre-send validation, error decoding, replaceRecentBlockhash
checklist.md	The land-it-reliably checklist + the didn't-land decision tree
error-reference.md	Error string/code → category → cause → fix lookup
resources.md	Source-of-truth links

Runnable Reference & Tooling

This skill ships an executable companion at examples/reliable-send/ (not just prose):

• reliableSend() — the standard pipeline as a drop-in, typed primitive.
• Pure, unit-tested core — CU sizing, fee clamping, and failure classification with a passing test suite and a strict typecheck against the real @solana/kit types. When writing send code, prefer mirroring these tested functions over re-deriving the math.
• tx-doctor CLI — npx tsx bin/tx-doctor.ts <signature> --rpc <url> classifies a real transaction's failure using the same decision tree as checklist.md / error-reference.md. Offline mode: --err '<json>'.

Core Solana Dev Skills (from solana-dev-skill)

Provided by solana-dev-skill — install if not present.

• frontend-framework-kit.md — Wallet connection, React hooks
• kit-web3-interop.md — Kit ↔ web3.js v1 boundary
• programs-anchor.md — Anchor programs
• testing.md — LiteSVM, Mollusk, Surfpool (test your send path locally)
• security.md — Program + client security checklist

---

Task Routing Guide

User asks about…	Primary file(s)
Transactions dropping / not confirming	sending-and-confirming.md → checklist.md
How much priority fee to pay	priority-fees.md
Estimating compute units	compute-budget.md, simulation.md
setComputeUnitLimit / setComputeUnitPrice	compute-budget.md
Helius getPriorityFeeEstimate	priority-fees.md
getRecentPrioritizationFees	priority-fees.md
sendAndConfirmTransactionFactory	sending-and-confirming.md
lastValidBlockHeight / blockhash expired	sending-and-confirming.md
skipPreflight / maxRetries / commitment	sending-and-confirming.md
Jito bundle / sendBundle	jito-bundles.md
Jito tip amount / tip floor	jito-bundles.md
Revert protection / bundleOnly	jito-bundles.md
Front-running / MEV protection	jito-bundles.md
Atomic multi-step (arb, liquidation)	jito-bundles.md
"Transaction too large"	versioned-tx-luts.md
Address Lookup Tables	versioned-tx-luts.md
v0 vs legacy transaction version	versioned-tx-luts.md
Offline signing / hardware wallet delay	durable-nonces.md
Nonce account	durable-nonces.md
simulateTransaction / preflight error	simulation.md
Decode a custom program error code	simulation.md → solana-dev → security.md
Why didn't signature X land?	checklist.md
Decode a specific error string/code	error-reference.md → simulation.md
Diagnose a live signature automatically	error-reference.md (tx-doctor CLI)
Audit my sending code	checklist.md → tx-optimizer agent
Writing the program itself	solana-dev → programs-anchor.md
Wallet adapter / connect button	solana-dev → frontend-framework-kit.md

---

Commands

Command	Description
/diagnose-tx	Diagnose why a given signature or error failed to land
/audit-send-path	Audit a repo's transaction-sending code against the reliability checklist

Agents

Agent	Purpose
tx-optimizer	Design/refactor a production send pipeline (CU, fees, retries, Jito)
tx-debugger	Root-cause a dropped/failed transaction and propose the fix