Archives/chantools
2
0
Fork 0
mirror of https://github.com/guggero/chantools synced 2024-11-15 06:12:49 +00:00
Code Issues Releases Wiki Activity

README+doc: fix formatting and small nits

Browse Source
This commit is contained in:
Oliver Gugger 2022-05-02 15:26:26 +02:00
parent b8d5e07e3e
commit b857a1a693
No known key found for this signature in database
GPG Key ID: 8E4256593F177720
2 changed files with 89 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -29,7 +29,7 @@ Example (make sure you always use the latest version!):
```shell ```shell
$ cd /tmp $ cd /tmp
$ wget -O chantools.tar.gz https://github.com/guggero/chantools/releases/download/v0.7.1/chantools-linux-amd64-v0.7.1.tar.gz $ wget -O chantools.tar.gz https://github.com/guggero/chantools/releases/download/v0.10.4/chantools-linux-amd64-v0.10.4.tar.gz
$ tar -zxvf chantools.tar.gz $ tar -zxvf chantools.tar.gz
$ sudo mv chantools-*/chantools /usr/local/bin/ $ sudo mv chantools-*/chantools /usr/local/bin/
``` ```
@ -38,7 +38,7 @@ $ sudo mv chantools-*/chantools /usr/local/bin/
If there isn't a pre-built binary for your operating system or architecture If there isn't a pre-built binary for your operating system or architecture
available or you want to build `chantools` from source for another reason, you available or you want to build `chantools` from source for another reason, you
need to make sure you have `go 1.13.x` (or later) and `make` installed and can need to make sure you have `go 1.16.x` (or later) and `make` installed and can
then run the following commands: then run the following commands:
```bash ```bash
@ -213,6 +213,10 @@ compacting the DB).
<br/><br/> <br/><br/>
Once you were contacted with a match, follow the instructions on the Once you were contacted with a match, follow the instructions on the
[Zombie Channel Recovery Guide](doc/zombierecovery.md) page. [Zombie Channel Recovery Guide](doc/zombierecovery.md) page.
<br/><br/>
If you know the peer of a zombie channel and have a way to contact them, you
can also skip the registration/matching process and [create your own match
file](doc/zombierecovery.md#file-format).
## Seed and passphrase input ## Seed and passphrase input

105
doc/zombierecovery.md
View File

@ -1,48 +1,106 @@
# Zombie Channel Recovery # Zombie Channel Recovery
## Read me first ## Read me first
It's useful to understand Zombie Channel recovery is one of the latest "desparate" steps in recovering balances. Basically the channel states are not known anymore: no one knows what the balances were (there is no channel DB, static channel backup did not work, force closing was not possible).
It's useful to understand Zombie Channel recovery is one of the latest
"desparate" steps in recovering balances. Basically the channel states are not
known anymore: no one knows what the balances were (there is no channel DB,
static channel backup did not work, force closing was not possible).
This means: This means:
1. Hou have to find the peer (which, if you want to do a zombie recovery, was probably offline if you tried to recover) 1. Hou have to find the peer (which, if you want to do a zombie recovery, was
probably offline if you tried to recover)
2. You have to find a way to contact this peer (twitter, email, ...) 2. You have to find a way to contact this peer (twitter, email, ...)
3. You and your peer will have to negotiate a closing state: you only know the total channel size, and neither of you knows with good confidence who owes what. _(Because if you did, you would be able to restore using the static channel backup or channel DB.)_ There might be some guessing involved here, or maybe you want to do a 50:50 split. 3. You and your peer will have to negotiate a closing state: you only know the
total channel size, and neither of you knows with good confidence who owes
what. _(Because if you did, you would be able to restore using the static
channel backup or channel DB.)_ There might be some guessing involved here,
or maybe you want to do a 50:50 split.
## Recovery steps ## Recovery steps
* Make sure you have your seed words ready, you will need these to generate addresses and prepare keys
* *Got a request from a counterparty* to prepare keys? Skip to step 4
* If you already have a way to contact your peer you can skip to step 3.
1. _(Optional -- only needed if you have no contact with the remote party)_ Register at [node-recovery.com](https://node-recovery.com). This web site helps you connect to peers, for recovery. You enter your public key and some way to reach you. Hopefully, a peer with whom you have a "crashed" channel, will also register. The site will inform you of the peer's contact details, and will send channel information. Preparation:
2. Got a message about a match? Congrats! You might be able to fix something together. Have a look in the recovery file, and look up the mentioned channel(s). Node-recovery has looked back at _their_ channel database and guessed if the channel needs to be recovered. Please check this, because if the guess was wrong, and the channel is active, you do not need to do this recovery at all and exit this guide! If you do not see it on your (recovered) node, continue: * Make sure you have your seed words ready, you will need these to generate
3. Send/upload the JSON file(s) to your node. If you open the JSON file(s), you will see your own node ID (and contact info) and the peers'. [Download or install chantools](https://github.com/guggero/chantools#installation). Technically, you do not _need_ to install chantools on the same machine as your node. Maybe you do not feel confident entering your seed words on your node and want to do this someplace else. addresses and prepare keys
4. Prepare the keys. Both parties will need to do this. The payout address is a bitcoin address your sats are sent to if you both agree on the offer (step 6). The final argument must be the match file, which you got in email. * *Got a request from a counterparty* to prepare keys? Skip to step 4 below.
* If you already have a way to contact your peer you can create your own match
file (see ["File format" section](#file-format)) and skip to step 3 below.
Steps:
1. _(Optional -- only needed if you have no contact with the remote party)_
Register at [node-recovery.com](https://node-recovery.com). This website
helps you connect to peers, for recovery. You enter your public key and some
way to reach you. Hopefully, a peer with whom you have a "crashed" channel,
will also register. The site will inform you of the peer's contact details,
and will send channel information.
2. Got a message about a match? Congrats! You might be able to fix something
together. Have a look in the recovery file, and look up the mentioned
channel(s). Node-recovery has looked back at _their_ channel database and
guessed if the channel needs to be recovered. Please check this, because if
the guess was wrong, and the channel is active, you do not need to do this
recovery at all and exit this guide! If you do not see it on your (recovered)
node, continue:
3. Send/upload the JSON file(s) to your node. If you open the JSON file(s), you
will see your own node ID (and contact info) and the peers'. [Download or
install chantools](https://github.com/guggero/chantools#installation).
Technically, you do not _need_ to install `chantools` on the same machine as
your node. Maybe you do not feel confident entering your seed words on your
node and want to do this someplace else.
4. Prepare the keys. Both parties will need to do this. The payout address is a
bitcoin address your sats will be sent to if you both agree on the offer
(step 6). The final argument must be the match file, which you got in email.
``` ```
./chantools zombierecovery preparekeys --payout_addr bc1xxx --match_file /tmp/match.json chantools zombierecovery preparekeys --payout_addr bc1xxx --match_file /tmp/match.json
``` ```
5. The command will output a file in the `results/` folder (relative from where you ran the command, so after the command finished you can probably do `cd results/` to go to the results folder. Type `ls` to view the files. You can view the result in a text editor (`nano preparedkeys*`), it's regular readable text. It has the contact info of the counterparty. Now is a good time to contact the peer. You can attach your preparedkeys file and propose a fee rate (sat/vB). Ask them to prepare keys too. 5. The command will output a file in the `results/` folder (relative from where
6. Either your counterparty or you will make an offer. As explained in the "read me first", there might be some guessing needed here. Basically the offer proposes a way to split the channel balance among you and your peer. If you sent your preparedkeysfile, your counterparty has enough information to create an offer. If they send their preparedkeysfile to you, you can create the offer. This has a split, which you might need to discuss with your peer. Either way, the command to advance to the next step is: you ran the command, so after the command finished you can probably do
`cd results/` to go to the results folder. Type `ls` to view the files. You
can view the result in a text editor (`nano preparedkeys*`), it's regular
readable text. It has the contact info of the counterparty. Now is a good
time to contact the peer. You can attach your preparedkeys file and propose a
fee rate (sat/vB). Ask them to prepare keys too.
6. Either your counterparty or you will make an offer. As explained in the
["Read me first" section](#read-me-first), there might be some guessing
needed here. Basically the offer proposes a way to split the channel balance
among you and your peer. If you sent your preparedkeysfile, your counterparty
has enough information to create an offer. If they send their
preparedkeysfile to you, you can create the offer. This has a split, which
you might need to discuss with your peer. Either way, the command to advance
to the next step is:
``` ```
chantools zombierecovery makeoffer \ chantools zombierecovery makeoffer \
--node1_keys preparedkeys-xxxx-xx-xx-<pubkey1>.json \ --node1_keys preparedkeys-xxxx-xx-xx-<pubkey1>.json \
--node2_keys preparedkeys-xxxx-xx-xx-<pubkey2>.json \ --node2_keys preparedkeys-xxxx-xx-xx-<pubkey2>.json \
--feerate 15 --feerate 15
``` ```
7. The output is a PSBT. It's signed by the party which created the offer. This must now be signed by the other party (thereby accepting the offer): 7. The output is a PSBT. It's signed by the party which created the offer. This
must now be signed by the other party (thereby accepting the offer):
``` ```
chantools zombierecovery signoffer \ chantools zombierecovery signoffer \
--psbt <offered_psbt_base64> --psbt <offered_psbt_base64>
``` ```
9. After signing, the transaction can be broadcast. From the PSBT (_partially signed_ bitcoin transaction), by signing, you have now (together) created a proper bitcoin transaction. An offer has been made, you have agreed on what split ("piece of the pie") goes to whom, created a transaction, signed it. This completed transaction can now be sent, for example using `bitcoin-cli sendrawtransaction`. 9. After signing, the transaction can be broadcast. From the PSBT (_partially
signed_ bitcoin transaction), by signing, you have now (together) created a
proper bitcoin transaction. An offer has been made, you have agreed on what
split ("piece of the pie") goes to whom, created a transaction, signed it.
This completed transaction can now be sent, for example using
`bitcoin-cli sendrawtransaction`.
## File format ## File format
For reference, the file format is below. If you get a match from node-recovery, the file looks like below example. It's human readable JSON, and you need to open the file to see the contact details.
For reference, the file format of the "match" file is below. If you get a match
from node-recovery.com, the file looks like below example. It's human-readable
JSON, and you need to open the file to see the contact details. Use any plain
text editor to open the file.
Components: Components:
* node1 and node2 are the peers of the channel, with contact details. This is not needed by chantools, you will use it to contact your peer * `node1` and `node2` are the peers of the channel, with contact details. This
* Then there is a list of channels, often just one though. It has meta data as seen by the network. is not needed by `chantools`, you will use it to contact your peer.
* As you are taking the steps above, the file format will be appended. For example, after step 4 (preparing keys), the file will have a list of `multisig_keys` for the node who prepared the keys. * Then there is a list of channels, often just one though. It has metadata as
seen by the network.
* As you are taking the steps above, the file format will be appended. For
example, after step 4 (preparing keys), the file will have a list of
`multisig_keys` for the node who prepared the keys.
```json ```json
{ {
@ -65,7 +123,10 @@ Components:
} }
``` ```
It's encouraged to look at the file, and what the files look like after doing the steps. It's encouraged to look at the file, and what the files look like after doing
each of the steps.
## More info ## More info
_More info at the help output of `chantools zombierecovery --help` or the generated [documentation for the zombierecovery command](chantools_zombierecovery.md)._ _More info at the help output of `chantools zombierecovery --help` or the
generated [documentation for the zombierecovery
command](chantools_zombierecovery.md)._