CHANGELOG, documentation: update changelog to reflect suffix changes.

Signed-off-by: Rusty Russell <[email protected]>

CHANGELOG.md

@@ -13,6 +13,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - plugins: `pay` is now a plugin.
 - protocol: `pay` will now use routehints in invoices if it needs to.
 - lightning-cli: `help <cmd>` finds man pages even if `make install` not run.
+- JSON API: `getroute`, `invoice`, `sendpay` and `pay` commands `msatoshi`
+  parameter can have suffixes `msat`, `sat` (optionally with 3 decimals) or `btc`
+  (with 8 or 11 decimals).
+- JSON API: `fundchannel` and `withdraw` commands `satoshi`
+  parameter can have suffixes `msat` (must end in `000`), `sat` or `btc`
+  (with 8 decimals).
+- JSON API: `decodepay`, `getroute`, `sendpay`, `pay`, `listpeers`, `listfunds`, `listchannels` and
+  all invoice commands now return an `amount_msat` field which has an `msat` suffix.
+- JSON API: `listfunds` `channels` now has `_msat` fields for each existing raw amount field, with `msat` suffix.
 - JSON API: `waitsendpay` now has an `erring_direction` field.
 - JSON API: `listpeers` now has a `direction` field in `channels`.
 - JSON API: `listchannels` now takes a `source` option to filter by node id.
@@ -32,6 +41,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Note: You should always set `allow-deprecated-apis=false` to test for
 changes.
 
+We recommend that you transition to the reading the new JSON `_msat`
+fields for your own sanity checking, and that you similarly
+provide appropriate suffixes for JSON input fields.
+
 - JSON API: `short_channel_id` fields in JSON commands with `:` separators (use `x` instead).
 
 ### Removed

doc/lightning-decodepay.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-decodepay
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 04/26/2018
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-DECODEPAY" "7" "04/26/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-DECODEPAY" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -138,6 +138,19 @@ The following fields are optional:
 .sp -1
 .IP \(bu 2.3
 .\}
+\fIamount_msat\fR: the same as above, with
+\fImsat\fR
+appended (if any)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 \fIfallbacks\fR: array of fallback address object containing a
 \fIhex\fR
 string, and both

doc/lightning-decodepay.7.txt

@@ -33,6 +33,7 @@ by BOLT11:
 The following fields are optional:
 
 - 'msatoshi': the number of millisatoshi requested (if any).
+- 'amount_msat': the same as above, with 'msat' appended (if any).
 - 'fallbacks': array of fallback address object containing a 'hex' string, and
   both 'type' and 'addr' if it is recognized as one of 'P2PKH', 'P2SH', 'P2WPKH', or 'P2WSH'.
 - 'routes':  an array of routes.  Each route is an arrays of objects, each containing 'pubkey', 'short_channel_id', 'fee_base_msat', 'fee_proportional_millionths' and 'cltv_expiry_delta'.

doc/lightning-fundchannel.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-fundchannel
 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 02/15/2019
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-FUNDCHANN" "7" "02/15/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-FUNDCHANN" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -38,7 +38,7 @@ The \fBfundchannel\fR RPC command opens a payment channel with a peer by committ
 .sp
 \fIid\fR is the peer id obtained from \fBconnect\fR\&.
 .sp
-\fIsatoshi\fR is the amount in satoshis taken from the internal wallet to fund the channel\&. The string \fIall\fR can be used to specify all available funds (or 16777215 satoshi if more is available)\&. The value cannot be less than the dust limit, currently set to 546, nor more than 16777215 satoshi\&.
+\fIsatoshi\fR is the amount in satoshis taken from the internal wallet to fund the channel\&. The string \fIall\fR can be used to specify all available funds (or 16777215 satoshi if more is available)\&. Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in \fIsat\fR, a whole number ending in \fI000msat\fR, or a number with 8 decimal places ending in \fIbtc\fR\&. The value cannot be less than the dust limit, currently set to 546, nor more than 16777215 satoshi\&.
 .sp
 \fIfeerate\fR is an optional feerate used for the opening transaction and as initial feerate for commitment and HTLC transactions\&. It can be one of the strings \fIurgent\fR, \fInormal\fR or \fIslow\fR to use lightningd\(cqs internal estimates: \fInormal\fR is the default\&.
 .sp

doc/lightning-fundchannel.7.txt

@@ -24,6 +24,7 @@ for the channel.
 
 'satoshi' is the amount in satoshis taken from the internal wallet to fund the channel.
 The string 'all' can be used to specify all available funds (or 16777215 satoshi if more is available).
+Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in 'sat', a whole number ending in '000msat', or a number with 8 decimal places ending in 'btc'.
 The value cannot be less than the dust limit, currently set to 546, nor more
 than 16777215 satoshi.
 

doc/lightning-getroute.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-getroute
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 02/16/2019
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-GETROUTE" "7" "02/16/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-GETROUTE" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -36,6 +36,8 @@ lightning-getroute \- Command for routing a payment (low\-level)\&.
 .sp
 The \fBgetroute\fR RPC command attempts to find the best route for the payment of \fImsatoshi\fR to lightning node \fIid\fR, such that the payment will arrive at \fIid\fR with \fIcltv\fR\-blocks to spare (default 9)\&.
 .sp
+\fImsatoshi\fR is in millisatoshi precision; it can be a whole number, or a whole number ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending in \fIsat\fR, or a number with 8 or 11 decimal places ending in \fIbtc\fR\&.
+.sp
 There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck in a delayed output if a node goes down during the process\&. The \fIriskfactor\fR floating\-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage)\&.
 .sp
 For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, \fIriskfactor\fR would be 20\&.
@@ -512,7 +514,7 @@ The default \fIfuzz\fR factor is 5%, so as you can see from the table above, tha
 The default for lightning\-pay(7) is 10, which starts to become a major factor for larger amounts, and is basically ignored for tiny ones\&.
 .SH "RETURN VALUE"
 .sp
-On success, a "route" array is returned\&. Each array element contains \fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis sent), and \fIdelay\fR (the number of blocks to timeout at this node)\&.
+On success, a "route" array is returned\&. Each array element contains \fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis sent), \fIamount_msat\fR (the same, with \fImsat\fR appended), and \fIdelay\fR (the number of blocks to timeout at this node)\&.
 .sp
 The final \fIid\fR will be the destination \fIid\fR given in the input\&. The difference between the first \fImsatoshi\fR minus the \fImsatoshi\fR given in the input is the fee\&. The first \fIdelay\fR is the very worst case timeout for the payment failure, in blocks\&.
 .SH "AUTHOR"

doc/lightning-getroute.7.txt

@@ -17,6 +17,11 @@ The *getroute* RPC command attempts to find the best route for the payment
 of 'msatoshi' to lightning node 'id', such that the payment will arrive
 at 'id' with 'cltv'-blocks to spare (default 9).
 
+'msatoshi' is in millisatoshi precision; it can be a whole number, or
+a whole number ending in 'msat' or 'sat', or a number with three
+decimal places ending in 'sat', or a number with 8 or 11 decimal
+places ending in 'btc'.
+
 There are two considerations for how good a route is: how low the
 fees are, and how long your payment will get stuck in a delayed output if a node goes down
 during the process.  The 'riskfactor' floating-point field controls
@@ -113,7 +118,7 @@ RETURN VALUE
 
 On success, a "route" array is returned.
 Each array element contains 'id' (the node being routed through), 'msatoshi'
-(the millisatoshis sent), and 'delay' (the number of blocks to timeout at this
+(the millisatoshis sent), 'amount_msat' (the same, with 'msat' appended), and 'delay' (the number of blocks to timeout at this
 node).
 
 The final 'id' will be the destination 'id' given in the input.  The

doc/lightning-invoice.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-invoice
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 12/17/2018
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-INVOICE" "7" "12/17/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-INVOICE" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -36,7 +36,7 @@ lightning-invoice \- Command for accepting payments\&.
 .sp
 The \fBinvoice\fR RPC command creates the expectation of a payment of a given amount of milli\-satoshi: it returns a unique token which another lightning daemon can use to pay this invoice\&. This token includes a \fIroute hint\fR description of an incoming channel with capacity to pay the invoice, if any exists\&.
 .sp
-The \fImsatoshi\fR can be the string "any", which creates an invoice that can be paid with any amount\&.
+The \fImsatoshi\fR parameter can be the string "any", which creates an invoice that can be paid with any amount\&. Otherwise it is in millisatoshi precision; it can be a whole number, or a whole number ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending in \fIsat\fR, or a number with 8 or 11 decimal places ending in \fIbtc\fR\&.
 .sp
 The \fIlabel\fR must be a unique string or number (which is treated as a string, so "01" is different from "1"); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice\&.
 .sp
@@ -48,7 +48,7 @@ The \fIfallbacks\fR array is one or more fallback addresses to include in the in
 .sp
 The \fIpreimage\fR is a 64\-digit hex string to be used as payment preimage for the created invoice\&. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system\&. \fBIMPORTANT\fR: if you specify the \fIpreimage\fR, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret\&. This parameter is an advanced feature intended for use with cutting\-edge cryptographic protocols and should not be used unless explicitly needed\&.
 .sp
-The \fIexposeprivatechannels\fR includes unpublished channels in the selection of channels for the route hint; by default they are excluded\&.
+If specified, \fIexposeprivatechannels\fR overrides the default route hint logic, which will use unpublished channels only if there are no published channels\&. If \fItrue\fR unpublished channels are always considered as a route hint candidate; if \fIfalse\fR, never\&.
 .SH "RETURN VALUE"
 .sp
 On success, a hash is returned as \fIpayment_hash\fR to be given to the payer, and the \fIexpiry_time\fR as a UNIX timestamp\&. It also returns a BOLT11 invoice as \fIbolt11\fR to be given to the payer\&.

doc/lightning-invoice.7.txt

@@ -18,8 +18,11 @@ lightning daemon can use to pay this invoice.  This token includes a
 'route hint' description of an incoming channel with capacity to pay
 the invoice, if any exists.
 
-The 'msatoshi' can be the string "any", which creates an invoice
-that can be paid with any amount.
+The 'msatoshi' parameter can be the string "any", which creates an invoice
+that can be paid with any amount.  Otherwise it is in millisatoshi
+precision; it can be a whole number, or a whole number ending in 'msat' or
+'sat', or a number with three decimal places ending in 'sat', or a number
+with 8 or 11 decimal places ending in 'btc'.
 
 The 'label' must be a unique string or number (which is treated as a
 string, so "01" is different from "1"); it is never revealed to other

doc/lightning-listchannels.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-listchannels
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 01/09/2019
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-LISTCHANN" "7" "01/09/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-LISTCHANN" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -115,6 +115,19 @@ Each object in the list contains the following data:
 .sp -1
 .IP \(bu 2.3
 .\}
+\fIamount_sat\fR
+: Same as above, but ending in
+\fIsat\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 \fImessage_flags\fR
 : Bitfield showing the presence of optional fields in the
 \fIchannel_update\fR

doc/lightning-listchannels.7.txt

@@ -42,6 +42,7 @@ ever have this value set to true.  Local channels are side-loaded by this node,
 rather than obtained through the gossip network, and so may have this value set
 to false.
 - 'satoshis' : Funds available in the channel.
+- 'amount_sat' : Same as above, but ending in 'sat'.
 - 'message_flags' : Bitfield showing the presence of optional fields in the
 'channel_update' message (BOLT #7).
 - 'channel_flags' : Bitfields indicating the direction of the channel and

doc/lightning-listfunds.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-listfunds
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 09/18/2018
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-LISTFUNDS" "7" "09/18/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-LISTFUNDS" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -93,6 +93,22 @@ Each entry in \fIoutputs\fR will include:
 .sp -1
 .IP \(bu 2.3
 .\}
+\fIamount_sat\fR
+(the same as
+\fIvalue\fR
+with
+\fIsat\fR
+appended)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 \fIstatus\fR
 .RE
 .sp
@@ -131,7 +147,21 @@ Each entry in \fIchannels\fR will include:
 .IP \(bu 2.3
 .\}
 \fIchannel_sat\fR
-\- available satoshis on our node\(cqs end of the channel (values rounded to the nearest satoshi as internal storage is in millisatoshi)\&.
+\- available satoshis on our node\(cqs end of the channel (values rounded down to satoshis as internal storage is in millisatoshi)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIour_amount_sat\fR
+\- same as above, but with
+\fIsat\fR
+appended\&.
 .RE
 .sp
 .RS 4
@@ -143,7 +173,21 @@ Each entry in \fIchannels\fR will include:
 .IP \(bu 2.3
 .\}
 \fIchannel_total_sat\fR
-\- total channel value in satoshi (values rounded to the nearest satoshi as internal storage is in millisatoshi)\&.
+\- total channel value in satoshi
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIamount_sat\fR
+\- same as above, but with
+\fIsat\fR
+appended\&.
 .RE
 .sp
 .RS 4

doc/lightning-listfunds.7.txt

@@ -33,6 +33,8 @@ Each entry in 'outputs' will include:
 
 - 'value'
 
+- 'amount_sat' (the same as 'value' with 'sat' appended)
+
 - 'status'
 
 Each entry in 'channels' will include: 
@@ -43,10 +45,13 @@ Each entry in 'channels' will include:
 number and output index of the channel funding transaction).
 
 - 'channel_sat' - available satoshis on our node's end of the channel 
-(values rounded to the nearest satoshi as internal storage is in millisatoshi).
+(values rounded down to satoshis as internal storage is in millisatoshi).
+
+- 'our_amount_sat' - same as above, but with 'sat' appended.
 
 - 'channel_total_sat' - total channel value in satoshi 
-(values rounded to the nearest satoshi as internal storage is in millisatoshi). 
+
+- 'amount_sat' - same as above, but with 'sat' appended.
 
 - 'funding_txid' - funding transaction id.
 

doc/lightning-listinvoices.7

@@ -2,12 +2,12 @@
 .\"     Title: lightning-listinvoices
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 08/27/2018
+.\"      Date: 02/18/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-LISTINVOI" "7" "08/27/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-LISTINVOI" "7" "02/18/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -37,7 +37,7 @@ lightning-listinvoices \- Command for querying invoice status
 The \fBlistinvoices\fR RPC command gets the status of a specific invoice, if it exists, or the status of all invoices if given no argument\&.
 .SH "RETURN VALUE"
 .sp
-On success, an array \fIinvoices\fR of objects is returned\&. Each object contains \fIlabel\fR, \fIpayment_hash\fR, \fIstatus\fR (one of \fIunpaid\fR, \fIpaid\fR or \fIexpired\fR), and \fIexpiry_time\fR (a UNIX timestamp)\&. If the \fImsatoshi\fR argument to lightning\-invoice(7) was not "any", there will be an \fImsatoshi\fR field\&. If the invoice \fIstatus\fR is \fIpaid\fR, there will be a \fIpay_index\fR field and an \fImsatoshi_received\fR field (which may be slightly greater than \fImsatoshi\fR as some overpaying is permitted to allow clients to obscure payment paths)\&.
+On success, an array \fIinvoices\fR of objects is returned\&. Each object contains \fIlabel\fR, \fIpayment_hash\fR, \fIstatus\fR (one of \fIunpaid\fR, \fIpaid\fR or \fIexpired\fR), and \fIexpiry_time\fR (a UNIX timestamp)\&. If the \fImsatoshi\fR argument to lightning\-invoice(7) was not "any", there will be an \fImsatoshi\fR field as a number, and \fIamount_msat\fR as the same number ending in \fImsat\fR\&. If the invoice \fIstatus\fR is \fIpaid\fR, there will be a \fIpay_index\fR field and an \fImsatoshi_received\fR field (which may be slightly greater than \fImsatoshi\fR as some overpaying is permitted to allow clients to obscure payment paths); there will also be an \fIamount_received_msat\fR field with the same number as \fImsatoshi_received\fR but ending in \fImsat\fR\&.
 .SH "AUTHOR"
 .sp
 Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.