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 }>


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

Edit this page

On this page