ExPlasma

ExPlasma is an Elixir library for encoding, decoding and validating transactions used for the OMG Network Plasma contracts.

Installation

If available in Hex, the package can be installed by adding ex_plasma to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_plasma, "~> 0.2.0"}
  ]
end

You will also need to specify some configurations in your config/config.exs:

config :ex_plasma,
  eip_712_domain: %{
    name: "OMG Network",
    salt: "0xfad5c7f626d80f9256ef01929f3beb96e058b8b4b0e3fe52d84f054c0e2a7a83",
    verifying_contract: "0xd17e1233a03affb9092d5109179b43d6a8828607",
    version: "1"
  }

Setup

ExPlasma requires Rust to be installed because it uses Rust NIFs for keccak hash and secp256k1.

1. Clone the repo to your desktop [email protected]:omgnetwork/ex_plasma.git
2. Run mix compile in your terminal.
3. If there are any unavailable dependencies, run mix deps.get.

Usage

To build a transaction use ExPlasma.Builder module:

{:ok, txn} =
  ExPlasma.payment_v1()
  |> ExPlasma.Builder.new()
  |> ExPlasma.Builder.add_input(blknum: 1, txindex: 0, oindex: 0)
  |> ExPlasma.Builder.add_output(output_type: 1, output_data: %{output_guard: <<1::160>>, token: <<0::160>>, amount: 1})
  |> ExPlasma.Builder.sign(["0x79298b0292bbfa9b15705c56b6133201c62b798f102d7d096d31d7637f9b2382"])
{:ok,
 %ExPlasma.Transaction{
   inputs: [
     %ExPlasma.Output{
       output_data: nil,
       output_id: %{blknum: 1, oindex: 0, txindex: 0},
       output_type: nil
     }
   ],
   metadata: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     0, 0, 0, 0, 0, 0, 0, 0, 0, 0>>,
   nonce: nil,
   outputs: [
     %ExPlasma.Output{
       output_data: %{
         amount: 1,
         output_guard: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
           0, 1>>,
         token: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>>
       },
       output_id: nil,
       output_type: 1
     }
   ],
   sigs: [
     <<236, 177, 165, 5, 109, 208, 210, 116, 68, 176, 199, 17, 168, 29, 30, 198,
       77, 45, 233, 147, 149, 38, 93, 136, 24, 98, 53, 218, 52, 177, 200, 127,
       26, 6, 138, 17, 36, 52, 97, 152, 240, 222, ...>>
   ],
   tx_data: 0,
   tx_type: 1,
   witnesses: []
}}

You can encode a transaction using ExPlasma.encode/2:

{:ok, rlp} = ExPlasma.encode(txn, signed: false)
{:ok,
 <<248, 116, 1, 225, 160, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 59, 154, 202, 0, 238, 237, 1, 235, 148, 0, 0,
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 148, 0, 0, 0, 0, 0, 0,
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 128, 160, 0, 0, 0, 0, 0, 0, 0,
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>>}

You can decode a transaction using ExPlasma.decode/2:

{:ok, txn} = ExPlasma.decode(rlp, signed: false)
{:ok,
 %ExPlasma.Transaction{
   inputs: [
     %ExPlasma.Output{
       output_data: nil,
       output_id: %{blknum: 1, oindex: 0, position: 1000000000, txindex: 0},
       output_type: nil
     }
   ],
   metadata: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
     0, 0, 0, 0, 0, 0, 0, 0, 0, 0>>,
   nonce: nil,
   outputs: [
     %ExPlasma.Output{
       output_data: %{
         amount: 1,
         output_guard: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
           0, 1>>,
         token: <<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>>
       },
       output_id: nil,
       output_type: 1
     }
   ],
   sigs: [],
   tx_data: 0,
   tx_type: 1,
   witnesses: []
 }}

You can validate a transaction using ExPlasma.validate/1:

ExPlasma.validate(txn)

View the documentation

Testing

You can run the tests by running;

mix test
mix credo
mix dialyzer

This will load up Ganche and the plasma contracts to deploy.

Conformance test

To ensure we can encode/decode according to the contracts, we have a separate suite of conformance tests that loads up mock contracts to compare encoding results. You can run the test by:

make up-mocks
mix test --only conformance

This will spin up ganache and deploy the mock contracts.

Contributing

1. Fork it!
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

ExPlasma is released under the Apache-2.0 License.