Update Protocol

graph LR ms-->ttt ms-->fb subgraph off-chain state fb["<b>Free Balance</b> (ETH) <br> Local Nonce: <tt>k + 1</tt> <br> Alice has 9 ETH <br> Bob has 9 ETH"] ttt["<b>TicTacToe App</b> <br> Local Nonce: 1 <br> Winner gets 2 ETH <br><center><b><tt>| X | &nbsp; | &nbsp; |<br>| &nbsp; | &nbsp; | &nbsp; |<br>| &nbsp; | &nbsp; | &nbsp; |</tt></b></center>"] end subgraph on-chain state ms["<b>AB Multisignature Wallet</b> <br> Balance: 20 ETH"] end

Once an application has been installed into the state channel, the multisignature wallet has transferred control over the installed amount from the free balance to the application’s computeOutcome function, a mapping from application state to funds distribution. For example, in the case of Tic-Tac-Toe, a possible payout function is: if X wins, Alice gets 2 ETH, else if O wins Bob gets 2 ETH, else send 1 ETH to Alice and Bob.

As the underlying state of the application changes, the result of the payout function changes. It is the job of the Update Protocol to mutate this state, independently of the rest of the counterfactual structure.

Using our Tic-Tac-Toe example, if Alice decides to place an X on the board, Alice could run the Update Protocol, transitioning our state to what is represented by the figure above. Notice how both the board changes and the local versionNumber for the app is bumped from 0 to 1. To play out the game, we can continuously run the update protocol, making one move at a time.


Two users run the protocol. They are designated as initiator and responder.


sequenceDiagram Alice->>+Bob: SetState Bob-->>-Alice: SetStateAck

For the below messages, the digest that is signed is represented as the following (reference: computeAppChallengeHash)

  ["bytes1", "bytes32", "uint256", "uint256", "bytes32"],
    keccak256(                        //
      abi.encode(                     //
        [uint256, address[]],         // NOTE: This is the
        [channelNonce, participants]  // appInstanceIdentityHash
      )                               //
    ),                                //

Type: UpdateParams

Field Type Description
appIdentityHash bytes32 Identifies app instance to update
newState JSON New state to set to

The SetState Message

Field Description
protocol "update"
params An UpdateParams object
fromAddress The address of initiator
toAddress The address of responder
seq 1
signature initiator's signed commitment digest

The SetStateAck Message

Field Description
protocol "update"
fromAddress The address of responder
toAddress The address of initiator
seq 2
signature responder's signed commitment digest


Commitment for SetState and SetStateAck:

The commitment can be visually represented like:

graph LR subgraph ChallengeRegistry setState setState-->appIdentity:AppIdentity setState-->req:SignedStateHashUpdate end

This transaction invoke the setState function with the signatures exchanged during the protocol.