mirror of
https://github.com/aljazceru/lightning.git
synced 2026-01-11 01:54:25 +01:00
docs: add notes on v2 openchannel plugin hooks
This commit is contained in:
niftynei
179
doc/PLUGINS.md
179
doc/PLUGINS.md
@@ -962,8 +962,8 @@ nodes in [BOLT 4][bolt4-failure-messages], a `result` field with the string
|
||||
|
||||
### `openchannel`
|
||||
|
||||
This hook is called whenever a remote peer tries to fund a channel to us,
|
||||
and it has passed basic sanity checks:
|
||||
This hook is called whenever a remote peer tries to fund a channel to us using
|
||||
the v1 protocol, and it has passed basic sanity checks:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -1010,6 +1010,181 @@ Note that `openchannel` is a chained hook. Therefore `close_to` will only be
|
||||
evaluated for the first plugin that sets it. If more than one plugin tries to
|
||||
set a `close_to` address an error will be logged.
|
||||
|
||||
### `openchannel2`
|
||||
|
||||
This hook is called whenever a remote peer tries to fund a channel to us using
|
||||
the v2 protocol, and it has passed basic sanity checks:
|
||||
|
||||
```json
|
||||
{
|
||||
"openchannel2": {
|
||||
"id": "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
|
||||
"channel_id": "252d1b0a1e57895e84137f28cf19ab2c35847e284c112fefdecc7afeaa5c1de7",
|
||||
"their_funding": "100000000msat",
|
||||
"dust_limit_satoshis": "546000msat",
|
||||
"max_htlc_value_in_flight_msat": "18446744073709551615msat",
|
||||
"htlc_minimum_msat": "0msat",
|
||||
"funding_feerate_per_kw": 7500,
|
||||
"commitment_feerate_per_kw": 7500,
|
||||
"feerate_our_max": 10000,
|
||||
"feerate_our_min": 253,
|
||||
"to_self_delay": 5,
|
||||
"max_accepted_htlcs": 483,
|
||||
"channel_flags": 1
|
||||
"locktime": 2453,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There may be additional fields, such as `shutdown_scriptpubkey`. You can
|
||||
see the definitions of these fields in [BOLT 2's description of the open_channel message][bolt2-open-channel].
|
||||
|
||||
The returned result must contain a `result` member which is either
|
||||
the string `reject` or `continue`. If `reject` and
|
||||
there's a member `error_message`, that member is sent to the peer
|
||||
before disconnection.
|
||||
|
||||
For a 'continue'd result, you can also include a `close_to` address,
|
||||
which will be used as the output address for a mutual close transaction; you
|
||||
can include a `psbt` and an `accepter_funding_msat` to contribute funds,
|
||||
inputs and outputs to this channel open.
|
||||
|
||||
Note that, like `openchannel_init`, the `accepter_funding_msat` amount
|
||||
must NOT be accounted for in any supplied output. Change, however, should be
|
||||
included and should use the `funding_feerate_per_kw` to calculate.
|
||||
|
||||
See `tests/plugins/df_accepter.py` for an example of how to use this hook
|
||||
to contribute funds to a channel open.
|
||||
|
||||
e.g.
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "continue",
|
||||
"close_to": "bc1qlq8srqnz64wgklmqvurv7qnr4rvtq2u96hhfg2"
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZrrw28Oed52hTw3N7t0HbIyZhFdcZRH3+61AQAAAAD9////AGYAAAAAAQDfAgAAAAABARtaSZufCbC+P+/G23XVaQ8mDwZQFW1vlCsCYhLbmVrpAAAAAAD+////AvJs5ykBAAAAFgAUT6ORgb3CgFsbwSOzNLzF7jQS5s+AhB4AAAAAABepFNi369DMyAJmqX2agouvGHcDKsZkhwJHMEQCIHELIyqrqlwRjyzquEPvqiorzL2hrvdu9EBxsqppeIKiAiBykC6De/PDElnqWw49y2vTqauSJIVBgGtSc+vq5BQd+gEhAg0f8WITWvA8o4grxNKfgdrNDncqreMLeRFiteUlne+GZQAAAAEBIICEHgAAAAAAF6kU2Lfr0MzIAmapfZqCi68YdwMqxmSHAQQWABQB+tkKvNZml+JZIWRyLeSpXr7hZQz8CWxpZ2h0bmluZwEIexhVcpJl8ugM/AlsaWdodG5pbmcCAgABAA==",
|
||||
"accepter_funding_msat": "39999000msat"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Note that `close_to` must be a valid address for the current chain,
|
||||
an invalid address will cause the node to exit with an error.
|
||||
|
||||
Note that `openchannel` is a chained hook. Therefore `close_to` will only be
|
||||
evaluated for the first plugin that sets it. If more than one plugin tries to
|
||||
set a `close_to` address an error will be logged.
|
||||
|
||||
|
||||
### `openchannel2_changed`
|
||||
|
||||
This hook is called when we received updates to the funding transaction
|
||||
from the peer.
|
||||
|
||||
```json
|
||||
{
|
||||
"openchannel2_changed": {
|
||||
"channel_id": "252d1b0a1e57895e841...",
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZr..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In return, we expect a `result` indicated to `continue` and an updated `psbt`.
|
||||
If we have no updates to contribute, return the passed in PSBT. Once no
|
||||
changes to the PSBT are made on either side, the transaction construction
|
||||
negotation will end and commitment transactions will be exchanged.
|
||||
|
||||
#### Expected Return
|
||||
```json
|
||||
{
|
||||
"result": "continue",
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZr..."
|
||||
}
|
||||
```
|
||||
|
||||
See `tests/plugins/df_accepter.py` for an example of how to use this hook
|
||||
to continue a v2 channel open.
|
||||
|
||||
|
||||
### `openchannel2_sign`
|
||||
|
||||
This hook is called after we've gotten the commitment transactions for a
|
||||
channel open. It expects psbt to be returned which contains signatures
|
||||
for our inputs to the funding transaction.
|
||||
|
||||
```json
|
||||
{
|
||||
"openchannel2_sign": {
|
||||
"channel_id": "252d1b0a1e57895e841...",
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZr..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In return, we expect a `result` indicated to `continue` and an partially
|
||||
signed `psbt`.
|
||||
|
||||
If we have no inputs to sign, return the passed in PSBT. Once we have also
|
||||
received the signatures from the peer, the funding transaction will be
|
||||
broadcast.
|
||||
|
||||
#### Expected Return
|
||||
```json
|
||||
{
|
||||
"result": "continue",
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZr..."
|
||||
}
|
||||
```
|
||||
|
||||
See `tests/plugins/df_accepter.py` for an example of how to use this hook
|
||||
to sign a funding transaction.
|
||||
|
||||
|
||||
### `rbf_channel`
|
||||
|
||||
Similar to `openchannel2`, the `rbf_channel` hook is called when a peer
|
||||
requests an RBF for a channel funding transaction.
|
||||
|
||||
```json
|
||||
{
|
||||
"rbf_channel": {
|
||||
"id": "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
|
||||
"channel_id": "252d1b0a1e57895e84137f28cf19ab2c35847e284c112fefdecc7afeaa5c1de7",
|
||||
"their_funding": "100000000msat",
|
||||
"funding_feerate_per_kw": 7500,
|
||||
"feerate_our_max": 10000,
|
||||
"feerate_our_min": 253,
|
||||
"locktime": 2453,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The returned result must contain a `result` member which is either
|
||||
the string `reject` or `continue`. If `reject` and
|
||||
there's a member `error_message`, that member is sent to the peer
|
||||
before disconnection.
|
||||
|
||||
For a 'continue'd result, you can include a `psbt` and an
|
||||
`our_funding_msat` to contribute funds, inputs and outputs to
|
||||
this channel open.
|
||||
|
||||
Note that, like the `openchannel_init` RPC call, the `our_funding_msat`
|
||||
amount must NOT be accounted for in any supplied output. Change,
|
||||
however, should be included and should use the `funding_feerate_per_kw`
|
||||
to calculate.
|
||||
|
||||
#### Return
|
||||
|
||||
```json
|
||||
{
|
||||
"result": "continue",
|
||||
"psbt": "cHNidP8BADMCAAAAAQ+yBipSVZrrw28Oed52hTw3N7t0HbIyZhFdcZRH3+61AQAAAAD9////AGYAAAAAAQDfAgAAAAABARtaSZufCbC+P+/G23XVaQ8mDwZQFW1vlCsCYhLbmVrpAAAAAAD+////AvJs5ykBAAAAFgAUT6ORgb3CgFsbwSOzNLzF7jQS5s+AhB4AAAAAABepFNi369DMyAJmqX2agouvGHcDKsZkhwJHMEQCIHELIyqrqlwRjyzquEPvqiorzL2hrvdu9EBxsqppeIKiAiBykC6De/PDElnqWw49y2vTqauSJIVBgGtSc+vq5BQd+gEhAg0f8WITWvA8o4grxNKfgdrNDncqreMLeRFiteUlne+GZQAAAAEBIICEHgAAAAAAF6kU2Lfr0MzIAmapfZqCi68YdwMqxmSHAQQWABQB+tkKvNZml+JZIWRyLeSpXr7hZQz8CWxpZ2h0bmluZwEIexhVcpJl8ugM/AlsaWdodG5pbmcCAgABAA==",
|
||||
"our_funding_msat": "39999000msat"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### `htlc_accepted`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user