diff --git a/Makefile b/Makefile index 3e77ae70a..cae831eb0 100644 --- a/Makefile +++ b/Makefile @@ -168,6 +168,14 @@ GEN_HEADERS := gen_pkt_names.h \ CDUMP_OBJS := ccan-cdump.o ccan-strmap.o +MANPAGES := doc/lightning-cli.1 \ + doc/lightning-delinvoice.7 \ + doc/lightning-getroute.7 \ + doc/lightning-invoice.7 \ + doc/lightning-listinvoice.7 \ + doc/lightning-sendpay.7 \ + doc/lightning-waitinvoice.7 + PROGRAMS := $(TEST_PROGRAMS) CWARNFLAGS := -Werror -Wall -Wundef -Wmissing-prototypes -Wmissing-declarations -Wstrict-prototypes -Wold-style-definition @@ -177,7 +185,10 @@ CFLAGS := $(CWARNFLAGS) $(CDEBUGFLAGS) -I $(CCANDIR) -I secp256k1/include/ -I . LDLIBS := -lprotobuf-c -lgmp -lsodium -lbase58 -lsqlite3 $(PROGRAMS): CFLAGS+=-I. -default: $(PROGRAMS) daemon-all +default: $(PROGRAMS) $(MANPAGES) daemon-all + +$(MANPAGES): doc/%: doc/%.txt + a2x --format=manpage $< # Everything depends on the CCAN headers. $(CCAN_OBJS) $(CDUMP_OBJS) $(HELPER_OBJS) $(BITCOIN_OBJS) $(TEST_PROGRAMS:=.o): $(CCAN_HEADERS) @@ -325,6 +336,7 @@ maintainer-clean: distclean @echo 'deletes files that may need special tools to rebuild.' $(RM) lightning.pb-c.c lightning.pb-c.h ccan/config.h $(GEN_HEADERS) $(RM) doc/deployable-lightning.pdf + $(RM) $(MANPAGES) clean: daemon-clean $(MAKE) -C secp256k1/ clean || true diff --git a/README.md b/README.md index 13ab506c3..cf6f21fd8 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,19 @@ the original "lightning network"). This implementation is being developed in parallel with the protocol definition, which you can find [on my fork of the protocol description repository](https://github.com/rustyrussell/lightning). -So far, we are working on the [inter-node encryption](https://github.com/rustyrussell/lightning-rfc/blob/master/bolts/01-encryption.md) and [transaction negotiation](https://github.com/rustyrussell/lightning-rfc/blob/master/bolts/02-wire-protocol.md) phases. +If you're interested in using the daemon to test payments, the +JSON-RPC interface is documented in the following manual pages: +* [invoice](doc/lightning-invoice.7.txt) +* [listinvoice](doc/lightning-listinvoice.7.txt) +* [waitinvoice](doc/lightning-waitinvoice.7.txt) +* [delinvoice](doc/lightning-delinvoice.7.txt) +* [getroute](doc/lightning-getroute.7.txt) +* [sendpay](doc/lightning-sendpay.7.txt) -Later steps will enhance the protocol to network individual daemons, -advertise their IP addresses, publish routes and fees, and use that -information to pay specific nodes. These details are currently being +So far, we have [inter-node encryption](https://github.com/rustyrussell/lightning-rfc/blob/master/bolts/01-encryption.md) and [transaction negotiation](https://github.com/rustyrussell/lightning-rfc/blob/master/bolts/02-wire-protocol.md). + +Routing between non-adjacent nodes is currently done manually using the 'dev-addroute' command; later on daemons will +advertise their IP addresses, and publish routes and fees. These details are currently being hashed out on the [mailing list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev) and the IRC channel [#lightning-dev](https://botbot.me/freenode/lightning-dev/) on Freenode. Final note: This is very much a testbed and work in progress; expect diff --git a/doc/lightning-cli.1 b/doc/lightning-cli.1 new file mode 100644 index 000000000..0fb5990b5 --- /dev/null +++ b/doc/lightning-cli.1 @@ -0,0 +1,81 @@ +'\" t +.\" Title: lightning-cli +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-CLI" "1" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-cli \- Control lightning daemon +.SH "SYNOPSIS" +.sp +\fBlightning\-cli\fR [\fIOPTIONS\fR] \fIcommand\fR\&... +.SH "DESCRIPTION" +.sp +\fBlightning\-cli\fR sends commands to the lightning daemon\&. +.SH "OPTIONS" +.PP +\fB\-\-lightning\-dir\fR=\fIDIR\fR +.RS 4 +Set the directory for the lightning daemon we\(cqre talking to; defaults to +\fI$HOME/\&.lightning\fR\&. +.RE +.PP +\fB\-\-rpc\-file\fR=\fIFILE\fR +.RS 4 +Named pipe to use to to talk to lightning daemon: default is +\fIlightning\-rpc\fR +in the lightning directory\&. +.RE +.PP +\fB\-\-help\fR/\fB\-h\fR +.RS 4 +Print summary of options to standard output and exit\&. +.RE +.PP +\fB\-\-version\fR/\fB\-V\fR +.RS 4 +Print version number to standard output and exit\&. +.RE +.SH "COMMANDS" +.sp +\fIlightning\-cli\fR simply uses the JSON RPC interface to talk to \fIlightningd\fR, and prints the results\&. Thus the commands available depend entirely on the lightning daemon itself\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&List commands\fR +.sp +lighting\-cli help +.SH "BUGS" +.sp +This manpage documents how it should work, not how it does work\&. The pretty printing of results isn\(cqt pretty\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly to blame\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning +.SH "COPYING" +.sp +Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD\-style MIT license\&. diff --git a/doc/lightning-cli.1.txt b/doc/lightning-cli.1.txt new file mode 100644 index 000000000..40e8d7c41 --- /dev/null +++ b/doc/lightning-cli.1.txt @@ -0,0 +1,60 @@ +LIGHTNING-CLI(1) +================== +:doctype: manpage + +NAME +---- +lightning-cli - Control lightning daemon + + +SYNOPSIS +-------- +*lightning-cli* ['OPTIONS'] 'command'... + +DESCRIPTION +----------- +*lightning-cli* sends commands to the lightning daemon. + +OPTIONS +------- +*--lightning-dir*='DIR':: + Set the directory for the lightning daemon we're talking to; defaults to + '$HOME/.lightning'. +*--rpc-file*='FILE':: + Named pipe to use to to talk to lightning daemon: default is 'lightning-rpc' + in the lightning directory. +*--help*/*-h*:: + Print summary of options to standard output and exit. +*--version*/*-V*:: + Print version number to standard output and exit. + +COMMANDS +-------- +'lightning-cli' simply uses the JSON RPC interface to talk to 'lightningd', +and prints the results. Thus the commands available depend entirely on the +lightning daemon itself. + +EXAMPLES +-------- +.List commands +=================================================================== +lighting-cli help +=================================================================== + +BUGS +---- +This manpage documents how it should work, not how it does work. The +pretty printing of results isn't pretty. + +AUTHOR +------ +Rusty Russell is mainly to blame. + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning + +COPYING +------- +Note: the modules in the ccan/ directory have their own licenses, but +the rest of the code is covered by the BSD-style MIT license. diff --git a/doc/lightning-delinvoice.7 b/doc/lightning-delinvoice.7 new file mode 100644 index 000000000..5ca813c8c --- /dev/null +++ b/doc/lightning-delinvoice.7 @@ -0,0 +1,49 @@ +'\" t +.\" Title: lightning-delinvoice +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-DELINVOIC" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-delinvoice \- Protocol for removing an unpaid invoice\&. +.SH "SYNOPSIS" +.sp +\fBdelinvoice\fR \fIlabel\fR +.SH "DESCRIPTION" +.sp +The \fBdelinvoice\fR RPC command removes an unpaid invoice\&. The caller should be particularly aware of the error case caused by a payment just before this command is invoked! +.SH "RETURN VALUE" +.sp +On success, the \fIrhash\fR, \fIlabel\fR and \fImsatoshi\fR will be returned\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-listinvoice(7), lightning\-waitinvoice(7), lightning\-invoice(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-delinvoice.7.txt b/doc/lightning-delinvoice.7.txt new file mode 100644 index 000000000..7bcf52e68 --- /dev/null +++ b/doc/lightning-delinvoice.7.txt @@ -0,0 +1,35 @@ +LIGHTNING-DELINVOICE(7) +======================= +:doctype: manpage + +NAME +---- +lightning-delinvoice - Protocol for removing an unpaid invoice. + +SYNOPSIS +-------- +*delinvoice* 'label' + +DESCRIPTION +----------- +The *delinvoice* RPC command removes an unpaid invoice. The caller +should be particularly aware of the error case caused by a payment +just before this command is invoked! + +RETURN VALUE +------------ +On success, the 'rhash', 'label' and 'msatoshi' will be returned. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-listinvoice(7), lightning-waitinvoice(7), lightning-invoice(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 new file mode 100644 index 000000000..49ad4d804 --- /dev/null +++ b/doc/lightning-getroute.7 @@ -0,0 +1,267 @@ +'\" t +.\" Title: lightning-getroute +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-GETROUTE" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-getroute \- Protocol for routing a payment\&. +.SH "SYNOPSIS" +.sp +\fBgetroute\fR \fImsatoshi\fR \fIid\fR \fIriskfactor\fR +.SH "DESCRIPTION" +.sp +The \fBgetroute\fR RPC command attempts to find the best route for the payment of \fImsatoshi\fR to lightning node \fIid\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 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), multiplied by the percentage chance of each node failing\&. +.sp +For example, if you thought there was a 1% chance that a node would fail, and it would cost you 20% per annum if that happened, \fIriskfactor\fR would be 20\&. +.sp +If you didn\(cqt care about risk, \fIriskfactor\fR would be zero\&. +.SH "RISKFACTOR EFFECT ON ROUTING" +.sp +The risk factor is treated as if it were an additional fee on the route, for the purposes of comparing routes\&. +.sp +The formula used is the following approximation: +.sp +.if n \{\ +.RS 4 +.\} +.nf +hop\-risk = num\-hops x per\-hop\-risk +timeout\-cost = blocks\-timeout x per\-block\-cost +risk\-fee = amount x hop\-risk x timeout\-cost +.fi +.if n \{\ +.RE +.\} +.sp +We are given a \fIriskfactor\fR; expressed as two multiplied percentages is the same as fractions multiplied by 10000\&. There are 52596 blocks per year, thus \fIper\-block\-cost\fR x \fIper\-hop\-risk\fR is riskfactor\*(Aq divided by 5,259,600,000\&. +.sp +The final result is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +risk\-fee = amount x num\-hops x blocks\-timeout x riskfactor / 5259600000 +.fi +.if n \{\ +.RE +.\} +.sp +Here are the risk fees as a percentage of the amount sent, using various parameters\&. For comparison with actual fees, we assume nodes charge 0\&.05%: +.TS +allbox tab(:); +ltB ltB ltB ltB ltB. +T{ +Riskfactor +T}:T{ +Nodes +T}:T{ +Delay per node +T}:T{ +Risk Fee % +T}:T{ +Route fee % +T} +.T& +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt +lt lt lt lt lt. +T{ +.sp +0\&.001 +T}:T{ +.sp +5 +T}:T{ +.sp +6 +T}:T{ +.sp +0 +T}:T{ +.sp +0\&.25 +T} +T{ +.sp +1 +T}:T{ +.sp +5 +T}:T{ +.sp +6 +T}:T{ +.sp +0 +T}:T{ +.sp +0\&.25 +T} +T{ +.sp +1000 +T}:T{ +.sp +5 +T}:T{ +.sp +6 +T}:T{ +.sp +0\&.0029 +T}:T{ +.sp +0\&.25 +T} +T{ +.sp +0\&.001 +T}:T{ +.sp +10 +T}:T{ +.sp +72 +T}:T{ +.sp +0 +T}:T{ +.sp +0\&.5 +T} +T{ +.sp +1 +T}:T{ +.sp +10 +T}:T{ +.sp +72 +T}:T{ +.sp +0\&.0001 +T}:T{ +.sp +0\&.5 +T} +T{ +.sp +1000 +T}:T{ +.sp +10 +T}:T{ +.sp +72 +T}:T{ +.sp +0\&.1369 +T}:T{ +.sp +0\&.5 +T} +T{ +.sp +0\&.001 +T}:T{ +.sp +20 +T}:T{ +.sp +1008 +T}:T{ +.sp +0 +T}:T{ +.sp +1\&.0 +T} +T{ +.sp +1 +T}:T{ +.sp +20 +T}:T{ +.sp +1008 +T}:T{ +.sp +0\&.0077 +T}:T{ +.sp +1\&.0 +T} +T{ +.sp +1000 +T}:T{ +.sp +20 +T}:T{ +.sp +1008 +T}:T{ +.sp +7\&.6660 +T}:T{ +.sp +1\&.0 +T} +.TE +.sp 1 +.SH "RECOMMENDED RISKFACTOR VALUES" +.sp +0\&.001 is a value for tie\-breaking in favor of shorter routes, but not really costing in any risk\&. +.sp +1 is a conservative value for a stable lightning network with very few failures\&. +.sp +1000 is an aggressive value for trying to minimize timeouts at all costs\&. +.SH "RETURN VALUE" +.sp +On success, a "route" array is returned\&. Each array element contains +.sp +timeout for the payment failure, in blocks\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-sendpay(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-getroute.7.txt b/doc/lightning-getroute.7.txt new file mode 100644 index 000000000..662697742 --- /dev/null +++ b/doc/lightning-getroute.7.txt @@ -0,0 +1,109 @@ +LIGHTNING-GETROUTE(7) +===================== +:doctype: manpage + +NAME +---- +lightning-getroute - Protocol for routing a payment. + + +SYNOPSIS +-------- +*getroute* 'msatoshi' 'id' 'riskfactor' + +DESCRIPTION +----------- +The *getroute* RPC command attempts to find the best route for the payment +of 'msatoshi' to lightning node 'id'. + +There are two considerations for how good a route is: how low the +fees are, and how long your payment will get stuck if a node goes down +during the process. The 'riskfactor' floating-point field controls +this tradeoff; it is the annual cost of your funds being stuck (as a +percentage), multiplied by the percentage chance of each node failing. + +For example, if you thought there was a 1% chance that a node would +fail, and it would cost you 20% per annum if that happened, +'riskfactor' would be 20. + +If you didn't care about risk, 'riskfactor' would be zero. + +RISKFACTOR EFFECT ON ROUTING +---------------------------- +The risk factor is treated as if it were an additional fee on the route, +for the purposes of comparing routes. + +The formula used is the following approximation: +---- +hop-risk = num-hops x per-hop-risk +timeout-cost = blocks-timeout x per-block-cost +risk-fee = amount x hop-risk x timeout-cost +---- + +We are given a 'riskfactor'; expressed as two multiplied percentages +is the same as fractions multiplied by 10000. There are 52596 blocks +per year, thus 'per-block-cost' x 'per-hop-risk' is riskfactor' +divided by 5,259,600,000. + +The final result is: +---- +risk-fee = amount x num-hops x blocks-timeout x riskfactor / 5259600000 +---- + +Here are the risk fees as a percentage of the amount sent, using +various parameters. For comparison with actual fees, we assume nodes +charge 0.05%: + +[options="header"] +|======================= +|Riskfactor |Nodes | Delay per node |Risk Fee % |Route fee % +|0.001 |5 | 6 |0 |0.25 +|1 |5 | 6 |0 |0.25 +|1000 |5 | 6 |0.0029 |0.25 + +|0.001 |10 | 72 |0 |0.5 +|1 |10 | 72 |0.0001 |0.5 +|1000 |10 | 72 |0.1369 |0.5 + +|0.001 |20 | 1008 |0 |1.0 +|1 |20 | 1008 |0.0077 |1.0 +|1000 |20 | 1008 |7.6660 |1.0 +|======================= + +RECOMMENDED RISKFACTOR VALUES +----------------------------- +0.001 is a value for tie-breaking in favor of shorter routes, but not really +costing in any risk. + +1 is a conservative value for a stable lightning network with very few +failures. + +1000 is an aggressive value for trying to minimize timeouts at all +costs. + +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 node). + +The final {id} will be the destination {id} given in the input. The +difference between the first {msatoshi} minus the {msatoshi} given in +the input is the fee. The first {delay} is the very worst case +timeout for the payment failure, in blocks. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-sendpay(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-invoice.7 b/doc/lightning-invoice.7 new file mode 100644 index 000000000..1183e7a18 --- /dev/null +++ b/doc/lightning-invoice.7 @@ -0,0 +1,51 @@ +'\" t +.\" Title: lightning-invoice +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-INVOICE" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-invoice \- Protocol for accepting payments\&. +.SH "SYNOPSIS" +.sp +\fBinvoice\fR \fImsatoshi\fR \fIlabel\fR +.SH "DESCRIPTION" +.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\&. +.sp +The \fIlabel\fR must be unique; it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice\&. +.SH "RETURN VALUE" +.sp +On success, a hash is returned as \fIrhash\fR to be given to the payer\&. On failure, an error is returned and no invoice is created\&. If the lightning process fails before responding, the caller should use getinvoice(7) to query whether this invoice was created or not\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-sendpay(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-invoice.7.txt b/doc/lightning-invoice.7.txt new file mode 100644 index 000000000..f721f9a0b --- /dev/null +++ b/doc/lightning-invoice.7.txt @@ -0,0 +1,44 @@ +LIGHTNING-INVOICE(7) +==================== +:doctype: manpage + +NAME +---- +lightning-invoice - Protocol for accepting payments. + +SYNOPSIS +-------- +*invoice* 'msatoshi' 'label' + +DESCRIPTION +----------- +The *invoice* 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. + +The 'label' must be unique; it is never revealed to other nodes on +the lightning network, but it can be used to query the status of this +invoice. + +RETURN VALUE +------------ + +On success, a hash is returned as 'rhash' to be given to the payer. +On failure, an error is returned and no invoice is created. If the +lightning process fails before responding, the caller should use +getinvoice(7) to query whether this invoice was created or not. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-sendpay(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-listinvoice.7 b/doc/lightning-listinvoice.7 new file mode 100644 index 000000000..c8ed65fc7 --- /dev/null +++ b/doc/lightning-listinvoice.7 @@ -0,0 +1,49 @@ +'\" t +.\" Title: lightning-listinvoice +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-LISTINVOI" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-listinvoice \- Protocol for querying invoice status +.SH "SYNOPSIS" +.sp +\fBlistinvoice\fR [\fIlabel\fR] +.SH "DESCRIPTION" +.sp +The \fBlistinvoice\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 containing \fIlabel\fR, \fIrhash\fR, \fImsatoshi\fR and \fIcomplete\fR will be returned\&. \fIcomplete\fR is a boolean\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-waitinvoice(7), lightning\-delinvoice(7), lightning\-invoice(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-listinvoice.7.txt b/doc/lightning-listinvoice.7.txt new file mode 100644 index 000000000..5a4580f27 --- /dev/null +++ b/doc/lightning-listinvoice.7.txt @@ -0,0 +1,36 @@ +LIGHTNING-LISTINVOICE(7) +======================== +:doctype: manpage + +NAME +---- +lightning-listinvoice - Protocol for querying invoice status + +SYNOPSIS +-------- +*listinvoice* ['label'] + +DESCRIPTION +----------- +The *listinvoice* RPC command gets the status of a specific invoice, if +it exists, or the status of all invoices if given no argument. + +RETURN VALUE +------------ +On success, an array 'invoices' of objects containing 'label', +'rhash', 'msatoshi' and 'complete' will be returned. 'complete' is a +boolean. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-waitinvoice(7), lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-sendpay.7 b/doc/lightning-sendpay.7 new file mode 100644 index 000000000..45cdf1497 --- /dev/null +++ b/doc/lightning-sendpay.7 @@ -0,0 +1,55 @@ +'\" t +.\" Title: lightning-sendpay +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-SENDPAY" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-sendpay \- Protocol for sending a payment via a route\&. +.SH "SYNOPSIS" +.sp +\fBsendpay\fR \fIroute\fR \fIhash\fR +.SH "DESCRIPTION" +.sp +The \fBsendpay\fR RPC command attempts to send funds associated with the given \fIhash\fR, along a route to the final destination in the route\&. +.sp +Generally, a client would call getroute(7) to resolve a route, then use \fBsendpay\fR to send it\&. If it fails, it would call getroute(7) again to retry\&. +.sp +The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBsendpay\fR with the same \fIhash\fR will fail; this prevents accidental multiple payments\&. +.SH "RETURN VALUE" +.sp +On success, a \fIpreimage\fR hex string is returned as proof that the destination received the payment\&. The \fIpreimage\fR will SHA256 to the \fIhash\fR given by the caller\&. +.sp +On error, if the error occurred from a node other than the final destination, the route table will be updated so that getroute(7) should return an alternate route (if any)\&. An error from the final destination implies the payment should not be retried\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-invoice(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-sendpay.7.txt b/doc/lightning-sendpay.7.txt new file mode 100644 index 000000000..9ec0f1f73 --- /dev/null +++ b/doc/lightning-sendpay.7.txt @@ -0,0 +1,52 @@ +LIGHTNING-SENDPAY(7) +==================== +:doctype: manpage + +NAME +---- +lightning-sendpay - Protocol for sending a payment via a route. + +SYNOPSIS +-------- +*sendpay* 'route' 'hash' + +DESCRIPTION +----------- + +The *sendpay* RPC command attempts to send funds associated with the +given 'hash', along a route to the final destination in the route. + +Generally, a client would call getroute(7) to resolve a route, then +use *sendpay* to send it. If it fails, it would call getroute(7) +again to retry. + +The response will occur when the payment fails or succeeds. Once a +payment has succeeded, calls to *sendpay* with the same 'hash' will +fail; this prevents accidental multiple payments. + +RETURN VALUE +------------ + +On success, a 'preimage' hex string is returned as proof that the +destination received the payment. The 'preimage' will SHA256 to the +'hash' given by the caller. + +On error, if the error occurred from a node other than the final +destination, the route table will be updated so that getroute(7) +should return an alternate route (if any). An error from the final +destination implies the payment should not be retried. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-listinvoice(7), lightning-delinvoice(7), +lightning-getroute(7), lightning-invoice(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning diff --git a/doc/lightning-waitinvoice.7 b/doc/lightning-waitinvoice.7 new file mode 100644 index 000000000..c8f669ba2 --- /dev/null +++ b/doc/lightning-waitinvoice.7 @@ -0,0 +1,51 @@ +'\" t +.\" Title: lightning-waitinvoice +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 09/06/2016 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-WAITINVOI" "7" "09/06/2016" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * 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-waitinvoice \- Protocol for waiting for payments\&. +.SH "SYNOPSIS" +.sp +\fBwaitinvoice\fR [\fIlastlabel\fR] +.SH "DESCRIPTION" +.sp +The \fBwaitinvoice\fR RPC command waits until an invoice is paid, then returns a single entry as per \fBlistinvoice\fR\&. It will not return for any invoices paid prior to or including \fIlastlabel\fR\&. +.sp +This is usually called iteratively: once with no arguments, then repeatedly with the returned \fIlabel\fR entry\&. This ensures that no paid invoice is missed\&. +.SH "RETURN VALUE" +.sp +On success, the \fIrhash\fR, \fIlabel\fR, and \fImsatoshi\fR will be returned\&. +.SH "AUTHOR" +.sp +Rusty Russell is mainly responsible\&. +.SH "SEE ALSO" +.sp +lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-invoice(7)\&. +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightning-waitinvoice.7.txt b/doc/lightning-waitinvoice.7.txt new file mode 100644 index 000000000..29bf3b89d --- /dev/null +++ b/doc/lightning-waitinvoice.7.txt @@ -0,0 +1,39 @@ +LIGHTNING-WAITINVOICE(7) +======================== +:doctype: manpage + +NAME +---- +lightning-waitinvoice - Protocol for waiting for payments. + +SYNOPSIS +-------- +*waitinvoice* ['lastlabel'] + +DESCRIPTION +----------- +The *waitinvoice* RPC command waits until an invoice is paid, then +returns a single entry as per *listinvoice*. It will not return for +any invoices paid prior to or including 'lastlabel'. + +This is usually called iteratively: once with no arguments, then +repeatedly with the returned 'label' entry. This ensures that no paid +invoice is missed. + +RETURN VALUE +------------ +On success, the 'rhash', 'label', and 'msatoshi' will be returned. + +//FIXME:Enumerate errors + +AUTHOR +------ +Rusty Russell is mainly responsible. + +SEE ALSO +-------- +lightning-listinvoice(7), lightning-delinvoice(7), lightning-invoice(7). + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning