From b5aa5e00d276f66e9f4ddc542901f7d45f45bd5f Mon Sep 17 00:00:00 2001 From: GitHub Date: Thu, 19 Sep 2024 00:21:14 +0000 Subject: [PATCH] update documentation --- docs/lnd/code_contribution_guidelines.md | 8 +-- docs/lnd/grpc/c#.md | 2 +- docs/lnd/grpc/javascript.md | 4 +- .../lnd/release-notes/release-notes-0.19.0.md | 3 + docs/lnd/signing_release_candidate.md | 70 +++++++++++++++++++ 5 files changed, 80 insertions(+), 7 deletions(-) create mode 100644 docs/lnd/signing_release_candidate.md diff --git a/docs/lnd/code_contribution_guidelines.md b/docs/lnd/code_contribution_guidelines.md index 9e4203c8..a847b6fe 100644 --- a/docs/lnd/code_contribution_guidelines.md +++ b/docs/lnd/code_contribution_guidelines.md @@ -77,7 +77,7 @@ security and performance implications. # Required Reading -- [Effective Go](http://golang.org/doc/effective_go.html) - The entire `lnd` +- [Effective Go](https://golang.org/doc/effective_go.html) - The entire `lnd` project follows the guidelines in this document. For your code to be accepted, it must follow the guidelines therein. - [Original Satoshi Whitepaper](https://bitcoin.org/bitcoin.pdf) - This is the white paper that started it all. Having a solid @@ -85,7 +85,7 @@ security and performance implications. - [Lightning Network Whitepaper](https://lightning.network/lightning-network-paper.pdf) - This is the white paper that kicked off the Layer 2 revolution. Having a good grasp of the concepts of Lightning will make the core logic within the daemon much more comprehensible: Bitcoin Script, off-chain blockchain protocols, payment channels, bidirectional payment channels, relative and absolute time-locks, commitment state revocations, and Segregated Witness. - The original LN was written for a rather narrow audience, the paper may be a bit unapproachable to many. Thanks to the Bitcoin community, there exist many easily accessible supplemental resources which can help one see how all the pieces fit together from double-spend protection all the way up to commitment state transitions and Hash Time Locked Contracts (HTLCs): - [Lightning Network Summary](https://lightning.network/lightning-network-summary.pdf) - - [Understanding the Lightning Network 3-Part series](https://bitcoinmagazine.com/articles/understanding-the-lightning-network-part-building-a-bidirectional-payment-channel-1464710791) + - [Understanding the Lightning Network 3-Part series](https://bitcoinmagazine.com/technical/understanding-the-lightning-network-part-building-a-bidirectional-payment-channel-1464710791) - [Deployable Lightning](https://github.com/ElementsProject/lightning/blob/master/doc/miscellaneous/deployable-lightning.pdf) @@ -140,7 +140,7 @@ code works correctly when it is fed correct data as well as incorrect data Go provides an excellent test framework that makes writing test code and checking coverage statistics straightforward. For more information about the -test coverage tools, see the [golang cover blog post](http://blog.golang.org/cover). +test coverage tools, see the [golang cover blog post](https://blog.golang.org/cover). A quick summary of test practices follows: - All new code should be accompanied by tests that ensure the code behaves @@ -168,7 +168,7 @@ extensively using the commands within our `Makefile`. As a result, we recommend - At a minimum every function must be commented with its intended purpose and any assumptions that it makes - Function comments must always begin with the name of the function per - [Effective Go](http://golang.org/doc/effective_go.html) + [Effective Go](https://golang.org/doc/effective_go.html) - Function comments should be complete sentences since they allow a wide variety of automated presentations such as [godoc.org](https://godoc.org) - The general rule of thumb is to look at it as if you were completely diff --git a/docs/lnd/grpc/c#.md b/docs/lnd/grpc/c#.md index 1ebebbc3..3f752118 100644 --- a/docs/lnd/grpc/c#.md +++ b/docs/lnd/grpc/c#.md @@ -219,4 +219,4 @@ client.GetInfo(new GetInfoRequest()); ### Conclusion -With the above, you should have all the `lnd` related `gRPC` dependencies installed locally in your project. In order to get up to speed with `protobuf` usage from C#, see [this official `protobuf` tutorial for C#](https://developers.google.com/protocol-buffers/docs/csharptutorial). Additionally, [this official gRPC resource](http://www.grpc.io/docs/tutorials/basic/csharp.html) provides more details around how to drive `gRPC` from C#. \ No newline at end of file +With the above, you should have all the `lnd` related `gRPC` dependencies installed locally in your project. In order to get up to speed with `protobuf` usage from C#, see [this official `protobuf` tutorial for C#](https://developers.google.com/protocol-buffers/docs/csharptutorial). Additionally, [this official gRPC resource](https://grpc.io/docs/languages/csharp/) provides more details around how to drive `gRPC` from C#. diff --git a/docs/lnd/grpc/javascript.md b/docs/lnd/grpc/javascript.md index 9cf65f63..42da61eb 100644 --- a/docs/lnd/grpc/javascript.md +++ b/docs/lnd/grpc/javascript.md @@ -235,9 +235,9 @@ client.getInfo({}, (err, response) => { With the above, you should have all the `lnd` related `gRPC` dependencies installed locally in your project. In order to get up to speed with `protofbuf` usage from Javascript, see [this official `protobuf` reference for -Javascript](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated). +Javascript](https://protobuf.dev/protobuf-javascript/). Additionally, [this official gRPC -resource](http://www.grpc.io/docs/tutorials/basic/node.html) provides more +resource](https://grpc.io/docs/languages/node/basics/) provides more details around how to drive `gRPC` from `node.js`. ## API documentation diff --git a/docs/lnd/release-notes/release-notes-0.19.0.md b/docs/lnd/release-notes/release-notes-0.19.0.md index bda48809..8d3a908f 100644 --- a/docs/lnd/release-notes/release-notes-0.19.0.md +++ b/docs/lnd/release-notes/release-notes-0.19.0.md @@ -52,6 +52,9 @@ # Technical and Architectural Updates ## BOLT Spec Updates +* Add new [lnwire](https://github.com/lightningnetwork/lnd/pull/8044) messages + for the Gossip 1.75 protocol. + ## Testing ## Database diff --git a/docs/lnd/signing_release_candidate.md b/docs/lnd/signing_release_candidate.md new file mode 100644 index 00000000..263e170d --- /dev/null +++ b/docs/lnd/signing_release_candidate.md @@ -0,0 +1,70 @@ +# Signing a LND Release + +When a new version of LND is released, binaries for the lnd and lncli programs +are provided for various platforms and CPU architectures. The hashes of all +these binaries are written into a file known as the "Manifest". This Manifest is +then signed by a quorum of trusted LND contributors (see [verify-install.sh](/scripts/verify-install.sh) +script for more details), ensuring that users can trust the binaries they +download, knowing they haven't been modified during the automated build process. + +To verify a release binary, users have two options: + +* Manual Verification: Users can manually download the signature files and +Manifest from GitHub LND release page, then verify the PGP signatures and +hashes. + +* Automated Verification: The LND repository provides a script, +[verify-install.sh](/scripts/verify-install.sh), that automates the verification process. This script uses a +set of trusted developer keys (located in the repo under [scripts/keys/](/scripts/keys)) and +downloads the necessary data from the GitHub server to verify the integrity of +the local lnd/lncli binaries. + +Running [verify-install.sh](/scripts/verify-install.sh) validates that trusted developers attest to the authenticity between the lnd release binaries hosted on Github and the developer's local builds. + +## Adding a new developer as a signer + +When another developer is added to the trusted group of people which are +allowed to sign the lnd/lncli releases, their public PGP key needs to be added to +the LND repo. These keys are added in a PR in which 2 reviewers ensure the developer +is in possession of the PGP key which will be added to the LND repo. +(See https://github.com/lightningnetwork/lnd/pull/8788 as an example). +It is important that the name of the PGP key equals the name in the +[verify-install.sh](/scripts/verify-install.sh) script. See also [scripts/keys/README.md](/scripts/keys/README.md) for more information. + +## Signing a release binary package + +If the new developer's PGP key has been successfully added to the LND repository, +through the aforementioned PR example, they are now able to provide their +signature for the new release's "Manifest" file. To do so, the developer must +follow these steps: + +* Follow the build instructions at https://github.com/lightningnetwork/lnd/blob/masterdocs/release.md#building-a-new-release. + +* After a successful build, all binaries and Manifest files, will be placed +in a directory, named after the tag, created within the directory in which the build occurred. For +instance, in the case mentioned above, the folder will be named +`lnd-v0.18.3-beta`. +Ensure that the SHA-256 hashes, in your locally-generated Manifest file, match +those in the Manifest file of the official release on the LND GitHub repository. +Tip: Download the official release Manifest file to your local maschine and do: +`diff lnd-v0.18.3-beta/manifest-v0.18.3-beta.txt ~/Downloads/manifest-v0.18.3-beta.txt` +(example command for a release candidate called `v0.18.3-beta`) +Only if all hashes are identical, should you sign the release. If the digests +match, see the example signing comand, assuming your PGP signing key is +available on your local device: +`gpg --local-user $KEYID --detach-sig --output manifest-$USERNAME-v0.18.3-beta.sig manifest-v0.18.3-beta.txt`. +`USERNAME` being the name in the `[verify-install.sh](../scripts/verify-install.sh)` +script and also the name of your PGP key file. The whole argument `--local-user $KEYID` +is only needed if there's more than one signing key on your local machine. Be +sure to substitute the TAG value `v0.18.3-beta` with the version you are +currently signing. + +* Finally, upload the signature file +(e.g. manifest-USERNAME-v0.18.3-beta.sig) to the GitHub release page. +Github write permissions are required to upload signatures to the LND release +page. To avoid interfering with other signers who may be updating the GitHub +release page, LND developers use a `KeyBase` communication channel to signal +when an edit is in progress. Once your signature file is successfully uploaded +and the release page is unlocked, the signing process is complete. + +Congratulations signing the LND release 🎉. \ No newline at end of file