Stellar Token Deployer (Nova Launch)

A user-friendly dApp for quick token deployment on Stellar, targeting creators in Nigeria and emerging markets.

Features • Quick Start • User Guides • Documentation • Contributing • Roadmap

Overview

Stellar Token Deployer (Nova Launch) is a decentralized application that enables creators, entrepreneurs, and businesses in emerging markets to deploy custom tokens on the Stellar blockchain without writing a single line of code.

Why Nova Launch?

🎯 No Coding Required: Simple form-based interface for token deployment
💰 Low Fees: Leverage Stellar's ultra-low transaction costs (~0.00001 XLM)
⚡ Fast: Deploy tokens in seconds, not hours
🌍 Emerging Markets Focus: Optimized for users in Nigeria and other developing regions
🔒 Secure: Non-custodial, wallet-based authentication
📱 Mobile-First: Responsive design for all devices
📲 PWA Support: Install as an app on any device with offline capabilities

Core Value Proposition

Pay minimal XLM fees to deploy and mint tokens directly to your wallet. Optional metadata (images, descriptions) can be added via IPFS for a small additional fee. All fees funnel to the platform treasury, creating a sustainable business model aligned with Stellar's cheap transaction model.

✨ Features

Current Features (MVP)

🏭 Token Factory Smart Contract

✅ Deploy custom tokens with configurable parameters
✅ Set token name, symbol, decimals, and initial supply
✅ Automatic minting to creator's wallet
✅ Admin-controlled post-deployment minting
✅ Fee collection to platform treasury
✅ Token registry for tracking deployments

🎨 Frontend Application

✅ Wallet connection via Freighter
✅ Network switching (Testnet/Mainnet)
✅ Multi-step token deployment form
✅ Real-time input validation
✅ Fee calculation and breakdown
✅ Transaction history tracking
✅ Responsive, mobile-first design
✅ Accessibility compliant (WCAG 2.1)
✅ PWA support with offline mode
✅ Installable on mobile and desktop

🖼️ Metadata Support

✅ Optional IPFS metadata upload
✅ Token images and descriptions
✅ On-chain metadata URI storage
✅ Image validation and preview

🧪 Testing & Quality

✅ Comprehensive unit tests
✅ Property-based testing
✅ 27+ passing tests
✅ >80% code coverage
✅ TypeScript strict mode

Coming Soon

🔄 Batch token deployment
📊 Token analytics dashboard
🔐 Pro tier (clawback, multi-sig)
🌐 Multi-wallet support
📱 Mobile app (iOS/Android)
🎨 Token templates
🔍 Token discovery marketplace

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React/TS)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Token Deploy │  │   Wallet     │  │  Transaction │     │
│  │     Form     │  │  Connection  │  │   History    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Integration Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Stellar SDK  │  │   Freighter  │  │     IPFS     │     │
│  │              │  │    Wallet    │  │   (Pinata)   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  Stellar Network (Soroban)                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │          Token Factory Contract (Rust)               │   │
│  │  - create_token()                                    │   │
│  │  - mint_tokens()                                     │   │
│  │  - set_metadata()                                    │   │
│  │  - collect_fees()                                    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Data Flow

User Input: User fills deployment form with token parameters
Validation: Frontend validates all inputs client-side
Metadata Upload (optional): Images uploaded to IPFS via Pinata
Transaction Building: Stellar SDK builds contract invocation
Wallet Signing: User signs transaction via Freighter
Submission: Transaction submitted to Stellar network
Confirmation: Monitor transaction status and confirmation
Result: Display token address and transaction details
History: Store deployment info in local storage

🛠️ Tech Stack

Smart Contracts

Technology	Version	Purpose
Rust	2021	Smart contract language
Soroban SDK	21.0.0	Stellar smart contract framework
soroban-token-sdk	Latest	Token standard implementation
proptest	1.4	Property-based testing

Frontend

Technology	Version	Purpose
React	19.2.0	UI framework
TypeScript	5.9.3	Type safety
Vite	8.0.0-beta	Build tool
Tailwind CSS	4.1.18	Styling
Vitest	4.0.18	Testing framework
fast-check	4.5.3	Property-based testing

Integration

Service	Purpose
Stellar SDK	Blockchain interaction
Freighter	Wallet connection
Pinata	IPFS metadata storage
Horizon API	Transaction monitoring

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ (Download)
npm or yarn
Rust 1.70+ (Install)
Soroban CLI (Install Guide)
Freighter Wallet (Chrome Extension)

Installation

Clone the repository

git clone https://github.com/Emmyt24/Nova-launch.git
cd Nova-launch

Install frontend dependencies

cd frontend
npm install

Install Rust dependencies

cd ../contracts/token-factory
cargo build

Set up Soroban environment

# Run the setup script
chmod +x ../../scripts/setup-soroban.sh
../../scripts/setup-soroban.sh

This script will:

Install Rust and wasm32 target
Install Soroban CLI
Configure Stellar testnet
Generate admin identity
Provide funding instructions

Development

Frontend Development

cd frontend

# Start development server
npm run dev

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Build for production
npm run build

# Preview production build
npm run preview

The frontend will be available at http://localhost:5173

Smart Contract Development

cd contracts/token-factory

# Build contract
cargo build --target wasm32-unknown-unknown --release

# Run tests
cargo test

# Optimize WASM (requires soroban-cli)
soroban contract optimize \
  --wasm target/wasm32-unknown-unknown/release/token_factory.wasm

Deploy Contract to Testnet

# Quick deployment (recommended)
./scripts/deploy-testnet.sh

# This script will:
# - Verify admin identity
# - Create treasury identity if needed
# - Deploy the contract
# - Initialize with proper configuration
# - Save deployment info to deployment-testnet.json
# - Run basic smoke tests

# Verify deployment
./scripts/verify-deployment.sh

# Update frontend environment
./scripts/update-frontend-env.sh

For detailed deployment instructions, see DEPLOYMENT_GUIDE.md.

📁 Project Structure

nova-launch/
├── contracts/                    # Smart contracts
│   ├── token-factory/           # Token factory contract
│   │   ├── src/
│   │   │   ├── lib.rs          # Main contract logic
│   │   │   ├── types.rs        # Data structures
│   │   │   ├── storage.rs      # Storage management
│   │   │   └── test.rs         # Contract tests
│   │   └── Cargo.toml
│   └── Cargo.toml               # Workspace config
│
├── frontend/                     # React frontend
│   ├── src/
│   │   ├── components/          # React components
│   │   │   ├── Layout/         # Layout components
│   │   │   ├── UI/             # Reusable UI components
│   │   │   ├── TokenDeployForm/
│   │   │   ├── WalletConnect/
│   │   │   └── TransactionHistory/
│   │   ├── services/            # API services
│   │   │   ├── stellar.ts      # Stellar SDK integration
│   │   │   ├── wallet.ts       # Wallet service
│   │   │   └── ipfs.ts         # IPFS service
│   │   ├── hooks/               # Custom React hooks
│   │   ├── types/               # TypeScript types
│   │   ├── utils/               # Utility functions
│   │   ├── config/              # Configuration
│   │   ├── test/                # Test utilities
│   │   ├── App.tsx              # Main app component
│   │   └── main.tsx             # Entry point
│   ├── public/                  # Static assets
│   ├── package.json
│   └── vite.config.ts
│
├── scripts/                      # Utility scripts
│   └── setup-soroban.sh         # Soroban setup script
│
├── .kiro/                        # Kiro specs (excluded from git)
│   └── specs/
│       └── stellar-token-deployer/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
│
├── .gitignore
└── README.md

📜 Smart Contracts

Token Factory Contract

The Token Factory is the core smart contract that handles token deployment and management.

Contract Functions

`initialize`

Initialize the factory with admin, treasury, and fee structure.

pub fn initialize(
    env: Env,
    admin: Address,
    treasury: Address,
    base_fee: i128,
    metadata_fee: i128,
) -> Result<(), Error>

`create_token`

Deploy a new token with specified parameters.

pub fn create_token(
    env: Env,
    creator: Address,
    name: String,
    symbol: String,
    decimals: u32,
    initial_supply: i128,
    fee_payment: i128,
) -> Address

`set_metadata`

Add metadata URI to an existing token.

pub fn set_metadata(
    env: Env,
    token_address: Address,
    admin: Address,
    metadata_uri: String,
    fee_payment: i128,
) -> Result<(), Error>

`mint_tokens`

Mint additional tokens (admin only).

pub fn mint_tokens(
    env: Env,
    token_address: Address,
    admin: Address,
    to: Address,
    amount: i128,
    fee_payment: i128,
) -> Result<(), Error>

`burn`

Allows token holders to burn their own tokens, permanently removing them from circulation.

pub fn burn(
    env: Env,
    token_address: Address,
    from: Address,
    amount: i128,
) -> Result<(), Error>

Parameters:

token_address: Address of the token contract
from: Address of the token holder burning tokens
amount: Amount of tokens to burn (in smallest unit)

Example:

// Burn 1000 tokens (with 7 decimals)
factory.burn(
    &token_address,
    &user_address,
    &1000_0000000
);

`admin_burn`

Allows token admin to burn tokens from any address (clawback).

pub fn admin_burn(
    env: Env,
    token_address: Address,
    admin: Address,
    from: Address,
    amount: i128,
) -> Result<(), Error>

Security Note: Only the token creator can perform admin burns.

`burn_batch`

Burn tokens from multiple addresses in a single transaction.

pub fn burn_batch(
    env: Env,
    token_address: Address,
    burns: Vec<(Address, i128)>,
) -> Result<(), Error>

Gas Optimization: More efficient than multiple individual burns.

`update_fees`

Update fee structure (admin only).

pub fn update_fees(
    env: Env,
    admin: Address,
    base_fee: Option<i128>,
    metadata_fee: Option<i128>,
) -> Result<(), Error>

`get_state`

Get current factory state.

pub fn get_state(env: Env) -> FactoryState

`get_base_fee`

Get the current base fee for token deployment.

pub fn get_base_fee(env: Env) -> i128

Returns the base fee amount in stroops that must be paid for any token deployment, regardless of metadata inclusion.

`get_metadata_fee`

Get the current metadata fee for token deployment.

pub fn get_metadata_fee(env: Env) -> i128

Returns the additional fee amount in stroops that must be paid when deploying a token with metadata (IPFS URI).

`get_token_info`

Get information about a deployed token.

pub fn get_token_info(
    env: Env,
    index: u32
) -> Result<TokenInfo, Error>

Error Codes

Code	Error	Description
1	`InsufficientFee`	Fee payment is below minimum
2	`Unauthorized`	Caller not authorized for action
3	`InvalidParameters`	Invalid token parameters
4	`TokenNotFound`	Token not found in registry
5	`MetadataAlreadySet`	Metadata already set for token
6	`AlreadyInitialized`	Factory already initialized
7	`BurnAmountExceedsBalance`	Burn amount exceeds token balance
8	`BurnNotEnabled`	Burn functionality not enabled
9	`InvalidBurnAmount`	Burn amount is zero or negative

Vault Error Codes

These codes are reserved for vault lifecycle failures and are guaranteed to remain stable for downstream clients.

Code	Error	Description
60	`VaultNotFound`	Referenced vault does not exist
61	`VaultLocked`	Unlock time or milestone has not been met
62	`VaultAlreadyClaimed`	Vault funds have already been claimed
63	`VaultCancelled`	Vault was cancelled and is immutable
64	`InvalidVaultConfig`	Vault parameters failed validation
65	`NothingToClaim`	No claimable balance remains (vaults/streams)

Events

`TokenBurned`

Emitted when tokens are burned.

Data:

token_address: Address
from: Address
amount: i128
burned_by: Address
timestamp: u64
is_admin_burn: bool

💻 Frontend Application

Components

UI Components

Located in frontend/src/components/UI/:

Button: Configurable button with variants and loading states
Input: Form input with validation and error display
Card: Content card with optional title
Spinner: Loading spinner with size variants
Tooltip: Contextual help tooltips
Modal: Accessible modal dialogs
Toast: Notification system
Skeleton: Loading placeholders
ErrorBoundary: Error handling wrapper

Layout Components

Header: Application header with branding
Container: Responsive content container

Services

StellarService

Handles all Stellar network interactions.

class StellarService {
  constructor(network: 'testnet' | 'mainnet');
  
  async deployToken(params: TokenDeployParams): Promise<DeploymentResult>;
  async mintTokens(tokenAddress: string, recipient: string, amount: string): Promise<string>;
  async getTokenInfo(tokenAddress: string): Promise<TokenInfo>;
  async getTransaction(hash: string): Promise<TransactionDetails>;
}

WalletService

Manages Freighter wallet connection.

class WalletService {
  async connect(): Promise<string>;
  disconnect(): void;
  async signTransaction(xdr: string): Promise<string>;
  async getBalance(address: string): Promise<string>;
  isInstalled(): boolean;
}

IPFSService

Handles metadata upload to IPFS.

class IPFSService {
  async uploadMetadata(image: File, description: string, tokenName: string): Promise<string>;
  async getMetadata(uri: string): Promise<TokenMetadata>;
}

Hooks

useWallet

Manages wallet connection state.

const {
  wallet,        // WalletState
  connect,       // () => Promise<void>
  disconnect,    // () => void
  isConnecting,  // boolean
  error          // string | null
} = useWallet();

useTokenDeploy

Manages token deployment process.

const {
  deploy,        // (params: TokenDeployParams) => Promise<DeploymentResult>
  isDeploying,   // boolean
  status,        // DeploymentStatus
  error          // AppError | null
} = useTokenDeploy();

useToast

Manages toast notifications.

const {
  toasts,        // ToastState[]
  success,       // (message: string) => void
  error,         // (message: string) => void
  info,          // (message: string) => void
  warning        // (message: string) => void
} = useToast();

Utilities

Validation

// Validate Stellar address
isValidStellarAddress(address: string): boolean

// Validate token parameters
validateTokenParams(params): { valid: boolean; errors: Record<string, string> }

// Validate image file
isValidImageFile(file: File): { valid: boolean; error?: string }

Formatting

// Format XLM amounts
formatXLM(amount: string | number): string

// Truncate addresses
truncateAddress(address: string, startChars?: number, endChars?: number): string

// Convert stroops to XLM
stroopsToXLM(stroops: number | string): number

// Convert XLM to stroops
xlmToStroops(xlm: number | string): number

🧪 Testing

Quick Start

Use the unified test runner for all test categories:

# Fast mode (2-5 min) - Local development
./scripts/run-tests.sh -m fast

# Full mode (10-15 min) - PR validation
./scripts/run-tests.sh -m full

# Nightly mode (30-60 min) - Comprehensive
./scripts/run-tests.sh -m nightly

See Test Runner Documentation for detailed usage.

Running Tests Manually

# Frontend tests
cd frontend
npm test                 # Run all tests
npm run test:ui         # Run with UI
npm run test:coverage   # Generate coverage report

# Contract tests
cd contracts/token-factory
cargo test              # Run all tests
cargo test -- --nocapture  # Run with output

Test Categories

Unit Tests

Tests individual functions and modules in isolation.

cargo test --lib --tests

Integration Tests

Tests interactions between components.

cargo test --test '*'

Property-Based Tests

Randomized testing for governance invariants:

Monotonic vote totals
Single-vote-per-address
Execution preconditions
Terminal state permanence
Vote distribution consistency

cargo test --lib --profile ci

Benchmarks

Performance testing (nightly mode only).

cargo bench --no-run

Test Modes

Mode	Duration	Tests	Use Case
Fast	2-5 min	Unit + Integration	Local dev, pre-commit
Full	10-15 min	+ Property tests	PR validation, CI
Nightly	30-60 min	+ Benchmarks + WASM	Release validation

CI Integration

Tests run automatically on:

Push: Fast mode
Pull Request: Full mode
Schedule: Nightly mode (2 AM UTC)

Test Coverage

Current coverage: >80%

# Generate coverage report
cd frontend
npm run test:coverage

# View report
open coverage/index.html

🔄 CI/CD

Continuous Integration

The project uses GitHub Actions for automated testing and validation. All checks must pass before code can be merged.

CI Pipeline

Rust Contract Tests: Formatting, linting, tests, and WASM build
Frontend Tests: Linting, tests, and production build
Security Audit: Dependency vulnerability scanning
Spec Validation: Ensures all spec files are complete

Running Checks Locally

Before pushing code, run the local CI validation:

./scripts/ci-check.sh

This runs all CI checks locally to catch issues early.

Setting Up Git Hooks

Enable pre-commit hooks to catch issues before committing:

git config core.hooksPath .githooks

For more details, see CI/CD Guide.

🚢 Deployment

Smart Contract Deployment

Testnet

cd contracts/token-factory

# Build optimized WASM
cargo build --target wasm32-unknown-unknown --release
soroban contract optimize --wasm target/wasm32-unknown-unknown/release/token_factory.wasm

# Deploy
CONTRACT_ID=$(soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/token_factory.wasm \
  --network testnet \
  --source admin)

echo "Contract deployed: $CONTRACT_ID"

# Initialize
soroban contract invoke \
  --id $CONTRACT_ID \
  --network testnet \
  --source admin \
  -- initialize \
  --admin $(soroban keys address admin) \
  --treasury $(soroban keys address treasury) \
  --base_fee 70000000 \
  --metadata_fee 30000000

Mainnet

# Same as testnet but use --network mainnet
# Ensure you have funded mainnet accounts

Frontend Deployment

Vercel (Recommended)

cd frontend

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Production deployment
vercel --prod

Netlify

cd frontend

# Build
npm run build

# Deploy dist/ folder to Netlify

Environment Variables

Create .env file in frontend/:

VITE_FACTORY_CONTRACT_ID=<your_contract_id>
VITE_NETWORK=testnet
VITE_IPFS_API_KEY=<your_pinata_api_key>
VITE_IPFS_API_SECRET=<your_pinata_api_secret>

⚙️ Configuration

Stellar Network Configuration

Edit frontend/src/config/stellar.ts:

export const STELLAR_CONFIG = {
  network: import.meta.env.VITE_NETWORK || 'testnet',
  factoryContractId: import.meta.env.VITE_FACTORY_CONTRACT_ID || '',
  
  testnet: {
    networkPassphrase: 'Test SDF Network ; September 2015',
    horizonUrl: 'https://horizon-testnet.stellar.org',
    sorobanRpcUrl: 'https://soroban-testnet.stellar.org',
  },
  
  mainnet: {
    networkPassphrase: 'Public Global Stellar Network ; September 2015',
    horizonUrl: 'https://horizon.stellar.org',
    sorobanRpcUrl: 'https://soroban-mainnet.stellar.org',
  },
};

IPFS Configuration

Edit frontend/src/config/ipfs.ts:

export const IPFS_CONFIG = {
  apiKey: import.meta.env.VITE_IPFS_API_KEY || '',
  apiSecret: import.meta.env.VITE_IPFS_API_SECRET || '',
  pinataApiUrl: 'https://api.pinata.cloud',
  pinataGateway: 'https://gateway.pinata.cloud/ipfs',
};

Fee Structure

Default fees (in stroops, 1 XLM = 10,000,000 stroops):

Tier	Features	Fee (XLM)	Fee (stroops)
Basic	Token deployment	7	70,000,000
Metadata	+ IPFS metadata	+3	+30,000,000
Total	With metadata	10	100,000,000

Fees can be updated by factory admin using update_fees function.

📚 API Reference

REST API (Coming Soon)

Currently, all interactions are direct with the blockchain via Stellar SDK.

GraphQL API (Planned)

Future versions will include a GraphQL API for:

Token discovery
Analytics
User profiles
Transaction history

🤝 Contributing

We welcome contributions from the community! Please see our Contributing Guidelines for details.

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Write/update tests
Ensure tests pass: npm test
Commit your changes: git commit -m 'feat: add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow existing code style
Write TypeScript with strict mode
Add JSDoc comments for public APIs
Include unit tests for new features
Update documentation as needed
Maintain >80% code coverage

Commit Convention

We follow Conventional Commits:

feat: add new feature
fix: bug fix
docs: documentation changes
style: code style changes
refactor: code refactoring
test: test changes
chore: build/tooling changes

Issue Labels

good first issue - Great for newcomers
enhancement - New feature
bug - Something isn't working
documentation - Documentation improvements
help wanted - Extra attention needed

🗺️ Roadmap

Phase 1: MVP (Current) ✅

Phase 2: Enhanced Features (Q2 2026)

Phase 3: Advanced Features (Q3 2026)

Phase 4: Pro Features (Q4 2026)

Phase 5: Ecosystem (2027)

❓ FAQ

General

Q: What is Nova Launch?
A: Nova Launch is a no-code platform for deploying custom tokens on the Stellar blockchain.

Q: Do I need coding experience?
A: No! Nova Launch is designed for non-technical users.

Q: What are the fees?
A: Base deployment is 7 XLM, with an additional 3 XLM for metadata.

Q: Which networks are supported?
A: Both Stellar testnet (for testing) and mainnet (for production).

Technical

**Q: Whi

Name		Name	Last commit message	Last commit date
Latest commit History 851 Commits
.githooks		.githooks
.github/workflows		.github/workflows
.nova/specs/stateful-contract-fuzzing		.nova/specs/stateful-contract-fuzzing
.trunk		.trunk
backend		backend
contracts		contracts
docs		docs
frontend		frontend
gas-dashboard		gas-dashboard
load-tests		load-tests
monitoring		monitoring
scripts		scripts
.gitignore		.gitignore
README.md		README.md
verify-issue-559.sh		verify-issue-559.sh

Folders and files

Latest commit

History

Repository files navigation