SDK Methods
Complete API reference for the @lumera-protocol/sdk-js package.
createLumeraClient
Factory function that creates a fully configured Lumera client.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
preset | "testnet" | "mainnet" | No | Use preset endpoints |
rpcEndpoint | string | No | Custom RPC endpoint |
lcdEndpoint | string | No | Custom LCD/REST endpoint |
snapiEndpoint | string | No | Custom SN-API endpoint |
signer | OfflineSigner | No | Wallet signer (required for write operations) |
address | string | No | Sender address (required for write operations) |
gasPrice | string | No | Gas price string (e.g., "0.025ulume") |
Returns: Promise<LumeraClient>
Cascade Uploader
uploadFile
Unified upload method that runs prepare, register, and send phases.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
fileBytes | Uint8Array | Yes | File content as bytes |
options.fileName | string | No | Filename metadata |
options.isPublic | boolean | No | Whether the file is publicly downloadable |
options.expirationTime | string | No | Unix timestamp for expiration |
options.taskOptions.pollInterval | number | No | Polling interval in ms (default: 2000) |
options.taskOptions.timeout | number | No | Timeout in ms (default: 300000) |
Returns: Promise<UploadResult> containing action_id and taskId
prepareFile
Converts input to bytes and computes the BLAKE3 hash.
Parameters:
| Field | Type | Description |
|---|---|---|
file | Uint8Array | File | Blob | Input file |
Returns: Promise<{ fileBytes: Uint8Array; dataHash: string }>
registerAction
Registers the Cascade action on-chain (generates layout, signs, broadcasts transaction).
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).
sendFileToSupernodes
Sends the file to the SN-API after on-chain registration.
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.
Parameters:
| Field | Type | Description |
|---|---|---|
actionId | string | The action ID from upload |
taskOptions | object | Optional polling configuration |
Returns: Promise<ReadableStream<Uint8Array>>
downloadFile
Full download with explicit options.
downloadPrivate
Identical to download — authentication is always applied via ADR-036 signature.
Blockchain Queries
getActionParams
Returns current chain parameters for Cascade actions.
Results are cached for 5 minutes.
getAction
Looks up a registered action by ID.
getActionFee
Estimates the storage fee for a given file size.
getSupernodes
Lists all registered Supernodes.
Wallet Helpers
getKeplrSigner
Returns a universal signer from the Keplr browser extension.
The returned signer supports signDirect, signAmino, and signArbitrary (ADR-036).
getLeapSigner
Same interface for the Leap browser extension.
Task Status Values
| 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 Supernodes 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 timeout |
sdk:download_failure | Failure | Download reconstruction failed |