LumensBlock

A visual drag-and-drop platform for building smart contracts and dApps on Stellar — no code required.

Stack blocks, configure logic, and deploy directly to the Stellar network.

---

What is LumensBlock?

LumensBlock removes the barrier between ideas and on-chain execution. Instead of writing Soroban smart contract code by hand, you assemble logic visually using a block-based editor and deploy with a single click.

It's designed for:

• Developers who want to prototype Stellar contracts faster
• Non-developers who want to build and deploy dApps without learning a new language
• Teams who want a shared visual layer for contract logic

---

Features

• 🧩 Drag-and-drop block editor — compose contract logic visually
• 🚀 One-click deployment — deploy to Stellar Testnet or Mainnet
• 🔗 dApp builder — connect your contracts to a frontend interface
• 🔍 No-code friendly — no Rust or Soroban knowledge needed to get started

---

Tech Stack

Layer	Technology
Frontend	Next.js + TypeScript
Block Editor	React Flow
Backend	Rust + Axum
Smart Contracts	Rust + Soroban SDK
Stellar Integration	js-stellar-sdk
Wallet	Freighter API
Styling	Tailwind CSS

---

Repository Structure

lumens-block/
├── frontend/          # Next.js web application (landing page + visual editor)
├── backend/           # Rust backend service (contract compilation & deployment API)
├── contracts/         # Soroban smart contract workspace (Rust)
└── README.md

---

Getting Started

Prerequisites: Node.js 18+, Rust + wasm32-unknown-unknown target, Freighter wallet

# Clone
git clone https://github.com/metro-logic/lumens-block.git
cd lumens-block

Frontend

cd frontend

# Install dependencies
npm install

# Run the development server
npm run dev

Open http://localhost:3000 and click Open Editor to start building.

Running Tests

Unit tests (Vitest):

cd frontend
npm test

End-to-end tests (Playwright):

cd frontend

# Install Playwright browsers on first run
npx playwright install --with-deps chromium

# Run all E2E tests (starts the Next.js dev server automatically)
npm run test:e2e

# Open the interactive Playwright UI
npm run test:e2e:ui

Tests are located in frontend/e2e/ and cover:

• Landing page load and navigation to /editor
• Dragging a block from the toolbar onto the canvas
• Connecting two nodes via their handles
• Clicking a Condition node to open its config panel
• Graph persistence via localStorage across page reloads

Backend (Rust API)

The backend service handles server-side compilation of Soroban smart contracts into WASM binaries and handles contract deployment submissions.

cd backend

# Check the project compiles
cargo check

# Run tests
cargo test

# Run the backend (default port: 8080)
cargo run

Endpoints

Endpoint	Method	Description
/health	GET	Health check (returns {"status": "ok"})
/compile	POST	Accepts Rust source ({"source": "<rust code>"}) and compiles server-side to Soroban WASM (base64)
/deploy	POST	Accepts WASM, Stellar network, and signed transaction XDR ({"signed_xdr": "..."}), submits to Stellar network, and returns contract ID

Configuration & Environment Variables

• PORT: Port to listen on (default: 8080)
• CARGO: Path to cargo binary for compilation (default: cargo)
• COMPILE_TIMEOUT_SECS: Maximum compilation time in seconds (default: 30)
• MAX_SOURCE_BYTES: Maximum allowed source code size in bytes (default: 65536)
• COMPILE_CPU_SECS: CPU time limit for cargo subprocess on Linux in seconds (default: 20)
• COMPILE_MEM_MB: Virtual memory limit for cargo subprocess on Linux in MB (default: 1024)
• COMPILE_WORK_DIR: Base directory for compilation workspaces (default: /tmp/lumens-compile)
• STELLAR_RPC_TESTNET: Custom Soroban RPC Testnet URL (default: https://soroban-testnet.stellar.org)
• STELLAR_RPC_MAINNET: Custom Soroban RPC Mainnet URL (default: https://soroban.stellar.org)

Running with Docker

cd backend
docker build -t lumens-block-backend .
docker run -p 8080:8080 lumens-block-backend

Soroban Smart Contracts

cd contracts
cargo build --target wasm32-unknown-unknown --release

---

Contributing

LumensBlock is open source and contributions are welcome!

How to Contribute

1. Fork the repository and create your branch from main
2. Make your changes — keep commits focused and descriptive
3. Test your changes before submitting
4. Open a pull request with a clear description of what you changed and why

Guidelines

• Follow the existing code style and conventions
• One feature or fix per pull request
• Write clear commit messages (e.g. fix: correct block connection logic)
• For larger changes, open an issue first to discuss the approach

Reporting Bugs

Open an issue with:

• A clear title and description
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if relevant

Feature Requests

Open an issue tagged enhancement and describe the use case. We prioritize features that align with the no-code / visual-first philosophy of LumensBlock.

---

License

MIT © Metro Logic