TPU-direct transaction submission for @solana/kit apps — send transactions straight to upcoming leaders over QUIC, bypassing RPC rate limits and reducing time-to-land.

solana-tpu-client is a TypeScript library that opens QUIC connections to the next N Solana leader nodes and fans out your signed transaction bytes directly, rather than routing through an RPC sendTransaction call. This mirrors what the Solana CLI and the Rust TpuClient do under the hood.

What it solves:

• RPC sendTransaction limits (rate limits, propagation lag, single-node SPF).
• Opaque landing failures — you get per-leader attempt results with RTTs and error kinds.
• Firedancer compatibility — ALPN negotiation (solana-tpu) is handled automatically.
• Observability gaps — a stable TpuEvent union lets you wire Prometheus counters without patching the library.

Built on @solana/kit 3.x primitives (no @solana/web3.js dependency), @matrixai/quic for QUIC transport, and @peculiar/x509 for X.509 cert generation.

Use solana-tpu-client when:

• You need full control over QoS identity and connection lifecycle.
• You want landing telemetry per attempt for SLAs or alerting.
• You are operating your own validator or staking infrastructure and already hold a funded identity keypair.
• You want a pure-TypeScript dependency with no managed-service lock-in.

Requires Node.js ≥ 22.11 (ESM only; native QUIC bindings require a recent Node ABI).

npm install solana-tpu-client @solana/kit @matrixai/quic @peculiar/x509

@solana/kit, @matrixai/quic, and @peculiar/x509 are peer dependencies and must appear in your project's dependencies.

CF Workers / Bun / Deno: @matrixai/quic compiles a native Node.js addon via node-gyp. CF Workers cannot load native bindings; the library will not work there. Bun and Deno may work if they expose a Node-compatible node:crypto and node:net surface, but this is untested. Lambda is supported — bundle with node_modules or use a Lambda Layer containing the native .node file.

This example transfers 0.001 SOL from a generated payer to a recipient using the @solana-program/system package.

Note: This is a compilable skeleton — payer must be pre-funded and the recipient must be a real address. See test/integration/validator.test.ts for a runnable example on solana-test-validator.

import { readFileSync } from 'node:fs';
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  generateKeyPairSigner,
  address,
  lamports,
  createTransactionMessage,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getBase64EncodedWireTransaction,
} from '@solana/kit';
import { getTransferSolInstruction } from '@solana-program/system';
import {
  createTpuClient,
  sendAndConfirmTpuTransactionFactory,
  ed25519KeyPairFromSolanaSecret,
} from 'solana-tpu-client';

// 1. Load your staked identity (64-byte solana-keygen JSON array).
const secretBytes = new Uint8Array(
  JSON.parse(readFileSync('/path/to/stake-identity.json', 'utf8')) as number[],
);
const identity = await ed25519KeyPairFromSolanaSecret(secretBytes);

// 2. Create RPC clients.
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const rpcSubscriptions = createSolanaRpcSubscriptions(
  'wss://api.mainnet-beta.solana.com',
);

// 3. Create the TPU client. Resolves when leader schedule is primed.
const tpu = await createTpuClient({ rpc, rpcSubscriptions, identity });

// 4. Build and sign a SOL transfer with @solana/kit + @solana-program/system.
const payer = await generateKeyPairSigner(); /* replace with a pre-funded signer */
const RECIPIENT = address('/* replace with a real, funded recipient */');
const { value: blockhash } = await rpc.getLatestBlockhash().send();

const transferIx = getTransferSolInstruction({
  source: payer,
  destination: RECIPIENT,
  amount: lamports(1_000_000n), // 0.001 SOL
});

const signedTx = await signTransactionMessageWithSigners(
  pipe(
    createTransactionMessage({ version: 0 }),
    (m) => setTransactionMessageFeePayerSigner(payer, m),
    (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
    (m) => appendTransactionMessageInstruction(transferIx, m),
  ),
);
const txBytes = new Uint8Array(
  Buffer.from(getBase64EncodedWireTransaction(signedTx), 'base64'),
);

// 5. Send and confirm.
const confirm = sendAndConfirmTpuTransactionFactory({ tpu, rpc, rpcSubscriptions });
const ac = new AbortController();

const result = await confirm(txBytes, {
  commitment: 'confirmed',
  abortSignal: ac.signal,
  lastValidBlockHeight: blockhash.lastValidBlockHeight,
});

console.log('landed:', result.signature);
console.log('attempts:', result.attempts);

// 6. Graceful shutdown.
await tpu.close();

Solana's stake-weighted QoS (implemented in both the Agave validator and Firedancer) grants QUIC connections more stream-slots proportional to the sender's stake weight. Under leader load, unstaked connections are dropped first.

When you pass identity: CryptoKeyPair to createTpuClient, the library:

1. Mints a self-signed Ed25519 X.509 certificate from that keypair.
2. Presents it in the QUIC ClientHello so the validator can identify the sender and apply stake-weighting.

Loading a solana-keygen keypair:

solana-keygen saves keypairs as a JSON array of 64 bytes: the 32-byte seed followed by the 32-byte public key.

import { readFileSync } from 'node:fs';
import { ed25519KeyPairFromSolanaSecret } from 'solana-tpu-client';

const raw = new Uint8Array(
  JSON.parse(readFileSync('/path/to/id.json', 'utf8')) as number[],
);
const identity = await ed25519KeyPairFromSolanaSecret(raw);

If you omit identity, an ephemeral (unstaked) keypair is generated and an ephemeral-identity TpuEvent fires. Ephemeral identities are fine for development but will be first-dropped by validators under production load.

QUIC-layer fix — one-line addition recommended in your app's package.json:

@matrixai/[email protected] has a stream-creation bug that blocks sends against peers that advertise initial_max_streams_uni: 0 and grant credit via MAX_STREAMS frames post-handshake — Agave's unstaked-QoS path (~80% of mainnet leaders).

This release depends on a patched fork at github:lmvdz/js-quic#release/tpu-fix via its direct dependencies entry, which gets installed automatically when you npm install solana-tpu-client. For belt-and-suspenders correctness — in case another package in your tree also depends on @matrixai/quic and npm hoists the registry version — add this to your app's root package.json:

{
  "overrides": {
    "@matrixai/quic": "github:lmvdz/js-quic#release/tpu-fix"
  }
}

This forces every resolution (transitive and direct) to the patched fork. The fork is @matrixai/[email protected] with a ~12-line diff to dist/QUICStream.js; native binaries still come from upstream's npm packages unchanged. Upstream PR: MatrixAI/js-quic#157 — when that merges + releases, we drop the fork and the overrides line becomes unnecessary.

Firedancer note: Firedancer (and its hybrid Frankendancer variant) enforce ALPN — connections without solana-tpu are rejected. This library sets ALPN automatically. Firedancer has been handling approximately 20% of leader slots on mainnet.

Pass onEvent to observe all internal state transitions:

import type { TpuEvent } from 'solana-tpu-client';

const tpu = await createTpuClient({
  rpc,
  rpcSubscriptions,
  identity,
  onEvent(e: TpuEvent) {
    switch (e.type) {
      case 'send':
        successCounter.inc({ ok: String(e.attempts.some((a) => a.ok)) });
        e.attempts.forEach((a) => {
          attemptHistogram.observe({ leader: a.identity, ok: String(a.ok) }, a.rttMs ?? 0);
        });
        break;
      case 'slot-stall':
        slotStallGauge.set(e.lastSlotAgeMs);
        break;
      case 'cert-pin-mismatch':
        alertManager.fire(`cert mismatch for leader ${e.identity}`);
        break;
      case 'error':
        errorCounter.inc({ kind: e.error.kind });
        break;
    }
  },
});

TpuEvent union — stable schema:

SemVer policy: Adding a new TpuEvent variant is a MINOR version bump. If you use an exhaustive switch over e.type, include a default: branch so your code remains forward-compatible.

Alpenglow SIMD-0326, as specified, does not change TPU ingress — transactions continue to be forwarded to leaders over QUIC at the same TPU port. This client will be re-tested at activation. See the SIMD: solana-foundation/solana-improvement-documents#228

Firedancer is Jump Trading's independent validator client. It requires:

• ALPN set to solana-tpu — handled automatically.
• A valid Ed25519 TLS certificate in the ClientHello — generated from your identity keypair.

Frankendancer (Firedancer networking + Agave consensus) has been handling roughly 20% of leader slots on mainnet. Tested against Agave (solana-test-validator for integration, mainnet nodes via the smoke script) and Frankendancer (mainnet smoke script). The nightly CI smoke probe re-verifies. See: https://docs.firedancer.io

Our QUIC client ALWAYS presents the client cert (required for stake-weighted QoS) and ALWAYS performs TLS. Whether we ALSO verify the server's cert pubkey against the gossip-advertised identity is governed by pinMode:

Why 'observe' and not 'strict' by default? Empirical probing of mainnet-beta (April 2026, npm run smoke:firedancer) shows that 100% of Frankendancer nodes and a meaningful fraction of Agave nodes present server certs whose SPKI does not equal the gossip identity — likely due to per-connection ephemeral certs, validator-side TLS terminators, or cloud-native load balancers in front of validator machines. Strict pinning would silently drop ~20%+ of the real leader schedule. In 'observe' mode you still get the telemetry signal (the event fires) without the connectivity loss.

If you are migrating from the previous TpuConnection API (which extended @solana/web3.js Connection), see MIGRATION.md.

All exports from the solana-tpu-client package:

Type documentation: Full JSDoc is emitted to lib/*.d.ts during build. Use your IDE's hover/IntelliSense for field-level descriptions.

ready: Promise<void> — Resolves when the slot tracker is primed and the first leader snapshot has been loaded. May resolve with an empty snapshot after a 5 s internal deadline if the leader cache could not populate; in that case sendRawTransaction throws {kind:'no-leaders'} until a subsequent refresh succeeds.

close(opts?: { timeoutMs?: number }): Promise<void> — Drains in-flight sends up to timeoutMs (default 5000 ms), then aborts internal signal and disposes resources. Idempotent; second call is a no-op.

If you are hand-rolling a custom QUIC transport (e.g. for testing), evaluatePinDecision lets you reuse the cert-pin logic without a live handshake:

import { evaluatePinDecision } from 'solana-tpu-client';

// gossipSpki: the 32-byte Ed25519 pubkey bytes from getClusterNodes
// peerSpki:   the SPKI bytes extracted from the peer's X.509 cert DER
// pinMode:    'strict' | 'observe' | 'off'
const decision = evaluatePinDecision({
  gossipSpki: myGossipPubkeyBytes,
  peerSpki: extractedCertSpki,
  pinMode: 'strict',
});

// decision: { action: 'accept' | 'reject' | 'observe'; mismatch: boolean }
if (decision.action === 'reject') {
  throw new Error(`cert pin mismatch for ${leaderIdentity}`);
}
if (decision.mismatch) {
  onEvent({ type: 'cert-pin-mismatch', identity: leaderIdentity, ... });
}

Prerequisites:

• solana-test-validator on your PATH (install via Solana CLI: https://docs.solana.com/cli/install-solana-cli-tools)
• Node.js >= 22.11

Steps:

# Start a local test validator in the background (takes ~5 s to prime).
solana-test-validator &

# Run the integration suite (targets localhost:8899 by default).
npm run test:integration

Set TPU_RPC_URL and TPU_WS_URL to point at a different cluster:

TPU_RPC_URL=https://api.devnet.solana.com \
TPU_WS_URL=wss://api.devnet.solana.com \
npm run test:integration

Expected runtime: ~30–60 s against a local validator; up to 3 min against devnet depending on congestion.

• Node ≥ 22.11 (ESM-only; no CommonJS support).
• ulimit -n 4096 — pool cap × stream slots needs ample file descriptors.
• UV_THREADPOOL_SIZE=16 — recommended for @peculiar/x509 crypto ops under load.
• Stage a staked identity keypair; never ship an ephemeral identity in production.
• Consume onEvent into structured logs or a metrics sink — don't leave it unwired in production.
• CF Workers won't work (native QUIC binding); Lambda needs the prebuilt .node file bundled or in a Lambda Layer.

No benchmarks have been captured yet. Architectural targets: up to 5k sendRawTransaction calls/s per client instance on commodity hardware with Node 22, subject to RPC refresh latency and leader QoS class. Real numbers will ship with the first stable release.

To verify the end-to-end path against devnet (airdrop → self-transfer → confirmed), run:

npm run smoke:devnet
# or: DEVNET_SMOKE=1 npx tsx scripts/devnet-smoke.ts

This takes ~30–60 s and prints the confirmed signature, per-leader attempt results, and a live getStats() snapshot. Not run in CI.

MIT