> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# How Cascade works
> Follow an upload from on-chain registration to permanent storage across the SuperNode network.
Cascade is the permanent storage service of Lumera Protocol. You pay one fee at upload time, and the network stores your file for good. This page follows one upload from start to finish, so you know what the SDK does on your behalf.
## Architecture at a glance
Cascade splits the work between two planes. The control plane is the Lumera blockchain. It records every stored file as an action and holds the storage fee. The data plane is the SuperNode network. It encodes, stores, and serves the actual bytes. The SDK drives both, so your app makes a single function call.
## The upload flow
The SDK prepares the file before it touches the chain.
1. It computes a BLAKE3 hash of the file. This `data_hash` becomes the permanent content identifier stored on chain.
2. It generates a RaptorQ layout. The layout is metadata that describes how the file will be encoded, not the encoding itself.
3. It signs the layout, derives deterministic layout IDs, and builds a signed index file.
The SDK then submits a `MsgRequestAction` transaction to the Lumera chain. The message carries the `data_hash`, the file name, a visibility flag for public or private access, and the one-time storage fee in `ulume`.
The chain validates the transaction, escrows the fee, and emits an `action_registered` event that contains the `action_id`. The SDK extracts the ID from the transaction response. The `action_id` is the permanent on-chain reference for your file.
The SDK sends a multipart POST to `/api/v1/actions/cascade` on SN-API, the REST gateway that runs inside each SuperNode. The request carries three fields.
| Field | Contents |
| ----------- | --------------------------------------------- |
| `action_id` | The on-chain reference from the previous step |
| `signature` | An ADR-036 signature of the `data_hash` |
| `file` | The raw file bytes |
ADR-036 is the Cosmos standard for signing arbitrary data offline. Cascade uses it to prove you control the uploading wallet without an extra transaction. SN-API returns a `task_id` that the SDK polls for progress.
The SuperNode that received the file does three things.
1. It verifies that the action exists on chain, the fee is valid, the BLAKE3 hash matches, and all signatures are correct.
2. It encodes the file with RaptorQ erasure coding. RaptorQ produces redundant symbols, and any sufficiently large subset of them can rebuild the file.
3. It distributes the encoded symbols across the SuperNode mesh, so no single node becomes a point of failure.
After encoding and distribution complete, the SuperNode submits a `MsgFinalizeAction` transaction back to the chain. The action state moves from `PENDING` through `PROCESSING` to `DONE`. If encoding or distribution fails, the state becomes `FAILED` instead. On success, the chain records the file as stored and retrievable, and the escrowed fee is released to the participating SuperNodes.
## Pay once, store forever
Cascade charges one storage fee when the action registers, and never bills again. The current fee is 10,000 `ulume` base plus 10 `ulume` per KB, which comes to about 0.02 LUME for a 1 MB file. These parameters can change through governance. The protocol handles payments and refunds automatically, so a failed or expired upload returns the escrowed fee to your wallet.
## Retrieving your file
Once the action reaches `DONE`, the file is permanently stored. To retrieve it, the SDK signs the `action_id` with an ADR-036 signature, authenticates with the SuperNode network, and streams the reconstructed file back to your app. See [Download lifecycle](/cascade/concepts/download-lifecycle) for the full flow.
## Next steps
Upload your first file in under five minutes.
Install the JavaScript and Go SDKs.
See every phase of an upload in detail.