Cascade upload lifecycle

Knowing what happens inside a Cascade upload helps you debug failed uploads and build custom flows on Lumera Protocol. This page walks through each phase, the on-chain action states, and the task states the SDK reports. A Cascade upload has three phases. The uploadFile method in the JavaScript SDK (@lumera-protocol/sdk-js) runs all three for you. You can also run them individually for fine-grained control.

Phase	SDK method
Prepare	`prepareFile`
Register	`registerAction`
Send	`sendFileToSupernodes`

Prepare the file

const { fileBytes, dataHash } = await client.Cascade.uploader.prepareFile(file);

The prepare phase does two things.

It converts the input file (a Uint8Array, File, or Blob) to a Uint8Array.
It computes a BLAKE3 hash over the file bytes. This hash becomes the permanent content identifier stored on-chain.

Register the action on-chain

const { actionId, authSignature } = await client.Cascade.uploader.registerAction(
  { fileBytes, dataHash },
  {
    fileName: "paper.pdf",
    isPublic: true,
    taskOptions: { pollInterval: 2000, timeout: 300000 },
  }
);

Registration runs seven sub-steps.

Fetch action parameters

The SDK queries the chain for the current action parameters.

const actionParams = await client.Blockchain.getActionParams();
// Returns: { max_raptor_q_symbols, ... }

These parameters determine the RaptorQ encoding configuration. The SDK caches the result for 5 minutes.

Generate the RaptorQ layout

The SDK runs the file through the RaptorQ WASM module to generate an erasure coding layout.

rq_ids_ic is a random counter seed in [0, max_raptor_q_symbols).
The layout contains block-level encoding metadata that SuperNodes need to store and reconstruct the file.
The layout JSON is compacted (no whitespace) to match the Go reference implementation.

See erasure coding for how the layout works.

Sign the layout with ADR-036

The compacted layout bytes are signed with ADR-036 signArbitrary. ADR-036 is the Cosmos standard for signing arbitrary data outside a transaction.

signer.signArbitrary(chainId, address, layoutBytes)

This signature proves the layout was created by the account that registered the action.

Derive layout IDs

Layout IDs are deterministic identifiers derived from the layout and its signature. The algorithm must match the on-chain Go implementation exactly.

For each i in [0, rq_ids_max):
  counter = rq_ids_ic + i
  input   = Base64(layout) + "." + Base64(signature) + "." + decimal(counter)
  compressed = zstd(input, level=3)
  hash    = BLAKE3(compressed)
  id      = Base58(hash)

These IDs are included in the on-chain action. SuperNodes use them to verify data integrity.

Build the LEP-1 index file

LEP-1 (Lumera Enhancement Proposal 1) defines a compact index that aggregates the layout IDs and the layout signature.

{
  "version": 1,
  "layout_ids": ["7K9x...", "3Jm2...", "..."],
  "layout_signature": "base64..."
}

The index file is signed with ADR-036 and included in the on-chain registration.

Create the auth signature

The SDK creates a separate signature over the dataHash. This auth signature later authenticates the file upload to the SN-API, the HTTP API served by SuperNodes.

Broadcast MsgRequestAction

The SDK simulates the transaction to estimate gas, then signs and broadcasts it.

// Simplified. The SDK builds this internally.
const msg = {
  typeUrl: "/lumera.action.v1.MsgRequestAction",
  value: {
    creator: address,
    actionType: "ACTION_TYPE_CASCADE",
    dataHash: dataHash,
    rqIds: layoutIds,
    // ... other fields
  },
};

The chain validates the message, escrows the storage fee, and emits an action_registered event. The SDK extracts the action_id from the event attributes. The action_id is your permanent reference to the stored file.

Send the file to SuperNodes

const uploadResult = await client.Cascade.uploader.sendFileToSupernodes(
  actionId,
  authSignature,
  fileBytes,
  { taskOptions: { pollInterval: 2000, timeout: 300000 } }
);

The send phase has four steps.

The SDK sends the file as multipart form data to POST /api/v1/actions/cascade.
The SN-API distributes chunks to the SuperNode mesh.
The SDK polls GET /api/v1/actions/cascade/tasks/{task_id} at the configured interval.
The upload completes when the task reaches a terminal status.

The multipart request carries three fields.

FormData {
  action_id: string
  signature: string (auth signature)
  file: Blob
}

Upload in one call

For most use cases, call uploadFile to run all three phases.

const result = await client.Cascade.uploader.uploadFile(fileBytes, {
  fileName: "document.pdf",
  isPublic: true,
  taskOptions: {
    pollInterval: 2000,  // Check every 2 seconds
    timeout: 300000,     // Fail after 5 minutes
  },
});

console.log(result.action_id); // Use this to download later

Action states on chain

After registration, the on-chain action moves through four states.

PENDING --> PROCESSING --> DONE
                |
                +--> FAILED

State	Meaning
`PENDING`	Action registered and fee escrowed, waiting for the file
`PROCESSING`	SuperNodes encode the file and distribute symbols
`DONE`	Symbols stored, the file is permanently available
`FAILED`	The upload failed or expired

The storage fee is escrowed at registration. If the action fails or expires, the fee is refunded. The current fee is a 10000 ulume base plus 10 ulume per KB. A 1 MB file costs about 0.02 LUME. Fee parameters can change through governance.

SDK task states

The SDK reports progress through task statuses.

Status	Phase	Meaning
`sdk:completed`	Upload	File successfully stored
`sdk:upload_completed`	Upload	Upload confirmed
`sdk:failed`	Upload	Generic failure
`sdk:supernodes_unavailable`	Upload	No SuperNode accepted the task
`sdk:registration_failure`	Register	On-chain registration failed
`sdk:upload_failed`	Upload	File transfer to the SN-API failed
`sdk:processing_failed`	Upload	The SN-API could not process the file
`sdk:processing_timeout`	Upload	Processing exceeded the timeout

Retry behavior

The SDK retries the SN-API upload up to 5 times with a 3-second delay between attempts. This covers the window where a SuperNode has not yet indexed the on-chain action. The chain and the SN-API are eventually consistent.

Next steps

Download lifecycle

How authenticated downloads stream files back from SuperNodes.

Erasure coding

How RaptorQ encoding and LEP-1 layout IDs work.

Error handling

Handle failed task states and retries in production.

Overview

Get started

The Intelligence Layer

SDKs

Smart contracts

Operate the Network

Interoperability

Applications

Protocol Reference

Prepare the file

Register the action on-chain

Fetch action parameters

Generate the RaptorQ layout

Sign the layout with ADR-036

Derive layout IDs

Build the LEP-1 index file

Create the auth signature

Broadcast MsgRequestAction

Send the file to SuperNodes

Upload in one call

Action states on chain

SDK task states

Retry behavior

Next steps

Download lifecycle

Erasure coding

Error handling

​Prepare the file

​Register the action on-chain

​Fetch action parameters

​Generate the RaptorQ layout

​Sign the layout with ADR-036

​Derive layout IDs

​Build the LEP-1 index file

​Create the auth signature

​Broadcast MsgRequestAction

​Send the file to SuperNodes

​Upload in one call

​Action states on chain

​SDK task states

​Retry behavior

​Next steps

Download lifecycle

Erasure coding

Error handling

Prepare the file

Register the action on-chain

Fetch action parameters

Generate the RaptorQ layout

Sign the layout with ADR-036

Derive layout IDs

Build the LEP-1 index file

Create the auth signature

Broadcast MsgRequestAction

Send the file to SuperNodes

Upload in one call

Action states on chain

SDK task states

Retry behavior

Next steps