Skip to content

README.md

Latest commit

 

History

History
162 lines (123 loc) · 11.4 KB

README.md

File metadata and controls

162 lines (123 loc) · 11.4 KB
Raw

LumaChain ☀️

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.

🗺️ Architecture Overview

  ┌──────────────────────────────────────────────────────────────────────┐
  │                         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

📖 Architecture & Smart Contract Logic

The core logic is divided into four modular Rust-based Soroban smart contracts. This architecture ensures separation of concerns, upgradeability, and isolated state management.

1. Solar Asset (solar_asset)

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.

2. Supply Chain Registry (registry)

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_number directly to its deployed contract_id.
  • Querying: Provides highly efficient reverse lookups (get_asset_by_serial) and owner inventory queries (get_assets_by_owner).

3. Warranty Claims (warranty)

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 OPEN and date-stamped.
  • Resolution: The manufacturer or authorized minter can update claim statuses (e.g., APPROVED, REJECTED, UNDER_REVIEW).

4. Maintenance Log (maintenance_log)

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.

🚀 Deployed Contracts (Stellar Testnet)

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.

🛠️ Project Structure & Getting Started

Stack Components

  • /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.

Project Status

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.

Quick Start

Prerequisites: Node.js 20+, Corepack, and pnpm. Contract development also requires Rust and the Stellar CLI.

corepack enable
pnpm install
pnpm test
pnpm run build

To 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 dev

The 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.

Deploy the API to Render

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, and MAINTENANCE_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".

Contributing

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.

Building & Deploying Locally

  1. Prerequisites: Ensure you have the Stellar CLI and Rust (target: wasm32v1-none) installed.
  2. Compile and Deploy: Run the deployment script to compile all contracts and sequentially deploy them to the Testnet. 
    bash scripts/deploy.sh
  3. Environment: The deployment script automatically generates a .contract-ids.env file in the root directory. Copy these variables to your API and Web frontend .env files to connect the stack.

License

LumaChain is available under the ISC License.