OmiseGO Plasma Framework Contracts

Root chain contracts for The OmiseGO Plasma Framework, a layer 2 scaling solution for Ethereum.

Contents

These contracts comprise the root chain component of an extensible plasma framework that can support many Minimal Viable Plasma (MVP) (Buterin) style plasma constructions. The framework features the ability to extend:

• transaction types, influenced by Plasma Group's Generalized Plasma Architecture
• exit games, which can support any MVP-compatible exit game
• token vaults, such as ETH and ERC-20

The framework includes a basic payment transaction type for UTXO transfers, with 4 inputs and 4 outputs. These transactions are secured under More Viable Plasma (MoreVP) (Fichter, Jones) exits.

The framework includes two token vaults, supporting ETH, ERC-20, and non-compliant ERC-20 tokens.

Child chain and Watchers

The child chain component of our plasma construction runs under Proof of Authority, with a single operator. The construction is secured by a distributed network of watchers. Detailed description of our child chain design is in Tesuji document.

The OmiseGO implementation of the child chain and watcher can be found in our elixir-omg GitHub repository.

Learn more

You can learn more about OmiseGO and get started developing with our plasma framework at developer.omisego.co.

Getting started

The easiest way to compile and deploy the contracts is with Truffle. Requires node.js >= 8.

All the code is in the plasma_framework directory, so go there first.

cd plasma_framework

Next install the dependencies.

npm install

You can then compile the contracts.

npx truffle compile

Or run the tests

npm run test

Configuration

The migration scripts can be configured in plasma_framework/config.js. Various properties of the contracts can be set here, such as the minimum exit period. See the file itself for more details. By default the development environment is used, but this can be set to production via the DEPLOYMENT_ENV environment variable.

You may also override the default exit period in development with an environment variable MIN_EXIT_PERIOD.

Deploying

Deploying the contracts requires three accounts:

1. DEPLOYER The account that actually deploys the contracts
2. AUTHORITY The account that used by the Child chain to submit blocks. It must not have made any transaction prior to calling the scripts i.e. its nonce must be 0.
3. MAINTAINER The account that can register new vaults, exit games, etc.

Normally you will deploy the contracts using an Ethereum client that you run yourself, such as Geth or Parity. Those Ethereum client would have default accounts on the node itself. For local testing, you can leverage those accounts and deploy with --network local flag. The first three accounts inside the Ethereum client would be the DEPLOYER, MAINTAINER, and AUTHORITY account with the order.

You can also use a remote provider such as Infura that does not have control of the private key and accounts with --network remote flag. In this case you'll need to know the private keys for the DEPLOYER, AUTHORITY and MAINTAINER accounts. See truffle-config.js for an example.

Run truffle, passing in the network e.g.

npx truffle migrate --network local

# or to deploy via a remote provider
npx truffle migrate --network remote

You can also run within the docker with the provided Dockerfile.

# run the following commands under the repo directory instead of under plasma_framework/

# build the docker image
docker build -t omisego/plasma-contract .

# deploy the contract
docker run --rm omisego/plasma-contracts npx truffle migrate --network remote

For more detail of the deploying scripts and the env vars to set, see deploying.md

The MAINTAINER account can also be a multisignature contract. The example we've built uses Gnosis MultiSigWallet. The project has been added as a git submodule (https://github.com/gnosis/MultiSigWallet/tree/v1.6.0):

git submodule init
git submodule update --remote

Their deployment scripts were slightly addapted. We can override them by executing:

cd MultiSigWalletOverride/
make init_multisig

While we're in the directory we can deploy the contract by executing:

truffle migrate <account1,account2,...,accountN> <requiredConfirmations> 

The address of the multisignature contract is exported into:

MultiSigWallet/build/multisig_instance

Building and running the python tests

We suggest running the following commands with an active python virtual environment ex. venv. All the code is in the plasma_framework/python_tests directory, so go there first.

Installing dependencies needed for compilation:

make init

Installing dependencies needed to run tests:

make dev

Building and running tests:

make test

Running slow (overnight) tests:

make runslow | tee raport.txt

Run Load Tests

We have code for load tests but is skipped by default. Currently it needs manual setup to run it locally. You should go to the test/loadTests/ folder to find the test you would like to enable. Remove the .skip part on the test, and change it to .only.

The load test would need a ETH network with super high block gas limit and high initial ETH fund for test accounts. You can do the following with ganache:

ganache-cli -e 10000000000000 -l 0xfffffffffff

Run the following command to run the test afterward:

npx truffle test --network loadTest

How to release a new plasma contracts version

• Update the CHANGELOG.md
• Bumps the version in package.json (the patch part)
• Creates a commit with specified message
• Tags that commit with the new version

npm version patch -m "Fixed a bug in X"