techraed/PlasmaManager

Manages interaction with a block producer and the smart-contract

PlasmaManager

PlasmaManager is your toolbelt for any kind of interactions with More Viable Plasma by Matter.

• Features
• Design Decisions
• Requirements
• Communication
• Transaction Structure
  • Input
  • Output
  • Transaction
  • Signed Transaction
• Block Structure
  • Block
  • Block Header
• Credits
  • Security Disclosure
• Donations
• License

---

• Usage Doc
  • UTXO
    • [UTXO structure](UTXO structure)
    • Get UTXOs list for Ethereum address
  • Transaction
    • Form input
    • Form output
    • Form transaction, sign it and serialize
  • Send transaction in Plasma
    • Send raw transaction
  • Blocks
    • Get last written Block and its number
    • Get block hash from storage and from Plasma Contract
    • Parse Block by its number
    • Get transactions list from Block and add some checks for it
  • Send transaction in Plasma
    • Send raw serialized transaction
  • Send transaction to Plasma Contract
    • Put deposit
    • Withdraw for chosen block number and serialized transaction

Features

• Based on More Viable Plasma Implementation by The Matter Team
• RLP encoding and decoding based on NPM Plasma Module
• Manages interaction with a block producer and the smart-contract
• Comprehensive Test Coverage
• Complete Documentation

Design Decisions

• Functionality was focused on serializing and signing transactions locally
• Sending raw transactions to The Matter Plasma network using REST API
• Sending raw transactions to Plasma Contract using web3.js

Communication

When using this lib, please make references to this repo and give your start! :) Nothing makes developers happier than seeing someone else use our work and go wild with it.

If you are using PlasmaManager in your project or know of an project that uses it, please add it to this list.

• If you need help, use Stack Overflow and tag PlasmaManager.
• If you need to find or understand an API, check our documentation.
• If you'd like to see PlasmaManager best practices, check Projects using this library.
• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

Transaction structure

The transaction structure, that is used in The Matter Plasma Implementation is the UTXO model with explicit enumeration of UTXOs in the inputs.

Input

An RLP encoded set with the following items:

• Block number, 4 bytes
• Transaction number in block, 4 bytes
• Output number in transaction, 1 byte
• "Amount" field, 32 bytes, that is more a data field, usually used for an amount of the output referenced by previous field, but has special meaning for "Deposit" transactions

Output

An RLP encoded set with the following items:

• Output number in transaction, 1 byte
• Receiver's Ethereum address, 20 bytes
• "Amount" field, 32 bytes

Transaction

An RLP encoded set with the following items:

• Transaction type, 1 byte
• An array (list) of Inputs, maximum 2 items
• An array (list) of Outputs, maximum 3 items. One of the outputs is an explicit output to an address of Plasma operator.

Signed transaction

An RLP encoded set with the following items:

• Transaction, as described above
• Recoverable EC of the transaction sender:
  1. V value, 1 byte, expected values 27, 28
  2. R value, 32 bytes
  3. S value, 32 bytes

From this signature Plasma operator deduces a sender, checks that the sender is an owner of UTXOs referenced by inputs. Signature is based on EthereumPersonalHash(RLPEncode(Transaction)). Transaction should be well-formed, sum of inputs equal to sum of the outputs, etc.

Block structure

Block header

• Block number, 4 bytes, used in the main chain to double check proper ordering
• Number of transactions in block, 4 bytes, purely informational
• Parent hash, 32 bytes, hash of the previous block, hashes the full header
• Merkle root of the transactions tree, 32 bytes
• V value, 1 byte, expected values 27, 28
• R value, 32 bytes
• S value, 32 bytes

Signature is based on EthereumPersonalHash(block number || number of transactions || previous hash || merkle root), where || means concatenation. Values V, R, S are then concatenated to the header.

Block

• Block header, as described above, 137 bytes
• RLP encoded array (list) of signed transactions, as described above

While some fields can be excessive, such block header can be submitted by anyone to the main Ethereum chain when block is available, but for some reason not sent to the smart contract. Transaction numbering is done by the operator, it should be monotonically increasing without spaces and number of transactions in header should (although this is not necessary for the functionality) match the number of transactions in the Merkle tree and the full block.

Credits

Alex Vlasov, @shamatar, alex.m.vlasov@gmail.com

Security Disclosure

If you believe you have identified a security vulnerability with PlasmaSwiftLib, you should report it as soon as possible via email to Alex Vlasov alex.m.vlasov@gmail.com. Please do not post it to a public issue tracker.

Donations

The Matters are charged with open-sorсe and do not require money for using their PlasmaManager. We want to continue to do everything we can to move the needle forward. If you use any of our libraries for work, see if your employers would be interested in donating. Any amount you can donate today to help us reach our goal would be greatly appreciated.

Our Ether wallet address: 0xe22b8979739d724343bd002f9f432f5990879901

License

PlasmaManager is available under the Apache License 2.0 license. See the LICENSE for details.