doc: adds manpage and changelog

CHANGELOG.md

@@ -59,6 +59,7 @@ This release named by Mark Beckwith @wythe.
 - JSON API: `listpayments` is now `listsendpays`.
 - lightning-cli: `help <cmd>` finds man pages even if `make install` not run.
 - pylightning: New class 'Millisatoshi' can be used for JSON API, and new '_msat' fields are turned into this on reading.
+- JSON API: New command `setchannelfee` sets channel specific routing fees.
 
 ### Changed
 

doc/Makefile

@@ -26,6 +26,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-newaddr.7 \
 	doc/lightning-pay.7 \
 	doc/lightning-sendpay.7 \
+	doc/lightning-setchannelfee.7 \
 	doc/lightning-waitinvoice.7 \
 	doc/lightning-waitanyinvoice.7 \
 	doc/lightning-waitsendpay.7 \

doc/lightning-setchannelfee.7

@@ -0,0 +1,80 @@
+'\" t
+.\"     Title: lightning-setchannelfee
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 03/12/2019
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-SETCHANNE" "7" "03/12/2019" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+lightning-setchannelfee \- Command for setting specific routing fees on a lightning channel\&.
+.SH "SYNOPSIS"
+.sp
+\fBsetchannelfee\fR \fIid\fR [\fIbase\fR] [\fIppm\fR]
+.SH "DESCRIPTION"
+.sp
+The \fBsetchannelfee\fR RPC command sets channel specific routing fees as defined in BOLT #7\&. The channel has to be in normal or awaiting state\&. This can be checked by \fBlistpeers\fR reporting a \fIstate\fR of CHANNELD_NORMAL or CHANNELD_AWAITING_LOCKIN for the channel\&.
+.sp
+\fIid\fR is required and should contain a scid (short channel ID), channel id or peerid (pubkey) of the channel to be modified\&.
+.sp
+\fIbase\fR is an optional value in millisatoshi that is added as base fee to any routed payment\&. If the parameter is left out, the global config value fee\-base will be used again\&.
+.sp
+\fIppm\fR is an optional value that is added proportionally per\-millionths to any routed payment volume in satoshi\&. For example, if ppm is 1,000 and 1,000,000 satoshi is being routed trhough the channel, an proportional fee of 1,000 satoshi is added, resulting in a 0\&.1% fee\&. If the parameter is left out, the global config value will be used again\&.
+.SH "RETURN VALUE"
+.sp
+On success, an object with fields \fIchannel_id\fR, \fIshort_channel_id\fR, \fIbase\fR and \fIppm\fR, describing the new values for this cannel, is returned\&.
+.SH "ERRORS"
+.sp
+The following error codes may occur:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\-1\&. Channel is in incorrect state, i\&.e\&. Catchall nonspecific error\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\-32602\&. JSONRPC2_INVALID_PARAMS, i\&.e\&. Given id is not a channel ID or short channel ID\&.
+.RE
+.SH "AUTHOR"
+.sp
+Michael Schmoock <michael@schmoock\&.net> is the author of this feature\&. Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible for the c\-lightning project\&.
+.SH "SEE ALSO"
+.sp
+lightningd\-config(5), lightning\-fundchannel(7), lightning\-listchannels(7), lightning\-listpeers(7)
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-setchannelfee.7.txt

@@ -0,0 +1,56 @@
+LIGHTNING-SETCHANNELFEE(7)
+========================
+:doctype: manpage
+
+NAME
+----
+lightning-setchannelfee -  Command for setting specific routing fees on a lightning channel.
+
+SYNOPSIS
+--------
+*setchannelfee* 'id' ['base'] ['ppm']
+
+DESCRIPTION
+-----------
+The *setchannelfee* RPC command sets channel specific routing fees as
+defined in BOLT #7. The channel has to be in normal or awaiting state.
+This can be checked by *listpeers* reporting a 'state' of CHANNELD_NORMAL
+or CHANNELD_AWAITING_LOCKIN for the channel.
+
+'id' is required and should contain a scid (short channel ID), channel id
+or peerid (pubkey) of the channel to be modified.
+
+'base' is an optional value in millisatoshi that is added as base fee to
+any routed payment. If the parameter is left out, the global config
+value fee-base will be used again.
+
+'ppm' is an optional value that is added proportionally per-millionths to
+any routed payment volume in satoshi. For example, if ppm is 1,000 and
+1,000,000 satoshi is being routed trhough the channel, an proportional
+fee of 1,000 satoshi is added, resulting in a 0.1% fee. If the parameter
+is left out, the global config value will be used again.
+
+RETURN VALUE
+------------
+On success, an object with fields 'channel_id', 'short_channel_id', 'base'
+and 'ppm', describing the new values for this cannel, is returned.
+
+ERRORS
+------
+The following error codes may occur:
+
+* -1. Channel is in incorrect state, i.e. Catchall nonspecific error.
+* -32602. JSONRPC2_INVALID_PARAMS, i.e. Given id is not a channel ID or short channel ID.
+
+AUTHOR
+------
+Michael Schmoock <michael@schmoock.net> is the author of this feature.
+Rusty Russell <rusty@rustcorp.com.au> is mainly responsible for the c-lightning project.
+
+SEE ALSO
+--------
+lightningd-config(5), lightning-fundchannel(7), lightning-listchannels(7), lightning-listpeers(7)
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightningd-config.5

@@ -1,13 +1,13 @@
 '\" t
 .\"     Title: lightningd-config
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\"      Date: 12/03/2018
+.\"      Date: 03/03/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNINGD\-CONFIG" "5" "12/03/2018" "\ \&" "\ \&"
+.TH "LIGHTNINGD\-CONFIG" "5" "03/03/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -188,12 +188,12 @@ Up to 32 UTF\-8 characters to tag your node\&. Completely silly, since anyone ca
 .PP
 \fBfee\-base\fR=\fIMILLISATOSHI\fR
 .RS 4
-The base fee to charge for every payment which passes through\&. Note that millisatoshis are a very, very small unit!
+The base fee to charge for every payment which passes through\&. Note that millisatoshis are a very, very small unit! Changing this value will only affect new channels and not existing ones\&.
 .RE
 .PP
 \fBfee\-per\-satoshi\fR=\fIMILLIONTHS\fR
 .RS 4
-This is the proportional fee to charge for every payment which passes through\&. As percentages are too coarse, it\(cqs in millionths, so 10000 is 1%, 1000 is 0\&.1%\&.
+This is the proportional fee to charge for every payment which passes through\&. As percentages are too coarse, it\(cqs in millionths, so 10000 is 1%, 1000 is 0\&.1%\&. Changing this value will only affect new channels and not existing ones\&.
 .RE
 .PP
 \fBignore\-fee\-limits\fR=\fIBOOL\fR
@@ -439,7 +439,7 @@ to authenticate to the Tor control port\&.
 .RE
 .SS "Lightning Plugins"
 .sp
-lightningd(8) supports plugins, which offer additional configuration options and JSON\-RPC methods, depending on the plugin\&. Some are supplied by default (usually located in \fBlibexec/c\-lightning/plugins\fR), but you can add your own, too\&.
+lightningd(8) supports plugins, which offer additional configuration options and JSON\-RPC methods, depending on the plugin\&. Some are supplied by default (usually located in \fBlibexec/c\-lightning/plugins/\fR), but you can add your own, too\&.
 .PP
 \fBplugin\fR=\fIPATH\fR
 .RS 4
@@ -448,10 +448,11 @@ Specify a plugin to run as part of c\-lightning\&. This can be specified multipl
 .PP
 \fBplugin\-dir\fR=\fIDIRECTORY\fR
 .RS 4
-Specify a directory to look for plugins; all files beginning with
+Specify a directory to look for plugins; all executable files not containing punctuation (other than
-\fIlplugin_\fR
+\fI\&.\fR,
-in
+\fI\-\fR
-\fIDIRECTORY\fR
+or
+\fI_) in \*(AqDIRECTORY\fR
 are loaded\&.
 \fIDIRECTORY\fR
 must exist; this can be specified multiple times to add multiple directories\&.

doc/lightningd-config.5.txt

@@ -140,12 +140,14 @@ Lightning node customization options
 
 *fee-base*='MILLISATOSHI'::
     The base fee to charge for every payment which passes through.  Note that
-    millisatoshis are a very, very small unit!
+    millisatoshis are a very, very small unit!  Changing this value will only
+    affect new channels and not existing ones.
 
 *fee-per-satoshi*='MILLIONTHS'::
     This is the proportional fee to charge for every payment which passes
     through.  As percentages are too coarse, it's in millionths, so 10000
-    is 1%, 1000 is 0.1%.
+    is 1%, 1000 is 0.1%.  Changing this value will only affect new channels and
+    not existing ones.
 
 *ignore-fee-limits*='BOOL'::
     Allow nodes which establish channels to us to set any fee they