Lumera Rust SDK (lumera-sdk-rs)

Official Rust SDK for integrating with Lumera chain actions and Cascade flows via sn-api-server.

This SDK covers the full action lifecycle used by apps and services:

• register ticket on-chain
• upload file via sn-api-server
• request and download file
• verify integrity by hash

Table of Contents

• What this SDK provides
• Requirements
• Installation
• Configuration
• Quick start
• Golden test (what it means)
• Local developer commands (Makefile)
• CI gates
• Contributing / PR checklist

What this SDK provides

lumera-sdk-rs exposes 3 layers:

1. Chain client (chain)

   • action params + fee lookup
   • account info lookup
   • action registration transaction flow
   • generic tx build/sign/broadcast utilities
   • tx gas simulation helper + adjusted gas signing flow
   • tx confirmation lookup/wait helpers

2. sn-api client (snapi)

   • start upload
   • poll upload/download status
   • request download + fetch output file

3. High-level SDK (cascade)

   • deterministic payload/ID generation
   • register ticket on-chain
   • upload/download orchestration through sn-api-server

Also included:

• config loading from env, .env, .toml, .json via config::SdkSettings
• runnable end-to-end example: examples/golden_devnet.rs

Requirements

• Rust stable (1.75+ recommended)
• Reachable Lumera endpoints (REST/RPC/gRPC)
• Reachable sn-api-server
• Signing keys for:
  • chain tx signing (cosmrs::crypto::secp256k1::SigningKey)
  • arbitrary payload signing (k256::ecdsa::SigningKey)

Installation

From crates.io (from the first release, 0.1.0):

cargo add lumera-sdk-rs

or in Cargo.toml:

[dependencies]
lumera-sdk-rs = "0.1"

From a release's source: each release in LumeraProtocol/releases carries sdk-rs-vX.Y.Z-src.tar.gz; unpack it and depend on it by path:

[dependencies]
lumera-sdk-rs = { path = "../sdk-rs-vX.Y.Z" }

Issues: LumeraProtocol/releases (label sdk-rs).

How a release is made

1. version in Cargo.toml is set to the new version.
2. A signed tag vX.Y.Z (git tag -s) on that commit runs .github/workflows/release.yml: it exports the publishable tree (scripts/export.sh, .release/allow), runs the tests and cargo package in that export, and attaches the source tarball with SHA256SUMS to a private draft Release.
3. The draft is reviewed and published to LumeraProtocol/releases and crates.io with release-kit's shelf-publish.sh. Nothing becomes public before that step.

Configuration

Supported configuration styles:

• explicit in code (CascadeConfig, ChainConfig)
• environment variables (SdkSettings::from_env())
• config file (SdkSettings::from_file("*.toml|*.json"))
• .env file (SdkSettings::from_env_file(".env"))

Common env vars:

• LUMERA_CHAIN_ID
• LUMERA_GRPC
• LUMERA_RPC
• LUMERA_REST
• LUMERA_GAS_PRICE
• SNAPI_BASE

Quick start

See:

• examples/golden_devnet.rs (full E2E register/upload/download/hash)
• examples/from_env_settings.rs (load config from env + construct SDK)
• examples/custom_config.rs (explicit in-code endpoint config)
• examples/README.md (examples index)

golden_devnet.rs executes full flow:

1. register ticket
2. upload
3. request download
4. download file
5. compare hash of original vs downloaded bytes

Simple Browser UI (sdk-rs API)

This repo now includes a minimal browser UI similar to sdk-js/examples/browser, but backed by sdk-rs API handlers:

• UI: examples/ui/index.html
• API server: examples/ui_server.rs

Run it:

cd sdk-rs
export LUMERA_MNEMONIC="..."
export LUMERA_CREATOR="lumera1..."
SNAPI_BASE=http://127.0.0.1:8089 cargo run --example ui_server

Then open:

http://127.0.0.1:3002

Optional env:

• SDK_RS_UI_PORT (default 3002)
• SNAPI_BASE (default http://127.0.0.1:8089)
• LUMERA_MNEMONIC (required for automatic register/sign flow)
• LUMERA_CREATOR (sender address; defaults to local dev value if omitted)
• LUMERA_REST, LUMERA_RPC, LUMERA_GRPC, LUMERA_CHAIN_ID

The UI calls Rust endpoints under /api/*, with no manual action/signature input:

• POST /api/workflow/upload (register ticket + sign + start upload)
• GET /api/upload/{task_id}/summary
• POST /api/workflow/download (uses last uploaded action by default)
• GET /api/download/{task_id}/summary
• GET /api/download/{task_id}/file

Golden test (what it means)

In this repo, golden test means a full-system integration run against a real Lumera + sn-api-server stack, with strict pass criteria:

• action is registered on-chain successfully
• upload task succeeds
• download task succeeds
• downloaded file hash exactly matches original file hash

This is not a unit test and not a mock test. It is an end-to-end correctness gate for protocol compatibility.

Run locally:

make golden

make golden calls scripts/run_golden_local.sh and runs cargo run --example golden_devnet.

Required env for local golden run:

• LUMERA_MNEMONIC
• LUMERA_CREATOR

Optional (defaults provided):

• LUMERA_REST (default http://127.0.0.1:1317)
• LUMERA_RPC (default http://127.0.0.1:26657)
• LUMERA_GRPC (default http://127.0.0.1:9090)
• SNAPI_BASE (default http://127.0.0.1:8080)
• LUMERA_CHAIN_ID (default lumera-devnet)
• GOLDEN_INPUT (default /tmp/lumera-rs-golden-input.bin)

Local developer commands (Makefile)

Use these before opening/updating a PR:

make fmt-check   # formatting gate
make lint        # clippy -D warnings
make test        # all tests
make doc         # docs with warnings denied
make check       # full local PR gate (fmt/lint/test/doc)

High-priority commands:

make build       # build all workspace targets
make check       # full quality gate
make golden      # full register/upload/download/hash test
make clean       # clean artifacts

For CI-parity PR E2E script against public testnet/public sn-api:

make e2e-pr

• Always runs public endpoint smoke checks.
• Runs full register/upload/download/hash flow when LUMERA_MNEMONIC and LUMERA_CREATOR are provided.

CI gates

Current workflows enforce:

• Lint + Format
• Test
• Docs
• Security (cargo audit)
• System E2E (PR, public sn-api):
  • runs on PR opened/reopened/synchronize
  • targets public endpoints (snapi.testnet.lumera.io, Lumera testnet RPC/REST/gRPC)
  • executes endpoint smoke checks for all PRs
  • executes full register → upload → download → hash match when testnet creds are configured as secrets
  • publishes run artifacts/logs

Contributing / PR checklist

Before PR creation and before each push to an open PR:

make check
make golden

If your change affects chain/sn-api/cascade behavior, run:

make e2e-pr

PRs should include:

• clear scope and compatibility notes
• test evidence (at minimum make check; include golden/e2e evidence where relevant)
• no unrelated refactors

Security notes

• never commit mnemonics/private keys
• inject secrets at runtime (env/secret manager)
• use dedicated keys per environment