Skip to main content
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

Upload flow from your app through the SDK, registering the action on chain, uploading the file to SN-API, RaptorQ encoding across the SuperNode mesh, and finalizing on chain.
1

Register the action on chain

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

Receive the action ID

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

Upload the file to a SuperNode

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

SuperNodes encode and distribute

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

Finalize on chain

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 for the full flow.

​
Next steps

Quickstart

Upload your first file in under five minutes.

Installation

Install the JavaScript and Go SDKs.

Upload lifecycle

See every phase of an upload in detail.