commitment_revocation -- Hook fired when a commitment transaction is revoked

DESCRIPTION

The commitment_revocation hook is called whenever a channel state is updated, and the old state was revoked. State updates in Lightning consist of the following steps:

Proposal of a new state commitment in the form of a commitment transaction
Exchange of signatures for the agreed upon commitment transaction
Verification that the signatures match the commitment transaction
Exchange of revocation secrets that could be used to penalize an eventual misbehaving party

The commitment_revocation hook is used to inform the plugin about the state transition being completed, and deliver the penalty transaction. The penalty transaction could then be sent to a watchtower that automatically reacts in case one party attempts to settle using a revoked commitment.

This is a chained hook: multiple plugins may be registered.

HOOK PAYLOAD

commitment_txid (txid): The txid of the revoked commitment transaction.
penalty_tx (hex): The penalty transaction that can spend the revoked commitment. Can be sent to a watchtower for enforcement.
channel_id (hash): The channel_id for which the revocation occurred. (added v0.10.2)
commitnum (u64): The commitment number identifying the revoked state. (added v0.10.2)

HOOK RETURN

result (string) (always "continue"): Plugins should always return "continue", otherwise subsequent hook subscribers would not get called.