Development Update #1–01.10.2019 – Counterfactual – Medium

Happy new year, ethereum!

We’re hitting the ground running in 2019, and expect this to be a huge year for the ecosystem in general and Counterfactual in particular. Watch this space for regular updates every two weeks.

📱 Application updates:

  • Chris Buckland is experimenting with channelizing MixEth. You can read about how he approached this here, deck from a recent presentation here, and find the code here.
  • Bruno Skvorc is building a POC called Valhello, an ethereum-based MUD. He’s going to experiment with Counterfactual, Loom, and Substrate to better understand each.

⚙️ Development updates:

Our current focus right now is to ship the Counterfactual Playground: a full end-to-end implementation of all parts of the Counterfactual stack, which includes demo applications & a demo environment.

We expect to ship the Playground in the next few weeks.

We’re building the Playground to demonstrate Counterfactual’s potential to the ethereum developer community. The Playground will feature multiple applications running in the same state channel, in a real-world environment (the browser), live on the Ropsten testnet.

Our focus is on building useful demo applications, with all the nuts and bolts available to read about on GitHub, to inspire developers to build Dapps with state channels.

So, where are we on the journey to shipping the Playground? Below we describe the different components of the Playground, and give updates on development of each.

If you want to first understand more about what Counterfactual is, and how it works, check out our previous development update here.


Our current research is focused on creating a clear written protocol for message exchange specifications and ethereum-based transactions. We have already specified these for the Install, Update, Uninstall, and Setup protocols, which are detailed at

Our next step is to finalize the VirtualAppInstallProtocol and add it to our specs repo.


The contract code implements the on-chain adjudication methods for situations where there is a communication breakdown between clients trying to use the Counterfactual protocol.

When users sign messages (according to the format described in the specifications), they are signing commitments that pertain to specific function calls in the on-chain contracts.

The last update to the contract code required to release the Playground is to add a parameter to the setState method supporting a specific kind of commitment required for virtual applications. Otherwise, everything else is implemented and ready for the Playground release.

Message Exchange & Ethereum Commitments Implementation (machine)

Clients which “speak” the Counterfactual protocol need to actually generate, and then sign, the particular transactions required by the protocol. This is implemented in the machine package right now, and has full support for the Install, Update, Uninstall, and Setup protocols.

Next steps are:

  • Add the Commitments implementation required for a VirtualApp to exist
  • Implement the method on the StateChannel model for installVirtualApp
  • Implement the state transition functions in the InstallVirtualAppProtocol “flow” that uses the above two mentioned functions

Client Node That Stores State & Handles Incoming Messages

The actual stateful class that is instantiated inside the browsers of our users on the Playground Demo is called the Node and it (a) stores the latest signed state of all channels, (b) sends and receives all messages for protocol exchanges and (c) registers all related middleware in the machine for things like signing messages using a private key stored in memory and saving all commitments to a database for use in the case of a dispute. Presently the Node supports proposeInstall, install, and addAppInstance.

Next steps are:

  • Finish connecting the Node to the machine APIs
  • Connecting the middleware to enforce correct signing by the locally stored private key
  • Connecting the middleware to store generated commitments in a database
  • Implement the additional methods that clients need as specified in the CF.js API reference


The NodeProvider is a small library that facilitates communication over the browser’s postMessage API. This enables Dapps to securely communicate with a Counterfactual Node, running inside the Playground UI, and in the near future, hopefully running within wallets like Metamask. The NodeProvider is complete and ready for the Playground launch.

High Roller Dapp

High Roller is one of the demo applications that users can try out in the Playground. It lets two users roll two dice and the person with the higher sum of the rolled dice faces wins all of the funds bet by the users.

This Dapp is a standalone web application written with TypeScript and Stencil.js that imports CF.js and uses the API to install an appInstance for itself and update the state of the application according to the rules of the game (as defined by a HighRollerDapp smart contract with an applyAction function).

Tic Tac Toe Dapp

We needed at least two demo applications to show off how Counterfactual can run multiple apps within a single channel, so we’ve recently added Tic Tac Toe to the Playground. It’s written in React and also uses our CF.js library in a similar way as High Roller.

Playground UI

To run state channel enabled Dapps inside the browser, we needed an environment to approximate what a state channel enabled wallet would do. Concretely, this means we need a semi-persistent process that runs the Counterfactual Node code and can present confirmation UIs to the user. This is the core purpose of the Playground UI. It’s a web app that instantiates the Node and displays Dapps the user can use. You can think of it as a state channel wallet running completely inside the browser that delegates to your existing wallet to make on-chain transactions, when necessary.

The Playground UI runs Dapps in iframes. The Dapps use the NodeProvider (which uses postMessage) to communicate to the Node process, which gives the app the power to use the Counterfactual API (install a new appInstance, update the state of an appInstance, uninstall an appInstance).

This is the general core functionality of the Playground:

a) Connect to the user’s existing wallet, eg. Metamask, to get an account that is used for authentication to the Playground Dapp

b) Use the API exposed by the Playground Server (see below) to create a multisig wallet on-chain between the user and the hub

c) Allow users to make a deposit into their state channel with the server via their wallet

d) Allow users to “open an app” (e.g. High Roller or Tic Tac Toe)

e) Run a Node that app can connect to sign commitments and update state

Playground Server

In order to support Virtual Apps, we need to create an intermediary for which two users can “virtualize” their app through. Since the Node itself is being designed to support the virtual app protocol, we can actually just run it within a Node.js server process using common isomorphic JavaScript patterns. That means the Node you run in your browser is the same code that our Playground Server runs too. This same server also supports some extra functionality to support the Playground UI with features like account authentication and matchmaking of users.

This is the general core functionality of the Playground Server:

a) Run a Node persistently to send/receive messages from Playground users

b) Expose endpoints for authentication

c) Expose endpoints for matchmaking (finding another user that wants to play a game)


The Counterfactual Node exposes a RPC interface that Dapps will need to call. It is nice to have a more user friendly JavaScript interface to the Node’s underlying RPC, similar to Web3.js or Ethers.js. CF.js provides a friendly, easy to use, API for developers to work with state channels.

Presently all functions defined in the API specification are implemented with 100% test coverage. You can see the API reference here.

More coming soon

We hope you’ve learned more about what Counterfactual is, how it works, and our recent progress towards shipping the Playground. We’re excited to see free, secure, and instant transactions & apps coming soon to ethereum!

If you’re interested in following along, or getting involved, you can follow on GitHub or talk to us on Discord.

See you in a couple weeks!