Home

Awesome

What is it

Fiat channels is a derived concept from original Hosted channels, or HC, proposal by Anton Kumaigoroski. Channels of this type were initially implemented in Bitcoin Lightning Wallet and since then continued in new Simple Bitcoin Wallet and IMMORTAN library.

Notable differences to the original Hosted channels RFC:

For the sake of convenience original RFC is mostly preserved.

Specifics

Fiat rate

There are three scenarios when the Host adjust the fiat rate of the channel.

Receiving payment

The scenario occurs when update_add_htlc message is sent from the Host to the Client. The new rate is calculated as average weighted summ of the old rate and new one:

newRate = round((old_balance * old_rate + payment_size * new_rate) / (old_balance + payment_size))

Note that old_rate and new_rate are reverse rates USD/BTC from the state_update and current state rates (they are msat/USD). Host places the new rate value inside the state_update message, signs it and sends it to the Client. The Client restores remote state with the new channel rate, signs it and proceed with their own state_update message as usual.

Sending payment

TODO

Sending with resize

TODO

Invoking

The invoke_hosted_channel Message

  1. type: 75535 (invoke_hosted_channel)
  2. data:

Rationale

The init_hosted_channel Message

  1. type: 75533 (init_hosted_channel)
  2. data:

Rationale

The last_cross_signed_state Message

  1. type: 75531 (last_cross_signed_state)
  2. data:

Rationale

Normal operation

The state_update Message

  1. type: 75529 (state_update)
  2. data:

Rationale

Failure and state overriding

Normal channel operation may be interrupted in a number of ways (incorrect state update numbers, signature, timed out outgoing HTLC etc). Once this happens a peer must put a channel in SUSPENDED state and send out an Error message. Hosted channel use tagged errors with first two bytes of Error message reserved for the following cases:

0001: Wrong blockday in a remote message. 0002: Wrong local signature from remote message. 0003: Wrong remote signature from remote message. 0005: Too many state_update messages without reaching of new local last_cross_signed_state (more than 16 in a row). 0006: Timed out outgoing HTLC. 0007: Remote peer has lost all upstream channels and can't resolve in-flight routed HTLCs. 0008: Hosted channel denied by Host when Client was trying to invoke it.

Normal operation may be resumed after channel gets SUSPENDED by Host sending a state_override message to Client which would erase all previous problematic state and set a new agreed upon balance breakdown. Client must manually accept this message which would send a state_update in return. Client's wallet UI/UX must be especially explicit about what is going on in this situation.

    +-------+                                           +-------+
    |       |<---------- state_override ----------------|       | // A has new local `last_cross_signed_state`
    |   A   |----------- state_update ----------------->|   B   | // B has new local `last_cross_signed_state`
    +-------+                                           +-------+

    Where B is Host and A is Client

The state_override Message

  1. type: 75527 (state_override)
  2. data:

Data format for channel state snapshot

When resolving disputes after a channel got SUSPENDED it may be necessary for a Client to manually provide a channel state snapshot which contains last cross signed state along with subsequent updates from both peers, those may include update_fulfill_htlc messages with preimages which can be used by Host to manually fulfill outstanding HTLCs. Otherwise channel snapshot must not contain any other types of secrets.

The hosted_state Message

  1. data:

Resolving edge cases

Peer misses a channel or falls behind

This situation is to be resolved in a standard way described in last_cross_signed_state Rationale.

Receiver stops responding while incoming payment is in-flight

Issue: malicious or offline peer may accept update_add_htlc and a following state_update without ever replying. In this situation sender has a limited time to either fulfill a payment downstream (which would require obtaining a preimage from non-responding peer) or fail it, otherwise sender risks downstream channel getting remotely force-closed.

Solution: similar to how this is handled in normal channels, right before CLTV timelock is about to expire a sender must put a hosted channel into SUSPENDED mode and fail a payment upstream. Hosted channel can be put back to operational mode at a later time by exchaning state_override messages where receiver balance is adjusted such that failed in-flight HTLC is removed.

Sender stops responding on obtaining a preimage

Issue: on receiving update_fulfill_htlc sender may use a preimage to fulfill a payment upstream and stop responding to receiver. Sender would thus get the funds into its upstream channel while receiver won't have an updated last_cross_signed_state with payment resolved.

Solution: the goal here is not to enforce payment receiving since this is impossible for hosted channels but to cryptographically prove that malicious behaviour has taken place on sender side. This is achieved in a following way:

  1. When sender transmits update_add_htlc to receiver and expects update_fulfill_htlc in return this can only mean that sender already has a committed in-flight payment upstream which can be unconditionally resolved once sender knows a preimage.

  2. After receiving update_add_htlc followed by state_update receiver has a new last_cross_signed_state where sender has signed an obligation to provide X funds to receiver if receiver reveals a preimage within next Y blocks (a CLTV expiry delta).

  3. When having this data along with preimage revealed (update_fulfill_htlc sent) a sender software must notify an owner if payment is not getting resolved within a reasonable time frame, but well before CLTV deadline (otherwise sender could claim receiver just was not cooperating so sender had to fail a payment on CLTV expiry). Sender is then expected to take action which can range from contacing receiver support to revealing a last_cross_signed_state along with preimage publically, thus giving sender no chance of denying that active in-flight HTLC exists and respected preimage is revealed. Note that for this to work a final CLTV window set by receiver software should be large enough, at least 285 blocks is recommended.

Host decides to refund a channel on-chain using Client's refund_scriptpubkey

Issue: After doing that Client may show up with last last_cross_signed_state claiming that funds are still in a hosted channel.

Solution: Host must wait at least 1 blockday until broadcasting an on-chain refunding transaction, in that case it will be included in a block whose blockday is higher than the one contained in Client's last_cross_signed_state. This will prove that refund has happened after any last known channel activity. After refunding this way hosted channel data may be safelly removed from Host database.