OmiseGO Plasma Framework Contracts
Root chain contracts for The OmiseGO Plasma Framework, a layer 2 scaling solution for Ethereum.
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.
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.
Next install the dependencies.
You can then compile the contracts.
npx truffle compile
Or run the tests
npm run test
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
Deploying the contracts requires three accounts:
DEPLOYERThe account that actually deploys the contracts
AUTHORITYThe 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.
MAINTAINERThe 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
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
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
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:
Building and running the python tests
We suggest running the following commands with an active python virtual environment ex.
All the code is in the
plasma_framework/python_tests directory, so go there first.
Installing dependencies needed for compilation:
Installing dependencies needed to run tests:
Building and running tests:
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.
.skip part on the test, and change it to
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"