> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK reference

> Every method, option, and status value in the Lumera JavaScript SDK.

This page lists the public surface of [`@lumera-protocol/sdk-js`](https://github.com/LumeraProtocol/sdk-js). For a guided start see the [JavaScript SDK page](/sdk/javascript).

## createLumeraClient

The factory function that builds a configured client.

```ts theme={null}
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](/sdk/javascript#wallet-options).

## Cascade uploader

### uploadFile

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

```ts theme={null}
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](/cascade/concepts/download-lifecycle) 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.

```ts theme={null}
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](/cascade/concepts/erasure-coding) 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](/cascade/error-handling) for recovery patterns.

## Next steps

<CardGroup cols={2}>
  <Card title="JavaScript SDK getting started" icon="js" href="/sdk/javascript">
    Install, connect a wallet, and run your first upload.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/cascade/error-handling">
    Handle every failure mode with working code.
  </Card>
</CardGroup>