Lumera Cascade
Reference

SDK Methods

Complete API reference for the @lumera-protocol/sdk-js package.

createLumeraClient

Factory function that creates a fully configured Lumera client.

import { createLumeraClient } from "@lumera-protocol/sdk-js";
 
const client = await createLumeraClient({
  preset: "testnet",       // "testnet" | "mainnet"
  signer: wallet,          // OfflineSigner (CosmJS wallet or Keplr)
  address: "lumera1...",   // Sender address
  gasPrice: "0.025ulume",  // Gas price for fee estimation
});

Parameters:

FieldTypeRequiredDescription
preset"testnet" | "mainnet"NoUse preset endpoints
rpcEndpointstringNoCustom RPC endpoint
lcdEndpointstringNoCustom LCD/REST endpoint
snapiEndpointstringNoCustom SN-API endpoint
signerOfflineSignerNoWallet signer (required for write operations)
addressstringNoSender address (required for write operations)
gasPricestringNoGas price string (e.g., "0.025ulume")

Returns: Promise<LumeraClient>


Cascade Uploader

uploadFile

Unified upload method that runs prepare, register, and send phases.

const result = await client.Cascade.uploader.uploadFile(fileBytes, {
  fileName: "document.pdf",
  isPublic: true,
  expirationTime: "1742553600", // Unix timestamp (optional)
  taskOptions: {
    pollInterval: 2000,         // ms between status polls
    timeout: 300000,            // ms before timeout
  },
});

Parameters:

FieldTypeRequiredDescription
fileBytesUint8ArrayYesFile content as bytes
options.fileNamestringNoFilename metadata
options.isPublicbooleanNoWhether the file is publicly downloadable
options.expirationTimestringNoUnix timestamp for expiration
options.taskOptions.pollIntervalnumberNoPolling interval in ms (default: 2000)
options.taskOptions.timeoutnumberNoTimeout in ms (default: 300000)

Returns: Promise<UploadResult> containing action_id and taskId


prepareFile

Converts input to bytes and computes the BLAKE3 hash.

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

Parameters:

FieldTypeDescription
fileUint8Array | File | BlobInput file

Returns: Promise<{ fileBytes: Uint8Array; dataHash: string }>


registerAction

Registers the Cascade action on-chain (generates layout, signs, broadcasts transaction).

const { actionId, authSignature } = await client.Cascade.uploader.registerAction(
  { fileBytes, dataHash },
  options
);

Returns: Promise<{ actionId: string; authSignature: string }>

This method requires WASM (RaptorQ) support. It works in browsers but has known issues in Node.js.


makeAuthSignature

Creates an authentication signature for an existing action (useful if you need to re-upload).

const authSig = await client.Cascade.uploader.makeAuthSignature(actionId, dataHash);

sendFileToSupernodes

Sends the file to the SN-API after on-chain registration.

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

Retries up to 5 times with 3-second delays for SN-API indexing delays.


Cascade Downloader

download

Downloads a file by action ID. Returns a readable stream.

const stream: ReadableStream<Uint8Array> = await client.Cascade.downloader.download(actionId);

Parameters:

FieldTypeDescription
actionIdstringThe action ID from upload
taskOptionsobjectOptional polling configuration

Returns: Promise<ReadableStream<Uint8Array>>


downloadFile

Full download with explicit options.

const stream = await client.Cascade.downloader.downloadFile({
  actionId: "your-action-id",
  taskOptions: {
    pollInterval: 2000,
    timeout: 120000,
  },
});

downloadPrivate

Identical to download — authentication is always applied via ADR-036 signature.

const stream = await client.Cascade.downloader.downloadPrivate(actionId);

Blockchain Queries

getActionParams

Returns current chain parameters for Cascade actions.

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

Results are cached for 5 minutes.


getAction

Looks up a registered action by ID.

const action = await client.Blockchain.getAction(actionId);
// { creator, actionType, dataHash, state, ... }

getActionFee

Estimates the storage fee for a given file size.

const fee = await client.Blockchain.getActionFee(fileSizeBytes);
// { fee: string } in ulume

getSupernodes

Lists all registered Supernodes.

const nodes = await client.Blockchain.getSupernodes();

Wallet Helpers

getKeplrSigner

Returns a universal signer from the Keplr browser extension.

import { getKeplrSigner } from "@lumera-protocol/sdk-js";
 
const signer = await getKeplrSigner("lumera-testnet-2");

The returned signer supports signDirect, signAmino, and signArbitrary (ADR-036).


getLeapSigner

Same interface for the Leap browser extension.

import { getLeapSigner } from "@lumera-protocol/sdk-js";
 
const signer = await getLeapSigner("lumera-testnet-2");

Task Status Values

StatusCategoryMeaning
sdk:completedSuccessOperation completed
sdk:upload_completedSuccessUpload confirmed
sdk:download_completedSuccessDownload ready
sdk:failedFailureGeneric failure
sdk:supernodes_unavailableFailureNo Supernodes accepted the task
sdk:registration_failureFailureOn-chain registration failed
sdk:upload_failedFailureFile transfer failed
sdk:processing_failedFailureSN-API processing failed
sdk:processing_timeoutFailureProcessing exceeded timeout
sdk:download_failureFailureDownload reconstruction failed

Next Steps