standardsats / plugin-hosted-channels Goto Github PK

• Obtain compatible Eclair release source code and compile it:

$ cd <eclair>
$ git checkout v0.7.0
$ mvn clean install -DskipTests=true

HC plugin depends on AlarmBot plugin to send out custom Telegram messages, and Eclair instance must be run with both of these plugins added, compile AlarmBot as follows:

$ cd <eclair-alarmbot-plugin>
$ mvn clean install -DskipTests=true

JAR file can be found in <eclair-alarmbot-plugin>/target folder.

$ cd <plugin-hosted-channels>
$ mvn clean install -DskipTests=true

JAR file can be found in <plugin-hosted-channels>/target folder.

1. Install Postgresql.
2. Create a new db called hc for example, same db name should be provided in HC config file.
3. Create a folder <eclair datadir>/plugin-resources/hosted-channels/.
4. Copy hc.conf file found in this repository into that folder and edit it accordingly.
5. Setup AlarmBot as specified in its readme.
6. Run eclair-node-<version>-<commit_id>/bin/eclair-node.sh 'hc-assembly-0.2.jar' 'eclair-alarmbot.jar'.

HC plugin extends base Eclair API with HC-specific methods.
HC API is accessed in a same way as base API e.g. ./eclair-cli.sh hc-phcnodes.

HC gets suspended for same reasons normal channels get force-closed: for example due to receiving an invalid state update signature or an out-of-sync update, or because of expired outgoing HTLC. Once suspended, a Host may issue an hc-overridepropose command with a new balance distribution. If Client accepts it by issuing hc-overrideaccept command then new HC state gets cross-signed and channel becomes operational again.

A tricky point here is that HC may get suspended while having incoming and outgoing active HTLCs, and this situation requires careful handling from Host and Client to properly calculate a new balance in hc-overridepropose. Specifically, Host must wait until all active HTLCs get resolved in one way or another, and only after that it's safe to propose an override.

For OUT ... -> Host -> Client -> ... payments there are 3 ways in which these HTLCs may get resolved:

1. Either Client provides a preimage for related HTLC off-chain before HTLC's CLTV expiry: in this case Host node resolves a payment upstream using a preimage immediately, and resolved payment info will be seen in logs later when Host inspects a suspended HC. An UpdateFulfillHtlc message will also be present in nextRemoteUpdates list of suspended HC.
2. Or Client provides a preimage on-chain via hc-broadcastpreimages command before HTLC's CLTV expiry: given that Host listens to Blockchain live data a suspended HC will be notified with chain-extracted preimage once it gets included in a block, and further progress will be similar to the first case.
3. Or client keeps doing nothing: in this case Host node waits until HTLC's CLTV expires and then fails a payment upstream.

In general this means that before issuing hc-overridepropose Host must make sure that all Host -> Client HTLCs are either fulfilled by Client in one way or another, or chain height got past all CLTV expiries. All fulfilled Host -> Client HTLCs must be subtracted from new Host HC balance, all failed ones must be added to new Host HC balance.

For IN ... <- Host <- Client <- ... payments Host must wait until they either get failed or fulfilled downstream. All fulfilled Host <- Client HTLCs must be added to new Host HC balance, all failed ones must be added to new Client HC balance.

A distinguishing feature of HC is that although its balance can not be enforced on chain it can be cryptographically proved at all times so issues can be resolved in standard ways and scam attempts are clearly visible by everyone.

First thing which can be proved is HC balance excluding in-flight HTLCs: each state update in HC contains balance distribution and gets cross-signed by both channel sides while having a monotonically increasing counter. Thus, any side of channel can claim that its cross-signed state is the latest one, the other side can refute this claim by providing a cross-signed update with a higher counter value, and they both can keep doing this until one of them fails to provide.

Second thing which can be proved is in-flight payment owner, but this one is more involved and may require an action to be taken. Any HTLC can be seen as the following contract: either receiving side can provide a secret preimage before certain block height and get the money or fail to do that, in which case money returns to sending side. This enables an adversarial condition where reciving side reveals a preimage but sender refuses to update channel state such that it clears an in-flight HTLC and assigns payment value to receiver.

In normal channels this is resolved by receiver force-closing a channel and using a preimage to obtain an in-flight payment on chain. In HC this is impossible, but receiver still can prove at a later time that he had revealed a preimage before HTLC expiry by embedding a preimage into blockchain by means of OP_RETURN.

This works as follows: after preimage for incoming HTLC has been revealed but channel state has not been updated for a number of blocks, and well before HTLC expiry a receiver would get a Telegram warning. After that receiver may broadcast an OP_RETURN transaction with a preimage using hc-broadcastpreimages API call. At a later time receiver will be able to demonstrate the latest cross-signed HC state with HTLC in-flight and a transaction with related preimage existing in a blockchain before HTLC expiry block.

Any pair of nodes can establish an HC and declare it public. By doing this HC routing parameters get gossiped to other HC-supporting nodes which form a parallel routing graph consisiting only of public HCs, which then in turn gets merged with normal channel graph. An effect of this is increased network liquidity and more routed payments.

There are 3 requirements which both public HC nodes must meet:

• Each node must have and keep maintaining at least 5 normal public channels.
• Each pair of nodes can have only one public HC declared between them.
• Each node can have at most 2 public HCs declared.

Failure to meet any of these requirements will make a public HC ignored by other nodes which follow these rules.

Once Eclair node has in-flight payments in HCs it must always be launched with HC plugin after restarts, otherwise money loss may happen. If one wishes to stop using an HC plugin then one should first make sure there are no in-flight HTLCs left in HCs (hc-hot and channels API methods are helpful here to determine which HTLCs are still pending in both HCs and normal channels).