​​State Channels API Notes

​​Meeting notes ​👇​

​​​+Shared Meeting Notes​ 

​​Channel Provider Spec RFC (WIP)

​​​+Channel Provider Specification​ 

​​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
​​