Implementation of a novel practical scheme for submarine commitments
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
contracts
generate_commitment
proveth @ a495a0e
test
.gitattributes
.gitignore
.gitmodules
.travis.yml
API.md
LICENSE
README.md
WORKFLOW.md
requirements.txt

README.md

LibSubmarine

Build Status

                    | \
                     '.|
     _-   _-    _-  _-||    _-    _-  _-   _-    _-    _-
       _-    _-   - __||___    _-       _-    _-    _-
    _-   _-    _-  |   _   |       _-   _-    _-
      _-    _-    /_) (_) (_\        _-    _-       _-
              _.-'           `-._      ________       _-
        _..--`                   `-..'       .'
    _.-'  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