mirror of
https://github.com/ChristopherA/Learning-Bitcoin-from-the-Command-Line.git
synced 2025-06-07 16:06:26 +00:00
first cut of revised section
pulled in "understanding/reading" content from 19.2
This commit is contained in:
Shannon Appelcline
GitHub
parent
dc8745087f
commit
4ec7631dea
@ -1,63 +1,129 @@
|
|||||||
|
|
||||||
# 19.1: Generate a Payment request.
|
# 19.1: Generating a Payment Request
|
||||||
|
|
||||||
> :information_source: **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.
|
> :information_source: **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.
|
||||||
|
|
||||||
This chapter shows what is and how to create a payment request. We will explain briefly how works payments on the Lightning Network.
|
This section describes how payments work on the Lightning Network, and how to create a payment request, or _invoice_. It depends on your having a second Lightning node, as described in [Accessing a Second Lightning Node](18_2__Interlude_Accessing_a_Second_Lightning_Node.md). These examples will use an LND node as its secondary node, to further demonstrate the possibilities of the Lightning Network. To differentiate between the nodes in these examples, the prompts will be shown as `c$` for the c-lightning node and `lnd$` as the LND node. If you want to reproduce this steps you should [install your own secondary LND node](18_2__Interlude_Accessing_a_Second_Lightning_Node.md#creating-a-new-lnd-node).
|
||||||
For this example we've created a second lightning node using LND implementation to create an invoice to be payed later using our main c-lighting installation in next chapter. We will refer to this instance using `lnd$ ` prompt shell to indicate place where we'll generate LND commands. If you want to reproduce this steps you should use Bitcoin Standup to create a second machine and install LND.
|
|
||||||
|
|
||||||
> :book: ***What is an invoice
|
> :book: ***What is an Invoice?** Almost all payments made on the Lightning Network require an invoice, which is nothing more than a **request for payment** made by the recipient of the money and sent by variety of means to the paying user. All payment requests are single use. Lightning invoices use bech32 encoding, which is already used by Segregated Witness for Bitcoin.
|
||||||
|
|
||||||
Almost all payments made on the Lightning Network require an invoice, which is nothing more than a **request for payment** made by the recipient of the money and sent by different means to the user who will pay. The format for a Lightning invoice uses bech32 encoding, which is already used for Bitcoin Segregated Witness and all payment requests are single use.
|
## Creating an Invoice
|
||||||
|
|
||||||
An invoice is made up of two parts, one is human readable and other is data part.
|
To create a new invoice on c-lightning you should use the `lightning-cli --network=testnet invoice` command.
|
||||||
|
|
||||||
- Human readable part: `ln` + (`lnbc` for Bitcoin mainnet, `lntb` for Bitcoin testnet, and `lnbcrt` for Bitcoin regtest) + data amount
|
Here's how it would work with c-lightning, using arguments of an amount (in msatoshis), a label, and a description.
|
||||||
|
```
|
||||||
|
c$ lightning-cli --network=testnet invoice 100000 joe-payment "The money you owe me for dinner"
|
||||||
|
{
|
||||||
|
"payment_hash": "07a1c4bd7a38b4dea35f301c173cd8f9aac253b66bd8404d7ad829f226342490",
|
||||||
|
"expires_at": 1603305795,
|
||||||
|
"bolt11": "lntb1u1p0cw3krpp5q7suf0t68z6dag6lxqwpw0xclx4vy5akd0vyqnt6mq5lyf35yjgqdpj235x2grddahx27fq09hh2gr0wajjqmt9ypnx7u3qv35kumn9wgxqyjw5qcqp2sp5r3puay46tffdyzldjv39fw6tzdgu2hnlszamqhnmgjsuxqxavpgs9qy9qsqatawvx44x5qa22m7td84jau5450v7j6sl5224tlv9k5v7wdygq9qr4drz795lfnl52gklvyvnha5e5lx72lzzmgzcfnp942va5thmhsp5sx7c2",
|
||||||
|
"warning_capacity": "No channels",
|
||||||
|
"warning_mpp_capacity": "The total incoming capacity is still insufficient even if the payer had MPP capability."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
However, for this example we're going to instead generate an invoice on an LND node, and then pay it on the c-lightning node. This requires the slightly different `addinvoice` commend. You can use `--amt` argument to indicate amount to be payed and add a description using the `--memo` argument.
|
||||||
|
|
||||||
- Data part : UNIX Timestamp + tagged parts include a payment hash, the pubkey of the payee node, an optional description of the payment, an expiration time, and some extra routing information.
|
```
|
||||||
|
lnd$ lncli -n testnet addinvoice --amt 10000 --memo "First LN Payment - Learning Bitcoin and Lightning from the Command line."
|
||||||
|
{
|
||||||
|
"r_hash": "6cacdedc95b89eec15e5244bd0957b88c0ab58b153eee549735b995344bc16bb",
|
||||||
|
"payment_request": "lntb100u1p0cwnqtpp5djkdahy4hz0wc909y39ap9tm3rq2kk9320hw2jtntwv4x39uz6asdr5ge5hyum5ypxyugzsv9uk6etwwssz6gzvv4shymnfdenjqsnfw33k76twypskuepqf35kw6r5de5kueeqveex7mfqw35x2gzrdakk6ctwvssxc6twv5hqcqzpgsp5a9ryqw7t23myn9psd36ra5alzvp6lzhxua58609teslwqmdljpxs9qy9qsq9ee7h500jazef6c306psr0ncru469zgyr2m2h32c6ser28vrvh5j4q23c073xsvmjwgv9wtk2q7j6pj09fn53v2vkrdkgsjv7njh9aqqtjn3vd",
|
||||||
|
"add_index": "1"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Note that these invoices don't directly reference the channel you create: it's necessary for paying, but not for requesting payment.
|
||||||
|
|
||||||
1. Destination: The public key of the person receiving the LN payment.
|
## Detailing an Invoice
|
||||||
2. payment_hash: The hash of the preimage that is used to lock the payment. You can only redeem a locked payment with the corresponding preimage to the payment hash. This enables routing on the Lightning Network without trusted third parties creating a conditional payment to be filled.
|
|
||||||
3. num_satoshis: The amount of satoshis to be paid.
|
|
||||||
4. expiry: Time when your node marks the invoice as invalid. Default is 1 hour or 3600 seconds.
|
|
||||||
5. timestamp: Time when the invoice was created. This is measured in seconds since 1970.
|
|
||||||
6. cltv_expiry: Delta to use for time-lock of CLTV extended to the final hop.
|
|
||||||
|
|
||||||
> :book: ***Conditional payments.
|
The `bolt11` `payment_request` that you created is made up of two parts: one is human readable and the other is data.
|
||||||
|
|
||||||
As we said in Setting a channel chapter and although the channels are created between two participants, the channels can be connected to each other forming a payment network to allow payments between all the network participants without having a direct channel between them using an smart contract called **Hashed Time Locked Contract**.
|
### Reading the Human-Readable Invoice Part
|
||||||
|
|
||||||
> :book: ***Hashed Time Locked Contract.
|
The human readable part of your invoices starts with an `ln`. It is `lnbc` for Bitcoin mainnet, `lntb` for Bitcoin testnet, or `lnbcrt` for Bitcoin regtest).
|
||||||
|
It then lists the funds requested in the invoice.
|
||||||
|
|
||||||
A Hashed Time Locked Contract is a conditional payment that use hashlocks and timelocks to ensure payment security. This means that receiver must presents a payment preimage or generate a cryptographic proof of payment before a given time otherwise the payer can cancel the contract by spending it. This contracts are created as outputs from the Commitment transaction.
|
For example, look at your invoice from LND:
|
||||||
|
```
|
||||||
|
lntb100u1p0cwnqtpp5djkdahy4hz0wc909y39ap9tm3rq2kk9320hw2jtntwv4x39uz6asdr5ge5hyum5ypxyugzsv9uk6etwwssz6gzvv4shymnfdenjqsnfw33k76twypskuepqf35kw6r5de5kueeqveex7mfqw35x2gzrdakk6ctwvssxc6twv5hqcqzpgsp5a9ryqw7t23myn9psd36ra5alzvp6lzhxua58609teslwqmdljpxs9qy9qsq9ee7h500jazef6c306psr0ncru469zgyr2m2h32c6ser28vrvh5j4q23c073xsvmjwgv9wtk2q7j6pj09fn53v2vkrdkgsjv7njh9aqqtjn3vd
|
||||||
|
```
|
||||||
|
The human readable part is `ln+tb+100u`.
|
||||||
|
|
||||||
> :book: ***Commitment transaction.
|
`lntb` says that this is a Lightning Network invoice on Testnet.
|
||||||
|
|
||||||
Commitment transaction is a transaction that spends the funding transaction. Each peer holds the other peer's signature meaning that either one can spent his commitment transaction whatever he wants. After each new commitment transaction is created the old one is revoked.
|
`1m` says that it is for 100 bitcoin times the microsatoshi multiplier. There are four (optional) funds multipliers:
|
||||||
|
|
||||||
### Node information
|
* `m` (milli): multiply by 0.001
|
||||||
|
* `u` (micro): multiply by 0.000001
|
||||||
|
* `n` (nano): multiply by 0.000000001
|
||||||
|
* `p` (pico): multiply by 0.000000000001
|
||||||
|
|
||||||
In this second instance that we refer before you may get information about it using `lnd$lncli -n testnet getinfo` command. Remember identity_pubkey field, due it will be the same value when you pay the invoice.
|
100 BTC * .000001 = .0001 BTC, which is the same as 10,000 satoshis.
|
||||||
|
|
||||||
**"identity_pubkey": "0302d48972ba7eef8b40696102ad114090fd4c146e381f18c7932a2a1d73566f84"**
|
### Reading the Data Invoice Part
|
||||||
|
|
||||||
> :warning: **WARNING:** Notice this example is using an LND instance, if you want to reproduce this steps you should use Bitcoin Standup Script and install a new LND instance.
|
The rest of the invoice (`1p0cwnqtpp5djkdahy4hz0wc909y39ap9tm3rq2kk9320hw2jtntwv4x39uz6asdr5ge5hyum5ypxyugzsv9uk6etwwssz6gzvv4shymnfdenjqsnfw33k76twypskuepqf35kw6r5de5kueeqveex7mfqw35x2gzrdakk6ctwvssxc6twv5hqcqzpgsp5a9ryqw7t23myn9psd36ra5alzvp6lzhxua58609teslwqmdljpxs9qy9qsq9ee7h500jazef6c306psr0ncru469zgyr2m2h32c6ser28vrvh5j4q23c073xsvmjwgv9wtk2q7j6pj09fn53v2vkrdkgsjv7njh9aqqtjn3vd`) contains a timestamp, specifically tagged data, and a signature. You obviously can't read it yourself, but you can ask `lightning-cli` to do so with the `decodepay` command on c-lightning:
|
||||||
|
|
||||||
|
```
|
||||||
|
c$ lightning-cli --network=testnet decodepay lntb100u1p0cwnqtpp5djkdahy4hz0wc909y39ap9tm3rq2kk9320hw2jtntwv4x39uz6asdr5ge5hyum5ypxyugzsv9uk6etwwssz6gzvv4shymnfdenjqsnfw33k76twypskuepqf35kw6r5de5kueeqveex7mfqw35x2gzrdakk6ctwvssxc6twv5hqcqzpgsp5a9ryqw7t23myn9psd36ra5alzvp6lzhxua58609teslwqmdljpxs9qy9qsq9ee7h500jazef6c306psr0ncru469zgyr2m2h32c6ser28vrvh5j4q23c073xsvmjwgv9wtk2q7j6pj09fn53v2vkrdkgsjv7njh9aqqtjn3vd
|
||||||
|
{
|
||||||
|
"currency": "tb",
|
||||||
|
"created_at": 1602702347,
|
||||||
|
"expiry": 3600,
|
||||||
|
"payee": "032a7572dc013b6382cde391d79f292ced27305aa4162ec3906279fc4334602543",
|
||||||
|
"msatoshi": 10000000,
|
||||||
|
"amount_msat": "10000000msat",
|
||||||
|
"description": "First LN Payment - Learning Bitcoin and Lightning from the Command line.",
|
||||||
|
"min_final_cltv_expiry": 40,
|
||||||
|
"payment_secret": "e946403bcb54764994306c743ed3bf1303af8ae6e7687d3cabcc3ee06dbf904d",
|
||||||
|
"features": "028200",
|
||||||
|
"payment_hash": "6cacdedc95b89eec15e5244bd0957b88c0ab58b153eee549735b995344bc16bb",
|
||||||
|
"signature": "304402202e73ebd1ef974594eb117e8301be781f2ba289041ab6abc558d432351d8365e902202a8151c3fd13419b9390c2b976503d2d064f2a6748b14cb0db64424cf4e572f4"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
Here's what most of those elements mean:
|
||||||
|
|
||||||
|
1. `currency`: The currency being paid.
|
||||||
|
1. `created_at`: Time when the invoice was created. This is measured in seconds since 1970.
|
||||||
|
1. `expiry`: The time when your node marks the invoice as invalid. Default is 1 hour or 3600 seconds.
|
||||||
|
1. `payee`: The public key of the person receiving the Lightning Network payment.
|
||||||
|
1. `msatoshi` and `amount_msat`: The amount of satoshis to be paid.
|
||||||
|
1. `description`: The user-input description.
|
||||||
|
1. `min_final_cltv_expiry`: Delta to use for time-lock of CLTV, extended to the final hop.
|
||||||
|
1. `payment_hash`: The hash of the preimage that is used to lock the payment. You can only redeem a locked payment with the corresponding preimage to the payment hash. This enables routing on the Lightning Network without trusteing third parties by creating a **Conditional Payment** to be filled.
|
||||||
|
1. `signature`: The DER-encoded signature.
|
||||||
|
|
||||||
|
> :book: ****What are Conditional Payments?*** Although Lightning Channels are created between two participants, multiple channels can be connected together, forming a payment network that allows payments between all the network participants, even those without a direct channel between them. This is done using an smart contract called a **Hashed Time Locked Contract**.
|
||||||
|
|
||||||
|
> :book: ***What is a Hashed Time Locked Contract (HTLC)?*** A Hashed Time Locked Contract is a conditional payment that use hashlocks and timelocks to ensure payment security. The receiver must present a payment preimage or generate a cryptographic proof of payment before a given time, otherwise the payer can cancel the contract by spending it. These contracts are created as outputs from the **Commitment Transaction**.
|
||||||
|
|
||||||
|
> :book: ***What is a Commitment Transaction?*** A Commitment Transaction is a transaction that spends the funding transaction. Each peer holds the other peer's signature, meaning that either one can spent his commitment transaction whatever he wants. After each new commitment transaction is created the old one is revoked.
|
||||||
|
|
||||||
|
### Checking Your Invoice
|
||||||
|
|
||||||
|
There are two crucial elements to check in the invoice. The first, obviously, is the payment amount. The second is the `payee` value, which is the pubkey of the recipient:
|
||||||
|
```
|
||||||
|
"payee": "032a7572dc013b6382cde391d79f292ced27305aa4162ec3906279fc4334602543",
|
||||||
|
```
|
||||||
|
You need to check that's the expected recipient.
|
||||||
|
|
||||||
|
Looking back at [§18.3](18_3_Setting_Up_a_Channel.md#opening-a-channel), you can see that's indeed the peer ID that you used when you created your channel. You could also verify it on the opposite node with the `getinfo` command.
|
||||||
```
|
```
|
||||||
lnd$ lncli -n testnet getinfo
|
lnd$ lncli -n testnet getinfo
|
||||||
{
|
{
|
||||||
"version": "0.10.99-beta commit=clock/v1.0.0-171-g8cb1276dbf0bfd9fcbf599df87a43238e599eaac",
|
"version": "0.11.0-beta.rc4 commit=v0.11.0-beta.rc4",
|
||||||
"commit_hash": "8cb1276dbf0bfd9fcbf599df87a43238e599eaac",
|
"commit_hash": "fc12656a1a62e5d69430bba6e4feb8cfbaf21542",
|
||||||
"identity_pubkey": "0302d48972ba7eef8b40696102ad114090fd4c146e381f18c7932a2a1d73566f84",
|
"identity_pubkey": "032a7572dc013b6382cde391d79f292ced27305aa4162ec3906279fc4334602543",
|
||||||
"alias": "0302d48972ba7eef8b40",
|
"alias": "StandUp",
|
||||||
"color": "#3399ff",
|
"color": "#3399ff",
|
||||||
"num_pending_channels": 0,
|
"num_pending_channels": 0,
|
||||||
"num_active_channels": 1,
|
"num_active_channels": 1,
|
||||||
"num_inactive_channels": 0,
|
"num_inactive_channels": 0,
|
||||||
"num_peers": 3,
|
"num_peers": 3,
|
||||||
"block_height": 1781444,
|
"block_height": 1862983,
|
||||||
"block_hash": "0000000018655b27a1801e976c800be99c6f42c9bfcf122695a7ef5c0fa12e73",
|
"block_hash": "00000000000000c8c2f58f6da2ae2a3884d6e84f55d0e1f585a366f9dfcaa860",
|
||||||
"best_header_timestamp": "1595509101",
|
"best_header_timestamp": "1602702331",
|
||||||
"synced_to_chain": true,
|
"synced_to_chain": true,
|
||||||
"synced_to_graph": true,
|
"synced_to_graph": true,
|
||||||
"testnet": true,
|
"testnet": true,
|
||||||
@ -68,7 +134,6 @@ lnd$ lncli -n testnet getinfo
|
|||||||
}
|
}
|
||||||
],
|
],
|
||||||
"uris": [
|
"uris": [
|
||||||
"0302d48972ba7eef8b40696102ad114090fd4c146e381f18c7932a2a1d73566f84@192.168.0.22:9736"
|
|
||||||
],
|
],
|
||||||
"features": {
|
"features": {
|
||||||
"0": {
|
"0": {
|
||||||
@ -110,39 +175,13 @@ lnd$ lncli -n testnet getinfo
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Generate a Payment request.
|
## Summary: Generating a Payment Request
|
||||||
|
|
||||||
To create a new invoice on c-lightning you should use invoice `lightning-cli --network=testnet invoice` command.
|
In most cases you need to receive an invoice to use Lightning Network payments. In this example we've created one manually, but if you had a production environment, you'd likely have systems automatically doing this whenever someone purchases products or services. Of course, once you've received an invoice, you need to understand how to read it!
|
||||||
It receives amount expresed on milisatoshis and description invoices texts.
|
|
||||||
|
|
||||||
```
|
|
||||||
c$ lightning-cli --network=testnet invoice 100000 test22 test22
|
|
||||||
{
|
|
||||||
"payment_hash": "743487bca87bb39a8f07314864e80d02f7686d97693ada32c69ee3a5e06132f7",
|
|
||||||
"expires_at": 1600684714,
|
|
||||||
"bolt11": "lntb1u1p047jp2pp5ws6g009g0wee4rc8x9yxf6qdqtmksmvhdyad5vkxnm36tcrpxtmsdq2w3jhxapjxgxqyjw5qcqp2sp5s3pyvvknhnaej6ukssvxlwc4sdqpcc2prrwue8jreke587ms68qq9qy9qsqhf5uhxk0mfw3sl87ukx8e5d757pkla6zlyu07p0wc666juzm5unhlaxeqmnl8f7v7vs3wz2thme9szs3f7whzr9uewz0kexqkl9jxgsq5r752l",
|
|
||||||
"warning_offline": "No channel with a peer that is currently connected has sufficient incoming capacity"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
For this example we'll create a payment request using `lnd$lncli -n testnet addinvoice` command. You can use --amt argument to indicate amount to be payed and add a description using --memo argument.
|
|
||||||
|
|
||||||
```
|
|
||||||
lnd$ lncli -n testnet addinvoice --amt 100000 --memo "First LN Payment - Learning Bitcoin and Lightning from the Command line."
|
|
||||||
{
|
|
||||||
"r_hash": "72fbf5c2baadc780b17a27d983bd685f7d6ddf682b028c6dc13a50976e9e6e6c",
|
|
||||||
"payment_request": "lntb1m1p03ft7lpp5zve4dsgwgdxekqqq39vhgcnv6gfa2g2ktqy9lf0aph60d0388xmqdqqcqzpgsp545a9fphd8m5ayplcu8m5845cr4m0zcnyxddwv4g3zm32yprkfd4q9qy9qsq3s4y6cmyvh0qw9qm0sf80llxyyjy9xwrjds7lpkqhzv247jsm6q5me8t9e6ftquma664gz5u4a2rvs0yf4f0mlwtwfs6as5uj5djzhcqpnqlcj",
|
|
||||||
"add_index": "1"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Summary: Generating a Payment request.
|
|
||||||
|
|
||||||
In most cases you need to receive an invoice to use Lightning Network payments. In this example we've created on manually but in real cases you can buy products and services that will generate a respective invoice for it.
|
|
||||||
|
|
||||||
## What's Next?
|
## What's Next?
|
||||||
|
|
||||||
Continue "Understanding Your Lightning Setup" with [§19.2: Paying_a_Invoice](19_2_Paying_a_Invoice.md).
|
Continue "Using Lightning" with [§19.2: Paying_a_Invoice](19_2_Paying_a_Invoice.md).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user