Lumen

Developer wallet for the Midnight blockchain ecosystem

A Chrome extension wallet designed for QA teams and developers to test Midnight dApps. Implements the full @midnight-ntwrk/dapp-connector-api specification with real wallet SDK integration.

Features

Wallet Management

Generate wallets - BIP39 mnemonic seed phrase generation
Import wallets - From seed phrase, private key, or hex seed
Prefunded localnet wallets - One-click import of genesis mint wallets (0-3)
Secure key storage - In-memory only, keys never persisted to disk

dApp Connector API

Full window.midnight API implementation (v4.0.0-beta.2)
InitialAPI with connect flow
ConnectedAPI with balance queries, signing, configuration
Compatible with Midnight dApps expecting standard wallet interface

Network Support

Network	Node	Indexer	Prover
Localnet	localhost:9944	localhost:8088	localhost:6300
DevNet	devnet.midnight.network	devnet indexer	devnet prover
QANET	qanet.midnight.network	qanet indexer	qanet prover
Preview	preview.midnight.network	preview indexer	preview prover
PreProd	preprod.midnight.network	preprod indexer	preprod prover
Custom	User-defined URLs

Debug Panel

Dust tab - DUST coin inventory with values and status
Shielded tab - Shielded wallet state and balances
Unshielded tab - Unshielded wallet state and balances
Transactions tab - Recent transaction history from both wallets

Health Monitoring

Real-time status indicators for Node, Indexer, and Prover
Color-coded health dots (green/yellow/red)
Latency display and error reporting
Automatic polling with exponential backoff

Quick Start

Prerequisites

Node.js 18+
npm 9+
Chrome browser

Installation

# Clone the repository
git clone https://github.com/user/lumen.git
cd lumen

# Install dependencies
npm install

# Build the extension
npm run build

Load in Chrome

Open Chrome and navigate to chrome://extensions
Enable Developer mode (toggle in top right)
Click Load unpacked
Select the dist/ folder from the project

First Use

Click the Lumen extension icon in Chrome toolbar
Select your target network (Localnet, DevNet, etc.)
Either:
- Click Generate Wallet to create a new wallet
- Click Import to restore from seed phrase
- For Localnet: Use quick-import buttons for prefunded wallets

dApp Integration

Detecting Lumen

// Check if Lumen is installed
if (window.midnight && window.midnight['lumen-wallet']) {
  console.log('Lumen wallet detected');
}

// Listen for wallet availability
window.addEventListener('midnight#ready', (event) => {
  console.log('Wallet ready:', event.detail.uuid);
});

Connecting

const lumen = window.midnight['lumen-wallet'];

// Connect to wallet
const api = await lumen.connect('devnet');

// Get addresses
const { dustAddress } = await api.getDustAddress();
const { unshieldedAddress } = await api.getUnshieldedAddress();

// Get balance
const { balance, cap } = await api.getDustBalance();
console.log(`Balance: ${balance} / ${cap}`);

Signing Data

const signature = await api.signData('Hello Midnight', {
  encoding: 'text',
  keyType: 'unshielded'
});

console.log('Signature:', signature.signature);
console.log('Verifying key:', signature.verifyingKey);

Getting Configuration

const config = await api.getConfiguration();
// Returns: { indexerUri, indexerWsUri, proverServerUri, substrateNodeUri, networkId }

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Chrome Extension                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │    Popup     │    │   Content    │    │   Inject     │       │
│  │  (popup.ts)  │    │  (content.ts)│    │ (inject.ts)  │       │
│  │              │    │              │    │              │       │
│  │  - UI/UX     │    │  - Message   │    │  - window.   │       │
│  │  - Settings  │    │    relay     │    │    midnight  │       │
│  │  - Debug     │    │  - Origin    │    │  - dApp API  │       │
│  │    panel     │    │    validation│    │              │       │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
│         │                   │                   │                │
│         └─────────┬─────────┴─────────┬─────────┘                │
│                   │                   │                          │
│                   ▼                   ▼                          │
│         ┌─────────────────────────────────────┐                  │
│         │         Service Worker              │                  │
│         │       (service-worker.ts)           │                  │
│         │                                     │                  │
│         │  ┌─────────────┐ ┌───────────────┐  │                  │
│         │  │   Wallet    │ │    Facade     │  │                  │
│         │  │   Core      │ │  (SDK wrap)   │  │                  │
│         │  │             │ │               │  │                  │
│         │  │ - Keys      │ │ - DustWallet  │  │                  │
│         │  │ - Signing   │ │ - Shielded    │  │                  │
│         │  │ - Import    │ │ - Unshielded  │  │                  │
│         │  └─────────────┘ └───────────────┘  │                  │
│         └─────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │      Midnight Network         │
              │                               │
              │  Node ─── Indexer ─── Prover  │
              └───────────────────────────────┘

Project Structure

src/
├── background/
│   └── service-worker.ts   # Wallet state, message handlers, SDK facade
├── content/
│   └── content.ts          # Message relay, origin validation
├── inject/
│   └── inject.ts           # window.midnight API implementation
├── popup/
│   ├── popup.html          # Extension popup markup
│   ├── popup.css           # Styles
│   └── popup.ts            # UI logic, debug panel
├── core/
│   ├── wallet.ts           # Key generation, signing, import
│   ├── network.ts          # RPC client, health checks
│   ├── facade.ts           # Wallet SDK wrapper
│   └── types.ts            # Shared type definitions
└── lib/
    └── messaging.ts        # Message passing utilities

Security

Lumen implements defense-in-depth security measures:

Key Protection

In-memory only - Keys never written to disk or chrome.storage
Secure wiping - Random overwrite before clearing key buffers
Popup-only access - Sensitive methods restricted to extension popup
Error cleanup - Automatic key wipe on uncaught errors

dApp Isolation

Origin validation - Approved origins tracked per session
Protocol blocking - Rejects data:, blob:, file:, javascript: URLs
Rate limiting - 100 requests/minute per origin
Specific postMessage - No wildcard origins

Data Protection

XSS prevention - HTML escaping for all blockchain data
Config integrity - SHA-256 checksums for stored settings
Response limits - 100KB max for health check responses
Generic errors - No implementation details leaked

Production Hardening

Conditional logging - Sensitive data only logged in development
Private IP blocking - SSRF protection for custom URLs
Exponential backoff - Circuit breaker for failed operations

Localnet Setup

Run a local Midnight network for development and testing.

Prerequisites

Docker and Docker Compose
Ports 9944, 8088, and 6300 available

Commands

npm run localnet:up      # Start all services
npm run localnet:down    # Stop all services
npm run localnet:logs    # View service logs
npm run localnet:reset   # Reset data and restart

Services

Service	Port	Description
node	9944	Midnight Substrate node (WebSocket RPC)
indexer	8088	GraphQL indexer API
proof-server	6300	ZK proof generation server

Prefunded Wallets

Localnet includes 4 prefunded genesis wallets with DUST:

Wallet	Quick Import
Wallet 0	Click "0" button in popup
Wallet 1	Click "1" button in popup
Wallet 2	Click "2" button in popup
Wallet 3	Click "3" button in popup

Custom Configuration

cp .env.example .env
# Edit .env to customize:
# - APP_INFRA_SECRET for indexer auth

Development

Setup

npm install          # Install dependencies
npm run build        # Production build
npm run dev          # Watch mode (rebuilds on changes)

Testing

npm test             # Run unit tests

Manual Testing

Load the extension in Chrome (see Quick Start)
Open test/dapp-test.html in a browser tab
Click "Detect Wallet" to verify API injection
Click "Connect" to test wallet connection flow

Build Output

dist/
├── manifest.json       # Extension manifest
├── background.js       # Service worker bundle (~29MB with WASM)
├── content.js          # Content script
├── inject.js           # Injected script
└── popup/
    ├── popup.html
    ├── popup.css
    └── popup.js

API Reference

InitialAPI (window.midnight['lumen-wallet'])

Property	Type	Description
`rdns`	string	Reverse DNS identifier (`io.lumen.wallet`)
`name`	string	Wallet name (`Lumen`)
`icon`	string	Base64 SVG icon
`apiVersion`	string	API version (`4.0.0-beta.2`)
`connect(networkId)`	function	Connect and return ConnectedAPI

ConnectedAPI

Method	Returns	Description
`getDustAddress()`	`{ dustAddress }`	Get DUST address
`getUnshieldedAddress()`	`{ unshieldedAddress }`	Get unshielded address
`getDustBalance()`	`{ balance, cap }`	Get DUST balance
`signData(data, options)`	`{ data, signature, verifyingKey }`	Sign arbitrary data
`getConfiguration()`	`Configuration`	Get network endpoints
`getConnectionStatus()`	`{ status, networkId }`	Check connection state

Troubleshooting

Extension not loading

Ensure dist/ folder exists (run npm run build)
Check Chrome developer mode is enabled
Look for errors in chrome://extensions

Wallet not connecting to dApp

Verify the dApp page is using window.midnight['lumen-wallet']
Check browser console for connection errors
Ensure wallet is unlocked (has active wallet loaded)

Balance showing 0

Wait for wallet sync (check debug panel for sync progress)
Verify network selection matches where funds exist
For localnet, use prefunded wallets (0-3)

Health indicators red

Check if localnet services are running (npm run localnet:logs)
Verify network URLs in settings
Check network connectivity

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

TypeScript strict mode
No any types without justification
ESLint + Prettier formatting

License

MIT License - see LICENSE for details.

Acknowledgments

Midnight Network - Blockchain platform
@midnight-ntwrk packages - Official SDK
Polkadot.js - Substrate RPC client

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.claude/commands/openspec		.claude/commands/openspec
docs		docs
openspec		openspec
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
build.mjs		build.mjs
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Lumen

Features

Wallet Management

dApp Connector API

Network Support

Debug Panel

Health Monitoring

Quick Start

Prerequisites

Installation

Load in Chrome

First Use

dApp Integration

Detecting Lumen

Connecting

Signing Data

Getting Configuration

Architecture

Project Structure

Security

Key Protection

dApp Isolation

Data Protection

Production Hardening

Localnet Setup

Prerequisites

Commands

Services

Prefunded Wallets

Custom Configuration

Development

Setup

Testing

Manual Testing

Build Output

API Reference

InitialAPI (window.midnight['lumen-wallet'])

ConnectedAPI

Troubleshooting

Extension not loading

Wallet not connecting to dApp

Balance showing 0

Health indicators red

Contributing

Code Style

License

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages