omgnetwork / omg-js

JavaScript Library for communication with OMG network
Apache License 2.0
42 stars 15 forks source link

OMG-JS

JavaScript Style Guide

JavaScript Style Guide

CircleCI

This is a Javascript library that allows you to interact with OmiseGo's MoreVP implementation of Plasma. It provides functions to:

  1. Deposit (Eth/Token) from the Root chain into the Child chain.
  2. Transact on the Child chain.
  3. Exit from the Child chain back to the Root chain.
  4. Challenge an invalid exit.

Compatibility

omg-js follows a modified semver with the first part referring to its own library versioning and the second part referring to its compatible elixir-omg version.

Getting Started

The project is organized into 3 submodules:

  1. @omisego/omg-js-rootchain
  2. @omisego/omg-js-childchain
  3. @omisego/omg-js-util

You can use any of them separately, or all at once by importing the parent @omisego/omg-js package.

Installation

Node

Requires Node >= 8.11.3 < 13.0.0

npm install @omisego/omg-js

Browser

You can add omg-js to a website quickly. Just add this script tag.

<script src="https://unpkg.com/@omisego/browser-omg-js"></script>

React Native

omg-js can easily be integrated with React Native projects. First, add this postinstall script to your project's package.json

"scripts": {
    "postinstall": "omgjs-nodeify"
}

Then install the react native compatible library.

npm install @omisego/react-native-omg-js

API Documentation

Documentation for omg-js

Design Documentation

Sending a transaction
How to sign a transaction

Examples

Prerequisites

Both Alice's and Bob's Ethereum accounts need to have some ETH in them. The ETH is used for gas costs on the rootchain, fees on the childchain and the actual ETH transferred from Alice to Bob. If you want to run the ERC20 examples, make sure the token address is recorded in your .env and either Alice or Bob has a balance on the rootchain.

Running the Examples

You can find example code inside the examples folder.

To run the examples:

Let's run through a story between Alice and Bob. In this story, Alice will first deposit some ETH from the root chain into the child chain. Then Alice will transfer some of that ETH to Bob on the child chain. Bob will then exit his funds from the child chain back into the root chain. His root chain balance will be reflected with the extra ETH that Alice sent to him on the child chain.

Note you can modify the values of the passed flags to suit your needs

Helpful Scripts

From the /examples folder run the following scripts:

ETH Examples

  1. Deposit some ETH from Alice's Rootchain to the Childchain

    node deposit-eth --owner=alice --amount=0.01

  2. Send some ETH from Alice's Childchain to Bob's Childchain

    node transaction-eth --from=alice --to=bob --amount=0.001

Alice has now sent some ETH to Bob. This should be reflected in Bob's childchain balance.

  1. Exit one of Bob's Childchain UTXOs to the Rootchain

    node exit-eth --owner=bob

Checking Bob's final rootchain balance you will notice it will be a little less than expected. This is because of rootchain gas costs Bob had to pay to exit the childchain.

  1. Bob starts and piggyback's an inflight exit for his ouput on a transaction sent by Alice

    node inflight-exit-eth --from=alice --to=bob --amount=0.01

ERC20 Examples

Before we begin, we need to deploy and mint some ERC20 tokens. From the examples folder run the following command:

npm run deploy-test-erc20 --prefix ../packages/integration-tests

Use the ERC20 contract address from the output above to configure ERC20_CONTRACT_ADDRESS in your .env file.

Now let's run through the same story above but for ERC20 deposit/transaction/exit.

  1. Deposit some ERC20 from Alice's Rootchain to the Childchain

    node deposit-erc20 --owner=alice --amount=10

  2. Send some ERC20 from Alice's Childchain to Bob's Childchain

    node transaction-erc20 --from=alice --to=bob --amount=1

  3. Exit one of Bob's Childchain ERC20 UTXOs to the Rootchain

    node exit-erc20 --owner=bob