Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
302 lines (211 sloc) 14 KB

Spark Lightning Wallet

npm release build status docker release MIT license Pull Requests Welcome IRC

⚡️ Simple & minimalistic ⚡️ Purely off-chain ⚡️ Near-zero configuration ⚡️ Progressive Web App ⚡️ Personalizable themes ⚡️ Mobile and desktop apps ⚡️ Automatic self-signed TLS ⚡️ LetsEncrypt integration ⚡️ Tor hidden service (v3) ⚡️

Spark screenshot



Spark is a minimalistic wallet GUI for c-lightning, accessible over the web or through mobile and desktop apps (for Android, Linux, macOS and Windows). It is currently oriented for technically advanced users and is not an all-in-one package, but rather a "remote control" interface for a c-lightning node that has to be managed separately.

Spark currently focuses on the core aspects of day-to-day usage: sending, receiving and viewing history. Peers and channels are expected to be managed using the RPC for now.

Spark is a purely off-chain wallet, with no on-chain payments. This allows Spark to fully realize the awesome UX enabled by lightning, without worrying about the complications and friction of on-chain. This might change someday.

Spark has a responsive UI suitable for mobile, tablet and desktop devices, but is best optimized for use on mobile.

⚠️ Spark is alpha-quality software under active development. Please use with care, preferably on testnet or with insignificant amounts. Spark comes with no guarantees, use at your own risk.

Big shout out to Blockstream for generously sponsoring this work!

Server installation

Requires a running c-lightning node (see setup instructions in the official docs or this tutorial) and nodejs v6.0 or newer (nodejs v8 is recommended, see instructions here. If you're running into permission issues, try this.)

$ npm install -g spark-wallet

$ spark-wallet # defaults: --ln-path ~/.lightning --port 9737

Or simply $ npx spark-wallet, which will install and start Spark (with the default args) in one go.

Spark will generate and print a random username and password that'll be used to login into the wallet. To specify your own login credentials, set --login [user]:[pass] or the LOGIN environment variable.

To access the wallet, open http://localhost:9737/ in your browser and login with the username/password.

See $ spark-wallet --help for the full list of command-line options (also available under CLI options).

Configuration file

Spark reads configuration options from ~/.spark-wallet/config (can be overridden with --config/-c <path>). The expected format is one key=value per line, like so:


Connecting remotely

To accept remote connections, set --host <listen-address> (shorthand -i, e.g. -i This will automatically enable TLS with a self-signed certificate.

For more information on TLS, instructions for setting up a CA-signed certificate using the built-in LetsEncrypt integration and for adding the self-signed certificate to Android, see doc/

To start Spark as a Tor hidden service, set --onion. You don't need Tor pre-installed for this to work. See doc/ for more details, the advantages of using an hidden service, and instructions for connecting from Android. This is highly recommended.

Deploy with Docker

Spark is also available as a Docker image that comes bundled with bitcoind and c-lightning. See doc/ for details.

Adding to startup with systemd

See doc/

Desktop apps

Electron-based desktop apps for Linux (packaged as deb, AppImage, snap and tar.gz), macOS (as zip) and Windows (installer and a portable) are available for download from the releases page.

The desktop apps comes bundled with the Spark server-side component. If you're connecting to a local c-lightning instance, you can configure the desktop app to connect to it directly without manually setting up the Spark server.

Connecting to a remote c-lightning instance requires setting up the Spark server on the same machine running c-lightning and connecting through it.

Mobile app

A Cordova-based native app for Android is available for download from the releases page (spark-wallet-[x.y.z]-android.apk). It is not currently published to the app store.

The app requires a Spark server to communicate with, which you need to setup as a prerequisite.

When the app starts for the first time, you'll need to configure your Spark server URL and API access key. You can print your access key to the console by starting Spark with --print-key/-k. You can also scan this information from a QR, which you can get with --pairing-qr/-Q.

For the native app to properly communicate with the server, the TLS certificate has to be signed by a CA or manually added as a user trusted certificate.

Progressive Web App

You can install Spark as a PWA (on mobile and desktop) to get a more native-app-like experience, including an home launcher that opens up in full screen, system notifications and faster load times.

Available in Chrome mobile under -> Add to homescreen (see here), in Chrome desktop under More tools -> Install to desktop (see here) and in Firefox mobile with an icon next to the address bar (see here).

Installing the PWA requires TLS and a CA-signed certificate (unless accessed via localhost).

Compared to the PWA, the main advantages of the mobile and desktop apps are the ability to handle lightning: URIs, better security sandbox (detached from the browser) and static client-side code.

Note for iOS users: iOS does not allow PWAs to use WebRTC (required for the QR scanner), but it works otherwise. The QR scanner works if you access Spark without using the PWA "Add to homescreen" feature.

GUI settings & controls

  • Pay and Request are pretty intuitive and don't require much explaining. Try them!

  • Display unit: Click the balance on the top-right or the unit in the "request payment" page to toggle the currency display unit. The available options are sat, bits, milli, btc and usd.

  • Theme switcher: Click the theme name on the bottom-right to change themes (you can choose between 16 bootswatch themes).

  • Payment details: Click on payments in the list to display more details. (note that the fee shown includes c-lightning's overpayment randomization)

  • Expert mode: Click the version number on the bottom-left to toggle expert mode. This will add two new menu items, "Logs" and "RPC Console", and display yaml dumps with additional information throughout the app.

  • Node address: Click the node id on the footer to display your node address (as text and QR).

Browser support

Supported on recent desktop and mobile version of Chrome, Firefox and Safari. IE is unsupported.

Requires iOS 11.2+ for WebRTC (used by the QR scanner), but works otherwise with iOS 9+. Chrome on iOS does not support WebRTC.


Spark is written in a reactive-functional style using rxjs and cycle.js, with bootstrap for theming and a nodejs/express server as the backend.

To start a development server with live compilation for babel, browserify, pug and stylus, run:

$ git clone && cd spark-wallet
$ npm install
$ npm start -- --ln-path /data/lightning

Cordova builds can be prepared with npm run dist:cordova. The .apk file will be available in cordova/platforms/android/app/build/outputs/apk/debug/.

Electron builds can be prepared with npm run dist:electron. They will be available under electron/dist.

To get more verbose output in the browser developer console, set localStorage.debug = 'spark:*'.

See doc/ for instructions setting up a regtest environment with multiple wallets.

Pull requests, suggestions and comments are welcome!

Code signing & reproducible builds

Signed distribution checksums are available in the git repo at SHA256SUMS.asc (updated with every versioned release) and on the releases page. Git version tags are signed too.

The releases are signed by Nadav Ivgi (@shesek). The public key can be verified on keybase, github, twitter (under bio), HN or on a domain he's known to control.

To install the signed NPM package, download it from the releases page, verify the hash and install using $ npm install -g spark-wallet-[x.y.z]-npm.tgz.

To install the signed Docker image, get the image hash from SHA256SUMS.asc and install it with $ docker pull shesek/spark-wallet@sha256:[image-hash-verified-by-be-signed].

The NPM package, Android apk builds, Linux tar.gz/snap builds, macOS zip builds and Windows builds (installer and portable) are deterministically reproducible.

CLI options

$ spark-wallet --help

  A minimalistic wallet GUI for c-lightning

    $ spark-wallet [options]

    -l, --ln-path <path>     path to c-lightning data directory [default: ~/.lightning]
    -u, --login <userpwd>    http basic auth login, "username:password" format [default: generate random]
    -p, --port <port>        http(s) server port [default: 9737]
    -i, --host <host>        http(s) server listen address [default: localhost]

    --force-tls              enable TLS even when binding on localhost [default: enable for non-localhost only]
    --no-tls                 disable TLS for non-localhost hosts [default: false]
    --tls-path <path>        directory to read/store key.pem and cert.pem for TLS [default: ~/.spark-wallet/tls/]
    --tls-name <name>        common name for the TLS cert [default: {host}]

    --letsencrypt <email>    enable CA-signed certificate via LetsEncrypt [default: false]
    --le-port <port>         port to bind LetsEncrypt verification server [default: 80]
    --le-noverify            skip starting the LetsEncrypt verification server [default: start when {letsencrypt} is set]
    --le-debug               display additional debug information for LetsEncrypt [default: false]

    -o, --onion              start Tor Hidden Service (v3) [default: false]
    -O, --onion-path <path>  directory to read/store hidden service data [default: ~/.spark-wallet/tor/]

    -k, --print-key          print access key to console (for use with the Cordova/Electron apps) [default: false]
    -q, --print-qr           print QR code with the server URL [default: false]
    -Q, --pairing-qr         print QR code with embedded access key [default: false]

    --no-webui               run API server without serving client assets [default: false]
    --no-test-conn           skip testing access to c-lightning rpc (useful for init scripts) [default: false]

    -c, --config <path>      path to config file [default: ~/.spark-wallet/config]
    -V, --verbose            display debugging information [default: false]
    -h, --help               output usage information
    -v, --version            output version number

    $ spark-wallet -l ~/.lightning

  All options may also be specified as environment variables:
    $ LN_PATH=/data/lightning PORT=8070 NO_TLS=1 spark-wallet