mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00
Code Issues Projects Releases Wiki Activity
d32433a553
core-lightning/doc/schemas/lightning-getroute.json
ShahanaFarooqui f92a4ccea5 doc: Updated json examples in schema files
2024-08-09 23:56:45 -07:00

434 lines
16 KiB
JSON
Raw Blame History

{
"$schema": "../rpc-schema-draft.json",
"type": "object",
"additionalProperties": false,
"rpc": "getroute",
"title": "Command for routing a payment (low-level)",
"description": [
"The **getroute** RPC command attempts to find the best route for the payment of *amount_msat* to lightning node *id*, such that the payment will arrive at *id* with *cltv*.",
"",
"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. ."
],
"categories": [
"readonly"
],
"request": {
"required": [
"id",
"amount_msat",
"riskfactor"
],
"properties": {
"id": {
"type": "pubkey",
"description": [
"Node pubkey to find the best route for the payment."
]
},
"amount_msat": {
"type": "msat",
"description": [
"Amount to send. 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 1 to 11 decimal places ending in *btc*. The 0 value is special: it ignores any *htlc_minimum_msat* setting on channels, and simply returns a possible route (if any) which is useful for simple probing."
]
},
"riskfactor": {
"type": "u64",
"description": [
"A non-negative floating-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage). For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, *riskfactor* would be 20. If you didn't care about risk, *riskfactor* would be zero."
]
},
"cltv": {
"type": "u32",
"description": [
"Cltv-blocks to spare."
],
"default": "9"
},
"fromid": {
"type": "pubkey",
"description": [
"The node to start the route from."
],
"default": "this node"
},
"fuzzpercent": {
"type": "u32",
"description": [
"Used to distort fees to provide some randomization to the route generated, but it was not properly implemented and is ignored."
]
},
"exclude": {
"type": "array",
"description": [
"A JSON array of short-channel-id/direction (e.g. ['564334x877x1/0', '564195x1292x0/1' ]) or node-id which should be excluded from consideration for routing. Note if the source or destination is excluded, the command result is undefined."
],
"default": "not to exclude any channels or nodes",
"items": {
"type": "string"
}
},
"maxhops": {
"type": "u32",
"description": [
"The maximum number of channels to return."
],
"default": "20"
}
}
},
"response": {
"required": [
"route"
],
"properties": {
"route": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"direction",
"channel",
"amount_msat",
"delay",
"style"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "pubkey",
"description": [
"The node at the end of this hop."
]
},
"channel": {
"type": "short_channel_id",
"description": [
"The channel joining these nodes."
]
},
"direction": {
"type": "u32",
"description": [
"0 if this channel is traversed from lesser to greater **id**, otherwise 1."
]
},
"amount_msat": {
"type": "msat",
"description": [
"The amount expected by the node at the end of this hop."
]
},
"delay": {
"type": "u32",
"description": [
"The total CLTV expected by the node at the end of this hop."
]
},
"style": {
"type": "string",
"description": [
"The features understood by the destination node."
],
"enum": [
"tlv"
]
}
}
}
}
},
"post_return_value_notes": [
"The final *id* will be the destination *id* given in the input. The difference between the first *amount_msat* minus the *amount_msat* given in the input is the fee (assuming the first hop is free). The first *delay* is the very worst case timeout for the payment failure, in blocks."
]
},
"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:",
"",
" risk-fee = amount x blocks-timeout x per-block-cost",
"",
"We are given a *riskfactor* expressed as a percentage. There are 52596 blocks per year, thus *per-block-cost* is *riskfactor* divided by 5,259,600.",
"",
"The final result is:",
"",
" risk-fee = amount x blocks-timeout x riskfactor / 5259600",
"",
"Here are the risk fees in millisatoshis, using various parameters. I assume a channel charges the default of 1000 millisatoshis plus 1 part-per-million. Common to_self_delay values on the network at 14 and 144 blocks.",
"",
"<table>",
"<colgroup>",
"<col style=\"width: 20%\" />",
"<col style=\"width: 20%\" />",
"<col style=\"width: 20%\" />",
"<col style=\"width: 20%\" />",
"<col style=\"width: 20%\" />",
"</colgroup>",
"<thead>",
"<tr class=\"header\">",
"<th style=\"text-align: left;\">Amount (msat)</th>",
"<th style=\"text-align: left;\">Riskfactor</th>",
"<th style=\"text-align: left;\">Delay</th>",
"<th style=\"text-align: left;\">Risk Fee</th>",
"<th style=\"text-align: left;\">Route fee</th>",
"</tr>",
"</thead>",
"<tbody>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>0</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>0</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>2</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>26</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>2</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>26</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>266</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>2661</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>266</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>2661</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>26617</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>14</p></td>",
"<td style=\"text-align: left;\"><p>266179</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>0</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>2</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>27</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>10,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>273</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>27</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>273</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>2737</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>1,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>27378</p></td>",
"<td style=\"text-align: left;\"><p>1001</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>2737</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>10</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>27378</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"odd\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>100</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>273785</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"<tr class=\"even\">",
"<td style=\"text-align: left;\"><p>100,000,000</p></td>",
"<td style=\"text-align: left;\"><p>1000</p></td>",
"<td style=\"text-align: left;\"><p>144</p></td>",
"<td style=\"text-align: left;\"><p>2737850</p></td>",
"<td style=\"text-align: left;\"><p>1100</p></td>",
"</tr>",
"</tbody>",
"</table>"
],
"recommended_riskfactor_values": [
"The default *fuzz* factor is 5%, so as you can see from the table above, that tends to overwhelm the effect of *riskfactor* less than about 5.",
"",
"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.",
"",
"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."
],
"author": [
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
],
"see_also": [
"lightning-pay(7)",
"lightning-sendpay(7)"
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
],
"examples": [
{
"request": {
"id": "example:getroute#1",
"method": "getroute",
"params": {
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"amount_msat": 10000,
"riskfactor": 1
}
},
"response": {
"route": [
{
"id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
"channel": "109x1x1",
"direction": 1,
"amount_msat": 10001,
"delay": 15,
"style": "tlv"
},
{
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"channel": "111x1x0",
"direction": 0,
"amount_msat": 10000,
"delay": 9,
"style": "tlv"
}
]
}
},
{
"request": {
"id": "example:getroute#2",
"method": "getroute",
"params": {
"id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
"amount_msat": 500000,
"riskfactor": 10,
"cltv": 9
}
},
"response": {
"route": [
{
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"channel": "111x1x0",
"direction": 0,
"amount_msat": 500006,
"delay": 15,
"style": "tlv"
},
{
"id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
"channel": "113x1x1",
"direction": 0,
"amount_msat": 500000,
"delay": 9,
"style": "tlv"
}
]
}
}
]
}
Reference in New Issue View Git Blame Copy Permalink