Stellar Laboratory is a browser-based interactive development toolkit for the Stellar blockchain network. It provides a comprehensive interface for building, signing, simulating, and submitting transactions, exploring smart contracts (Soroban), testing API endpoints, and converting between data formats. The application serves as both a learning tool for developers new to Stellar and a production-ready utility for experienced builders testing and debugging blockchain operations.
This document provides a high-level overview of the entire application architecture, technology stack, and major feature areas. For detailed information about specific subsystems, refer to:
Stellar Laboratory is built as a Next.js 15 application using TypeScript and React 19 with server-side rendering capabilities. The architecture follows a modular design with clear separation between presentation, state management, and data fetching layers.
Sources: package.json1-83 src/store/createStore.ts README.md26-33
The application is organized into five major feature areas, each with dedicated UI components, state slices, and API integration logic.
Sources: src/app/(sidebar)/ directory structure, Diagram 1 from high-level architecture
The application relies on the following key technologies and libraries:
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Framework | Next.js | 15.5.9 | React framework with SSR and routing |
| Language | TypeScript | 5.8.3+ | Type-safe JavaScript |
| UI Library | React | 19.2.2 | Component-based UI |
| Design System | @stellar/design-system | 3.2.7 | Stellar UI components |
| State Management | Zustand | 5.0.6 | Global state with immer middleware |
| Data Fetching | @tanstack/react-query | 5.83.0+ | Async state management and caching |
| Blockchain SDK | @stellar/stellar-sdk | 14.3.3 | Stellar operations and XDR handling |
| XDR Conversion | @stellar/stellar-xdr-json | 23.0.0 | XDR to JSON conversion (SEP-51) |
| Contract Parsing | @stellar-expert/contract-wasm-interface-parser | 4.0.0 | WASM metadata extraction |
| Code Editor | @monaco-editor/react | 4.7.0 | Monaco editor integration |
| Styling | Sass | 1.86.3+ | CSS preprocessing |
| Testing | Playwright | 1.57.0+ | End-to-end testing |
| Testing | Jest | 30.2.0+ | Unit testing |
Wallet Integrations:
| Wallet Type | Library | Version |
|---|---|---|
| Browser Extensions | @creit.tech/stellar-wallets-kit | 1.9.3 |
| Ledger Hardware | @ledgerhq/hw-app-str | 7.2.9 |
| Trezor Hardware | @trezor/connect-web | 9.6.4 |
Monitoring & Analytics:
| Service | Library | Version | Environment |
|---|---|---|---|
| Error Tracking | @sentry/nextjs | 10.29.0 | Production |
| Usage Analytics | @amplitude/analytics-browser | 2.20.1 | lab.stellar.org only |
Sources: package.json26-58 README.md25-35
The codebase follows Next.js App Router conventions with a clear separation of concerns:
Key Directories:
src/app/(sidebar)/ - All main application pages using Next.js App Router with a shared sidebar layoutsrc/components/ - Reusable React components (NetworkSelector, DataTable, CodeEditor, etc.)src/helpers/ - Pure utility functions for transactions, Soroban operations, formatting, and validationsrc/query/ - TanStack Query hooks for data fetching from RPC, Horizon, and Stellar.Expert APIssrc/store/ - Zustand store configuration with slices for different feature domainssrc/types/ - TypeScript type definitions for networks, transactions, contracts, and API responsessrc/constants/ - Static configuration including network definitions, operation types, and limitsSources: src/ directory structure, src/app/(sidebar)/layout.tsx src/store/createStore.ts
The application uses pnpm 10.15.1 as its package manager and requires Node.js 22.22.0 or higher. The development server automatically fetches Stellar network limits before starting:
Network Limits: The predev script automatically executes scripts/fetch-network-limits.mjs to retrieve current network resource limits (CPU instructions, memory, I/O) from Mainnet, Testnet, and Futurenet RPC endpoints. This generates src/constants/networkLimits.ts with typed exports.
Sources: package.json9-24 README.md37-65
The application uses Next.js standalone output mode for optimized production deployment:
The build process:
build/standalone/build/static/build/standalone/public/_next/static/ for deploymentnode server.js in the standalone directoryDocker Deployment: A Dockerfile is provided that builds the application with commit hash tracking for version identification:
The Docker container exposes port 80 and sets a 65-second keep-alive timeout to prevent connection timeouts during long-running operations.
Sources: README.md81-106 Dockerfile1-21 Makefile1-16
The application integrates with two analytics services in production environments:
Amplitude Analytics (@amplitude/analytics-browser): Tracks user interactions and feature usage exclusively on lab.stellar.org. Events are logged for contract invocations, transaction submissions, endpoint requests, and navigation patterns. Implementation is in src/metrics/tracking.ts
Google Analytics: Provides additional usage metrics via @next/third-parties. Can be disabled in custom deployments by setting:
Sentry Error Tracking (@sentry/nextjs): Captures JavaScript errors, unhandled promise rejections, and performance metrics in production with source map support for debugging.
Sources: package.json27-33 README.md108-121
The application supports three predefined Stellar networks plus custom network configuration:
| Network | Purpose | Default RPC Endpoint | Default Horizon Endpoint |
|---|---|---|---|
| Mainnet | Production network | https://mainnet.stellar.validationcloud.io | https://horizon.stellar.org |
| Testnet | Testing environment | https://soroban-testnet.stellar.org | https://horizon-testnet.stellar.org |
| Futurenet | Bleeding-edge features | https://rpc-futurenet.stellar.org | https://horizon-futurenet.stellar.org |
| Custom | User-defined network | Configurable | Configurable |
Network selection is managed through the NetworkSelector component and persisted to local storage. The active network configuration affects all API calls, transaction submissions, and contract interactions.
Network Passphrase: Each network has a unique passphrase used for transaction signing:
"Public Global Stellar Network ; September 2015""Test SDF Network ; September 2015""Test SDF Future Network ; October 2022"Sources: src/components/NetworkSelector/ src/constants/networks.ts Diagram 4 from high-level architecture
The application implements a three-tier state management pattern:
The zustand-querystring middleware selectively syncs state to URL query parameters, enabling shareable links for specific application states (e.g., ?network=testnet&contractId=C...).
All blockchain operations (RPC calls, transaction submissions, contract invocations) use TanStack Query for:
Sources: src/store/createStore.ts src/query/provider.tsx Diagram 4 from high-level architecture
Certain features are conditionally enabled based on environment variables:
| Feature | Environment Variable | Default | Purpose |
|---|---|---|---|
| Transactions Explorer | NEXT_PUBLIC_ENABLE_EXPLORER | false | Browse recent network transactions |
| Commit Hash Display | NEXT_PUBLIC_COMMIT_HASH | Git SHA | Version tracking in footer |
| Telemetry | NEXT_TELEMETRY_DISABLED | 1 | Disable Next.js telemetry |
The commit hash is automatically injected during build via git rev-parse --short HEAD and displayed in the application footer for version identification.
Sources: package.json12 Dockerfile12 Makefile5-12
Refresh this wiki