JavaScript SDK reference

This page lists the public surface of @lumera-protocol/sdk-js. For a guided start see the JavaScript SDK page.

createLumeraClient

The factory function that builds a configured client.

import { createLumeraClient } from "@lumera-protocol/sdk-js";

const client = await createLumeraClient({
  preset: "testnet",
  signer: wallet,
  address: "lumera1...",
  gasPrice: "0.025ulume",
});

Field	Type	Required	Description
`preset`	`"testnet"` or `"mainnet"`	No	Fills in chain ID and endpoints for the chosen network
`rpcUrl`	`string`	No	Custom CometBFT RPC endpoint
`lcdUrl`	`string`	No	Custom LCD or REST endpoint
`chainId`	`string`	No	Custom chain ID when not using a preset
`cascade.snapiBaseUrl`	`string`	No	Custom SN-API gateway endpoint
`signer`	`OfflineSigner`	No	Wallet signer, required for writes
`address`	`string`	No	Sender address, required for writes
`gasPrice`	`string`	No	Gas price string such as `"0.025ulume"`

Returns Promise<LumeraClient>. The signer needs signDirect, signAmino, and signArbitrary for the full feature set. See wallet options.

Cascade uploader

uploadFile

Runs the whole upload in one call. Prepare, register on chain, and send to SuperNodes.

const result = await client.Cascade.uploader.uploadFile(fileBytes, {
  fileName: "document.pdf",
  isPublic: true,
  expirationTime: "1742553600",
  taskOptions: { pollInterval: 2000, timeout: 300000 },
});

Option	Type	Description
`fileName`	`string`	Filename metadata
`isPublic`	`boolean`	Whether the file downloads without the owner signature
`expirationTime`	`string`	Unix timestamp. Unfinalized uploads past this time refund the fee
`taskOptions.pollInterval`	`number`	Milliseconds between status polls, default 2000
`taskOptions.timeout`	`number`	Milliseconds before timeout, default 300000

Returns a result with action_id, the permanent on-chain reference to the file.

Lower level upload steps

Use these when you need control over individual phases.

Method	Purpose
`prepareFile(file)`	Convert `Uint8Array`, `File`, or `Blob` to bytes and compute the BLAKE3 hash
`registerAction({ fileBytes, dataHash }, options)`	Generate the layout, sign it, and broadcast the registration transaction
`makeAuthSignature(actionId, dataHash)`	Create an auth signature for an existing action
`sendFileToSupernodes(actionId, authSignature, fileBytes, options)`	Send the file to the SN-API gateway after registration

sendFileToSupernodes retries up to 5 times with 3 second delays to absorb SN-API indexing lag.

Cascade downloader

Method	Purpose
`download(actionId, taskOptions?)`	Download by action ID. Returns `Promise<ReadableStream<Uint8Array>>`
`downloadFile({ actionId, taskOptions })`	Same download with an explicit options object
`downloadPrivate(actionId)`	Download with the owner ADR-036 signature always applied

Every download authenticates with an ADR-036 signature over the action ID. The download lifecycle page shows how to consume the stream.

Blockchain queries

Method	Returns
`Blockchain.getChainId()`	The connected chain ID
`Blockchain.getActionParams()`	Current action parameters such as `max_raptor_q_symbols`
`Blockchain.getAction(actionId)`	The action record with `creator`, `actionType`, `dataHash`, and `state`
`Blockchain.getActionFee(fileSizeBytes)`	The estimated storage fee in `ulume`
`Blockchain.getSupernodes()`	All registered SuperNodes
`Blockchain.Tx.simulate(address, msgs)`	Gas estimate for a set of messages
`Blockchain.Tx.broadcast(signedTx)`	Broadcast result for a signed transaction

Chain parameter queries are cached for 5 minutes.

Wallet helpers

Helper	Purpose
`getKeplrSigner(chainId)`	Signer from the Keplr extension with `signDirect`, `signAmino`, and `signArbitrary`
`getLeapSigner(chainId)`	The same interface for the Leap extension
`isKeplrAvailable()`	Whether the Keplr extension is present

LEP-1 helpers

For deterministic layout and ID work that must match on-chain validation.

import {
  createSingleBlockLayout,
  generateIds,
  buildIndexFile,
} from "@lumera-protocol/sdk-js";

const layoutBytes = await createSingleBlockLayout(fileBytes);
const layoutIds = await generateIds(layoutFileB64, layoutSignatureB64, rq_ids_ic, rq_ids_max);
const index = buildIndexFile(layoutIds, layoutSignatureB64);

The erasure coding page explains the derivation scheme these helpers implement.

Task status values

The SDK reports task progress with these statuses.

Status	Category	Meaning
`sdk:completed`	Success	Operation completed
`sdk:upload_completed`	Success	Upload confirmed
`sdk:download_completed`	Success	Download ready
`sdk:failed`	Failure	Generic failure
`sdk:supernodes_unavailable`	Failure	No SuperNode accepted the task
`sdk:registration_failure`	Failure	On-chain registration failed
`sdk:upload_failed`	Failure	File transfer failed
`sdk:processing_failed`	Failure	SN-API processing failed
`sdk:processing_timeout`	Failure	Processing exceeded the timeout
`sdk:download_failure`	Failure	Download reconstruction failed

On-chain action states are separate. They move from PENDING to PROCESSING to DONE or FAILED. See error handling for recovery patterns.

Overview

Get started

The Intelligence Layer

SDKs

Smart contracts

Operate the Network

Interoperability

Applications

Protocol Reference

createLumeraClient

Cascade uploader

uploadFile

Lower level upload steps

Cascade downloader

Blockchain queries

Wallet helpers

LEP-1 helpers

Task status values

Next steps

JavaScript SDK getting started

Error handling

​createLumeraClient

​Cascade uploader

​uploadFile

​Lower level upload steps

​Cascade downloader

​Blockchain queries

​Wallet helpers

​LEP-1 helpers

​Task status values

​Next steps

JavaScript SDK getting started

Error handling

createLumeraClient

Cascade uploader

uploadFile

Lower level upload steps

Cascade downloader

Blockchain queries

Wallet helpers

LEP-1 helpers

Task status values

Next steps