Skip to content

thesumedh/stellar-bloom

BranchesTags

Repository files navigation

✨ StellarBloom — Gasless Onboarding Infrastructure for Soroban


StellarBloom is a lightweight onboarding layer that enables users to interact with Soroban applications without requiring a wallet, crypto, or gas fees. Users simply click an action (e.g., "Claim Free Coffee"), and everything happens invisibly — a temporary wallet is created, the request is signed, and a Relayer submits a real sponsored transaction on their behalf. The user instantly sees a verified result without understanding anything about blockchain.

⚫ Level 6 — Black Belt Submission

✅ Submission Checklist

📦 Submission Pack

If you want the fastest possible review path, start here:

🚀 What StellarBloom Does

Without StellarBloom With StellarBloom
Install Freighter wallet extension Nothing — just open the app
Write down 24-word seed phrase Nothing
Buy XLM for gas on an exchange Nothing
Sign incomprehensible transaction Click one button
90% user drop-off Transaction done in ~18 seconds

👥 Verified Active Wallet Validation

The following active wallets successfully executed gasless transactions on Stellar Testnet via StellarBloom. Each transaction is verifiable on Stellar Expert.

ℹ️ Note on Source Accounts: In StellarBloom's gasless architecture, all transactions are submitted through a single shared Sponsor/Relayer account — this is by design. Each row's "Session Key / Wallet" is the unique ephemeral keypair generated fresh in the user's browser. The sponsor account pays gas on behalf of all session wallets via FeeBump, which is why the on-chain source account appears the same across transactions. Each wallet address and transaction hash is distinct and independently verifiable.

# Session Key / Wallet Transaction
1 GCKYUDH2UTV35NNTUGG5HZ46LRDQABXHBBW3BN526D5VH7XFK5JEGF6L View on Stellar Expert
2 GD4J4B453BCRICFTSFK4AMLM454PLMRUSOTB5JZ5GWC4IJONX5PU7Y62 View on Stellar Expert
3 GBIKQMEDPPUSCXSVSQSE4CF2DXMDX6DEXA2JUNNFYGDAMW4VUB4FP6Y3 View on Stellar Expert
4 GBGQV475SQSGULTJTX7VY6HCY64PXPDGNVMZYTSG3K56RRYOJDBACOGR View on Stellar Expert
5 GAGRMCFYSC6NI7AZI42LELS4STJCFTPG7WEAA4SVSNGT6Z3NH3EOX4UN View on Stellar Expert
6 GAFYZMK75GAKFOVVU4YBNUWQRDV6OKDI7I6ZSSOBHYUDRXOYBURQJHDC View on Stellar Expert
7 GDSWYJVKOPI5OOFYGZQTG3KSFIF73U5DVKMQUXKSHJFWDK4ZLEVFDY2H View on Stellar Expert
8 GCVDOL6YKPW7LNRQWU3XCTSWUZINRUQAM42FDAXGDTI6OTTG4KZKSSRP View on Stellar Expert
9 GD4GLUDTO7QBIYWQBVJV6MB4RCILQ4XFNJ2XSBXCTMV4SPY4YG473KYF View on Stellar Expert
10 GDIULGXY2QWYZBALJNX2V3E6PV35OPEQNAZMT6KY2KWQWLHYU4IR235M View on Stellar Expert
11 GCFOBNEPOEJICH5KUOMCFNAZGNBDG2Z2EGBNAA6EJQWHWYI6GDJOEQ4S View on Stellar Expert
12 GC7LMLG7O4SQRWOYHNRXYHETNUDG4GX3GPVIDGPBMR325OLP6GAXIEM4 View on Stellar Expert
13 GCF3JKJXTH7HGNHGKYFNG3HCKCWR472TJSSBHREMSTZOLBBTQRALF4TX View on Stellar Expert
14 GDTK545LLULLRYRCZF56GVXYQCTMNXFJH6WD2XX4FQOJIYTMINOG7LNV View on Stellar Expert
15 GAMWM6WTUZYC4KQ362O6NYOV422YPRAC43TBUWIOQ6SLOBW5ETQN3LRK View on Stellar Expert
16 GDOARCXWEAHPKS4P3WY2W2PZE6YLXYBXX7MWV7QVT2FCDC6PRDHNKJUD View on Stellar Expert
17 GC3556RRT63FCDULEDZCMUL5YE2MHH5OH4GBLG6P5TPRWI2L4D4TLQJN View on Stellar Expert
18 GA2LLTRBJF5UNO6KVOBYIQGC6SW6TYWQZV32HVZ67L73IKCIYQZITNNI View on Stellar Expert
19 GALGC3Z7BBPIIDGWHL3JOSFB3KBCJGIPXFZW33T7QTE47JHB3WX5HWVH View on Stellar Expert
20 GCA4F6ASOQO4IL53P7EHVCMWKOTRX3SGT2GVVGTHHVHBKDZOSQUIIOOB View on Stellar Expert
21 GAMWCP3KLSPCVFA63SXXQU6JMRWW7GQV4TJGCTNDZMKZ77445VHMQVUJ View on Stellar Expert
22 GDKGTR2B2TOBJDYCBFS2TNZO2YEDBNXNTMP3KQMJ7J5O4AI7XJXS7CJU View on Stellar Expert
23 GCMKZMLSYBVZT7XQYRISFMF5AN4VI3XFSPNBRGOTLNNHE47AGAGPVEAO View on Stellar Expert
24 GAYU66UUT6KMRXNR5PNZTGIVRILQ3HGN5PZA6HUBHG2ZOP64NL574UD6 View on Stellar Expert
25 GD5Q2RFWJDV6RYORBNJ4FB27NYGPY5INUWSVDN6LT4V4IHQ6EAIPLY6S View on Stellar Expert
26 GDJDGT3DZMU6E5S7UPQQR4Q5OIWUNPR2QNDR7ZLKFHAWOMR5I6FCYLIE View on Stellar Expert
27 GBPSIJ6J5UAOEVT3ILDHHHMOEDG3MBAQTRMEI3ZMHISZGQ5R74PET7TC View on Stellar Expert
28 GC3TX2ZJMBK3FCR7OAQLOJOINJJZK465LU24CIQ6LWRWLEJCS4UU326X View on Stellar Expert
29 GAKUDZDUNFDUENEHM6K4DICD2IVCBNC6S56BZ7DSJB4DGII2EIXN4DLV View on Stellar Expert
30 GDPWCRMVUO7Z4BR5KIJZF5LBOVTOPQJIDYJ56PKHF3E3ZO2Y3QXMQ2HW View on Stellar Expert

Example verified transaction: View on Stellar Expert

📊 Metrics Dashboard

StellarBloom includes a live indexed metrics dashboard to track platform activity and Black Belt growth:

  • Live Metrics Endpoint: https://stellar-bloom.onrender.com/api/metrics
  • Tracked Metrics: total transactions, unique wallets, repeat wallets, daily active usage, action mix, recent transactions, and sponsor spend
  • Current Snapshot: 46 total transactions, 38 unique wallets, 4 repeat wallets, and 4 active days from the relayer log
  • Frontend Surface: Metrics are also visible in the Developer Docs dashboard inside the live app

📈 Monitoring

Production monitoring is active for the deployed relayer:

📋 User Feedback

User feedback was collected via Google Forms and exported into an Excel sheet for analysis.

  • Feedback Form: https://forms.gle/XvnXMovWR3uSaQTH9
  • Feedback Sheet: Excel Sheet
  • Key Finding: Users found the 1-click flow intuitive with zero blockchain knowledge required
  • Iteration Implemented: Added real-time stage tracker ("Generating wallet → Signing → Sponsoring gas → Confirmed") based on feedback that users wanted to see what was happening behind the scenes
  • Evidence Summary: docs/BLACK_BELT_EVIDENCE.md

📝 User Feed Implementation

The table below maps each user's feedback to the wallet they used during testing and the specific commit where their feedback was acted upon.

User Name User Email User Wallet Address Commit ID
Rahul Sharma [email protected] GBYKQS5FVB4ICO7F7RONL4X4ZWM7PS5JK76MTTOQLO4XISEB3FLH2G5A e22886e
Priya Mehta [email protected] GD3JOETXFUJDSE6CWSISSGMZSYKDKA6PJFW7JRL2N5GW2GKXY7ZYRXIY bb40827
Amit Kulkarni [email protected] GAW4B7OMNSMVNXKMYNBZAOJMSSO65GHYUK4BVRMDUTSV2AVCRAG2R6YB 3e3b967
Vikas Patil [email protected] GAEHMU6AJ7IQZO45TMAI6RCNODKJFTNN5R2KX2SNBRK4VQXPY7SRXDR6 e22886e
Rohit Deshmukh [email protected] GAVVWQD2F3663RR2J27XODWCZOJSCVKTY6GAGBRVZGTZ56U4ZMN2CWKN bb40827

Next Phase Improvements Based on Feedback

  1. Improve relayer analytics and persistent indexing so usage is easier to present at Demo Day. Commit reference: e22886e
  2. Expand hosted-relayer readiness by removing hardcoded local assumptions in the frontend integration flow. Commit reference: bb40827
  3. Continue improving active-wallet validation and real transaction proof for onboarding quality. Commit reference: 3e3b967

⚡ Advanced Feature — Fee Sponsorship

StellarBloom implements Fee Sponsorship as its Level 6 advanced feature.

Proof of implementation:

  1. relayer/index.js exposes a /relay endpoint that wraps signed XDRs in a real Stellar FeeBump transaction and pays the fee.
  2. The live onboarding flow uses the relayer to sponsor gasless actions for session wallets in the deployed demo.
  3. The resulting transactions are publicly verifiable on Stellar Expert via the wallet table above.

🗂️ Data Indexing

StellarBloom implements data indexing for Level 6 through a persistent transaction log plus a live aggregation endpoint.

🧠 Architecture

StellarBloom separates cryptographic intent generation from blockchain gas execution.

graph TD
    A[User clicks action] -->|No wallet needed| B[Bloom SDK]
    B -->|Generates ephemeral Ed25519 keypair| C[Signs intent locally]
    C -->|Sends signed payload + nonce| D[StellarBloom Relayer]
    D -->|Verifies signature & nonce| E[Rejects replays]
    D -->|Sponsors gas / FeeBump support| F[Stellar Horizon Testnet]
    F -->|Returns tx hash| D
    D -->|Returns hash| A
Loading

Full architecture details: 📄 Read ARCHITECTURE.md

Core Components:

  1. bloom-sdk.ts — Browser SDK: generates ephemeral keypair, signs intent with UUID nonce, submits to Relayer
  2. relayer/index.js — Node.js Relayer: verifies Ed25519 signature, prevents replay attacks, supports sponsored execution and fee bump flows
  3. App.tsx — React frontend with Freighter wallet session support, metrics dashboard, and animated 1-click demo

🔒 Security

  • Replay Attack Prevention — Every intent requires a crypto.randomUUID() nonce. The Relayer rejects any duplicate nonce immediately.
  • Rate Limiting — 100 requests per 15 minutes per IP via express-rate-limit
  • Non-Custodial — The ephemeral private key is generated in the browser and never sent to any server
  • Isolated Sponsor Key — SPONSOR_SECRET is stored as a server environment variable, never exposed to clients
  • Security Checklist: 🔒 SECURITY.md

⚫ Level 6 Feature Additions (vs Level 5)

Feature Description
Live Metrics Dashboard /api/metrics exposes indexed usage and sponsor analytics
Monitoring Active /health endpoint and live frontend relayer status panel
Fee Sponsorship Advanced feature implemented with relayer-backed gasless flow and fee bump support
Full Documentation Architecture, security checklist, and user guide added
30+ Verified Wallets Active wallet proof section with verifiable Stellar Expert links
Feedback Export Google Form + linked feedback Excel sheet
Data Indexing Persistent transaction log aggregated into dashboard metrics

📸 Screenshots

StellarBloom Landing Page Mobile View Coffee Shop Demo

⚙️ Local Development

Prerequisites: Node.js 18+, a funded Stellar Testnet account secret key

# 1. Clone the repo
git clone https://github.com/thesumedh/stellar-bloom.git
cd stellar-bloom

# 2. Start the Relayer (port 3000)
cd relayer
cp .env.example .env        # Add your SPONSOR_SECRET
npm install && node index.js

# 3. Start the Frontend (port 5173)
cd ../stellar-bloom
npm install && npm run dev

Open http://localhost:5173 → click "Claim Free Coffee" → watch a real Stellar transaction execute.

🌐 Deployed Infrastructure

Service URL
Frontend https://stellar-bloom.vercel.app
Relayer API https://stellar-bloom.onrender.com
Relayer Health https://stellar-bloom.onrender.com/health
Metrics Dashboard https://stellar-bloom.onrender.com/api/metrics
Deployed Contract CAZMBK5...EHZLEI

🥋 Progression History

Level Belt Key Achievement
Level 2 Yellow Soroban Rust smart contract + multi-wallet support (Freighter, Albedo, xBull)
Level 4 Green Gasless Relayer + CI/CD pipeline + FeeBump infrastructure
Level 5 Blue 1-click demo + deployed infra + replay protection
Level 6 Black Metrics dashboard, monitoring, security checklist, fee sponsorship proof, full docs, and 30+ verified active wallets

About

Level 6 - Zero-Wallet Onboarding Infrastructure for Soroban

stellar-bloom.vercel.app

Resources

Readme

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages