mfsDocs.md

Minimal Feature Set (MFS) - Docs

Overview

This SDK is composed of 2 parts:

1. Smart contracts
2. TypeScript

The smart contracts provide base contracts that need to be extended for a specific use-case (state machine). The state machine executes p2p in real-time without any fees, with shared security inherited from a distributed ledger (blockchain).

The TypeScript part of the SDK implements all the functionality and makes it easily available through a simple setup that wraps/ensrhnies ethers contract instances. After the setup, the wrapped/enshrined contracts can be used as a direct substitute for the original contracts, and the system will handle everything. The contracts preserve the same TypeChain generated type.

General Usage

1. Implement a specific state machine (smart contract) by extending AStateMachine. (Example);

2. Implement a specific StateChannelManager contract by extending AStateChannelManager. (Example);

3. Compile your contracts (we use Hardhat);

4. Deploy contracts (Example):

• Deploy StateChannelUtil or use an existing deployment (Example);
• Deploy DisputeManagerFacet or use an existing deployment (Example);
• Deploy the implemented StateMachine contract (Example);
• Deploy the implemented StateChannelManager contract (Example);

5. Run setup on ethers contract instances (Example);

6. Use the enshrined contract as a direct substitute for the original contract (Example).

AStateMachine interface

function _setState(bytes memory encodedState) internal virtual;

Unconditionally sets the state of the state machine contract, by deserializing (decoding) bytes. (Example)

function getState() public view virtual returns (bytes memory);

Serializes (encodes) the state of the state machine contract and returns it. (Example)

function getParticipants() public view virtual returns (address[] memory);

Returns the current participants of the state channel. (Example)

function getNextToWrite() public view virtual returns (address);

Returns the next participant whose turn is to progress (mutate) the state machine. (Example)

function _joinChannel(JoinChannel memory joinChannel) internal virtual returns (bool);

Triggered when someone joins the state channel. Used to modify the state machine to incorporate the addition into the state. (type JoinChannel) (Example)

function _slashParticipant(address adr) internal virtual returns (bool, ProcessExit memory);

Triggered when someone is slashed - when provable fraud is detected. Allows the state machine to define custom behavior how to handle and apply the slash. (Example)

function _removeParticipant(address adr) internal virtual returns (bool, ProcessExit memory);

Triggered when someone is removed from the state channel, but not as aggressive as slash. Currently triggered on timeout. (Example)

Each state machine has to override the above-listed functions as they're expected by the system (SDK), but can add its own functions to extend the interface and thus build arbitrary state machines in its own way.

AStateChannelManager interface

function openChannel(
        bytes32 channelId,
        bytes[] calldata openChannelData,
        bytes[] calldata signatures
    ) public virtual;

Executed on-chain once for every unique channelId. Performs all the composable operations on the global (world) state (can interact with other contracts). Atomic success or failure.

• channelId - unique identifier of the channel

• openChannelData - array of bytes for every participant in the channel - bytes hold commitment data (eg. amount of tokens to deposit). - usually the bytes are interpreted as JoinChannel, but you can use your own custom types and have a fully custom verification logic.

• signatures - array of sigantures - signed openChannelData by each participant in the channel.

(Example)

This is for the MFS (minimal feature set) - the full feature set will include more functionality.