Data modelling · November 18, 2026 · 7 min read

Provisional rows: storing what you saw before the chain agreed

Data decoded from shreds is early by design, so it has to be stored as a claim, not a fact. Here is a small status model, the events that move a row through it, and the queries that keep early rows away from readers who expect final data.

A provisional blockchain data model stores every early row with a status, so nothing decoded before confirmation is ever shown as final. Rows start as seen, move to confirmed when RPC reports the transaction in a block that will stay, and become dropped once their slot is skipped and their blockhash expires unused. A second field records success or failure.

Why early data needs its own status#

A transaction decoded from shreds is the leader's proposal. Three things can still happen to it: its block is accepted, its slot is skipped, or it lands and fails. Without a status column, all three look the same in your tables, and the first person to notice is a user who saw a deposit that never arrived.

Status also gives you a clean audit trail. You can measure how often early rows turn out wrong, which is the number that tells you whether acting on early data is worth it for your product.

Four states, two questions#

Two questions describe a transaction's fate: did it land in a block that stays, and did it succeed? Mixing them in one column causes trouble, because a failed transaction still lands and still pays its fee. Keep them apart.

ColumnValuesAnswers
inclusionseen, confirmed, finalized, droppeddid the transaction land in a block that stays
outcomeunknown, succeeded, failedwhat execution did with it

Since Alpenglow, the confirmed and finalized commitment levels are equivalent, so for new data you can move straight from seen to finalized and treat confirmed as an alias. Keeping both values costs nothing and leaves room for historic rows from before the change, when the two levels were different guarantees.

Allowed transitions:

  1. seen to confirmed or finalized, when RPC reports the signature at that commitment.
  2. confirmed to finalized, for chains or periods where the two differ.
  3. seen to dropped, when the row cannot land any more.
  4. outcome moves from unknown to succeeded or failed once RPC returns a status, and never moves back.

No transition goes from confirmed back to seen. If you ever need one, your confirmation source is wrong, and that deserves an alert rather than a quiet update.

What moves a row from one state to the next#

Every transition needs an event you can point to:

TransitionTriggerWhere it comes from
seen to confirmed or finalizedgetSignatureStatuses, called with searchTransactionHistory: true, returns a confirmationStatus of confirmed or finalized (never act on processed)RPC, up to 256 signatures per call
outcome setthe same call returns err as null (success) or an errorRPC
seen to droppedno status, the transaction's blockhash has expired on the finalized bank, and a second status check after that still finds nothing; a durable nonce transaction never expires this way, so keep it seenisBlockhashValid at finalized commitment, then getSignatureStatuses again
seen to dropped (alternative)no status after a timeout you choose, longer than blockhash expiryyour own policy

The blockhash rule matters because a transaction from a skipped slot may still land in a later one, as long as its blockhash is valid (see how blockhash expiry works). Drop a row only after that window closes, or you will delete rows that would have confirmed a few slots later. Check expiry at finalized commitment, not processed, because a processed view can sit on a fork that dies, and ask for the status once more after expiry, since the transaction may have landed in between. The reconcile guide runs these checks in order.

What readers should see by default#

Pick defaults by audience, and make the early view something a reader opts into:

  • Balances and totals: count confirmed and finalized rows with outcome succeeded only.
  • Activity feeds: show seen rows with a visible pending label, and remove them if they drop.
  • Alerts: fire on seen if speed matters, then send a follow-up when the row confirms or drops.
  • Analytics: report early and confirmed figures as separate series, never blended.

A simple view per audience keeps that logic in one place, so application code never filters on raw status values by hand.

Cleaning up dropped rows#

Dropped rows are evidence, not junk. Keep them for a while, because they show how often early data misleads you and which programs or wallets cause it. Then age them out with a retention job. If storage is tight, keep a compact record (signature, slot, the time first seen, the time dropped) and delete the decoded detail.

Questions about provisional data#

Should a failed transaction be marked dropped?#

No. A failed transaction landed and paid its fee, so once its block is confirmed its inclusion is confirmed and its outcome is failed. Dropped means it never landed in a block that stays.

Do I still need finalized if confirmed equals finalized now?#

For new rows the two are equivalent. Keep the value anyway, so historic rows and any future change in commitment rules fit the same column.

How often should I poll for status?#

Batch signatures and poll on a short interval that suits your traffic. The RPC method accepts up to 256 signatures per call, so batching keeps the request count low.

Trade-offs of a provisional model#

A status model adds writes: every row is written at least twice, once when seen and once when settled. It also needs a reconcile job that keeps running, plus monitoring for rows stuck in seen. If your product only ever shows settled data, skipping the provisional layer and indexing confirmed blocks directly is simpler, and raw shreds bring you little.

Build it out#

Reconcile with RPC shows the job that moves rows through these states, and a status column in Postgres turns the model into a schema. The failure case is covered in transactions that land but fail, and Alpenglow and finality explains why confirmed and finalized merged. For early totals done right, see provisional DEX volume. When you are ready to feed the model with live data, compare plans and prices.

For the stages that come before a row exists at all, see why packets are not yet data.

Rows that share a slot also need a stable sort, which order inside a slot covers.

Sources#

Raw shreds on your own server

Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.

Read nextLanded but failed: why a transaction in a block may have done nothing