Tanisha fonseca

Posted on May 15

Solana transactions expire and nobody warned me 💀

#mlh #100daysofsolana #blockchain #learning

okay so I need to talk about something that genuinely caught me off guard during #100DaysOfSolana and I feel like nobody explains it properly so here we go

you know how in Web2, if you build an API call and it fails, you just... retry it? same request, same body, send again. worst case you get a duplicate, you handle it with idempotency keys, whatever the request itself doesn't have an expiry date baked in

Solana transactions have an expiry date baked in

like structurally. at the protocol level. you cannot opt out of it

let me explain because this is actually kind of wild

the blockhash thing

every Solana transaction contains something called a recent blockhash. it's a 32-byte hash of a recent block, and it's required you literally cannot construct a valid transaction without one

const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

const tx = await pipe(
  createTransactionMessage({ version: 0 }),
  m => setTransactionMessageFeePayerSigner(sender, m),
  m => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m), // 👈 this
  // ...
);

that latestBlockhash you fetched? it's valid for approximately 150 slots

slots happen every ~400 milliseconds

150 × 400ms = 60 seconds

your transaction has roughly 60-90 seconds to land on the network before it is permanently dead. not retryable. not recoverable. you need to build a brand new transaction with a fresh blockhash

why does this exist though

Okay here's where it gets interesting

The blockhash serves two purposes simultaneously and they're both actually really smart:

1. it proves the transaction is fresh

If there was no expiry, someone could intercept your signed transaction and replay it weeks later. the blockhash ties your transaction to a specific point in time after ~150 slots, that blockhash is no longer considered valid, so the transaction dies even if someone tries to resubmit it

2. It prevents literal duplicate transactions

Imagine you send 0.1 SOL to someone. the transaction looks identical to the last time you sent 0.1 SOL to that same person. without the blockhash, the network would have no way to tell "did this already happen or is this a new send?" WITH the blockhash, every transaction is unique because it references a specific recent block

so like... it's doing the job of a CSRF token AND an idempotency key AND a TTL all in one field. that's kind of a lot of work for 32 bytes

what this looks like when it goes wrong

Here's the scenario that'll get you: you build a transaction, get a blockhash, do some other stuff (UI interactions, user confirmations, whatever), and THEN try to send it

// ❌ bad pattern : time passes between fetch and send
const { value: blockhash } = await rpc.getLatestBlockhash().send();

await waitForUserToClickConfirm(); // this takes 2 minutes
await doSomeOtherAsyncThing();     // and this takes another minute

// by here? blockhash might be expired already
const signature = await sendTransaction(signedTx);
// TransactionExpiredBlockheightExceededError 💀

the fix is to fetch the blockhash as late as possible — right before you sign and send, not when you start building

// ✅ fetch blockhash late, sign, send immediately
const tx = buildTransactionWithoutBlockhash(sender, recipient, amount);

// fetch RIGHT before sending
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
const txWithBlockhash = setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx);
const signed = await signTransactionMessageWithSigners(txWithBlockhash);

// send immediately after signing
const signature = await rpc.sendTransaction(
  getBase64EncodedWireTransaction(signed),
  { encoding: "base64" }
).send();

minimize the gap between "I got a blockhash" and "I sent the transaction"

and if it expires mid-flight?

sometimes the transaction reaches the network but confirmation takes longer than the blockhash window. this happens more on mainnet under load

the network will eventually return TransactionExpiredBlockheightExceededError and you need to handle this explicitly:

try {
  // wait for confirmation
  const status = await waitForConfirmation(signature);
} catch (err) {
  if (err.message.includes('BlockheightExceeded')) {
    // the transaction is dead, not pending
    // you need to rebuild with a fresh blockhash and try again
    console.log('Transaction expired rebuilding with fresh blockhash');
    return await sendTransfer(sender, recipient, amount); // retry the whole thing
  }
  throw err; // different error, rethrow
}

the key thing: TransactionExpiredBlockheightExceededError is NOT a "try again with the same transaction" situation. that transaction is gone. you build a new one

the thing that makes this different from everything else

In literally every other system I've worked with, "retry" means "resend the same thing"

In Solana, retry means "construct a new thing that does the same action"

your signed transaction isn't a reusable object : it's a snapshot tied to a specific moment in time. once that moment passes, the snapshot is invalid. you're not retrying a request, you're making a new one that happens to do the same thing

This is a mental model shift that took me a minute to actually internalize because it runs against every HTTP instinct I have

tldr

every Solana transaction embeds a recent blockhash that expires in ~60-90 seconds
this is on purpose, it prevents replay attacks and duplicate transactions
fetch the blockhash as late as possible before signing and sending
if a transaction expires, don't retry it, rebuild it from scratch with a fresh blockhash
TransactionExpiredBlockheightExceededError = make a new transaction, not send the old one again

the more I learn about Solana's design decisions the more I realize how much thought went into things that feel annoying at first, this being a perfect example. The expiry isn't a bug, it's load-bearing

Anyway that's what got me this week 🙂

Epoch 1 of #100DaysOfSolana. Writing about the things that actually surprised me so the next person is slightly less confused.

#100daysofsolana #solana #web3 #blockchain

DEV Community