lightning/doc/lightning-decodepay.7

'\" t
.\"     Title: lightning-decodepay
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/13/2018
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "LIGHTNING\-DECODEPAY" "7" "01/13/2018" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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-decodepay \- Protocol for decoding a bolt11 string (low\-level)
.SH "SYNOPSIS"
.sp
\fBdecodepay\fR \fIbolt11\fR [\fIdescription\fR]
.SH "DESCRIPTION"
.sp
The \fBdecodepay\fR RPC command checks and parses a \fIbolt11\fR string as specified by the BOLT 11 specification\&.
.SH "RETURN VALUE"
.sp
On success, an object is returned with the following fields, as specified by BOLT11:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIcurrency\fR: the BIP173 name for the currency\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItimestamp\fR: the UNIX\-style timestamp of the invoice\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIexpiry\fR: the number of seconds this is valid after
\fItimestamp\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIpayee\fR: the public key of the recipient\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIpayment_hash\fR: the payment hash of the request\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIsignature\fR: the DER\-encoded signature\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIdescription\fR: the description of the purpose of the purchase (see below)
.RE
.sp
The following fields are optional:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fImsatoshi\fR: the number of millisatoshi requested (if any)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIfallback\fR: fallback address object containing a
\fIhex\fR
string, and both
\fItype\fR
and
\fIaddr\fR
if it is recognized as one of
\fIP2PKH\fR,
\fIP2SH\fR,
\fIP2WPKH\fR, or
\fIP2WSH\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIroutes\fR: an array of routes\&. Each route is an arrays of objects, each containing
\fIpubkey\fR,
\fIshort_channel_id\fR,
\fIfee_base_msat\fR,
\fIfee_proportional_millionths\fR
and
\fIcltv_expiry_delta\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIextra\fR: an array of objects representing unknown fields, each with one\-character
\fItag\fR
and a
\fIdata\fR
bech32 string\&.
.RE
.sp
Technically, the \fIdescription\fR field is optional if a \fIdescription_hash\fR field is given, but in this case \fBdecodepay\fR will only succeed if the optional \fIdescription\fR field is passed and matches the \fIdescription_hash\fR\&. In practice, these are currently unused\&.
.SH "AUTHOR"
.sp
Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
.SH "SEE ALSO"
.sp
lightning\-pay(7), lightning\-getroute(7), lightning\-sendpay(7)\&.
.sp
BOLT #11\&.
.SH "RESOURCES"
.sp
Main web site: https://github\&.com/ElementsProject/lightning