Added documentation

Author: Rjected

cmd/fred/README.md

@@ -24,20 +24,20 @@ Based on the hardware in existence, it represents the minimum amount of time to
 ## Auction protocol
 Each auction has an Auction ID parameter.
 
-  1. Submit
+  1. **Submit**
       * The submit stage should take roughly `(b*t)/n` time. `n` should be greater than 1.
       * During the submit stage, users will submit timelock-encrypted orders with time parameter `t`.
-  2. Commit
+  2. **Commit**
       * The commit stage marks the end of the "Submit" stage.
       * During the commit stage, the exchange broadcasts a commitment to a set of encrypted orders.
       * These encrypted orders include an unsolved puzzle, ciphertext, intended auction, and a hash.
-  3. Respond
+  3. **Respond**
       * Users who receive the commitment before `b*t` send a signature on the commitment to the exchange.
       * If the exchange receives unanimous signatures before `b*t`, the exchange broadcasts these signatures.
       * If not all users signed off on the commitment, the entire auction is marked as invalid and must start over.
       * Users should sign during this period if they're confident that the exchange could not have possibly solved a single one of the puzzles in the commitment.
       * A single malicious user can halt the exchange during this step.
-  4. Decrypt
+  4. **Decrypt**
       * This stage starts once the exchange has solved a puzzle, and decrypted an order in the set it committed to.
       * This should happen after `b*t`.
       * The exchange signs this data.
@@ -55,10 +55,10 @@ Each auction has an Auction ID parameter.
       Then the exchange won't be able to sign an update to the data without revealing their private key.
       In this case the auction would have to be restarted.
       * In any case of an invalid auction, users don't need to pay attention to anything the exchange does that depends on the invalid auction.
-  5. Match
+  5. **Match**
       * The exchange matches the orders, and signs the outcome of the matching.
       * If the matching is incorrect, then it's incorrect and you can prove it.
-  6. Execute
+  6. **Execute**
       * The exchange facilitates the trades through whatever settlement it feels like.
       * Ideally this would be done through lightning atomic swaps, since proofs can be produced for an honest execution.
       * In the case of lightning atomic swaps, blame can't be assigned to the user or the exchange if either party refuses to execute the trade.
@@ -83,3 +83,22 @@ Users could do a proof of work on their message once the auction has started, an
 This would only be an issue if there is a large domain for proof of work.
 This will normally be the case, since the message will include a signature, and the signature will be variable, depending on R.
 This doesn't mean anyone can front-run, since the orders are still hidden and the exchange will be committing to taking a position if it commits to its own orders before a puzzle could have possibly been solved.
+
+Stateless matching algorithms can be considered to be time independent.
+
+### Stateful matching algorithms
+
+We don't *have to* be stuck with only stateless matching algorithms.
+We can use a combination of known, stateful algorithms that have a time priority requirement, and a stateless matching algorithm to have a persistent orderbook.
+Every order in an auction must have the same time priority, so we can do the following steps to be compatible with a persistent orderbook:
+
+  1. Match in auction
+      * Nothing is different here than in the **Match** section of the protocol.
+      * Here, we must match according to a stateless matching algorithm.
+  2. Drop unfilled onto orderbook
+      * Here, we'll still be using a stateless matching algorithm, but only to settle "ties".
+      * Unfilled orders get put on the order queue with the highest time priority so far.
+      The sequence of auctions determines the time priority for orders on this orderbook.
+      In the case that multiple orders can be filled, but those orders have the same time priority, a stateless algorithm is used.
+  3. Match according to any matching algorithm
+      * Now, since we can settle ties with a stateless algorithm, we can use a stateful matching algorithm with the persistent orderbook.

crypto/rsw/rswtimelock.go

@@ -1,3 +1,5 @@
+// Package rsw is an implementation of Rivest-Shamir-Wagner timelock puzzles, from RSW96. 
+// The puzzles are based on modular exponentiation, and this package provides an easy to use API for creating and solving these types of puzzles.
 package rsw
 
 import (

crypto/rsw/rswtimelock_test.go

@@ -3,9 +3,36 @@ package rsw
 import (
 	"bytes"
 	"fmt"
+	"log"
 	"testing"
 )
 
+// This is how you create a solvable RSW timelock puzzle.
+func ExampleTimelockRSW_SetupTimelockPuzzle() {
+	// Allocate memory for key
+	key := make([]byte, 32)
+	// set key to be some bytes that we want to be the solution to the puzzle
+	copy(key[:], []byte(fmt.Sprint("!!! secret < 32 bytes !!!")))
+	// Create a new timelock. A timelock can be used to create puzzles for a key with a certain time.
+	rswTimelock, err := New2048A2(key)
+	if err != nil {
+		log.Fatalf("Error creating a new timelock puzzle: %s", err)
+	}
+
+	// set the time to be some big number
+	t := uint64(1000000)
+
+	// Create the puzzle. Puzzles can be solved.
+	puzzle, expectedAns, err := rswTimelock.SetupTimelockPuzzle(t)
+	if err != nil {
+		log.Fatalf("Error creating puzzle: %s", err)
+	}
+
+	fmt.Printf("Puzzle nil? %t. Expected Answer: %s", puzzle == nil, string(expectedAns))
+	// Puzzle nil? false. Expected Answer: !!! secret < 32 bytes !!!
+
+}
+
 func createSolveTest2048A2(time uint64, t *testing.T) {
 	key := make([]byte, 32)
 	copy(key[:], []byte(fmt.Sprintf("opencxcreatesolve%d", time)))

crypto/timelock.go

@@ -6,7 +6,7 @@ type Timelock interface {
 	SetupTimelockPuzzle(t uint64) (puzzle Puzzle, answer []byte, err error)
 }
 
-// Puzzle is what can actually be solved. It should return the same time t
+// Puzzle is what can actually be solved. It should return the same answer that was the result of SetupTimelockPuzzle.
 type Puzzle interface {
 	// Solve solves the puzzle and returns the answer, or fails
 	Solve() (answer []byte, err error)

logging/logging.go

@@ -1,3 +1,4 @@
+// Package logging provides utilities to easily set a universal log level, as well as intuitively set a log file.
 package logging
 
 // Log Levels:
@@ -24,18 +25,24 @@ import (
 type LogLevel int
 
 const (
-	LogLevelError   LogLevel = 0
+	// LogLevelError is the log level that prints Panics, Fatals, and Errors.
+	LogLevelError LogLevel = 0
+	// LogLevelWarning is the log level that prints Panics, Fatals, Errors, and Warnings.
 	LogLevelWarning LogLevel = 1
-	LogLevelInfo    LogLevel = 2
-	LogLevelDebug   LogLevel = 3
+	// LogLevelInfo is the log level that prints Panics, Fatals, Errors, Warnings, and Infos.
+	LogLevelInfo LogLevel = 2
+	// LogLevelDebug is the log level that prints Panics, Fatals, Errors, Warnings, Infos, and Debugs.
+	LogLevelDebug LogLevel = 3
 )
 
 var logLevel = LogLevelError // the default
 
+// SetLogLevel sets the global log level
 func SetLogLevel(newLevel int) {
 	logLevel = LogLevel(newLevel)
 }
 
+// SetLogFile sets a file to write to in addition to standard output.
 func SetLogFile(logFile io.Writer) {
 	log.SetFlags(log.Ldate | log.Ltime | log.Lmicroseconds)
 	logOutput := io.MultiWriter(os.Stdout, logFile)
@@ -46,91 +53,106 @@ func getPrefix(level string) string {
 	return fmt.Sprintf("[%s]", level)
 }
 
+// Fatalln prints a message and a new line, then calls os.Exit(1).
 func Fatalln(args ...interface{}) {
 	log.Fatalln(args...)
 }
 
+// Fatalf prints a message with a formatting directive, then calls os.Exit(1).
 func Fatalf(format string, args ...interface{}) {
 	log.Fatalf(format, args...)
 }
 
+// Fatal prints a message, then calls os.Exit(1).
 func Fatal(args ...interface{}) {
 	log.Fatal(args...)
 }
 
+// Debugf prints debug logs with a formatting directive.
 func Debugf(format string, args ...interface{}) {
 	if logLevel >= LogLevelDebug {
 		log.Printf(fmt.Sprintf("%s %s", getPrefix("DEBUG"), format), args...)
 	}
 }
 
+// Infof prints info logs with a formatting directive.
 func Infof(format string, args ...interface{}) {
 	if logLevel >= LogLevelInfo {
 		log.Printf(fmt.Sprintf("%s %s", getPrefix("INFO"), format), args...)
 	}
 }
 
+// Warnf prints warning logs with a formatting directive.
 func Warnf(format string, args ...interface{}) {
 	if logLevel >= LogLevelWarning {
 		log.Printf(fmt.Sprintf("%s %s", getPrefix("WARN"), format), args...)
 	}
 }
 
+// Errorf prints error logs with a formatting directive.
 func Errorf(format string, args ...interface{}) {
 	if logLevel >= LogLevelError {
 		log.Printf(fmt.Sprintf("%s %s", getPrefix("ERROR"), format), args...)
 	}
 }
 
+// Debugln prints debug logs, followed by a new line.
 func Debugln(args ...interface{}) {
 	if logLevel >= LogLevelDebug {
 		args = append([]interface{}{getPrefix("DEBUG")}, args...)
 		log.Println(args...)
 	}
 }
 
+// Infoln prints info logs, followed by a new line.
 func Infoln(args ...interface{}) {
 	if logLevel >= LogLevelInfo {
 		args = append([]interface{}{getPrefix("INFO")}, args...)
 		log.Println(args...)
 	}
 }
 
+// Warnln prints warning logs, followed by a new line.
 func Warnln(args ...interface{}) {
 	if logLevel >= LogLevelWarning {
 		args = append([]interface{}{getPrefix("WARN")}, args...)
 		log.Println(args...)
 	}
 }
 
+// Errorln prints error logs, followed by a new line.
 func Errorln(args ...interface{}) {
 	if logLevel >= LogLevelError {
 		args = append([]interface{}{getPrefix("ERROR")}, args...)
 		log.Println(args...)
 	}
 }
 
+// Debug prints debug logs.
 func Debug(args ...interface{}) {
 	if logLevel >= LogLevelDebug {
 		args = append([]interface{}{getPrefix("DEBUG")}, args...)
 		log.Print(args...)
 	}
 }
 
+// Info prints info logs.
 func Info(args ...interface{}) {
 	if logLevel >= LogLevelInfo {
 		args = append([]interface{}{getPrefix("INFO")}, args...)
 		log.Print(args...)
 	}
 }
 
+// Warn prints warning logs.
 func Warn(args ...interface{}) {
 	if logLevel >= LogLevelWarning {
 		args = append([]interface{}{getPrefix("WARN")}, args...)
 		log.Print(args...)
 	}
 }
 
+// Error prints error logs.
 func Error(args ...interface{}) {
 	if logLevel >= LogLevelError {
 		args = append([]interface{}{getPrefix("ERROR")}, args...)

match/consts.go

@@ -1,3 +1,4 @@
+// Package match provides utilities and useful structures for building exchange systems.
 package match
 
 import (