Skip to content

Commit 3eee55d

Browse files
Leo Weesegitbook-bot
Leo Weese
authored andcommitted
GITBOOK-310: L402s
1 parent cd4ae90 commit 3eee55d

File tree

26 files changed

+130
-134
lines changed

26 files changed

+130
-134
lines changed

README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ Pool is a non-custodial marketplace where users can buy inbound liquidity from n
4545

4646
Taro is a Taproot-powered protocol for issuing assets on the bitcoin blockchain that can be transferred over the Lightning Network for instant, high volume, low fee transactions.
4747

48-
{% content-ref url="the-lightning-network/lsat/lsat.md" %}
49-
[lsat.md](the-lightning-network/lsat/lsat.md)
48+
{% content-ref url="the-lightning-network/l402/l402.md" %}
49+
[l402.md](the-lightning-network/l402/l402.md)
5050
{% endcontent-ref %}
5151

5252
Lightning Service Authentication Tokens cleverly combine the capabilities of macaroons with that of a Lightning payment, making it easy to charge satoshis for API requests.

SUMMARY.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,12 @@
2929
* [Managing Liquidity on the Lightning Network](the-lightning-network/liquidity/manage-liquidity.md)
3030
* [How to get inbound capacity on the Lightning Network](the-lightning-network/liquidity/how-to-get-inbound-capacity-on-the-lightning-network.md)
3131
* [Lightning Service Provider](the-lightning-network/liquidity/lightning-service-provider.md)
32-
* [LSAT](the-lightning-network/lsat/README.md)
33-
* [Macaroons](the-lightning-network/lsat/macaroons.md)
34-
* [LSAT](the-lightning-network/lsat/lsat.md)
35-
* [Aperture](the-lightning-network/lsat/aperture.md)
36-
* [📋 Protocol Specification](the-lightning-network/lsat/protocol-specification.md)
37-
* [Implementations and Links](the-lightning-network/lsat/implementations-and-links.md)
32+
* [L402: Lightning HTTP 402 Protocol](the-lightning-network/l402/README.md)
33+
* [Macaroons](the-lightning-network/l402/macaroons.md)
34+
* [L402](the-lightning-network/l402/l402.md)
35+
* [Aperture](the-lightning-network/l402/aperture.md)
36+
* [📋 Protocol Specification](the-lightning-network/l402/protocol-specification.md)
37+
* [Implementations and Links](the-lightning-network/l402/implementations-and-links.md)
3838
* [Taro](the-lightning-network/taro/README.md)
3939
* [Taro Protocol](the-lightning-network/taro/taro-protocol.md)
4040
* [Taro on Lightning](the-lightning-network/taro/taro-on-lightning.md)

community-resources/glossary.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -348,13 +348,13 @@ Loop Out is the process of making a Lightning payment and receiving an equivalen
348348

349349
The Lightning Service Authentication Token (LSAT) combines [Macaroons](glossary.md#macaroon) with [preimages](glossary.md#preimage) as proof of payment to create tickets for paid APIs or other services that require authentication and payment.
350350

351-
[Read more: LSAT](../the-lightning-network/lsat/)
351+
[Read more: LSAT](../the-lightning-network/l402/)
352352

353353
## Macaroon
354354

355355
Macaroons are bearer credentials that allow for detailed attenuation as well as delegation.
356356

357-
[Read more: Macaroons explained](../the-lightning-network/lsat/macaroons.md)
357+
[Read more: Macaroons explained](../the-lightning-network/l402/macaroons.md)
358358

359359
## Merkle Sum Tree <a href="#docs-internal-guid-da9e136d-7fff-c284-15eb-82132eee8d94" id="docs-internal-guid-da9e136d-7fff-c284-15eb-82132eee8d94"></a>
360360

lapps/guides/polar-lapps/run-the-app-without-lnd.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -15,33 +15,33 @@ Open your browser to [http://localhost:3000](http://localhost:3000) if it doesn
1515

1616
If all went well with your development environment setup, you should see the initial screen below:
1717

18-
![](<../../../.gitbook/assets/preLND01 (1) (1) (1) (1).png>)
18+
![](<../../../.gitbook/assets/preLND01 (1) (1) (1).png>)
1919

2020
Click on the **Create a Post** button to go to the Create screen.
2121

22-
![](<../../../.gitbook/assets/preLND02 (1) (1).png>)
22+
![](<../../../.gitbook/assets/preLND02 (1).png>)
2323

2424
Fill in some info for the _Username_, _Title_, and _Content_ fields, then click on the **Submit** button. You will be redirected back to the screen displaying the list of posts.
2525

26-
![](<../../../.gitbook/assets/preLND03 (1).png>)
26+
![](../../../.gitbook/assets/preLND03.png)
2727

2828
Add a couple more posts, just to have some data to play with.
2929

30-
![](<../../../.gitbook/assets/preLND04 (1).png>)
30+
![](../../../.gitbook/assets/preLND04.png)
3131

3232
Click on the **Upvote** button on a post to see the votes counter increment and the posts reorder based on which has the highest votes.
3333

34-
![](<../../../.gitbook/assets/preLND05 (1).png>)
34+
![](../../../.gitbook/assets/preLND05.png)
3535

3636
The app makes use of WebSockets to update the UI in real-time when posts are created and upvoted on the backend. To see this in action, open a second browser window side-by-side with the first window. Create a new post on the left to see it automatically appear on the right. Upvote a post on the right to see it increment and reorder on the left automatically.
3737

38-
![](<../../../.gitbook/assets/preLND06 (1).png>)
38+
![](../../../.gitbook/assets/preLND06.png)
3939

4040
## Architecture
4141

4242
This application is split into two parts, the backend API server and the frontend browser-based UI.
4343

44-
![](<../../../.gitbook/assets/appArchitecture (1).png>)
44+
![](../../../.gitbook/assets/appArchitecture.png)
4545

4646
### Backend API
4747

lightning-network-tools/lightning-terminal/accounts.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: >-
66

77
# LND Accounts
88

9-
Using litd, users are able to create virtual off-chain accounts on top of their LND node, each with their own [macaroon](../../the-lightning-network/lsat/macaroons.md) and spending rules, such as spending limits or an expiration date.
9+
Using litd, users are able to create virtual off-chain accounts on top of their LND node, each with their own [macaroon](../../the-lightning-network/l402/macaroons.md) and spending rules, such as spending limits or an expiration date.
1010

1111
The accounts feature does not validate whether the sum of all account balances is smaller or equal to the channel balance held in the underlying LND node. A user issued such an account enters a trust relationship with the node operator regarding availability of the funds and the node. The account balances are tracked and enforced by LND.
1212

lightning-network-tools/lightning-terminal/loop-fees.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ A Loop Out allows you to trade your off-chain balance for on-chain bitcoin. Ther
1919

2020
Loop will give us an estimate over the fees we are expected to pay before we confirm our swap. These fees depend on transaction size and current demand for on-chain payments and fall into three categories:
2121

22-
**LSAT**: When you perform your first Loop your node will purchase an [LSAT](../../the-lightning-network/lsat/). This LSAT does not expire and costs 1 satoshi.
22+
**LSAT**: When you perform your first Loop your node will purchase an [LSAT](../../the-lightning-network/l402/). This LSAT does not expire and costs 1 satoshi.
2323

2424
**Estimated on-chain fee**: This is the fee you are expected to pay in miners fees to claim your bitcoin from the [HTLC address](../../the-lightning-network/multihop-payments/understanding-submarine-swaps.md#3.-claim-bitcoin-from-the-smart-contract) into your personal wallet. This fee is calculated based on current on-chain fee conditions and may be higher if by the time the Loop Out concludes the mempool is significantly more congested. Larger transaction sizes do not increase this fee, but faster desired confirmation times do.
2525

lightning-network-tools/lightning-terminal/pool.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ To open the account, click on ‘Open an Account’ on the left bar of Lightning
1818

1919
If you want to primarily sell channels, the funds in your Pool account need to be able to cover the capacity of the channels you intend to sell. If you are only buying channels, you only need to commit enough to cover the fees.
2020

21-
To authenticate your account to the Pool server, your node will purchase an [LSAT](../../the-lightning-network/lsat/) for 1000 satoshis. This transaction is made over the Lightning Network and you will be able to see it in your Dashboard.
21+
To authenticate your account to the Pool server, your node will purchase an [LSAT](../../the-lightning-network/l402/) for 1000 satoshis. This transaction is made over the Lightning Network and you will be able to see it in your Dashboard.
2222

2323
### Custody
2424

lightning-network-tools/lnd/macaroons.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ description: >-
88

99
LND, Loop, Pool and litd all use macaroons to authenticate RPC calls. Macaroons are similar to cookies in that they are bearer instruments, but they can be more easily verified by the server using HMACs and a root key alone. They can also be attenuated, both by the server and by the user. This greatly simplifies how LND authenticates RPC calls while expanding the detail in which authority over specific RPC calls is permissioned.
1010

11-
[Learn more about Macaroons here.](../../the-lightning-network/lsat/macaroons.md)
11+
[Learn more about Macaroons here.](../../the-lightning-network/l402/macaroons.md)
1212

1313
## The default macaroons <a href="#docs-internal-guid-ad1fdcaf-7fff-adcf-644d-0f14be97523e" id="docs-internal-guid-ad1fdcaf-7fff-adcf-644d-0f14be97523e"></a>
1414

the-lightning-network/lsat/README.md renamed to the-lightning-network/l402/README.md

+11-12
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
---
22
description: >-
3-
Lightning Service Authentication Tokens cleverly combine the capabilities of
4-
macaroons with that of a Lightning payment, making it easy to charge satoshis
5-
for API requests.
3+
Lightning API keys cleverly combine the capabilities of macaroons with that of
4+
a Lightning payment, making it easy to charge satoshis for API requests.
65
---
76

8-
# LSAT
7+
# L402: Lightning HTTP 402 Protocol
98

10-
LSAT is a new standard to support the use case of charging for services and authenticating users in distributed networks. It combines the strengths of Macaroons for better authentication with the strengths of the Lightning Network for better payments.
9+
L402 is a standard to support the use case of charging for services and authenticating users in distributed networks. It combines the strengths of Macaroons for better authentication with the strengths of the Lightning Network for better payments.
1110

12-
Aperture is an implementation of this standard. It functions as a reverse HTTP proxy with support for gRPC and REST requests. It allows the safe and efficient creation of paid APIs that separate the logic of payments, permissioning and fulfilling requests. Aperture is used today by Lightning [Loop](../../lightning-network-tools/loop/) and [Pool](../../lightning-network-tools/pool/), a non-custodial swap service for Bitcoin.
11+
Aperture is an implementation of this standard. It functions as a reverse HTTP proxy with support for gRPC and REST requests. It allows the safe and efficient creation of paid APIs that separate the logic of payments, permissioning and fulfilling requests. Aperture is used today by Lightning [Loop](../../lightning-network-tools/loop/), a non-custodial swap service for Bitcoin and [Pool](../../lightning-network-tools/pool/), a non-custodial marketplace for channel liquidity.
1312

14-
LSATs leverage the following tools and mechanisms:
13+
L402 leverages the following tools and mechanisms:
1514

1615
## Macaroons <a href="#docs-internal-guid-444dcdd8-7fff-4158-aecb-571c65c3d819" id="docs-internal-guid-444dcdd8-7fff-4158-aecb-571c65c3d819"></a>
1716

@@ -23,19 +22,19 @@ Macaroons include permissions, and can be attenuated and delegated by the bearer
2322
[macaroons.md](macaroons.md)
2423
{% endcontent-ref %}
2524

26-
## LSAT <a href="#docs-internal-guid-10a6402c-7fff-d1f6-1a90-f2015a91174d" id="docs-internal-guid-10a6402c-7fff-d1f6-1a90-f2015a91174d"></a>
25+
## L402 <a href="#docs-internal-guid-10a6402c-7fff-d1f6-1a90-f2015a91174d" id="docs-internal-guid-10a6402c-7fff-d1f6-1a90-f2015a91174d"></a>
2726

28-
Lightning Service Authentication Tokens are Macaroons that only become valid together with a cryptographic secret obtained as a preimage through payment a Lightning Network invoice tied to the Macaroon by its payment hash. Where Macaroons allow the separation of issuance, permissioning and validation, LSATs allow the separation of issuance and payment.
27+
Lightning API keys are Macaroons that only become valid together with a cryptographic secret obtained as a preimage through payment a Lightning Network invoice tied to the Macaroon by its payment hash. Where Macaroons allow the separation of issuance, permissioning and validation, L402s allow the separation of issuance and payment.
2928

3029
In practice, a service can hand out Macaroons together with Lightning Network invoices to their potential customers, but does not need to validate specifically whether these invoices have been paid. The mere cryptographic validity of the Macaroon guarantees that the payer has obtained the preimage through their payment.
3130

32-
{% content-ref url="lsat.md" %}
33-
[lsat.md](lsat.md)
31+
{% content-ref url="l402.md" %}
32+
[l402.md](l402.md)
3433
{% endcontent-ref %}
3534

3635
## The Aperture proxy <a href="#docs-internal-guid-2415a258-7fff-3d3d-25b9-4e3b0c38b8ca" id="docs-internal-guid-2415a258-7fff-3d3d-25b9-4e3b0c38b8ca"></a>
3736

38-
The Aperture proxy is a reverse proxy that will forward requests with valid LSATs to their relevant API endpoint, while issuing Macaroons and Lightning Network invoices to new users.
37+
The Aperture proxy is a reverse proxy that will forward a request with a valid L402 to their relevant API endpoint, while issuing Macaroons and Lightning Network invoices to new users.
3938

4039
Aperture allows for pricing for API endpoints on the fly, including automatic tier upgrades, per-request pricing or surge pricing. In another light, this can be viewed as a global HTTP 402 reverse proxy at the load balancing level for web services and APIs.
4140

the-lightning-network/lsat/aperture.md renamed to the-lightning-network/l402/aperture.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
---
2-
description: Aperture is an implementation of LSATs as a reverse HTTP proxy.
2+
description: Aperture is an implementation of L402s as a reverse HTTP proxy.
33
---
44

55
# Aperture
66

77
Aperture is a reverse proxy that acts as a payment and authentication gateway for Lightning Network powered APIs. It can handle gRPC requests over HTTP/2 as well as REST over HTTP/1 and 2.
88

9-
Aperture receives incoming connections, verifies the validity of the LSAT and either forwards the request to the appropriate end point, or obtains a Macaroon and sends it together with a Lightning invoice and the HTTP status code 402 Payment Required.
9+
Aperture receives incoming connections, verifies the validity of the L402 and either forwards the request to the appropriate end point, or obtains a Macaroon and sends it together with a Lightning invoice and the HTTP status code 402 Payment Required.
1010

1111
Aperture is currently used in production in Lightning [Loop](../../lightning-network-tools/loop/) and [Pool](../../lightning-network-tools/pool/).
1212

1313
## Install Aperture
1414

15-
Requirements: go 1.13 or later
15+
Requirements: go 1.19 or later
1616

1717
`git clone` [`https://github.com/lightninglabs/aperture.git`](https://github.com/lightninglabs/aperture.git)\
1818
`cd aperture`\
@@ -29,11 +29,11 @@ To run Aperture, simply run the following command from within aperture's directo
2929

3030
`./aperture`
3131

32-
## LSAT demo
32+
## L402 demo
3333

34-
A demonstration of LSATs can be found at [https://lsat-playground-bucko.vercel.app/](https://lsat-playground-bucko.vercel.app/) ([Testnet version here](https://testnet-lsat-playground.vercel.app/))
34+
A demonstration of L402 can be found at [https://lsat-playground-bucko.vercel.app/](https://lsat-playground-bucko.vercel.app/) ([Testnet version here](https://testnet-lsat-playground.vercel.app/))
3535

36-
Here you can go through the process of minting a Macaroon, turning it into an LSAT, restricting and validating it as well as see code snippets.
36+
Here you can go through the process of minting a Macaroon, turning it into an L402, restricting and validating it as well as see code snippets.
3737

3838
[See how the client interceptor is coded in Aperture](https://github.com/lightninglabs/aperture/blob/master/lsat/client\_interceptor.go)
3939

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: Projects using L402 today, code examples and further reading
3+
---
4+
5+
# Implementations and Links
6+
7+
Not listed? [Fill out this form!](https://docs.google.com/forms/d/e/1FAIpQLSdT6kP3oUzd6xWytkDcflU9byHcp8nP9IyYntm\_6wa9Cw6qqg/viewform)
8+
9+
## L402 implementations and libraries <a href="#docs-internal-guid-835019d0-7fff-c5a5-1425-7948dcc6dd6f" id="docs-internal-guid-835019d0-7fff-c5a5-1425-7948dcc6dd6f"></a>
10+
11+
* [​Aperture: A gRPC/HTTP authentication reverse proxy using L402​](https://github.com/lightninglabs/aperture)
12+
* [​lsat-js: A utility library for working with L402​](https://github.com/Tierion/lsat-js)
13+
* [​boltwall: Nodejs middleware-based authentication using L402](https://github.com/tierion/boltwall)
14+
* [now-boltwall: The Boltwall deployment toolkit](https://github.com/tierion/now-boltwall)
15+
* [Aperture Dynamic Pricing Demo](https://github.com/ellemouton/aperture-demo)
16+
17+
## Projects using L402
18+
19+
* [​Lightning Pool](../../lightning-network-tools/pool/)
20+
* [Lightning Loop](../../lightning-network-tools/loop/)
21+
* [​L402 Playground​](https://lsat-playground.bucko.now.sh/)
22+
23+
## Further reading
24+
25+
* [Tierion: Pseudonymous Authentication using Bitcoin Lightning Payments](https://medium.com/tierion/lsats-pseudonymous-authentication-using-bitcoin-lightning-payments-459e209b4b36)
26+
*[Macaroons: Cookies with Contextual Caveats](https://research.google/pubs/pub41892/)\
27+
the 2014 paper published on Google Scholar.
28+
*[HTTP/1.1 RFC, Section 6.5.2: 402 Payment Required](https://tools.ietf.org/html/rfc7231#section-6.5.2)

0 commit comments

Comments
 (0)