lorenzb/libsubmarine

Implementation of a novel practical scheme for submarine commitments

LibSubmarine

                    | \
                     '.|
     _-   _-    _-  _-||    _-    _-  _-   _-    _-    _-
       _-    _-   - __||___    _-       _-    _-    _-
    _-   _-    _-  |   _   |       _-   _-    _-
      _-    _-    /_) (_) (_\        _-    _-       _-
              _.-'           `-._      ________       _-
        _..--`                   `-..'       .'
    _.-'  o/o                     o/o`-..__.'        ~  ~
 .-'      o|o                     o|o      `.._.  // ~  ~
 `-._     o|o                     o|o        |||<|||~  ~
     `-.__o\o                     o|o       .'-'  \\ ~  ~
LGB       `-.______________________\_...-``'.       ~  ~
                                    `._______'.

---

A work-in-progress implementation of better submarine sends for Ethereum.

Submarine Steps

• A User
• B Commit Address (No Private key)
• C Libsubmarine
• D Dapp, Application (e.g Auction, DEX, ICO, etc.)
• MPT Merkle-Patricia Proof of TxCommit Inclusion on-chain

     TxCommit (1)
A +-------------------> B
+                       +
|                       |   TxUnlock (3)
|                       | (calls unlock)
|                       v
+---------------------> C < - - - - - - - - - - - - -+ D
                         (overload) onSubmarineReveal
    TxReveal (2)           (query) revealedAndUnlocked(submarineId)
 (call reveal + MPT
 + RLP-encoded TxUnlock)
                                                        

---

Workflow and API Guide

For a more in-depth discussion of what the workflow / steps from a user's perspective for a Submarine transaction looks like, refer to WORKFLOW.md.

For an in-depth discussion of how to incorporate LibSubmarine into your existing application, as well as some software architecture notes, see API.md.

---

Contract Unit Tests / Examples / Offchain Components

Install Solc (Installation guide)

Use pip to install python dependencies (we recommend using a virtualenv with >= python3.6):

pip3 install -r requirements.txt

Run the tests:

python3 test/test_whateverComponent.py

The tests are particularly useful to see as a reference, since they basically model an end-users interaction with LibSubmarine from start to finish.

---

Disclaimer

This project is a Work in Progress. It has not undergone a formal security audit from an independent 3rd party (though we would like to have that done).

For a high level discussion around the research of Submarine Sends and some historical implementations, please refer to the blog post: To Sink Frontrunners, Send in the Submarines.

---

Authors

LibSubmarine's development was started by the Submarines group at the 2018 IC3 Ethereum bootcamp, but is now an open source project. Anyone is encouraged to contribute.

IC3 Ethereum Bootcamp <3 2018