lightninglabs / docs.lightning.engineering Goto Github PK

Building lapps, running lnd, and more

Shell 0.07% Markdown 99.93%

docs.lightning.engineering's Introduction

description
This repository is designed as a home for those looking to learn about the Lightning Network, use and build on LND, Lightning Terminal, Loop, Pool as well as those developing their own LAPPS.

Welcome to the Builder's Guide to the LND Galaxy!

{% content-ref url="broken-reference" %} Broken link {% endcontent-ref %}

Start here if the terms "payment channel" and "hash time-locked contract" are foreign to you.

{% content-ref url="lightning-network-tools/lnd/" %} lnd {% endcontent-ref %}

Look here if you're getting started with LND, want to configure it optimally or learn how to integrate LND into your production environment.

{% content-ref url="lightning-network-tools/lightning-terminal/" %} lightning-terminal {% endcontent-ref %}

Lightning Terminal is a browser-based, self-hosted dashboard for Lightning Labs products. Read this guide to learn how to set up Lightning Terminal and get the most out of it.

{% content-ref url="lightning-network-tools/loop/" %} loop {% endcontent-ref %}

Loop is a service that makes it easier to send and receive funds on Lightning, serving as an on and off ramp between the Lightning Network and the Bitcoin blockchain. Read our guides to Loop to optimally use Loop.

{% content-ref url="lightning-network-tools/pool/" %} pool {% endcontent-ref %}

Pool is a non-custodial marketplace where users can buy inbound liquidity from node operators. Read our guides on how to join Pool as either a buyer or seller.

{% content-ref url="the-lightning-network/taproot-assets/" %} taproot-assets {% endcontent-ref %}

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

{% content-ref url="the-lightning-network/l402/l402.md" %} l402.md {% endcontent-ref %}

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.

{% content-ref url="broken-reference" %} Broken link {% endcontent-ref %}

We have you covered if you're starting with your first LAPP or running a professional service and want to leverage best practices when it comes to APIs, channel backups, key management, et al.

{% content-ref url="broken-reference" %} Broken link {% endcontent-ref %}

If you're looking for inspiration, we've included a sampling of community projects for you to look to. We hope you add whatever you build to this page!

Additional external resources include our Developer Slack, Github organization, and API documentation, including LND, Loop, Pool, Faraday & Taproot Assets.

docs.lightning.engineering's People

Contributors

Stargazers

Watchers

docs.lightning.engineering's Issues

Sparse Merkle trees

I think there is a small mistake in the docs for the taproot assets protocol

For example, we may create a Sparse Merkle tree using a fictitious hashing function of sha002, which results in a number between 0 and 3. We generate a Sparse Merkle tree with 4 leaves: 0, 1, 2 and 3. Only leaf 2 is populated, all other leaves are empty. To find leaf 2 (written 10 in binary), we go right at the first branch (1), then left at the second branch (0).

This suggests that in binary format a 1 means turning right and a 0 means turning left (which is correct).

But I think there is a small error in the next section:

In Sparse Merkle trees, every leaf can be described as a guide to itself through a map when expressed in binary form. The map is the Sparse Merkle tree itself, and the guide is represented by instructions on whether to turn left or right at each fork. The 9th leaf in a 2^4 large Sparke Merkle tree for example is expressed in binary as 1001, meaning we find the appropriate leaf by turning left, then right, right and finally left.

This suggests to turn left on a 1 and right on a 0. It should be the other way round.

Furthermore, in my opinion the wording "9th" leaf is is somewhat misleading. Since we start with the index 0 the "9th" leaf would be leaf number 8. I think the text should say something like "leaf number 9".

Can someone confirm the small mistake mentioned above? If so, I will create a pull request.

docs: warn against changing documents that are synced from upstream repos

first (issue)!

Once #34 is merged, we will have documents from various LL repos pulled in to docs/{repo name} with an hourly sync. If changes are made to those synced documents by people looking to contribute to the docs dir, they will be overwritten by the sync. Changes should instead be made to the upstream repo, and then the sync will take care of the rest.

This isn't the best contributor flow, but is a consequence of our decision to leave docs in their upstream repos. Some documentation around this would be useful to prevent headaches for the kind souls who take the time to help us improve our docs.

How do I find the owner of Taproot Assets?

What method should I use to find out which addresses are holding an asset with a known asset id?

URLs in repo with HTTP 404 error response

Script to find URLs in repo with 404 error response

$ grep --color -rhsI . -oE -e "(http|https)://[a-zA-Z0-9./?@=_-]*" | sort | uniq | parallel 'echo -n "{} "; curl --write-out '%{http_code}' --silent --output /dev/null {}; echo' > ~/responsecodes

$ grep " 404" ~/responsecodes | awk '{print $1}' | tr -d \' | parallel 'grep -rn {}; echo'

Output

./lightning-network-tools/lnd/recovery-planning-for-failure.md:51:[Learn how to recover your funds.](https://docs.lightning.engineering/lightning-network-tools/lnd/recovery)

./docs/lnd/grpc/javascript.md:239:Javascript](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated).

./community-resources/resource-list.md:110:* [LNBits](https://lnbits.org)

./the-lightning-network/lsat/aperture.md:38:[See how the client interceptor is coded in Aperture](https://github.com/lightninglabs/aperture/blob/master/lsat/client\_interceptor.go)

./lightning-network-tools/lnd/macaroons.md:44:The macaroon files are the only files with highly sensitive information that are not encrypted \(unlike the wallet file and the macaroon database file that contains the [root key](https://github.com/lightninglabs/docs.lightning.engineering/tree/33bc7e27861f932d5d0676912bf45cf608534ceb/docs/macaroons/README.md), these are always encrypted, even if no password is used\).
./lightning-network-tools/lnd/macaroons.md:127:The macaroon bakery is described in more detail in the [README in the macaroons package](https://github.com/lightninglabs/docs.lightning.engineering/tree/33bc7e27861f932d5d0676912bf45cf608534ceb/docs/macaroons/README.md).

./lightning-network-tools/lightning-terminal/lnc-npm.md:104:* Check out the relevant code in the project’s [readme](https://github.com/lightninglabs/lnc-web/blob/update-connect-demo/demos/connect-demo/README.md)

./the-lightning-network/taro.md:42:[Bitcoin UTXO](https://mirror.xyz/0xaFaBa30769374EA0F971300dE79c62Bf94B464d5/Yetu-6pZkbQCOpsBxswn\_7dGUZDxoBU8NrOQIZScwpg)

./build-a-lapp/local-cluster-setup-with-polar/README.md:5:This tutorial will leverage the Polar application for setting up a local cluster of Lightning Network nodes on regtest. Polar [can be downloaded](https://github.com/lightninglabs/docs.lightning.engineering/tree/9423e81a91e5a382442d5fa2fdacde019133dbcb/build-a-lapp/lightningpolar.com) for MacOS, Linux, and Windows. The source code is hosted [on Github](https://github.com/jamaljsr/polar/releases/).

./lightning-network-tools/lnd/safety.md:53:* For more technical information [see the aezeed README](https://github.com/lightninglabs/docs.lightning.engineering/tree/f123436bd902a6be74cb853447456c5c65307dd6/docs/aezeed/README.md).

./lightning-network-tools/lnd/safety.md:67:See the [high-level macaroons documentation](https://github.com/lightninglabs/docs.lightning.engineering/tree/f123436bd902a6be74cb853447456c5c65307dd6/docs/lnd/macaroons.md) or the [technical README](https://github.com/lightninglabs/docs.lightning.engineering/tree/f123436bd902a6be74cb853447456c5c65307dd6/docs/macaroons/README.md) for more information.

./lightning-network-tools/lightning-terminal/lightning-node-connect.md:53:[Read also: the gRPC service definition of Terminal Web Proxy.](https://github.com/lightninglabs/subasta/blob/master/auctioneerrpc/hashmail.proto)

./lightning-network-tools/lnd/macaroons.md:123:Have a look at the [Java GRPC example](https://github.com/lightninglabs/docs.lightning.engineering/tree/33bc7e27861f932d5d0676912bf45cf608534ceb/docs/grpc/java.md) for programmatic usage details.

Note: some URL point to internal LL resources which will return 404 for outside viewers but not for repo maintainers logged in.

URLs in repo don't conform to rfc1738 due to forward slash

Found URLs with forward slashes which don't conform to rfc1738

grep -rI . -Eo -e '(http|https)://[a-zA-Z0-9./\?@=_-]*' | grep -F "\\"

./community-resources/resource-list.md:https://docs.google.com/forms/d/e/1FAIpQLSdT6kP3oUzd6xWytkDcflU9byHcp8nP9IyYntm\_6wa9Cw6qqg/viewform
./community-resources/glossary.md:https://www.researchgate.net/publication/336890138\_Sphinx\_A\_Transport\_Protocol\_for\_High-Speed\_and\_Lossy\_Mobile\_Networks
./the-lightning-network/multihop-payments/understanding-submarine-swaps.md:https://www.youtube.com/watch?v=eB\_HkYb7Y2M
./the-lightning-network/lsat/implementations-and-links.md:https://docs.google.com/forms/d/e/1FAIpQLSdT6kP3oUzd6xWytkDcflU9byHcp8nP9IyYntm\_6wa9Cw6qqg/viewform
./the-lightning-network/lsat/macaroons.md:https://www.youtube.com/watch?v=CGBZO5n\_SUg
./the-lightning-network/lsat/aperture.md:https://github.com/lightninglabs/aperture/blob/master/lsat/client\_interceptor.go
./the-lightning-network/taro.md:https://mirror.xyz/0xaFaBa30769374EA0F971300dE79c62Bf94B464d5/Yetu-6pZkbQCOpsBxswn\_7dGUZDxoBU8NrOQIZScwpg
./lightning-network-tools/lnd/macaroons.md:https://en.wikipedia.org/wiki/Link-local\_address
./lightning-network-tools/lnd/macaroons.md:https://en.wikipedia.org/wiki/Multicast\_address
./lightning-network-tools/lnd/send-messages-with-keysend.md:https://github.com/satoshisstream/satoshis.stream/blob/main/TLV\_registry.md

So the links don't return the desired result:
in situ:
https://en.wikipedia.org/wiki/Link-local\_address
Objective:
https://en.wikipedia.org/wiki/Link-local_address

Wording of page etymology

docs.lightning.engineering/the-lightning-network/payment-channels/etymology.md

I find that Nomenclature would describe intention of page better then Etymology

thanks

Sweeping docs

Awesome to see sweeping related documentation. Referring to: https://github.com/lightninglabs/docs.lightning.engineering/blob/master/the-lightning-network/payment-channels/understanding-sweeping.md

When an anchor channel is force-closed, two anchors of 330 satoshis each are created.

Is this always true? For example: https://mempool.space/tx/a45d5f9b86414a3066a4417e017ed6a8829ffb5222b2acc083421af3d02b1aec

Not to come off as the "well ackshully" guy, but I personally was so confused by sweeper behavior, especially with anchors, that the more verbose the docs the better.

URLs in repo with HTTP 404 error response 2024-03-27 edition

docs.lightning.engineering/community-resources/resource-list.md

Line 58 in c7eb375

 * [lngraph](https://github.com/xsb/lngraph) - Personal Lightning Network explorer using Neo4j Browser 

docs.lightning.engineering/lightning-network-tools/lnd/send-messages-with-keysend.md

Line 56 in c7eb375

 Messages are typically sent with the record ID `34349334`. You can find a registry for such records [here](https://github.com/satoshisstream/satoshis.stream/blob/main/TLV\_registry.md). You may also submit your own suggestions. 

docs.lightning.engineering/lightning-network-tools/lnd/send-messages-with-keysend.md

Line 76 in c7eb375

 The actual message is sent with record `34349334`. Depending on the purpose of the message, [other records](https://github.com/satoshisstream/satoshis.stream/blob/main/TLV\_registry.md) may be used. 

docs.lightning.engineering/the-lightning-network/taproot-assets/taproot-assets-protocol.md

Line 19 in c7eb375

 [Bitcoin UTXO](https://mirror.xyz/0xaFaBa30769374EA0F971300dE79c62Bf94B464d5/Yetu-6pZkbQCOpsBxswn\_7dGUZDxoBU8NrOQIZScwpg) 

docs.lightning.engineering/docs/lnd/musig2.md

Line 22 in c7eb375

BIP](https://github.com/jonasnick/bips/blob/musig2/bip-musig2.mediawiki)

docs.lightning.engineering/docs/lnd/musig2.md

Line 124 in c7eb375

draft](https://github.com/jonasnick/bips/blob/musig2/bip-musig2.mediawiki)

docs.lightning.engineering/lightning-network-tools/aperture/get-aperture.md

Line 42 in c7eb375

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

docs.lightning.engineering/lightning-network-tools/lnd/rpc-middleware-interceptor.md

Line 139 in c7eb375

 [https://github.com/lightninglabs/lndclient/blob/master/lightning\_client.go#L256](https://github.com/lightninglabs/lndclient/blob/master/lightning\_client.go#L256) 

docs.lightning.engineering/lightning-network-tools/lnd/channel-acceptor.md

Line 151 in c7eb375

 {% embed url="https://github.com/lightninglabs/lndclient/blob/master/lightning_client.go#L230" %} 

docs.lightning.engineering/lightning-network-tools/lnd/htlc-interceptor.md

Line 297 in c7eb375

 [https://github.com/lightninglabs/lndclient/blob/master/router\_client.go#L58](https://github.com/lightninglabs/lndclient/blob/master/router\_client.go#L58) 

docs.lightning.engineering/docs/lnd/INSTALL.md

Line 358 in c7eb375

`v0.23.5`](https://github.com/btcsuite/btcd/releases/tag/v0.23.5) MUST be used.

docs.lightning.engineering/lightning-network-tools/lnd/contribute-to-lnd.md

Line 39 in c7eb375

 [Must read: Code contribution guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code\_contribution\_guidelines.md) 

docs.lightning.engineering/build-a-lapp/local-cluster-setup-with-polar/README.md

Line 5 in c7eb375

 This tutorial will leverage the Polar application for setting up a local cluster of Lightning Network nodes on regtest. Polar [can be downloaded](https://github.com/lightninglabs/docs.lightning.engineering/tree/9423e81a91e5a382442d5fa2fdacde019133dbcb/build-a-lapp/lightningpolar.com) for MacOS, Linux, and Windows. The source code is hosted [on Github](https://github.com/jamaljsr/polar/releases/). 

docs.lightning.engineering/docs/lnd/release-notes/release-notes-0.16.0.md

Line 516 in c7eb375

[README](https://github.com/lightningnetwork/lnd/tree/master/lntemp) for more

docs.lightning.engineering/docs/lnd/grpc/javascript.md

Line 238 in c7eb375

 Javascript](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated). 

404 macaroon link

Macaroon link to learn about how to bake macaroons with custom permissions leads to 404.

docs.lightning.engineering/lightning-network-tools/lnd/macaroons.md

Fee calculation rules unclear

Background

Quoting from https://github.com/lightninglabs/docs.lightning.engineering/blob/master/lightning-network-tools/lnd/channel-fees.md, " Fees are applied only once per channel by the party which is forwarding the fee. Meaning, as you push a payment to your neighbor node, you are able to charge a fee, and as payments are pushed to you, your neighbor charges the fee, even if the channel was created by you."

Inferring from the fees calculated by LND suggests that the fees charged & received by a node X forwarding a payment are calculated using the base fees and fee rates as set by node X for the inbound channel and outbound channel of the forwarded payment by the following formula: feed charged = max (fee(inbound channel), fee(outbound channel)).

The documentation is not explicit about the rules that LND uses to establish the fees and about their impact on how a node uses these rules in the payment routing policy.
Your environment

version of lnd lncli version 0.14.1-beta commit=v0.14.1-beta
which operating system (uname -a on *Nix) Ubuntu server 16.04
version of btcd, bitcoind, or other backend Bitcoin Core RPC client version v22.0.0
any other relevant environment details

Steps to reproduce

Documentation issue, see above
Expected behaviour

The document should be explicit about the rules used to calculate and charge the fee by a node on the basis of the fee policy that this node applies for its channels, taking into account whether the channel is inbound or outbound for the payment.
The documentation should be explicit about the impact of these rules on the routing policy of a payment.
Actual behaviour

Not clear whether the fees charged by a node are based on the inbound channel and/or outbound channel fee policy(ies).

docs: outdated config in LiT documentation for MacOS remote mode

It looks like the page for MacOS remote mode configuration for Lightning Terminal is out of date: it suggests copying many more files than required, and suggests outdated config options that now cause errors.

Suggest duplicating the content in the lightning terminal GitHub, which appears to be accurate.

I'm happy to take this on, but wanted to flag first.

discord link 404

Hey, i noticed the Discord link is dead on this page: (at the very bottom)

https://docs.lightning.engineering/lightning-network-tools/lnd/recovery-planning-for-failure

Maybe you guys can fix it?

lightninglabs / docs.lightning.engineering Goto Github PK

docs.lightning.engineering's Introduction

Welcome to the Builder's Guide to the LND Galaxy!

docs.lightning.engineering's People

Contributors

Stargazers

Watchers

Forkers

docs.lightning.engineering's Issues

Output

Recommend Projects

Recommend Topics

Recommend Org