joule-labs / joule-extension

Lightning payments extension for Chrome

NOTICE: Joule is no longer being actively developed. You can find other WebLN browser extensions that are actively maintained in the WebLN documentation. This repository now primarily serves as a learning resource for aspiring WebLN developers. Thanks for the support.

---

Overview

A browser extension that lightning-charges your browser with webln, giving you the ability to pay and use your node as an identity on the web.

WARNING: Joule is no longer acitvely developed, and should not be used for large mainnet funds

Project Layout

joule-extension/
├── src                   # All source code
│   ├── app                 # The main React app, used by the other clients
│   │   ├── index.tsx         # Entry point for the app
│   │   ├── AppRoutes.tsx     # Routes used in the popup and options clients
│   │   ├── PromptRoutes.tsx  # Routes used in the prompt client
│   │   ├── components        # All reusable components
│   │   ├── lib               # Standalone libraries, potentially split into node modules
│   │   ├── modules           # Vertical slices of business logic, mostly redux code
│   │   ├── pages             # Container components for app routes
│   │   ├── prompts           # Container components for prompts
│   │   ├── static            # Static assets that are compiled and processed
│   │   ├── store             # Redux setup and configuration
│   │   ├── style             # Global or common-use styles
│   │   ├── typings           # Module typings for TypeScript
│   │   └── utils             # Miscellanious utility functions and constants
│   ├── background_script  # Extension background script
│   ├── content_script     # Extension content script, injects inpage_script and communicates with background_script
│   ├── inpage_script      # In-page injected script, manages WebLN
│   ├── options            # Options client, full screen version of the app
│   ├── popup              # Popup client, opened by clicking icon in toolbar
│   ├── prompt             # Prompt client, opened by WebLN and BOLT-11 links
│   └── webln              # WebLN implementation, injected via inpage_script
├── static             # Static assets that don't go through any processing
├── dist-dev           # Developer builds go here, not checked into git
└── dist-prod          # Production builds go here, not checked into git

Development

1. Run yarn install && yarn run dev
2. Open Chrome -> More Tools -> Extensions
3. Toggle "Developer mode" (if such a toggle exists)
4. Click "Load unpacked"
5. Select the joule-extension/dist-dev folder you created
6. Get to work!

If you're also working on webln, you'll want to clone and build that repository, and run yarn link. Then come back to the joule folder and run yarn link webln.

NOTE: After making changes, you'll need to close and re-open the extension to load the latest build.

Redux DevTools:

1. Open the extension popup or full page
2. Right click on the background
3. Choose Redux Devtools -> Open Remote DevTools
4. A new window will open displaying the Redux actions list

React DevTools:

1. Run npm install -g react-devtools
2. Be sure to use yarn run dev to build the app
3. Run react-devtools in a new Terminal
4. A new window will open displaying the React vdom inspector

React Hot Reload:

1. Run yarn run hot instead of yarn run dev

Building

To make a production build, follow these steps

1. Run yarn build
2. Raw files and a zip of them will be output to dist-prod

Releasing

1. Bump the version number in package.json and static/manifest.json and commit it to develop
2. Create a git tag called v${version} and push it
3. CI will make a release with the assets uploaded and place it in draft
4. Build the release locally with Docker and sign the manifest with

   yarn build:docker && cd dist-docker && gpg --output manifest-[version].wbobeirne.sig --detach-sig manifest.txt

5. Download the manifest-[version].txt from the release and verify it with the signature you just made

   gpg --verify manifest-[version].wbobeirne.sig manifest-[version].txt

6. Upload the built zip to the Chrome developer dashboard + Firefox addons site

Testing

...regrettably, TBD

Contributing

Please see the Contributor Guidelines on the Wiki.

Shoutouts

• Thanks to the MetaMask team for establishing a ton of the UX best practices for browser crypto payments.
• Thanks to @afilini for providing a small prototype reference implementation of the extension flow.
• Thanks to Chaincode Labs for putting together the 2018 Lightning residency, where this was born.

joule-extension's Issues

Documentation for using node as an identity

Hey! Where can I read some documentation about how to use joule-extension as an identity for the web? I just read the readme but I could not find any other documentation about it.

Thank!! 👍

Switch to gRPC API

The HTTP REST API has too many issues, swap out the library with a .proto-typed gRPC implementation.

Extension is already on Chrome Web Store

Hi,

I think you should redirect the link of the install for Google Chrome button on https://lightningjoule.com/ to https://chrome.google.com/webstore/detail/joule/aejmoogjdllanidlpfjmmmmimfaficio as it's already released on Chrome Web Store.

Thanks

Trouble building extension

I've attempted to clone, build, and link webln:

git clone [email protected]:/wbobeirne/webln
cd webln
yarn
yarn link

and then clone and build joule-extension:

git clone [email protected]:/wbobeirne/joule-extension
cd joule-extension
yarn link webln
yarn
yarn run build-dev
yarn run dev

node: v10.13.0
npm: v6.4.1
yarn: v1.12.1

This does not appear to build a manifest file in ./dist, so I'm unable to install the unpacked extension.

Did I skip a step?

Use RouteHints from payment request

If a payment request comes with route hints, present them to the user and let them choose if they want to use them.

TLS handshake error while connecting

When trying to connect joule to my remote node Joule tells me it "Failed to connect to node"
and lnd gives me the following error in the log:

http: TLS handshake error from ip:51475: tls: first record does not look like a TLS handshake

I also can't access http://ip:8080/v1/getinfo. It just says invalid html response

Add how-to for `lnd` self-signed TLS certificate management

By default, Chromium Browser / Google Chrome won't recognize the self-signed TLS certificate prepared by lnd. This will prevent Joule from successfully connecting to lnd.

Chrome can be made to accept the self-signed cert by following these steps:

1. navigate to https://localhost:8080/v1/getinfo
2. click on the lock next to the URL and view the certificate
3. navigate to the certificate viewer's "details" tab and export the cert to a file
4. navigate to edit > preferences > manage certificates > authorities > import
5. check all of the boxes and import the cert

Now Chrome should accept the cert and Joule should be able to connect to lnd!

Newbiw question: Is it possible connect BLW with Lightningjoule

Hi,

I have this lightning wallet on my android: https://lightning-wallet.com/
I would like to know if it's technically possible connect lightningjoule with BLW. For example: I have my BLW wallet with channels opened.... So I think I have a node, right? So I could use something like what you describe as macaroon, and connect my BLW "credentials" to Lightningjoule.

Thanks.

Context menu entry for highlighted payments & QR codes

If you right click on a highlighted BOLT-11 payment string / qr code, it would be awesome to have a one-click option to prompt you to pay, rather than having to copy / paste it in.

Add clear node settings button to settings

Should have an option to clear your connection settings and macaroons. Ideally ejects you to splash page, but doesn't require you to re-fill out the password part.

Scan more ports for local node setup

Looks like there are some instances of apps setting up the REST api on different ports. I'll try to keep a list of them all here, but we should scan them all:

• 8080 - LND default
• 8086 - Lightning App

Paying invoice without numerical amount fails

Parsing an invoice where amount is not set to a numerical value fails:

type mismatch, parameter: amt, error: strconv.ParseInt: parsing "undefined": invalid syntax

e.g.

lnbc1pwq6e83pp5vxfk7n7z2rh27p60cnzsgy9txdamv948aka7nv5kjnnxtm0j2zgqdpsgejk2erfdenjqarfwpcxjm3wd4jjqum9wfmx2unnyrcflr9wcqzysxqzjcc7chlhzh0qeuvud0g67llyxujxqz39e5sjhy290vu34n3g6r0e5h0jgwl0dug0c6ysf6xaaqtdh3jat58284s48hvpkf0rug0q9gwxspkx0wgu

C-Lightning node compatibility

C-Lightning has an HTTP RPC interface as well, but it's different from LND, so we'll need to support that. Documentation is here: https://github.com/ElementsProject/lightning#further-information

Fix production build

yarn build fails out right now due to TypeScript errors. Get those resolved so we can get a production build out and into the extension store at some point.

Joule tries to connect to remote node without macaroon.

I can't get Joule to connect to my remote node. It seems like it is trying to connect before presenting me with the macaroon upload page? I am able to curl to my lnd's REST server and getinfo just fine.

Don't inject WebLN until a node is set

This just results in failed calls, so it's useless anyway

Open & close channels

We have a list of them, so it would be nice to be able to open new channels and close existing ones. This would also be a good opportunity to list recommended channels to connect to(?).

Potentially blocked on lightningnetwork/lnd#2197

Add fiat pairs

Should show fiat wherever possible, allow specifying pairs. Potentially allow disabling fiat altogether.

Make contribution guidelines, issue templates, code standards

In order to promote contributors, we need the following:

• CONTRIBUTORS.md that comes with any information or quirks
• Issue templates for features & bug reports
• Pull request template to standardize what those look like
• A prettier config, and husky pre-commit hook to auto-prettier. Add prettier checks to CI.

List and add peers

Should be able to view your peers, and enter a peer connection string somewhere (e.g. [email protected]:port)

Cannot connect Joule to `lnd` within extension pop-up window

When the Joule extension pop-up loses focus, it disappears and reverts to the extension's home page. This makes it impossible to select the macaroons when connecting Joule to lnd. The same issue makes it difficult to retrieve a password from a password manager to unlock Joule while paying a copied-and-pasted Lightning Network invoice.

The best workaround is to open Joule in its own page by navigating to e.g. chrome-extension://lnbbaakgapeflbgngbbjhmnjfhidhlhe/popup.html. Joule can then be successfully connected to lnd.

To remedy this, it would be helpful if the Joule pop-up included a link to the full-page view, and/or if the extension window could be made to persist even when it loses focus.

Easier set-up with BTCPay Server node

I'm trying to set-up Joule with my remote node, which is a BTCPay Server instance. After the lnd rest api url, Joule asks me to upload my .macaroon file. This is kind of painful in this case, as it means that I must ssh to my BTCPay Server and then find the .macaroon file in a docker volume (I actually don't know how to do it atm) Would be a lot easier for me if I could just paste my admin macaroon as a string, because I can copy it from my BTCPay Server admin console.

WordPress Plugin Installation

Hi, this might be something for me to do rather than request you to make a plugin for WordPress. But for the web site owner, I deal with a lot of non-technical users. Is there an implementation for this for installing on WordPress sites? As in... What does a site admin need to have in order to put this on their website? I do a good deal of plugin bridging for rewards sites between crypto plugins and various other store and/or rewards systems.

I know most of them aren't technical knowledgeable to run their own nodes, but I know Dashed-Slug's plugin uses Coinpayments.net as a node (option to run a regular BTC node was in a long time ago), so if you could use a trusted node or even I could run one for them as I already do that with a browser mining stratum.

What would be the technical requirements (server setup) required for a WordPress install... Its given they have at least PHP 5.* and cPanel and although that usually is CentOS, many of them don't have SSH to do terminal stuff.

With my browser miner stuff, I rent Debian servers, but perhaps I should get your view on if this is possible, already done in a plugin somewhere, or not a good idea. I could maybe even ask Dashed Slug if he has something in the works.

Unlock symbol on password prompt fails to submit the form

Clicking the unlock symbol on the password prompt fails to submit the form.

Hitting enter on the keyboard submits the password and completes the payment.

Inject WebLN faster

Some folks are getting an Error: Your browser does not support WebLN because they're calling requestProvider before Joule can inject it. While the WebLN client library could be made to provide some wiggle-room for detection, we should also be injecting it a little faster. MetaMask does this by inlining the javascript and cramming it into <head>: https://github.com/MetaMask/metamask-extension/blob/f6e042b7b12fec755b0a91ff24a1e812f65b638d/app/scripts/contentscript.js

Remember WebLN authorizations

If a user accepts an enable request from a page, we shouldn't ask them again. Likewise for a reject This will probably require a whitelist / blacklist settings page, but that can be a separate issue.

Use joule as mobile app on iOS/Android

How hard would it be to port this app to use it as an iOS or Android app? Is there a plan to implement this or is this not the intention?

Using Joule as standard lightning link application

I am using Chrome and when I click lightning links sometimes they want to open Zap Wallet instead of the Joule extension. Is there a way to make Joule the default? I tried to follow some guides with mailto links but they didn't work for me.

Send bitcoin transactions

There's a form for sending lightning transactions, but bitcoin transactions are also possible using the POST /v1/transactions API.

Recommended apps list

This is for a ways out, but it would be nice to point people towards cool lapps that integrate well with Joule & WebLN. It could probably fit in as another tab between Channels & Transactions. It should also auto-add any application that you've enabled with WebLN (#11 as a prerequisite.) Open to any suggestions if people have apps they'd like added initially. Current working list is:

• yalls.org
• satoshis.place
• lightningspin.com

My suggestions for lightningjoule extension

Hi,

First of all, thanks for developing lightningjoule extension.

Suggestions:

1- I think shouldn't have an option to deposit.
2- I think should only have option to send and request bitcoin lightning payments. Shouldn't have option to send payments to bitcoin addresses.
3- I think should have an option to mirror Android Bitcoin lightning wallets with lightningjoule extension using bluetooth tecnology. Look like is possible: (https://developers.google.com/web/updates/2015/07/interact-with-ble-devices-on-the-web)
4- I don't see why is necessary to show channels tab on lightningjoule.
5- I don't think you should add options like open or close channels.
6- I think the balance should have a better design like the Brave one:

Automatically create invoices

If a webln.makeInvoice passes a fixed amount, we should just automatically generate the invoice for the website. This should be something you can configure on and off in the enable screen, if for some reason you don't want it (e.g. you need to balance liquidity.) It should also be rate limited to avoid spamming the user's node (e.g. if they request another invoice within a few seconds, either reject or prompt the user this time.)

Handle HTTP 402 payment required responses

I am wondering what your thoughts are on trying to handle HTTP 402 responses to request payments:
If a server responds with a 402 HTTP status and a lightning invoice the extension could prompt the user to confirm the payment and "refresh" the page with a proof of payment.
(if auto-payments are enabled for the domain the payment could be done automatically.)

From what I've seen so far it might be tricky to get this working with the available extensions APIs, but I've looked into the chrome.webRequest.onBeforeSendHeaders which allows to check the response headers and to block/redirect the request... maybe it can somehow be hacked.

I've lately experimented with a similar flow for API requests (blog post) also ln-paywall is pretty cool.

Would love to see this to pay for content :)

Date day display is wrong

In the extension the day of every date is always the numerical representation of the month. For example all transactions/invoices of the month december have the date dec. 12th and all of november have the date november 11th, ...

So I think there is somewhere a mistake in the date display.

Subscribe to invoices, show notifications on payment

Since we have background_script.js running already, tap into some invoices and alert the user when they're paid. Potentially do the same for payments when they do it through the prompt.

Setting for preferred bitcoin denomination

Allow users to choose BTC, mBTC, or satoshis. Sync this storage. Maybe allow them to do fiat-only? (#3 related.)

Joule will not connect to lnd when URL has a trailing slash

Joule will not connect to lnd when the entered hostname has a trailing slash.

It results in Joule requesting https://hostname:port//v1/getinfo which results in a 404. (Double slash in URI)

Intercept lighting URIs

https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md#encoding-overview

If we detect a click on one of these, we should open up a Joule payment request (Regardless of whether or not they've hooked into the WebLN provider yet) since it's clear the user wants to pay.

Eclair node compatibility

https://github.com/ACINQ/eclair

Looks like it doesn't use Macaroons, so it'll probably require some agnostic auth changes since a lot of assumptions are made around using them.

Add change password to settings screen

Pretty straightforward, enter old one, enter new one, confirm new one. Should have the same restrictions as onboarding.

Make more permissions optional

Currently the extension is asking for the whole enchilada of permissions, but this could very easily be made opt-in during the onboarding flow, and have limited functionality without them. Users who don't provide access on every page can be limited to the activeTab permission and be required to click the extension before doing its thing.

Show pending channels

When you create a new channel, it's visible via https://api.lightning.community/rest/index.html#v1-channels-pending until it's confirmed. We should query and display this as well.

Auth documentation

Handling prompts from inactive tabs

If you're browsing in a different tab or window, and a page requests an action that triggers a prompt, what should we do?

• Steal focus from the user and thrust the tab in front of them?
• Reject the request with an error that lets them know the tab isn't active?
• Queue the request for the next time they focus the tab?

Open to any and all options

Remove hard-coded files from dist

The icons and manifest.json are currently manually checked into dist/. There should be a webpack plugin to either move or generate these in the right place.

Allow user to setup automatic payments per lapp

Provide an interface where a user can setup automatic no-ask payments for certain lapps. This would be limited by domain, and have the following configurations:

• Maximum amount per transaction (e.g. ask if it's more than 1000 satoshis)
• Maximum amount total (e.g. up to 100,000 satoshis)
• Maximum amount per hour / day (e.g. 1000 satoshis per hour)

Should a maximum be exceeded, the user will be prompted for the payment instead of it being automatic.

Ideally they could configure this during or after a payment request (Maybe a checkbox?) There should also be a list of active auto pay configs, and some UI treatment for when you're on a page that can auto-pay (and perhaps after each auto-payment.)

Handle offline server / invalid macaroons

If their server goes down, or their macaroons are invalidated, we need to provide an escape hatch

Invoice amount restricted to fiat HTML input step size

Prevents me from denominating the invoice in sats.

Setup continuous integration

Setup Travis or Circle to ensure that (at the very least) no changes break the build.

Add BTCPay Server option to onboarding

Allow users to quickly connect with the BTC pay server by providing the config string from /server/services/lnd/BTC and having that set them up. Make it a separate option from "local node" and "remote node" so that instructions can be laid out for them.