Home < VR Bitcoin < Oliver Gugger, LSAT

Oliver Gugger, LSAT

Speakers: Oliver Gugger

Date: May 16, 2020

Transcript By: Michael Folkson

Category: Meetup

Media: https://www.youtube.com/watch?v=IW08RJUpzw0

Topic: LSAT - Your Ticket Aboard The Lightning Native Web

Location: Reckless VR


Happy to be here to talk about LSAT, let’s jump right in. We are going to have a look at LSAT. What the motivation was to come up with this? What the use cases for and we are going to jump into the technical detail. This is going to be a technical talk. There will be some low level details.


First who am I? Why am I giving this talk? I joined Lightning Labs in September last year. LSAT was one of my first projects that I started working on Lightning Labs. I helped code the aperture which I am also going to talk about. I also helped write some of the specification.

What is LSAT?

We are not going to talk about the Law School Admissions Test. Apparently there is a collision in the acronym. What we mean with LSAT is the Lightning Service Authentication Token. It is first and foremost a protocol specification originally written by Laolu aka roasbeef. It is also a proposal for a new standard. We wrote a document. Most of what I am talking about you can find in this document under lsat.tech. It is a combination of HTTP, macaroons, of course Lightning and these three things combined equal LSAT. It is also the future as mentioned in the official HTTP RFC. The status code 402 was in there from the beginning but it was reserved for future use. At the time there was no way to pay online through a digital cash system. It stayed reserved until the Lightning Network arrived and we think that the future is now. Now we have a digital cash system that we can use to pay on the internet.


Before we look at how exactly it works we want to look at the motivation or why do we need yet another protocol or yet another standard. Today’s web is skewed a bit. You either use a service and if it is free you are the product. You being on the service is solved by either looking at ads or you looking at more ads because you look at an article which doesn’t contain any useful information. You are tracked throughout the experience. Every penny is pressed out of you as a user. On the other hand if you want to pay for something you usually give all your information. Your name, your date of birth, your credit card information, email address. You have to choose a password, hopefully a new password every time. Either way it is usually not a satisfying experience. Most of the incentives are just not aligned with what a user expects or wants. We want to change that or hope that this can change.

Use Cases

What can we do with LSAT? First of all it allows you as an owner of content on a website to sell it. You can monetize the content that before you either gave out for free or monetized through ads or solved through a credit card based subscription system. It also allows you to give paid access to your API. If you are a service provider you can replace the API keys that you might have used before with LSAT as a technology. That allows you to give the user the possibility to create an adhoc identifier. No personal information from the user has to be given. A Lightning payment is involved but the payer doesn’t give out any information. Not even the public key of the node that it is paying. The service that accepts LSAT doesn’t know anything about you other than the identifier it gives you. Because the second part we are using is a cool technology called macaroons you can also come up with your own custom payment model. You can pay per request. Every time you load a new article you have to pay. Or you can do metered payment. Every megabyte you download you have to get a new token and pay again. Or you can say “Let’s make a token that is valid for a week or a month.” We are going to look into the technical details of these macaroons later.

You could also get some side effects from using LSAT. If you are using a reverse proxy you also get simple denial of service protection. If you say “You can only access the resource after you have paid a Lightning payment” this prevents brute force distributed DOS. For the developers if you can put some reverse proxy in front of your application you have a very strong decoupling from the payment logic and the authentication from what you as a developer care about providing to your service. It is a nice way of extracting the payment part and you as a developer can focus what you are building for your users. On the user side if software is starting to use this protocol and support it, maybe build into browsers through plugins or external tools or add this as a mobile app then you get the unified user experience across all of these websites that use LSAT for authentication and payment. For example the last time I gave this talk it was live-streamed and I could do a demo. It is hard to do in VR. There I could use a tool, a browser plugin to easily pay something and get access to the paid content immediately. The whole process took me less than five seconds.

High level end-to-end LSAT authentication flow

This might be a bit small for VR but the diagram is also on the website. Let’s look at what actually happens if I go to a website that uses LSAT. On the left side we have the client. Let’s say this is my browser. I want to read an article which is the protected resource. It is an article that the author wants me to pay for. The author of the website put an authentication server in front. This acts as a gatekeeper. It is tasked with the authentication part. It is sometimes also called a reverse proxy. All the requests I do go through this reverse proxy and are checked every time. I am the client, I open a website, go to the article and click on “Read article.” The authentication server intercepts my request and sees there is no token of any sort attached. It goes to lnd, creates an invoice, creates a macaroon and sends both of these pieces back to me, the client. With a HTTP status code 402 Payment Required. The plugin that I use recognizes this, can extract the invoice, it is connected to lnd itself, pays the invoice and by paying the invoice I get back a preimage which is a secret that proves that I have paid. The preimage together with the token that I received, I can combine into what we call the LSAT. The LSAT is the final token and exists once you have the macaroon plus the proof of payment. These two pieces combined equal the LSAT.

High level auth flow

The next time I click on the “Read article”, this would happen in the background after I clicked the first time the plugin would handle this and try the request again. Now with the token, the macaroon and the preimage combined sends the same request again. The authentication server can check it is paid, fetches the resource, the article I wanted to read and returns it to me. I can read it. Real world this would probably take less than a second.

Why do we need this token? I know there are other services that do similar schemes already where you can pay for an article. One of the well known examples is Yalls.org. Why do we need an extra token? Why isn’t a Lightning payment enough? The problem is that the preimage, this payment secret, is in theory is known to all of the nodes that are involved in the payment. All of the hops my payment goes through could in theory use this to read the same article which isn’t always optimal. The second reason is that with just having paid I don’t get any of the fine-grained control over what am I allowed to do now. The website would still need to create some sort of identity and link the payment to it to allow for more fine-grained control. What makes LSAT different from all the other proposed protocols is that we use a token. Of course it is not a payment token as in a s***coin. It is some signed piece of data that has a signature of the person or the authority that issued it. In our case it is the authentication server. Because we already use macaroons in lnd we know it is an awesome technology. It gives us many cool features so we used macaroons as the cryptographic token. We could have gone with a chosen web token or any similar technology that allows us to have a signature but we already are familiar with macaroons. We will see all of the benefits soon. Now let’s see how this looks on the HTTP level.

HTTP implementation

It is kind of simple. There is not even a new HTTP header. The www-Authenticate and the authorization headers, they both exist and they even give you the opportunity to add your own scheme. What we did here is 100 percent HTTP compliant. Every browser understands it. It doesn’t necessarily know what it contains or what to do with it but it won’t reject it because it is a valid HTTP header. The first part, the challenge is what the authentication server sends back to the client if it detects that I haven’t paid yet or don’t have a token yet. What it contains is firstly the macaroon, the cryptographic token. It is Base64 encoded and we also get an invoice which is bech32 I believe according to the BOLT11 specification. I get these two pieces of data, I as a client store the macaroon for later use, take the invoice, take it to my lnd node, pay it. I receive the preimage and then I do the same request again and this time I attach a header that says authorization, LSAT, here’s my macaroon and then here is my preimage. Both of these two pieces combined, the server can make sure the user paid and can then give me the resource I requested.

gRPC implementation

The cool thing is because we use gRPC for services, gRPC is HTTP/2 on steroids or a subset of a HTTP/2. This more or less works out of the box with gRPC as well. The small difference is that gRPC ignores the HTTP status code. It doesn’t really know what 402 means which is sad because it is kind of cool to finally use this HTTP status code. We just include this gRPC message which is a custom message. Everything else works more or less the same.


Let’s go into some details about macaroons. What are they exactly? It is a 3-tuple of a public identifier. This is basically your pseudonymous user identification. It contains a list of caveats. We will explain what these are in the next slide. And a signature. The signature allows the receiver of the macaroons to check whether they themselves created it. If a server creates a macaroon it can later check if it is still the same, it hasn’t been modified or not modified in an illegal way, and the server actually created it. If you want to know more about how they work on a technical level you can watch my YouTube recording from last year’s Lightning Hack Day. I go into all the HMAC stuff and all the low level basics. Why do we use them in LSAT? I mentioned some of the features before. The cool thing about this is that in the macaroon you have capabilities encoded. It is not an identity that I have to map roles onto on the server. The macaroon itself contains what I am allowed to do. As a server I can encode all the rights and capabilities I have into the macaroon. Because a user cannot change it without breaking the signature I can’t add any rights to it. It also gives myself as the user the possibility to attenuate these rights, restrict them myself and then give the restricted subset maybe to another user. If I, the service operator, receive a macaroon from somewhere I can attach further restrictions to it and then give it to someone else to use. We will come to possible use cases there. The macaroon itself can also contain a very fine-grained list of permissions. Let’s look at an example.

One of our first products or services that we enabled LSAT on is Lightning Loop. This is the first of many services that we are going to enable LSAT on. For the moment if you use the newest client software it will in the background automatically acquire a LSAT and pay for it. The price is very low, it is 1 satoshi at the moment. It is in the testing phase to see if everything works as expected. It is not really expensive.

Q - What is Loop?

Loop is a service that allows you to manage your liquidity so you can exchange your offchain balance that you have in your channels to onchain balance. I can send my Lightning Bitcoin onchain or the other way round. If I don’t have any outgoing liquidity anymore I can pay some onchain payment and then receive that in Lightning. It is a way to manage my channel liquidity. Because it is an interesting service to start experimenting on with these tokens we enabled LSAT on the Loop service a few weeks ago. What you get in the background if you use the service is a LSAT token that contains more or less the information you see on the screen. The first part, the identifier part, contains a version, it is also good to have a version. It contains a user_id. That is a random ID that is created. It doesn’t link to anything you are doing or you are. The payment_hash is the same hash that was in the invoice that you paid to get the token. Then the list of caveats. These are now restrictions put in by the server. At the moment they don’t really look like restrictions, more enumerations of things you can do. For example, we say “You can do Loop with this.” The service you are allowed to use is Loop and the service tier is zero. We don’t have tier one yet, for future use. On Loop you have the capabilities of doing Loop Out and doing Loop In. These are the only two operations you can do on Loop. You have all rights there are. This isn’t implemented yet but in the future we could also say “For Loop Out your monthly allowed volume in satoshis is 200 million, 2 BTC.” With this token you could use both Loop In and Loop Out indefinitely but only up to a monthly volume. Now let’s say I am a business Bitrefill and I do a lot of Loops. Maybe you do them from different nodes with different users. This is the admin macaroon I get and now I have employees I want to give the right to do the actual Loops. I go ahead myself without interaction with the Lightning Labs server, I take this macaroon and I add my own caveats to it.

I add these two new lines. Append this to the existing one. Caveats are always gone through in order. Now with this new macaroon the user only has the capability of doing Loop In and only for 1 BTC a month. Without going to the server and saying “We have a new user that needs restricted access. Can you please give me a new token that does only Loop In?” I can do that myself. Because I as the user I cannot go back. That is the cool thing about the macaroons. The cryptographic construct is that I can only add stuff. If I don’t have the previous version without these restrictions I cannot take them away. I am stuck with only doing Loop In and only 1 BTC a month.

3rd party macaroon authentication

What we talked about here, these are the first party caveats. There are also third party caveats. This is a bit advanced stuff and we didn’t implement any of this yet but this shows the potential that this offers when we are using macaroons. What we can do with these so called third party caveats is do delegation of the authentication. We go into the same territory as OAuth. I can say and code into my macaroon “Here you have it but you need someone else to sign on it.” We have come up with this example for a Bitcoin bounty hunt, a first person shooter. I think they are going to implement this. We talked about this and came up with this scheme. For those who are not with familiar with a shooter, the players can run around in this world, collect satoshis that are lying around and kill other players with weapons and collect the bounties that are on their heads. External advertisers can buy space inside the game to put on their ads. That is where the satoshis come from that the player collects. The players are paid for playing and looking at ads. We look at ads on the internet which I said is bad. Here at least I get paid for looking at ads and killing other players. What the author of the game told me is that they want to auction these rights to sell the ad spots. But they don’t want to write a whole auction platform. It would be cool if the auction platform was a third party. The game could say “Here is a macaroon and an invoice. Go to this auction platform and make sure you are the highest bidder. Get the signature from the auction platform and once you come back with the third party signature you can then upload your ad image.” The cool thing is that even though the auction platform is involved and sees part of the authentication steps they themselves cannot misuse their power and place ads themselves because they don’t have the whole macaroon that the user has. Long story short we can do really cool stuff with this in the future and all the pieces are there. We added a PR in lnd that lets you create this shared secret that is necessary for this. All the details are in this very old issue.

What’s Aperture?

What’s Aperture? It is very simple. It is what we implemented to make LSAT work. It is a simple reverse proxy and authentication reverse proxy. It supports proxying HTTP HTTP/2 and gRPC that includes all the streaming stuff. We can put this proxy in front of any service that we want to use LSAT with. That is the software we put in front of Loop. All the client requests go through it and are checked for the token. It has been in production for a few weeks now. How does this look?

We have the Aperture in the middle. It is a very simple HTTP proxy. We could have written an Nginx plugin or an Apache plugin but we didn’t want to depend on any other software so we wrote it ourselves. We hope that someone will implement plugins soon that do the same. It takes all the browser or Loop client requests and makes sure they have a token. It stores the secrets necessary for the macaroons in an etcd database and then forwards the requests once they are authenticated to the actual backend which in this case would be the Loop server. Or as another example the BOS score if you wanted to sell access to node scoring backend servers.


Q - For me what I am most excited about with LSAT is the privacy element and the ability to not have to login. To be able to authenticate you don’t need to use your username and password. There are so many sites out there. Udi and I talked about this in VR last week, where our personal data and information is stored. I know you talked a little about the gaming user cases, what use cases are you most excited about for LSAT? What have we seen? I know some people are building some apps in the community. What are they doing right now in terms of building?

A - I’m not really that good in thinking up cool ideas and use cases. I have heard many. Why do I need to give my email address and password if I just want to use the service once and never go back there. Everything that they usually want is my money and I can just give it to them. If it is a digital good they shouldn’t need to care who I am or where I live. They can just give me the video or the picture that I want to buy or use. Or the article I want to read. I think this would eliminate the need for most of our username and password logins today. Of course everything that is linked to the real world you probably need to give a shipping address or something. It could be a shipping proxy or whatever. There are so many websites that I feel I use once but they still have a password and an email address and probably much more. I am really excited to get rid of this. For me personally the problem with ads is a bigger one. I install an adblocker, it is the first thing I do after installing a browser. I just hate ads. But there is usually no possibility to donate a few sats to a website that creates awesome content. I am really willing to pay, that is not a problem. Everyone who says “No, users want everything for free.” I don’t believe that if we can get clean content without any advertising or our data being sold I think users are wiling to pay for this. Use cases that are already being implemented, I know the Boltwall project which switched over to LSAT after we published the specification. Before there was some collaboration. They jumped on this idea very quickly and they implemented it on their paywall product. They also wrote a very cool online Javascript toolkit where you can play around with the encoding with the LSAT. I think it is called the LSAT playground. People really appreciate this effort to create this standard. I think it was also the people at Tierion that worked with Christopher Allen from the W3C committee. There are already talks about this to make it an official standard. It is not driven by Lightning Labs but we of course support this. It would be awesome to have an official W3C standard that finally gives the 402 status code a real meaning. Maybe we could even rewrite the original RFC and remove the future use in there. Maybe that is taking it too far.

Q - This is a huge win for users and consumers especially on the privacy side. How do you think about some of the incentives for corporations and companies that really do stand to benefit from tracking users’ data and benefitting from the analytics? What incentives do they have on this on their platforms?

A - It is probably going to be hard to transition the existing companies to not track you anymore. They earn their money with this. My hope is that you can implement LSAT as an additional income. All the users that you might not get because they are not willing to pay 50 dollars for a year subscription, you can give the option to read one article and pay through Lightning. It could be an additional revenue stream. If the consumers jump on this and are willing to use this it could maybe push the incentives toward getting rid of the subscriptions, getting rid of the tracking. Of course it is also important that we as the users really are careful that we insist on not giving our information. Of course you can do tracking with LSAT but it is not in the protocol by default. You as a service provider, you could add but we as users we don’t want this and we have to be insistent on not being tracked.

Q - We will probably end up seeing both options. The option to use LSAT without having to give your information but some sort of additional incentives for a user to give their information to their company so they can continue to track that user. Everybody is going to have to become mindful of your data and privacy.

A - And hopefully we can get rid of some of the existing services and replace them with non-clickbait versions that actually contain useful content.

Q - We are sitting here in VR. The world has changed in the last couple of months. I see this as a window of opportunity with people saying we are having a decade worth of change in a couple of weeks. But if it was possible in a couple of weeks I see new entrants and new players having huge opportunities. One example would be in the US bank payments are so slow between banks. Just today I saw that it was possible to send faster payments between certain accounts. What was the incentive against that? The banks make less money because they get more interest when they hold your money longer so you can’t instantly send between accounts. Of course there were a variety of other systems that made it slower. Similarly I think this is consumer and user demand for products that aren’t going to track you. I think we have a window of opportunity to create new products and new paradigms and systems that are not going to subscribe to that. If people continue to do that maybe they won’t last because we will have new entrants and new opportunities. I am really excited to see what people build. In terms of using LSAT to track people you can always reauthenticate with another token so you are not going to have to persistently tracked even if someone was going to try.

A - If you want to get rid of your previous identity you create a new token. Maybe we want to keep them cheap.

Q - You could have a portable identity of sorts or a transient identity where you are using a service, you get rid of it and you have a new one?

A - Definitely

Q - Key send has been part of lnd for some time now. Is there a way to pay for the token with the first request so you can knock off some round trips in the protocol so you don’t have to wait for the recheck? You can pay upfront and then get the token back immediately. Is that possible?

A - Maybe with some tricks we could do it that way. The problem is that you also need to get the macaroon and the macaroon is linked to the payment.

Q - The preimage is encrypted in the payment and you can have some custom records as well. You can describe what you want in the custom records? You can put arbitrary data there?

A - Definitely. I could send a keysend payment and encode in there that this is for the LSAT I am going to request in a moment. It is a great idea. Of course we accept PRs to the specification itself. If you are interested I’d be happy to look at it and review it.

Q - I can see how for this super useful for metered services but if I wanted to offer a monthly subscription what would stop my users from sharing the LSAT with other friends?

A - That is a recurring question. The sharing of the token is not handled by the protocol or the specification itself. It is quite easy to share it. But I think that might be up to the service to decide whether this is a big problem or not. Whether this should be allowed. I think of the Netflix model where you are allowed to use up to five computers. There is some sharing of accounts. They know people are going to share. Do you want to make it very difficult or try to ban users? It is up to the service. You can of course to try to limit. After 5 different IP addresses that use the token I am going to block it. We left that open in the protocol but it is maybe something you as a service provider want to think about. Whether you tolerate it up to a certain limit or not. It is definitely something to think about.

Q - If I pay my invoice I will get a preimage. How do I get a preimage in the browser? Do I have to have a plugin in the browser or is there a manual method? How does it work?

A - We do have a testate instance and there we have this demo I did in person last time. It is a very simple HTML page where you can try this out. There you have two possibilities. If you have a plugin like tool installed you can just click on a button, it will open and ask you whether you want to pay this 1 satoshi. You say yes and then it happens in the background automatically. If you don’t have a plugin then of course the browser itself wouldn’t know what it is. Not yet but maybe in the future. You can also copy the invoice out, pay it, copy the preimage and then put it back into the browser. Both steps work. Of course it would be so cool if instead of integrating a ****coin in your Brave browser why not integrate Lightning? That would be great.

Q - Let’s say you buy an article and your browser crashes before you read it and you come back. Is that stored somewhere that you purchased it already?

A - It depends. I can say how it works in Loop. There we store the token that we get and we store it on disk. Next time we start Loop it still knows that I have the token, that we already paid. Hopefully the browser plugin would store the token and the service would know that you have paid for this article, you are allowed to read it again. Or maybe it is already encoded in the macaroon which article you paid for. As long as the token is stored before your crash you can read it whenever you want.

Q - When you are doing the authentication process you send back the invoice that needs to be paid. How do you do that? Is that the header?

A - It is the www-Authenticate header where you say here is the macaroon and the second part is here is the invoice.

Q - Is there a website where I can try using Loop with Joule?

A - No because Loop currently only works with gRPC. Joule is a browser plugin and the browser doesn’t know gRPC so unfortunately not yet. But I heard that Will O’Beirne is maybe integrating Loop into Joule.

Q - Is LSAT something that I can experiment with today or is that totally hashtag reckless? I can imagine the first types of applications would be Lightning based infrastructural services like inbound liquidity or API services for information about the network, routing, stuff like that. In which case I would like to experiment using that on my own node either for APIs or web based services. Would that be reckless?

A - I wouldn’t say it is reckless. It is first and foremost a specification. We use it in production so the Loop server is already behind a LSAT proxy so you have to pay to get a token. I would definitely encourage you to experiment with it. The Lightning part itself might be considered reckless on mainnet but the rest of the LSAT spec is not reckless I would say. Macaroons as a technology have been around since 2014. Invented by Google. I know Google uses it internally so the cryptography behind it is probably quite sound. It would be nice to see more people experimenting. Go ahead and ask us questions on GitHub too. The spec itself is also on GitHub. If you go to lsat.tech there is a button somewhere that links you to the spec document.