Rust SDK

Overview

The Rust SDK is the official SDK for building high-performance server-side applications, CLI tools, and system-level integrations with Lumera Protocol. It communicates with the chain over gRPC and routes file operations through SN-API Supernode REST gateway.

Installation

# Initialize a project if you don't have one yet
cargo init .
 
# Add the SDK and async runtime
cargo add lumera-sdk-rs --git https://github.com/LumeraProtocol/sdk-rs.git
cargo add tokio --features full

Requirements: Rust stable (edition 2021+).

Architecture

The Rust SDK is organized into three core modules:

Module	Purpose
`chain`	On-chain operations: action parameters, fee lookups, transaction build/sign/broadcast, gas simulation
`snapi`	SN-API interaction: upload, download, status polling, file retrieval
`cascade`	High-level orchestration: deterministic payload/ID generation, ticket registration, upload/download workflows

Client Setup

Configure via environment variables or explicit config:

use lumera_sdk_rs::chain::ChainConfig;
use lumera_sdk_rs::{CascadeConfig, CascadeSdk};
 
let chain_cfg = ChainConfig::new(
    "lumera-testnet-2",
    "https://grpc.testnet.lumera.io",
    "https://rpc.testnet.lumera.io",
    "https://lcd.testnet.lumera.io",
    "0.025ulume",
);
let cfg = CascadeConfig::new(chain_cfg, "https://snapi.testnet.lumera.io");
let sdk = CascadeSdk::new(cfg);

Or use environment variables:

use lumera_sdk_rs::{CascadeSdk, SdkSettings};
 
// Load .env file if present
let _ = dotenvy::dotenv();
 
let settings = SdkSettings::from_env();
let sdk = CascadeSdk::new(settings.to_cascade_config());

Environment Variables

The SDK's built-in defaults assume you are running a local devnet. For testnet, override them in a .env file or shell environment:

Variable	Testnet Value	Purpose
`LUMERA_CHAIN_ID`	`lumera-testnet-2`	Chain identifier
`LUMERA_GRPC`	`https://grpc.testnet.lumera.io`	gRPC endpoint
`LUMERA_RPC`	`https://rpc.testnet.lumera.io`	RPC endpoint
`LUMERA_REST`	`https://lcd.testnet.lumera.io`	REST/LCD endpoint
`SNAPI_BASE`	`https://snapi.testnet.lumera.io`	SN-API server base URL
`LUMERA_GAS_PRICE`	`0.025ulume`	Gas price

Derive Signing Keys

Both upload and download require a SigningIdentity derived from your mnemonic:

use lumera_sdk_rs::SigningIdentity;
 
let identity = SigningIdentity::from_mnemonic(
    &mnemonic,
    "lumera",
    "m/44'/118'/0'/0/0",
)?;

Upload a File

Uploads happen in two steps: register the action on-chain, then stream the file to SN-API.

use lumera_sdk_rs::RegisterTicketRequest;
use std::path::PathBuf;
 
let file_path = PathBuf::from("./my-document.pdf");
 
// 1. Register on-chain action
let registered = sdk.register_ticket(
    &identity.chain_signing_key,
    &identity.arbitrary_signing_key,
    &identity.address,
    &file_path,
    RegisterTicketRequest {
        file_name: "my-document.pdf".to_string(),
        is_public: true,
        expiration_time: expiration.to_string(), // Unix timestamp
    },
).await?;
 
// 2. Upload file to SN-API
let task = sdk.upload_via_snapi(
    &registered.action_id,
    &registered.auth_signature,
    &file_path,
).await?;
 
// 3. Poll upload status
let status = sdk.snapi.upload_status(&task).await?;
 
println!("Stored with action ID: {}", registered.action_id);

Download a File

// 1. Request a download task with your arbitrary signing key
let down_task = sdk.request_download(
    &registered.action_id,
    &identity.arbitrary_signing_key,
).await?;
 
// 2. Stream the file bytes from SN-API
let bytes = sdk.snapi.download_file(&down_task).await?;
 
std::fs::write("./downloaded-file.pdf", &bytes)?;

Key Dependencies

cosmrs Cosmos SDK signing and gRPC
reqwest HTTP client with rustls
tokio Async runtime
blake3 File integrity verification
prost Protobuf encoding

Overview

Installation

Architecture

Client Setup

Environment Variables

Derive Signing Keys

Upload a File

Download a File

Key Dependencies

Next Steps

How Cascade Works

Cascade Architecture

On this page