A modern, developer-focused utility for parsing and understanding Lightning Network payment data. Built with React 19, TypeScript, and shadcn/ui for the Bitcoin/Lightning ecosystem.
- Lightning Address Resolution — Resolve Lightning Addresses (user@domain.com) to their LNURL-pay endpoints and inspect response data
- LNURL Decoding — Decode LNURL requests (lnurl-pay, lnurl-withdraw, lnurl-auth, lnurl-channel) to inspect callback URLs and parameters
- BOLT11 Invoice Decoding — Parse Lightning Network invoices to view amount, description, expiry, payment hash, routing hints, and encoded fields
- BOLT12 Offer Support — Decode BOLT12 offers, invoices, and invoice requests using the latest Lightning Network standard
- QR Code Scanning — Scan QR codes directly from your camera to decode Lightning payment data
- LUD-01 Fallback Support — Handle URLs with
lightning=query parameters per the LUD-01 specification
- Light & Dark Themes — System-aware theme with persistent preference storage
- Component Library — Built with shadcn/ui components, fully customizable
- Storybook Documentation — Interactive component documentation with live examples
- Type Safety — Full TypeScript support across the codebase
- Comprehensive Testing — 52 tests covering all invoice types and edge cases
- Modern Architecture — Modular component design with clear separation of concerns
- Node.js 18+ (recommended: 20+)
- npm, yarn, or pnpm
# Clone the repository
git clone https://github.com/andrerfneves/lightning-decoder.git
cd lightning-decoder
# Install dependencies
npm install
# Start development server
npm run devThe app will be available at http://localhost:5173.
- Visit lightningdecoder.com or run locally
- Paste a Lightning invoice, LNURL, or Lightning Address into the input field
- Press Enter or click the decode button
- View the decoded payment data in a structured format
# Lightning Address
user@domain.com
# LNURL
LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7MF0V9CXJ0M385EKVCENX...
# BOLT11 Invoice
lnbc10u1p3pj257pp5yztkwjcz5ftl4laxkla5ue77w3lpax8qzqj8qzqj8qz...
# BOLT12 Offer
lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2q3...
# URL with lightning= parameter
https://example.com/pay?lightning=LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7...Explore all components in an interactive environment:
# Start Storybook
npm run storybook
# Build Storybook
npm run build-storybookStorybook will be available at http://localhost:6006.
src/
├── components/
│ ├── ui/ # shadcn/ui base components
│ │ ├── button.tsx
│ │ ├── input.tsx
│ │ ├── card.tsx
│ │ └── ...
│ ├── header.tsx # App header with theme toggle & menu
│ ├── search-input.tsx # Invoice/address input
│ ├── invoice-details.tsx # Decoded invoice display
│ ├── error-display.tsx # Error/warning callout component
│ ├── payment-hash-verifier.tsx # Payment hash verification tool
│ ├── qr-scanner.tsx # QR code scanner modal
│ ├── theme-provider.tsx # Theme context provider
│ ├── *.stories.tsx # Storybook stories for each component
│ └── *.test.tsx # Component unit tests
├── constants/
│ └── keys.js # Shared BOLT11/LNURL/BOLT12 key constants
├── lib/
│ ├── bolt11.js # BOLT11 invoice encode/decode
│ ├── bolt11-networks.test.js # BOLT11 network tests
│ └── utils.ts # Utility functions (cn helper)
├── utils/
│ ├── app-routes.ts # Reserved route and invoice URL helpers
│ ├── invoices.js # Invoice parsing logic
│ ├── internet-identifier.js # Lightning Address validation
│ ├── keys.js # Key formatting utilities
│ └── *.test.js # Utility function unit tests
├── app.tsx # Main application component
├── main.tsx # React DOM entry point
└── index.css # Tailwind CSS imports and theme variables
- bitcoinjs-lib — BOLT11 invoice decoding
- bech32 — LNURL bech32 decoding
- bolt12-decoder — BOLT12 offer/invoice parsing
- @radix-ui — Accessible UI primitives
- lucide-react — Beautiful icon set
- tailwind-merge — Smart class merging
# Run all tests
npm testCurrent test suite: 52 tests across 8 test suites
- Invoice parsing (BOLT11, LNURL, BOLT12)
- Lightning Address validation
- LUD-01 fallback scheme support
- Edge cases and error handling
- Vercel — One-click deployment with automatic CI/CD
- Docker — Containerized deployment for any environment
- Static Hosting — Deploy to any static hosting service
# Build optimized production bundle
npm run build
# Preview production build locally
npm run previewOutput is generated in the build/ directory.
The application supports light and dark themes with system preference detection:
import { ThemeProvider } from '@/components/theme-provider'
<ThemeProvider defaultTheme="system" storageKey="ui-theme">
<App />
</ThemeProvider>Theme preferences are automatically saved to localStorage.
| Command | Description |
|---|---|
npm run dev |
Start development server |
npm run build |
Build for production |
npm run preview |
Preview production build |
npm run test |
Run test suite |
npm run storybook |
Start Storybook |
npm run build-storybook |
Build Storybook |
npm run deploy |
Build and deploy to Vercel |
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
npm test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure your PR includes:
- Clear description of changes
- Tests for new functionality
- Updated documentation if needed
MIT Licensed 2026 — See LICENSE for details.
- Live Demo: lightningdecoder.com
- GitHub: github.com/andrerfneves/lightning-decoder
- Issues: Report a bug
- LNURL Specs: github.com/lnurl/luds
- BOLT Specifications: github.com/lightning/bolts
- shadcn for the amazing UI component system
- bitcoinjs-lib maintainers
- The Lightning Network community and specification authors