core-lightning/doc/schemas/lightning-getroute.json
Rusty Russell b327bd30c3 doc: fix all JSON schemas to enforce no additional properties.
Without this, we have hardly any enforcement.  This is why the schema
mistake fixed in the previous patches weren't spotted immediately.

The hard work was done by:

```
$ for f in lightning-*.json; do grep -v '^  "additionalProperties": false,' $f | bagto $f; done
$ for f in lightning-*.json; do sed 's/"properties": {/"additionalProperties": false, "properties": {/' $f | bagto $f; done
$ make fmt-schemas
```

Then checking where 'additionalProperties: true' had been turned to
false (we deliberately use it in some places where there are if
statements in the schema, or occasionally where there can be arbitrary
fields).

[Including doc/rpc-schema-draft.json update by Shahana]
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2024-10-30 15:39:12 +10:30

434 lines
16 KiB
JSON

{
"$schema": "../rpc-schema-draft.json",
"type": "object",
"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"
],
"additionalProperties": false,
"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"
],
"additionalProperties": false,
"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"
}
]
}
}
]
}