LumaChain is a decentralized Web3 supply chain management platform specifically tailored for the solar energy industry. Built natively on the Stellar/Soroban smart contract network, it provides immutable, end-to-end traceability for solar assets (panels, inverters, batteries) from manufacturing through installation, warranty, and maintenance.
┌──────────────────────────────────────────────────────────────────────┐
│ Stellar Testnet │
│ (Soroban Smart Contracts) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ solar_asset │ │ registry │ │ warranty │ │
│ │ │ │ │ │ │ │
│ │ • Mint │ │ • Register │ │ • Init │ │
│ │ • Transfer │◄──│ • Lookup │ │ • File Claim │ │
│ │ • Verify │ │ • Inventory │ │ • Resolve │ │
│ │ • History │ │ │ │ │ │
│ └──────────┬───┘ └──────────────┘ └──────────┬───┘ │
│ │ │ │ │
│ └──────────┬───────────────────┘ │ │
│ │ │ │
│ ┌──────────▼───────────────────────────▼───┐ │
│ │ maintenance_log │ │
│ │ • Log Entry • Ownership Handoff │ │
│ └──────────────────┬──────────────────────┘ │
└────────────────────────────────┼─────────────────────────────────────┘
│ Soroban RPC
┌────────────────────────────────▼─────────────────────────────────────┐
│ @lumachain/sdk │
│ Stellar SDK · Freighter API · QR Encode/Scan │
└────────────────────────────────┬─────────────────────────────────────┘
│ TypeScript API
┌────────────────────────────────▼─────────────────────────────────────┐
│ @lumachain/api │
│ Hono + Zod · REST Gateway · Port 3001 │
│ │
│ /api/assets /api/registry /api/warranty /api/maintenance │
└────────────────────────────────┬─────────────────────────────────────┘
│ REST (JSON)
┌────────────────────────────────▼─────────────────────────────────────┐
│ /web │
│ React · Vite · Framer Motion · Lucide · Router v7 │
│ │
│ • Landing Page • Dashboard • Asset Verification │
└────────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────────▼─────────────────────────────────────┐
│ Docker Compose · Container Orchestration │
└──────────────────────────────────────────────────────────────────────┘
── Supply Chain Flow ──────────────────────────────────────────────────
MANUFACTURER ──► SUPPLIER ──► WAREHOUSE ──► INSTALLER ──► CUSTOMER
mint transfer transfer transfer own
asset custody custody custody asset
Immutable on-chain history
recorded per asset NFT
The core logic is divided into four modular Rust-based Soroban smart contracts. This architecture ensures separation of concerns, upgradeability, and isolated state management.
Acts as a digital twin (NFT-like) for a physical solar component.
- Minting: Called by the manufacturer to initialize an asset with static metadata (
serial_number,product_type,manufacturer,model,rated_power_w, and an IPFS CID for specifications). - Supply Chain Transfers: Facilitates transferring custody between roles (
SUPPLIER->WAREHOUSE->INSTALLER->CUSTOMER). - History Tracking: Automatically maintains a chronological, immutable ledger of all previous owners and transfer timestamps.
- Verification: Allows external parties to verify an asset's authenticity via its serial number.
A central directory mapping physical serial numbers and owners to their respective on-chain smart contracts.
- Registration: An admin registers a newly minted asset, mapping its
serial_numberdirectly to its deployedcontract_id. - Querying: Provides highly efficient reverse lookups (
get_asset_by_serial) and owner inventory queries (get_assets_by_owner).
Manages the lifecycle of manufacturer warranties tied to specific assets.
- Initialization: Sets an absolute expiry timestamp (Unix epoch).
- Filing Claims: Submitting a claim records the submitter, description, and an IPFS hash of photo evidence. Claims are automatically marked as
OPENand date-stamped. - Resolution: The manufacturer or authorized minter can update claim statuses (e.g.,
APPROVED,REJECTED,UNDER_REVIEW).
An append-only immutable ledger tracking the service history of a deployed solar asset.
- Logging: Authorized owners can add entries detailing technician IDs, service types (e.g.,
INSPECTION,REPAIR,CLEANING), notes, and IPFS photographic proofs. - Ownership Handoff: Integrates with the main asset contract to hand off authorization when the physical asset changes hands.
These contracts are fully compiled, verified, and live on the Soroban Testnet:
- Solar Asset Contract:
CBXEQXUCHYLTW2EKTHDY6WICCK4QGPDOPUPIIMKNU3QIR4LE6TXPUUMH - Registry Contract:
CBM33RV7SS5Z3LZT4Y7A772YYFZFMHTZMCCBZTPRIPWO6YIBJQ3HCKZO - Warranty Contract:
CCYDY6EU4RFGG5XQFMS63CY6PVJ3QQH3A6PWMC3HQ3WQXJMRDTWGTYTR - Maintenance Log Contract:
CCOKH2CPGCK4I7SZBOEA37MI2FVSCV2RMZVF2TEJPKR5EB62FA5CLWEV
Note: You can view these contracts and their transaction history on Stellar Expert.
/contracts: Core Rust/Soroban smart contracts./sdk: TypeScript SDK for interacting with the blockchain./api: Node.js/Hono REST API Gateway bridging Web2 applications with the Stellar network./web: React/Vite frontend.
LumaChain is an open-source Stellar/Soroban prototype. The four contracts above are deployed on Stellar Testnet. The repository contains the frontend, API, SDK, and contract source needed to develop the platform; run the checks below before opening a pull request.
Prerequisites: Node.js 20+, Corepack, and pnpm. Contract development also requires Rust and the Stellar CLI.
corepack enable
pnpm install
pnpm test
pnpm run buildTo run the services locally, copy api/.env.example to api/.env, set the deployed contract IDs, then start the API and frontend in separate terminals:
pnpm --filter @lumachain/api dev
pnpm --filter web devThe frontend is configured for Vercel through vercel.json. The API is a separate Node.js service and needs its own hosting environment with the variables in api/.env.example.
The repository includes a Render Blueprint for the Dockerized API. In Render, create a new Blueprint from this repository and provide:
CORS_ORIGIN: the exact public Vercel URL for the frontend, without a trailing slash.SOLAR_ASSET_CONTRACT_ID,REGISTRY_CONTRACT_ID,WARRANTY_CONTRACT_ID, andMAINTENANCE_LOG_CONTRACT_ID: the Stellar Testnet IDs above, or the IDs from your own deployment.
Render exposes a public URL after deployment. Verify it by requesting its / endpoint, which should return the API name, version, and "status": "ok".
We welcome focused contributions that improve Stellar/Soroban integration, contract safety, API coverage, frontend accessibility, test coverage, documentation, and developer tooling. Please read CONTRIBUTING.md before opening an issue or pull request.
- Prerequisites: Ensure you have the Stellar CLI and Rust (
target: wasm32v1-none) installed. - Compile and Deploy: Run the deployment script to compile all contracts and sequentially deploy them to the Testnet.
bash scripts/deploy.sh
- Environment: The deployment script automatically generates a
.contract-ids.envfile in the root directory. Copy these variables to your API and Web frontend.envfiles to connect the stack.
LumaChain is available under the ISC License.