Skip to content

browser

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

browser

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
test-assets
test-assets
 
 
README.md
README.md
 
 
index.html
index.html
 
 
main.ts
main.ts
 
 
package.json
package.json
 
 
pnpm-lock.yaml
pnpm-lock.yaml
 
 
tsconfig.json
tsconfig.json
 
 
vite.config.ts
vite.config.ts
 
 

README.md

Browser Example

This example demonstrates the full Lumera SDK workflow in a browser environment with Keplr wallet integration.

Overview

This interactive web application showcases:

  • Keplr Wallet Connection: Seamless integration with the Keplr browser extension
  • Blockchain Queries: Real-time queries to the Lumera testnet
  • File Upload: Upload files to Cascade distributed storage
  • File Download: Download and verify files from Cascade storage
  • Progress Tracking: Visual feedback for all operations
  • Activity Logging: Real-time activity log for debugging and transparency

Prerequisites

  1. Node.js 18+ - Required for building the example
  2. Keplr Browser Extension - Install from keplr.app
  3. Lumera Testnet Tokens - Ensure your Keplr wallet has testnet LUME tokens

Installation

  1. Navigate to the browser example directory:

    cd examples/browser

  2. Install dependencies:

    pnpm install

Running the Example

Start the development server:

pnpm run dev

This will:

  • Build the application with Vite
  • Start a local development server (at http://localhost:3001 by default)
  • Automatically open your browser

The browser example is always wired to the local SDK source.
Vite resolves @lumera-protocol/sdk-js and its browser shims to the code in ../../src, so any changes you make in sdk-js/src are immediately reflected when you run the example.

Using the Application

Step 1: Connect Your Wallet

  1. Click the "Connect Keplr Wallet" button
  2. Keplr will prompt you to approve the connection
  3. Once connected, your address will be displayed
  4. The application will automatically query blockchain parameters

Step 2: Upload a File

  1. Click "Choose a file to upload" to select a file from your computer
  2. The file name and size will be displayed
  3. Click "Upload to Cascade" to start the upload
  4. Progress will be shown with a progress bar
  5. When complete, a unique action ID will be assigned to your file

Step 3: Download the File

  1. After uploading, click "Download Last Uploaded File"
  2. The file will be downloaded from Cascade storage
  3. Progress will be tracked and displayed
  4. The file will be saved to your downloads folder

Activity Log

The activity log at the bottom of the page shows:

  • ℹ️ Info messages (blue) - General operations
  • ✓ Success messages (green) - Completed operations
  • ⚠️ Warning messages (yellow) - Important notices
  • ✗ Error messages (red) - Failed operations

Building for Production

To create a production build:

pnpm run build

The built files will be in the dist/ directory and can be deployed to any static hosting service.

To preview the production build locally:

pnpm run preview

Project Structure

examples/browser/
├── index.html         # Main HTML file with UI structure
├── main.ts           # TypeScript application logic
├── package.json      # Dependencies and scripts
├── vite.config.ts    # Vite build configuration (uses local sdk-js/src)
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file

Code Architecture

State Management

The application maintains state for:

  • client: LumeraClient instance
  • address: Connected wallet address
  • chainId: Target blockchain network
  • lastActionId: Most recent upload action ID
  • selectedFile: File selected for upload

Key Functions

connectWallet()

  • Checks for Keplr availability
  • Requests wallet connection
  • Creates LumeraClient with Keplr signer
  • Queries blockchain parameters

uploadFile()

  • Reads selected file as ArrayBuffer
  • Generates unique action ID
  • Uploads to Cascade storage via SDK
  • Tracks progress and displays results

downloadFile()

  • Requests file from Cascade storage
  • Streams file chunks
  • Combines chunks into complete file
  • Triggers browser download

UI Updates

The application provides real-time feedback through:

  • Status indicators (connected/disconnected)
  • Progress bars for uploads and downloads
  • Activity log with color-coded messages
  • Button state management based on application state

Common Issues

"Keplr extension not found"

Solution: Install the Keplr browser extension from keplr.app

Connection timeout or network errors

Solutions:

  • Check your internet connection

  • Verify the Lumera testnet is operational

  • Try increasing timeout values in main.ts:

    http: {
  timeout: 60000,  // Increase to 60 seconds
  maxRetries: 5,   // Increase retry attempts
}

"Insufficient funds" errors

Solution: Request testnet tokens from the Lumera faucet. Your wallet needs LUME tokens to pay for transaction fees.

Upload or download fails

Troubleshooting steps:

  1. Check the activity log for specific error messages
  2. Verify your wallet is still connected
  3. Ensure the file size is reasonable (< 10MB for testing)
  4. Try with a smaller file first
  5. Check browser console for detailed error messages

Keplr doesn't prompt for connection

Solutions:

  • Refresh the page and try again
  • Check if Keplr is locked (unlock it)
  • Disable other wallet extensions that might interfere
  • Clear browser cache and cookies

Development Tips

Enabling Source Maps

Source maps are enabled by default in vite.config.ts for easier debugging:

build: {
  sourcemap: true,
}

Hot Module Replacement (HMR)

Vite provides automatic HMR - changes to main.ts will instantly reflect in the browser without a full page reload.

TypeScript Checking

To check for TypeScript errors without building:

pnpm exec tsc --noEmit

Browser Console

Use the browser's developer console (F12) to see detailed logs and debug issues. All log messages are duplicated to the console.

Automated End-to-End Test (Browser + sn-api + Keplr)

The SDK includes a Playwright-based harness that drives this example end-to-end using your existing sn-api config and Keplr profile.

Prerequisites

  • sn-api-server built at ../sn-api-server/bin/snapi (from repo root: cd sn-api-server && API_BIN=snapi make build)
  • A Chrome/Chromium profile with Keplr installed and a Lumera testnet account (e.g. profile name "Matee")
  • ~/.snapi/.env configured for your sn-api instance (HTTP_PORT, GRPC_ADDR, CHAIN_ID, KEY_NAME, etc.)

Environment variables

From sdk-js/ set:

export E2E_CHROME_EXECUTABLE="/usr/bin/google-chrome"              # or your Chromium path
export E2E_CHROME_PROFILE_DIR="$HOME/.config/google-chrome-playwright-matee"
# Optional overrides:
# export E2E_SNAPI_BIN="$PWD/../sn-api-server/bin/snapi"
# export E2E_SNAPI_URL="http://localhost:3000"
# export E2E_BROWSER_URL="http://localhost:3001"
# Optional Keplr automation:
# export E2E_KEPLR_PASSWORD="your-keplr-password"   # used to unlock the wallet
# export E2E_KEPLR_AUTO_APPROVE=1                   # auto-approve Keplr popups (default)

Run the harness

cd sdk-js
pnpm install
pnpm run e2e:browser

The harness will:

  • Ensure sn-api is running (reusing an existing instance on E2E_SNAPI_URL or starting snapi serve)
  • Ensure this browser example dev server is running on E2E_BROWSER_URL
  • Launch Chrome with your Keplr profile
  • Click Connect Keplr Wallet and wait until the app shows Connected: in the wallet info
  • Select a small test file (examples/browser/test-assets/hello-lep1.txt)
  • Click Upload to Cascade and wait for an Upload completed log entry
  • Click Download Last Uploaded File and wait for File saved to browser downloads

If E2E_KEPLR_PASSWORD is set and the selected profile has Keplr installed and enabled, the harness will attempt to unlock the wallet and auto-approve Keplr popups (connect, ADR-036 signatures, transaction, download auth). Otherwise, it will fail fast if window.keplr is not present on the test page. All other steps are fully automated, and the script fails with a non-zero exit code on timeout or error.

Understanding the Workflow

1. Wallet Connection Flow

User clicks "Connect"
    ↓
Check Keplr availability
    ↓
Request Keplr connection (user approves)
    ↓
Get account address
    ↓
Create LumeraClient with Keplr signer
    ↓
Query blockchain parameters
    ↓
Update UI with connection status

2. Upload Flow

User selects file
    ↓
Read file as ArrayBuffer
    ↓
Convert to Uint8Array
    ↓
Generate unique action ID
    ↓
Get blockchain parameters
    ↓
Call client.Cascade.uploader.uploadFile()
    ↓
Monitor upload progress
    ↓
Display completion status

3. Download Flow

User clicks "Download"
    ↓
Request download via action ID
    ↓
Get ReadableStream
    ↓
Read stream chunks
    ↓
Combine chunks into Uint8Array
    ↓
Create Blob from data
    ↓
Trigger browser download

Security Considerations

  • Private Keys: Never expose mnemonics or private keys in browser code
  • Signature Requests: Always verify what you're signing in Keplr prompts
  • HTTPS: Use HTTPS in production to protect wallet communications
  • CSP Headers: Implement Content Security Policy headers for production

Next Steps

Support

For issues or questions: