A protocol is defined as the set of instructions executed and messages exchanged between a set of parties to achieve an outcome (e.g., installing a new state channel application). Instructions executed include producing digital signatures, reading persistent state to disk, etc.

Counterfactual writes client software that speak the same Counterfactual protocol, specified in the following page.

Many protocols are specialized to two-party and specified as such. We plan to extend them to n-party channels in the future.

Protocol Structure

A protocol consists of the following components:

  • Exchange. The protocol exchange is the series of messages exchanged between all parties in the state channel, as well as dependencies between messages.
  • Message. A message is the set of information that must be exchanged by the parties to recreate and validate the commitment signatures and associated transactions that those signatures enable. Each protocol may in general contain multiple message types.
  • Commitments. A protocol produces one or more commitments. Both the signatures and the data contained within the commitments must be stored.
Note: Messages are represented as JSON-encoded objects; the transport layer should be able to reliably send and receive such messages.
Note: Some data required for signature verification is not present in these messages but is deterministically generated by each party. For example, setKeyAsUninstalled requires a salt, which is a monotonically increasing counter on the number of applications in a channel.

Commitment Structure

  • Signature. The resultant data generated by computing a cryptographic signature over some hash representing the transaction to be executed.
  • Data. Supplementary data that that allows any party in the protocol to reconstruct the hash and thus verify the signature.
  • Transaction Digest. The transaction digest is the hash that is signed by each party, enabling the protocol’s transaction to be executed on-chain. The calldata, if present, is used to generate the digest.
  • Transaction. The transaction is the (to, val, data, op) tuple that a given protocol allows one to broadcast on-chain. These transactions enforce commitments created from the calldata and signature digests, manifesting the off-chain counterfactual state into the on-chain reality.

Primitive Types

Type Description Sample
address Ethereum address 0x3bfc20f0b9afcace800d73d2191166ff16540258
xpub HD wallet extended public key xpub6GhhMtkVjoPi5DKtqapKzMzrzdGjo1EPc7Ka6KdeoXYdCrTBH1Hu1wKysm8boWSy8VeTKVJi6gQJ2qJ4YG2ZhvFDcUUgMJrFCJWN1PGtBry
uint8 8 bit unsigned integer
uint256 256 bit unsigned integer
bytes32 32 bytes

Singleton Contracts

Variable Name Type Description
REGISTRY address The deployed on-chain address of the Registry singleton contract
NONCE_REGISTRY address The deployed on-chain address of the NonceRegistry singleton contract


This type specifies a modification of JSON that disallows the following primitive types: true, false, null. Note that when represented in javascript, large numbers which fint into uint256 must be represented as either BigNumbers or as serialized BigNumbers (e.g., { _hex: '0x01'}).

Type: CfAppInterface

Field Type Description
address address The on-chain address of the AppDefinition contract implementing the application logic
stateEncoding string The ABIEncoderV2 representation of the application's state encoding (e.g., "tuple(address,uint8)")
actionEncoding Optional<string> The ABIEncoderV2 representation of the application's action encoding, if it exists