Canonical: https://solanashreds.xyz/blog/provisional-rows

# 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.

| Column | Values | Answers |
|---|---|---|
| `inclusion` | `seen`, `confirmed`, `finalized`, `dropped` | did the transaction land in a block that stays |
| `outcome` | `unknown`, `succeeded`, `failed` | what 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:

| Transition | Trigger | Where it comes from |
|---|---|---|
| seen to confirmed or finalized | `getSignatureStatuses`, called with `searchTransactionHistory: true`, returns a confirmationStatus of confirmed or finalized (never act on processed) | RPC, up to 256 signatures per call |
| outcome set | the same call returns `err` as null (success) or an error | RPC |
| seen to dropped | no 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 seen | `isBlockhashValid` at finalized commitment, then `getSignatureStatuses` again |
| seen to dropped (alternative) | no status after a timeout you choose, longer than blockhash expiry | your 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](https://solanashreds.xyz/learn/blockhash-and-expiry)). 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](https://solanashreds.xyz/docs/pipeline/reconcile) 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](https://solanashreds.xyz/docs/pipeline/reconcile) shows the job that moves rows through these states, and [a status column in Postgres](https://solanashreds.xyz/docs/pipeline/postgres) turns the model into a schema. The failure case is covered in [transactions that land but fail](https://solanashreds.xyz/blog/landed-but-failed), and [Alpenglow and finality](https://solanashreds.xyz/blog/alpenglow-for-indexers) explains why confirmed and finalized merged. For early totals done right, see [provisional DEX volume](https://solanashreds.xyz/blog/dex-volume-before-confirmation). When you are ready to feed the model with live data, compare [plans and prices](https://solanashreds.xyz/pricing).

For the stages that come before a row exists at all, see [why packets are not yet data](https://solanashreds.xyz/blog/packets-are-not-data).

Rows that share a slot also need a stable sort, which [order inside a slot](https://solanashreds.xyz/blog/order-inside-a-slot) covers.
