Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(express): add architecture readme for lightning #5447

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

davidkaplanbitgo
Copy link
Contributor

BTC-1794

TICKET: BTC-1794

@@ -0,0 +1,84 @@
# Self-custodial Lightning

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Self-custodial Lightning
# Self-Custody Lightning

Comment on lines +3 to +7
The [lightning network](https://lightning.network/) is a L2 settlement network built on top of Bitcoin that allows you
to send funds off-chain. It allows the Bitcoin ecosystem to scale without limit while conserving much of the security
guarantees of Bitcoin, all while increasing the payment speed to much faster than waiting for a block to confirm. For
more information about lightning, [Lightning-Labs](https://docs.lightning.engineering/the-lightning-network/overview)
has a great overview. The rest of the documentation is regarding BitGo's self-custodial lightning wallet.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [lightning network](https://lightning.network/) is a L2 settlement network built on top of Bitcoin that allows you
to send funds off-chain. It allows the Bitcoin ecosystem to scale without limit while conserving much of the security
guarantees of Bitcoin, all while increasing the payment speed to much faster than waiting for a block to confirm. For
more information about lightning, [Lightning-Labs](https://docs.lightning.engineering/the-lightning-network/overview)
has a great overview. The rest of the documentation is regarding BitGo's self-custodial lightning wallet.
The [lightning network](https://lightning.network/) is an L2 settlement network built on top of the Bitcoin network that enables you to quickly send bitcoin off-chain. This enables Bitcoin to scale to smaller and more rapid transactions, while conserving many of the security guarantees provided by the Bitcoin protocol.
To learn more about lightning, see [Lightning-Labs](https://docs.lightning.engineering/the-lightning-network/overview). To learn more about self-custody lightning wallets at BitGo, continue reading here.

Comment on lines +9 to +14
BitGo has created a self-custodial lightning wallet, fully integrated into the BitGo wallet ecosystem, that allows you
to send funds over the lightning network. We leverage
[Lightning Labs's Lightning Network Daemon (LND) open-source software](https://lightning.engineering/api-docs/api/lnd/) to run the node.
We have integrated running the LND node with BitGo's Express server. For information on how to set up Express, please
refer to the [top level Express documentation](../../README.md). The rest of this documentation assumes that you have
set up an express and you can make requests to it.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
BitGo has created a self-custodial lightning wallet, fully integrated into the BitGo wallet ecosystem, that allows you
to send funds over the lightning network. We leverage
[Lightning Labs's Lightning Network Daemon (LND) open-source software](https://lightning.engineering/api-docs/api/lnd/) to run the node.
We have integrated running the LND node with BitGo's Express server. For information on how to set up Express, please
refer to the [top level Express documentation](../../README.md). The rest of this documentation assumes that you have
set up an express and you can make requests to it.
Self-custody lightning wallets at BitGo are fully integrated into the greater BitGo ecosystem, enabling you to send bitcoin over the lightning network, while leveraging other BitGo features, such as policies. BitGo's lightning node runs using [BitGo Express](https://developers.bitgo.com/guides/get-started/express/install) and [Lightning Labs's Lightning Network Daemon (LND) open-source software](https://lightning.engineering/api-docs/api/lnd/).
The rest of this documentation assumes that you set up BitGo Express and you can make requests to it.

Comment on lines +53 to +60
* `Lightning p2p network`: This is the peer-to-peer lightning network where off-chain settlements are performed. To connect
to the lightning network, we (BitGo) run a `watch-only` node that acts as the interface between the lightning network and
your wallet
* `watch-only lnd`: This is a LND node that contains no private information. It is initialized with the public keys that are
created when you generate a wallet. However, the private keys stay with you, running along side your express in the
`signer lnd node`, where they are offline except for a few very specific connections. The `watch-only lnd` node's job is to
communicate what is happening on the lightning network with BitGo and your signing node, but nothing else. It contains
no ability or permissions to move funds.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `Lightning p2p network`: This is the peer-to-peer lightning network where off-chain settlements are performed. To connect
to the lightning network, we (BitGo) run a `watch-only` node that acts as the interface between the lightning network and
your wallet
* `watch-only lnd`: This is a LND node that contains no private information. It is initialized with the public keys that are
created when you generate a wallet. However, the private keys stay with you, running along side your express in the
`signer lnd node`, where they are offline except for a few very specific connections. The `watch-only lnd` node's job is to
communicate what is happening on the lightning network with BitGo and your signing node, but nothing else. It contains
no ability or permissions to move funds.
* `Lightning p2p network`: This is the peer-to-peer lightning network that performs off-chain settlements. To connect to the lightning network, BitGo runs a `watch-only` node that acts as the interface between the lightning network and your wallet.
* `watch-only lnd`: This is an LND node that doesn't contain any private information. It initializes using the public keys that you created when you generated the wallet. Meanwhile, you manage your private keys using Express in the `signer lnd node`. Your private keys remain offline, except for a few specific connections. The `watch-only lnd` node communicates what's happening on the lightning network to BitGo and your signing node - nothing else. The `watch-only lnd` doesn't contain any ability or permissions to move bitcoin.

Comment on lines +62 to +69
The node is also connected to the bitcoin network (`bitcoind/btcd`), where the node watches for funds moving on/off the
wallet and to watch for any closing/opening of lightning channels.
* `signer lnd node`: This is the node that contains the private key information used to authorize the transfer for funds,
both on-chain and off-chain. This node is not connected to the lighting network or bitcoin directly. Instead, information
about what is happening comes from the `watch-only lnd` node. You can think of this node being the other half for the LND
node, and it is completely in the customers control. This signing node is deployed within your own infrastructure along
side of the `Express` app. Only `Express` and the `watch-only lnd` node can make connections to this application. We
separate the `watch-only` and `signer` LND nodes because:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The node is also connected to the bitcoin network (`bitcoind/btcd`), where the node watches for funds moving on/off the
wallet and to watch for any closing/opening of lightning channels.
* `signer lnd node`: This is the node that contains the private key information used to authorize the transfer for funds,
both on-chain and off-chain. This node is not connected to the lighting network or bitcoin directly. Instead, information
about what is happening comes from the `watch-only lnd` node. You can think of this node being the other half for the LND
node, and it is completely in the customers control. This signing node is deployed within your own infrastructure along
side of the `Express` app. Only `Express` and the `watch-only lnd` node can make connections to this application. We
separate the `watch-only` and `signer` LND nodes because:
The node also connects to the Bitcoin network (`bitcoind/btcd`). Here, the node watches for bitcoin moving in or out of the wallet and also watches for any lightning channels opening or closing.
* `signer lnd node`: This node contains your private key information that you use to authorize transfers, both on-chain and off-chain. This node isn't connected to the lighting network or Bitcoin directly. Instead, information about what's happening comes from the `watch-only lnd` node. The `signer lnd node` node is the other half of the LND node and is completely in your control. This signing node is deployed within your infrastructure alongside the `Express` app. Only `Express` and the `watch-only lnd` node can make connections to this application. BitGo separates the `watch-only` and `signer` LND nodes because:

Comment on lines +71 to +79
1. It is safer; the private keys are not directly online.
2. Keeps the keys in your control while delegating most of the operational complexities of running LND nodes to BitGo.
* `Express`: This is the self-hosted server that you are running that makes requests to BitGo and the `signer lnd node`.
* `BitGo Platform`: This is a server that we run to serve the requests of customers. For more information, see the
[developer documentation](https://developers.bitgo.com/guides/get-started/intro).
* `bitcoind/btcd`: This is the Bitcoin network.
* `BitGo Infrastructure`: These are services and connections that are managed by BitGo. You as a client do not need to
worry about these services
* `Client Infrastructure`: These are the services that are going to be deployed in your infrastructure.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. It is safer; the private keys are not directly online.
2. Keeps the keys in your control while delegating most of the operational complexities of running LND nodes to BitGo.
* `Express`: This is the self-hosted server that you are running that makes requests to BitGo and the `signer lnd node`.
* `BitGo Platform`: This is a server that we run to serve the requests of customers. For more information, see the
[developer documentation](https://developers.bitgo.com/guides/get-started/intro).
* `bitcoind/btcd`: This is the Bitcoin network.
* `BitGo Infrastructure`: These are services and connections that are managed by BitGo. You as a client do not need to
worry about these services
* `Client Infrastructure`: These are the services that are going to be deployed in your infrastructure.
1. It's safer, because the private keys aren't directly online.
2. It keeps the keys in your control, while delegating most of the operational complexities of running LND nodes to BitGo.
* `Express`: This is the self-hosted server that you run and use to make requests to BitGo and the `signer lnd node`.
* `BitGo Platform`: This is a server that BitGo runs to serve your requests. For more information, see the
[Introduction to BitGo](https://developers.bitgo.com/guides/get-started/intro) on the [Developer Portal](https://developers.bitgo.com/).
* `bitcoind/btcd`: This is the Bitcoin network.
* `BitGo Infrastructure`: These are services and connections that BitGo manages. You don't need to manage these services.
* `Client Infrastructure`: These are the services that deploy in your infrastructure.

Comment on lines +81 to +84
We have built our self-custodial lightning product to:

1. maximize the control of the signer lnd node while keeping it offline
2. minimize the control of the watch-only lnd

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We have built our self-custodial lightning product to:
1. maximize the control of the signer lnd node while keeping it offline
2. minimize the control of the watch-only lnd
BitGo built self-custody lightning wallets to:
1. Maximize your control of the signer LND node while keeping it offline.
2. Minimize your control of the watch-only LND node.

Confirm this is still accurate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants