State Channels API Notes

Meeting notes 👇

+Shared Meeting Notes 

Channel Provider Spec RFC (WIP)

Rest of this doc:


If you’re reading this, this document is a rough overview of what the high level API of a generalized state channels network looks like based on some aggregation of the various techniques seen so far.

Please feel free to add to the document or add comments before the workshop begins.

Depositing & Withdrawing State Deposits into a State Deposit Holder (on-chain)
Before a state channel can have any kind of usefulness, the most important functionality is to support depositing state deposits (e.g., ETH, ERC20 tokens, etc) into the channel construction. Essentially, this moves on-chain state in the possession of a user’s account to off-chain state in the possession of the state deposit holder on-chain and the user off-chain.

These are the key APIs used for on-boarding and off-boarding.
API Method
Description
deposit
Co-operatively deposit state into a state channel’s state deposit holder
withdraw
Co-operatively withdraw state out of a state channel’s state deposit holder

Related concepts / similar API method ideas:
  • openChannel: The “open channel” concept is a specific instance of the deposit API method. It can be thought of simply the first time a deposit is made. An engineering optimization in the contracts is to make all channels “already open” in a sense and ready to be deposited into.
  • dynamicDeposit: This is the name Celer Network gives to the generic deposit method.
  • closeChannel: In the same way that “open channel” is just making the first deposit, “close channel” is just withdrawing all of the state out of the channel.
  • cooperativeWithdraw: This is the name Celer Network gives to the withdraw method.

📟 Application Lifecycle (off-chain)
These are the APIs to progress the lifecycle of a particular state channel application. Roughly speaking, this life cycle include a “starting up” phase, a “state exchange” phase and a “tear down” phase, cooperatively or through on-chain settlement. 

Starting of an application
API Method
Description
createApp/ createChannel
Participants agree on a nonce of a particular new app to be funded in future
sendConditionalPayment
Executes an off-chain payment with a condition attached to it
installApp / fundApp
Allocates some of the deposit in a state deposit holder to an off-chain use case
uninstallApp
De-allocates of the deposit in a state deposit holder from an off-chain use case
resolveConditionGroup
Resolve a certain conditional dependency in the state channel network.

State progression of an application
API Method
Description
proposeState
A method to update the state of an off-chain app.
takeAction / makeMove
A method to take an action / make a move if a state machine paradigm exists.

Handling Protocol Failures
The most common kind of protocol failure has, based on FunFair and Celer’s experience, been one user not responding to the rest. This is counter-party unresponsiveness / the “connectivity issue".
API Method
Description
instantiateApp
Instantiate the application contract on-chain and validate the most recent state during connectivity challenge and hand over control to normal web-3 flow.
intendSettle / setState
First leg of forced settlement, triggers a timeout challenge. Initiate the connectivity challenge. Triggers a timeout. If state is resolvable, can put resolution on chain as engineering optimization.
confirmSettle 
Second leg of forced settlement, resolve the base-layer on-chain state(fund) deposit.
setStateAndAction / forceMove
Sets state on chain and takes the required action to progress it one step forward
progressDispute / respondToChallenge
Progresses the state machine if there is a valid action to take