Preimage
Introduction
Section titled “Introduction”A preimage is the original content of a hash that has been referenced on-chain. The classic example: a governance referendum points at the hash of a proposal, and the preimage is the proposal's actual bytes. The chain stores only the hash to keep block size down; the bytes have to be made available off-chain before the referenced operation can execute. Polkadot Desktop exposes a preimage submission surface that Products can call through the Host API.
This page is the reference for that surface. The Bulletin Chain reference documents the storage layer that preimage submission often interacts with.
What the Preimage Surface Does
Section titled “What the Preimage Surface Does”Conceptually, the preimage surface lets a Product:
- Submit a preimage: Submit off-chain content for an on-chain operation that will reference it by hash. The Host signs the submission with the user's account, subject to the usual
ChainSubmitpermission and per-transaction approval on the paired App. - Provide hosting: Host the preimage so it is reachable when the on-chain operation executes. In practice, this often means writing the bytes to the Bulletin Chain and recording the resulting CID, but the exact storage path is part of the surface still being finalized.
Statement vs Preimage
Section titled “Statement vs Preimage”Statements and preimages are off-chain content addressed by hash, and both surfaces look superficially similar: your Product submits some bytes, gets a hash back, and the on-chain world refers to that hash later. The two are not interchangeable, though, and choosing the wrong one is a real failure mode.
| Property | Statement (Statement Store) | Preimage |
|---|---|---|
| What it is for | Real-time signaling between users: chat, presence, typing indicators, multiplayer state | Off-chain content that an on-chain operation must dereference: governance proposals, scheduled call payloads |
| Lifetime | Short TTL (default 30 seconds, gossip-distributed) | Lives until the referencing on-chain operation has completed (or until explicitly cleaned up) |
| Availability guarantee | Best-effort gossip; can be missed entirely if no peer was listening on the topic | Must be available for the referencing operation to execute; storage is durable |
| Validation gate | Allowance-gated by pallet-statement-store (max_count and max_size per account) | Gated by the same permission and signing requirements as any other on-chain submission |
| When to use | Anything users observe in real time and accept losing if the network dropped it | Anything an on-chain operation needs to read back later |
A useful rule of thumb: if your Product would still be correct after the bytes expire from network gossip, it is a statement. If the bytes need to be there in 30 minutes for a referendum to execute, it is a preimage.
Where to Go Next
Section titled “Where to Go Next”-
Statement Store via Host API
The other half of the Statement-vs-Preimage decision: when your content belongs on the gossip-distributed signaling layer instead of as an on-chain-referenced preimage.
-
Store Data on Chain
The Product-side how-to for Bulletin Chain storage, which the preimage surface often delegates to underneath.