Build a browser app

In this guide you build a Vite and TypeScript single page app that connects to the Keplr wallet, uploads files to Cascade, and retrieves them again by action ID. Cascade is the permanent storage service of Lumera Protocol. You pay once at upload time and the file stays available forever. Every upload returns an action ID. This is the permanent on-chain reference you later use to download the file. The app talks to Cascade straight from the browser. The SDK handles the SN-API transfer, so you do not need a backend server for storage.

What you need

Node.js 18 or later
The Keplr browser extension
Testnet LUME for fees. Request tokens from the faucet.

Build the app

Scaffold the project

Create a new Vite project and install the SDK together with the browser build tooling.

npm create vite@latest my-cascade-app -- --template vanilla-ts
cd my-cascade-app
npm install @lumera-protocol/sdk-js @cosmjs/proto-signing @cosmjs/stargate
npm install -D vite-plugin-node-polyfills vite-plugin-wasm vite-plugin-top-level-await

Configure Vite

The SDK depends on WASM modules and Node.js globals that need polyfilling in the browser.

vite.config.ts

import { defineConfig } from "vite";
import { nodePolyfills } from "vite-plugin-node-polyfills";
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  plugins: [
    wasm(),
    topLevelAwait(),
    nodePolyfills({
      include: ["buffer", "process"],
      globals: { Buffer: true, global: true, process: true },
    }),
  ],
  optimizeDeps: {
    exclude: ["undici", "@bokuweb/zstd-wasm"],
  },
  define: {
    "process.env": "{}",
  },
});

Add the chain configuration

This file holds the testnet chain ID, the gas price, and the chain record the app suggests to Keplr.

src/config.ts

export const CHAIN_ID = "lumera-testnet-2";
export const GAS_PRICE = "0.025ulume";
export const CHAIN_INFO = {
  chainId: CHAIN_ID,
  chainName: "Lumera Testnet",
  rpc: "https://rpc.testnet.lumera.io",
  rest: "https://lcd.testnet.lumera.io",
  bip44: { coinType: 60 },
  bech32Config: {
    bech32PrefixAccAddr: "lumera",
    bech32PrefixAccPub: "lumerapub",
    bech32PrefixValAddr: "lumeravaloper",
    bech32PrefixValPub: "lumeravaloperpub",
    bech32PrefixConsAddr: "lumeravalcons",
    bech32PrefixConsPub: "lumeravalconspub",
  },
  currencies: [
    { coinDenom: "LUME", coinMinimalDenom: "ulume", coinDecimals: 6 },
  ],
  feeCurrencies: [
    {
      coinDenom: "LUME",
      coinMinimalDenom: "ulume",
      coinDecimals: 6,
      gasPriceStep: { low: 0.025, average: 0.03, high: 0.04 },
    },
  ],
  stakeCurrency: {
    coinDenom: "LUME",
    coinMinimalDenom: "ulume",
    coinDecimals: 6,
  },
  features: ["stargate", "ibc-transfer", "eth-address-gen", "eth-key-sign"],
};

Connect the Keplr wallet

experimentalSuggestChain registers the Lumera testnet in Keplr the first time a user connects.

src/wallet.ts

import { CHAIN_ID, CHAIN_INFO } from "./config";

export async function connectKeplr(): Promise<{
  address: string;
  signer: any;
}> {
  if (!window.keplr) {
    throw new Error("Keplr extension not found. Please install Keplr.");
  }

  // Suggest the Lumera chain to Keplr
  await window.keplr.experimentalSuggestChain(CHAIN_INFO);
  await window.keplr.enable(CHAIN_ID);

  const offlineSigner = await window.keplr.getOfflineSignerAuto(CHAIN_ID);
  const accounts = await offlineSigner.getAccounts();

  return {
    address: accounts[0].address,
    signer: offlineSigner,
  };
}

Create the Cascade client

The getKeplrSigner helper wraps the Keplr signer with the ADR-036 signArbitrary support that Cascade uses to authenticate storage operations. ADR-036 is the Cosmos standard for signing arbitrary off-chain messages.

src/cascade.ts

import { createLumeraClient, getKeplrSigner } from "@lumera-protocol/sdk-js";
import { CHAIN_ID, GAS_PRICE } from "./config";

let client: Awaited<ReturnType<typeof createLumeraClient>> | null = null;

export async function initCascade(address: string) {
  const signer = await getKeplrSigner(CHAIN_ID);

  client = await createLumeraClient({
    preset: "testnet",
    signer,
    address,
    gasPrice: GAS_PRICE,
  });

  return client;
}

export async function uploadFile(
  file: File,
  onProgress?: (status: string) => void
): Promise<string> {
  if (!client) throw new Error("Client not initialized");

  onProgress?.("Reading file...");
  const fileBytes = new Uint8Array(await file.arrayBuffer());

  onProgress?.("Registering action on-chain...");
  const result = await client.Cascade.uploader.uploadFile(fileBytes, {
    fileName: file.name,
    isPublic: true,
    taskOptions: {
      pollInterval: 2000,
      timeout: 300000,
    },
  });

  const actionId =
    (result as any).action_id || result.taskId || `file-${Date.now()}`;

  onProgress?.(`Upload complete! Action ID: ${actionId}`);
  return actionId;
}

export async function downloadFile(actionId: string): Promise<Uint8Array> {
  if (!client) throw new Error("Client not initialized");

  const stream = await client.Cascade.downloader.download(actionId);
  const reader = stream.getReader();
  const chunks: Uint8Array[] = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    if (value) chunks.push(value);
  }

  // Reassemble chunks
  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
  const result = new Uint8Array(totalLength);
  let offset = 0;
  for (const chunk of chunks) {
    result.set(chunk, offset);
    offset += chunk.length;
  }

  return result;
}

Wire up the UI

The page has three controls. A connect button, an upload button with a file picker, and a download button with an action ID field.

src/main.ts

import { connectKeplr } from "./wallet";
import { initCascade, uploadFile, downloadFile } from "./cascade";

const connectBtn = document.getElementById("connect") as HTMLButtonElement;
const uploadBtn = document.getElementById("upload") as HTMLButtonElement;
const downloadBtn = document.getElementById("download") as HTMLButtonElement;
const fileInput = document.getElementById("file") as HTMLInputElement;
const actionIdInput = document.getElementById("actionId") as HTMLInputElement;
const status = document.getElementById("status") as HTMLDivElement;

let address: string | null = null;

connectBtn.addEventListener("click", async () => {
  try {
    const wallet = await connectKeplr();
    address = wallet.address;
    await initCascade(address);
    status.textContent = `Connected: ${address}`;
    uploadBtn.disabled = false;
    downloadBtn.disabled = false;
  } catch (err: any) {
    status.textContent = `Error: ${err.message}`;
  }
});

uploadBtn.addEventListener("click", async () => {
  const file = fileInput.files?.[0];
  if (!file) {
    status.textContent = "Please select a file first.";
    return;
  }

  try {
    const actionId = await uploadFile(file, (s) => {
      status.textContent = s;
    });
    actionIdInput.value = actionId;
    status.textContent = `File stored permanently! Action ID: ${actionId}`;
  } catch (err: any) {
    status.textContent = `Upload error: ${err.message}`;
  }
});

downloadBtn.addEventListener("click", async () => {
  const actionId = actionIdInput.value.trim();
  if (!actionId) {
    status.textContent = "Enter an action ID to download.";
    return;
  }

  try {
    status.textContent = "Downloading...";
    const data = await downloadFile(actionId);
    status.textContent = `Downloaded ${data.length} bytes.`;

    // Trigger browser download
    const blob = new Blob([data]);
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "cascade-file";
    a.click();
    URL.revokeObjectURL(url);
  } catch (err: any) {
    status.textContent = `Download error: ${err.message}`;
  }
});

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Cascade File Storage</title>
    <style>
      body { font-family: system-ui; max-width: 600px; margin: 2rem auto; padding: 0 1rem; }
      button { padding: 0.5rem 1rem; margin: 0.25rem; cursor: pointer; }
      input { padding: 0.5rem; margin: 0.25rem; width: 100%; box-sizing: border-box; }
      #status { margin-top: 1rem; padding: 1rem; background: #f5f5f5; border-radius: 0.5rem; }
    </style>
  </head>
  <body>
    <h1>Cascade File Storage</h1>
    <button id="connect">Connect Keplr</button>
    <hr />
    <h2>Upload</h2>
    <input type="file" id="file" />
    <button id="upload" disabled>Upload to Cascade</button>
    <hr />
    <h2>Download</h2>
    <input type="text" id="actionId" placeholder="Enter action ID" />
    <button id="download" disabled>Download from Cascade</button>
    <div id="status">Not connected</div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Run the app

npm run dev

Open http://localhost:5173, connect Keplr, and upload a file. The returned action ID is your permanent reference. Use it to retrieve the file from anywhere, at any time.

Key takeaways

Use getKeplrSigner or getLeapSigner from the SDK. They wrap the wallet extension signer with the ADR-036 signArbitrary support that Cascade requires.
The action ID is your permanent reference. Store it in your database, on chain, or wherever your application tracks state.
Uploads run in two phases. The SDK first registers the action on chain, then transfers the file to a SuperNode.
Downloads are streamed. Read from the ReadableStream so large files never sit fully in memory.

Next steps

Encrypted storage

Encrypt files client-side before uploading them to Cascade.

Research Archive example

Explore a full publishing platform built on Cascade.

Node.js guide

Run the same SDK on a server with a programmatic signer.

Overview

Get started

The Intelligence Layer

SDKs

Smart contracts

Operate the Network

Interoperability

Applications

Protocol Reference

What you need

Build the app

Key takeaways

Next steps

Encrypted storage

Research Archive example

Node.js guide

​What you need

​Build the app

​Key takeaways

​Next steps

Encrypted storage

Research Archive example

Node.js guide

What you need

Build the app

Key takeaways

Next steps