Finalizing a channel
Finalization of a state channel is a necessary step before defunding it. It can happen on- or off-chain.
In the so-called 'happy' case, all participants cooperate to achieve this.
A participant wishing to end the state channel will sign a state with
isFinal = true. Then, the other participants may support that state. Once a full set of
n such signatures exists (this set is known as a finalization proof) the channel is said to be 'closed' or 'finalized'.
In most cases, the channel would be finalized and defunded off chain, and no contract calls are necessary.
On chain -- calling
In the case where assets were deposited against the channel on chain (the case of direct funding), anyone in possession of a finalization proof may use it to finalize the
outcome on-chain. They would do this by calling
conclude on the adjudicator. This enables assets to be released.
The conclude method allows anyone with sufficient off-chain state to immediately finalize an outcome for a channel without having to wait for a challenge to expire (more on that later).
The off-chain state(s) is submitted (in an optimized format), and once relevant checks have passed, an expired challenge is stored against the
channelId. (This is an implementation detail -- the important point is that the chain shows that the channel has been finalized.)
When cooperation breaks down, it is possible to finalize a state channel without requiring on-demand cooperation of all
n participants. This is the so-called 'sad' path to finalizing a channel, and it requires a supported (but not necessarily
isFinal) state(s) being submitted to the chain.
challenge function allows anyone holding the appropriate off-chain state(s) to register a challenge state on chain. It is designed to ensure that a state channel can progress or be finalized in the event of inactivity on behalf of a participant (e.g. the current mover).
The required data for this method consists of a single state, along with
n signatures. Once these are submitted (in an optimized format), and once relevant checks have passed, an
outcome is registered against the
channelId, with a finalization time set at some delay after the transaction is processed.
This delay allows the challenge to be cleared by a timely and well-formed respond or checkpoint transaction. We'll get to those shortly. If no such transaction is forthcoming, the challenge will time out, allowing the
outcome registered to be finalized. A finalized outcome can then be used to extract funds from the channel (more on that below, too).
challengeDuration is a fixed parameter expressed in seconds, that is set when a channel is proposed. It should be set to a value low enough that participants may close a channel in a reasonable amount of time in the case that a counterparty becomes unresponsive; but high enough that malicious challenges can be detected and responded to without placing unreasonable liveness requirements on responders. A
challengeDuration of 1 day is a reasonable starting point, but the "right" value will likely depend on your application.
The challenger needs to sign this data:
in order to form
challengerSig. This signals their intent to challenge this channel with this particular state. This mechanism allows the challenge to be authorized only by a channel participant.
We provide a handy utility function
signChallengeMessage to form this signature.
A challenge being registered does not mean that the channel will inexorably finalize. Participants have the timeout period in order to be able to respond. Perhaps they come back online after a brief spell of inactivity, or perhaps the challenger was trying to (maliciously) finalize the channel with a supported but outdated (or 'stale') state.
Clear a challenge
checkpoint method allows anyone with a supported off-chain state to establish a new and higher
turnNumRecord on chain, and leave the resulting channel in the "Open" mode. It can be used to clear a challenge.
It is important to understand that a challenge may be "cleared" by another more recent challenge. The channel will be left in challenge mode (so it has not really been 'cleared' in that sense), but some on chain storage will be updated, such as the deadline for responding.
Extract info from Adjudicator Events
You may have noticed that to respond, the challenge state itself must be (re)submitted to the chain. To save gas, information is only stored on chain in a hashed format. Clients should, therefore, cache information emitted in Events emitted by the adjudicator, in order to be able to respond to challenges.