Merge branch 'master' into privval_tests

Author: fbockaj

README.md

@@ -10,10 +10,10 @@ SignCTRL is a high availability solution for Tendermint that enables the creatio
 
 ## Why SignCTRL?
 
-1) Built-in double-signing protection.
-2) Very lightweight due to not introducing any additional communication overhead for coordination work.
-3) No more sentry nodes are needed, as the validators in the set back each other up.
-4) A minimal setup requires only two nodes to be run.
+1) Built-in double-signing protection
+2) Very lightweight (no additional communication overhead for coordination work)
+3) No more sentry nodes are needed, as the validators in the set back each other up
+4) Minimal setup requires only two nodes
 
 ## Requirements
 
@@ -25,7 +25,7 @@ SignCTRL is a high availability solution for Tendermint that enables the creatio
 Get the repository via
 
 ```shell
-$ git clone https://github.com/BlockscapeNetwork/signctrl && cd signctrl
+$ git clone https://github.com/BlockscapeNetwork/signctrl
 ```
 
 ## Build & Install
@@ -45,7 +45,8 @@ $ make install
 
 ## Getting Started
 
-To get started, please see the [Guides/Tutorials](docs/guides/README.md).
+To get started, please see the [Guides/Tutorials](docs/guides/README.md).</br>
+If you get stuck, see the [FAQ](docs/core/faq.md).
 
 ## Documentation
 

cmd/start.go

@@ -2,13 +2,11 @@ package cmd
 
 import (
 	"fmt"
-	"log"
 	"net/http"
 	"os"
 	"os/signal"
 	"strings"
 	"syscall"
-	"time"
 
 	"github.com/BlockscapeNetwork/signctrl/config"
 	"github.com/BlockscapeNetwork/signctrl/privval"
@@ -34,9 +32,9 @@ var (
 			cfgDir := config.Dir()
 
 			// Set the logger and its mininum log level.
-			logger := log.New(os.Stderr, "", 0)
+			logger := types.NewSyncLogger(os.Stderr, "", 0)
 			filter := &logutils.LevelFilter{
-				Levels:   config.LogLevels,
+				Levels:   types.LogLevels,
 				MinLevel: logutils.LogLevel(cfg.Base.LogLevel),
 				Writer:   os.Stderr,
 			}
@@ -64,7 +62,7 @@ var (
 
 			// Start the SignCTRL service.
 			if err := pv.Start(); err != nil {
-				fmt.Println(err)
+				logger.Error(err.Error())
 				if err := pv.Stop(); err != nil {
 					fmt.Println(err)
 					os.Exit(1)
@@ -78,21 +76,15 @@ var (
 
 			select {
 			case <-pv.Quit(): // Used for self-induced shutdown
-				pv.Logger.Println("[INFO] signctrl: Shutting SignCTRL down... \u23FB (quit)")
+				pv.Logger.Info("Shutting SignCTRL down... \u23FB (quit)")
 			case <-sigs: // The sigs channel is only used for OS interrupt signals
-				pv.Logger.Println("[INFO] signctrl: Shutting SignCTRL down... \u23FB (user/os interrupt)")
-			}
-
-			if err := pv.Stop(); err != nil {
-				fmt.Println(err)
-				os.Exit(1)
+				pv.Logger.Info("Shutting SignCTRL down... \u23FB (user/os interrupt)")
+				if err := pv.Stop(); err != nil {
+					logger.Error(err.Error())
+					os.Exit(1)
+				}
 			}
 
-			// TODO: The current logger is async which is why some of the last log messages before
-			// shutdown aren't printed out. Make the logger sync. For now, wait a second for everything
-			// to be printed out.
-			time.Sleep(time.Second)
-
 			// Terminate the process gracefully with exit code 0.
 			os.Exit(0)
 		},

config/config.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/BlockscapeNetwork/signctrl/types"
 	"github.com/hashicorp/logutils"
 	"github.com/spf13/viper"
 )
@@ -20,11 +21,6 @@ const (
 	File = "config.toml"
 )
 
-var (
-	// LogLevels defines the loglevels for SignCTRL logs.
-	LogLevels = []logutils.LogLevel{"DEBUG", "INFO", "WARN", "ERR"}
-)
-
 // Base defines the base configuration parameters for SignCTRL.
 type Base struct {
 	// LogLevel determines the minimum log level for SignCTRL logs.
@@ -56,11 +52,36 @@ type Base struct {
 	RetryDialAfter string `mapstructure:"retry_dial_after"`
 }
 
+// validateAddress validates the configuration's addresses.
+func validateAddress(addr string, addrName string) error {
+	protocol := regexp.MustCompile(`(tcp|unix)://`).FindString(addr)
+	switch protocol {
+	case "":
+		return fmt.Errorf("%v is missing the protocol", addrName)
+
+	case "tcp://":
+		host, _, err := net.SplitHostPort(strings.TrimPrefix(addr, protocol))
+		if err != nil {
+			return fmt.Errorf("%v is not in the host:port format", addrName)
+		}
+		if ip := net.ParseIP(host); ip == nil {
+			return fmt.Errorf("%v is not a valid IPv4 address", addrName)
+		}
+
+	case "unix://":
+		if !strings.HasSuffix(addr, ".sock") {
+			return fmt.Errorf("%v is not a unix domain socket address", addrName)
+		}
+	}
+
+	return nil
+}
+
 // validate validates the configuration's base section.
 func (b Base) validate() error {
 	var errs string
-	if match, _ := regexp.MatchString(logLevelsToRegExp(&LogLevels), b.LogLevel); !match {
-		errs += fmt.Sprintf("\tlog_level must be one of the following: %v\n", LogLevels)
+	if match, _ := regexp.MatchString(logLevelsToRegExp(&types.LogLevels), b.LogLevel); !match {
+		errs += fmt.Sprintf("\tlog_level must be one of the following: %v\n", types.LogLevels)
 	}
 	if b.SetSize < 2 {
 		errs += "\tset_size must be 2 or higher\n"
@@ -71,34 +92,11 @@ func (b Base) validate() error {
 	if b.StartRank < 1 {
 		errs += "\tstart_rank must be 1 or higher\n"
 	}
-	protocol := regexp.MustCompile(`(tcp|unix)://`).FindString(b.ValidatorListenAddress)
-	if protocol == "" {
-		errs += "\tvalidator_laddr is missing the protocol\n"
-	} else if protocol == "tcp://" {
-		host, _, err := net.SplitHostPort(strings.TrimPrefix(b.ValidatorListenAddress, protocol))
-		if err != nil {
-			errs += "\tvalidator_laddr is not in the host:port format\n"
-		} else {
-			if ip := net.ParseIP(host); ip == nil {
-				errs += "\tvalidator_laddr is not a valid IPv4 address\n"
-			}
-		}
-	} else if protocol == "unix://" {
-		if !strings.HasSuffix(b.ValidatorListenAddress, ".sock") {
-			errs += "\nvalidator_laddr is not a unix domain socket address\n"
-		}
+	if err := validateAddress(b.ValidatorListenAddress, "validator_laddr"); err != nil {
+		errs += fmt.Sprintf("\t%v\n", err.Error())
 	}
-	if !strings.HasPrefix(b.ValidatorListenAddressRPC, "tcp://") {
-		errs += "\tvalidator_laddr_rpc is missing the protocol\n"
-	} else {
-		host, _, err := net.SplitHostPort(strings.TrimPrefix(b.ValidatorListenAddressRPC, "tcp://"))
-		if err != nil {
-			errs += "\tvalidator_laddr_rpc is not in the host:port format\n"
-		} else {
-			if ip := net.ParseIP(host); ip == nil {
-				errs += "\tvalidator_laddr_rpc is not a valid IPv4 address\n"
-			}
-		}
+	if err := validateAddress(b.ValidatorListenAddressRPC, "validator_laddr_rpc"); err != nil {
+		errs += fmt.Sprintf("\t%v\n", err.Error())
 	}
 	if b.RetryDialAfter == "" {
 		errs += "\tretry_dial_after must not be empty\n"

connection/dial.go

@@ -3,7 +3,6 @@ package connection
 import (
 	"errors"
 	"fmt"
-	"log"
 	"net"
 	"os"
 	"os/signal"
@@ -12,6 +11,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/BlockscapeNetwork/signctrl/types"
 	tm_ed25519 "github.com/tendermint/tendermint/crypto/ed25519"
 	tm_p2pconn "github.com/tendermint/tendermint/p2p/conn"
 )
@@ -29,28 +29,28 @@ var (
 
 // retryDialTCP keeps dialing the given TCP socket address until success, using the
 // given connkey for encryption and returns the secret connection.
-func retryDialTCP(address string, connkey tm_ed25519.PrivKey, sigs chan os.Signal, logger *log.Logger) (net.Conn, error) {
+func retryDialTCP(address string, connkey tm_ed25519.PrivKey, sigs chan os.Signal, logger *types.SyncLogger) (net.Conn, error) {
 	for {
 		select {
 		case <-sigs:
 			return nil, ErrAbortDial
 
 		case <-time.After(RetryDialInterval):
 			if conn, err := net.Dial("tcp", strings.TrimPrefix(address, "tcp://")); err == nil {
-				logger.Println("[INFO] signctrl: Successfully dialed the validator ✓")
+				logger.Info("Successfully dialed the validator ✓")
 				return tm_p2pconn.MakeSecretConnection(conn, connkey)
 			}
 
 			// After the first dial, dial in intervals of 1 second.
 			RetryDialInterval = time.Second
-			logger.Println("[DEBUG] signctrl: Retry dialing...")
+			logger.Debug("Retry dialing...")
 		}
 	}
 }
 
 // retryDialUnix keeps dialing the given unix domain socket address until success and
 // returns the connection.
-func retryDialUnix(address string, sigs chan os.Signal, logger *log.Logger) (net.Conn, error) {
+func retryDialUnix(address string, sigs chan os.Signal, logger *types.SyncLogger) (net.Conn, error) {
 	addrWithoutProtocol := strings.TrimPrefix(address, "unix://")
 
 	for {
@@ -61,21 +61,21 @@ func retryDialUnix(address string, sigs chan os.Signal, logger *log.Logger) (net
 		case <-time.After(RetryDialInterval):
 			unixAddr := &net.UnixAddr{Name: addrWithoutProtocol, Net: "unix"}
 			if conn, err := net.DialUnix("unix", nil, unixAddr); err == nil {
-				logger.Println("[INFO] signctrl: Successfully dialed the validator ✓")
+				logger.Info("Successfully dialed the validator ✓")
 				return conn, nil
 			}
 
 			// After the first dial, dial in intervals of 1 second.
 			os.RemoveAll(addrWithoutProtocol)
 			RetryDialInterval = time.Second
-			logger.Println("[DEBUG] signctrl: Retry dialing...")
+			logger.Debug("Retry dialing...")
 		}
 	}
 }
 
 // RetryDial keeps dialing the given address until success and returns the connection.
-func RetryDial(cfgDir, address string, logger *log.Logger) (net.Conn, error) {
-	logger.Printf("[INFO] signctrl: Dialing %v... (Use Ctrl+C to abort)", address)
+func RetryDial(cfgDir, address string, logger *types.SyncLogger) (net.Conn, error) {
+	logger.Info("Dialing %v... (Use Ctrl+C to abort)", address)
 	sigs := make(chan os.Signal, 1)
 	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
 
@@ -86,7 +86,7 @@ func RetryDial(cfgDir, address string, logger *log.Logger) (net.Conn, error) {
 		// a secret/encrypted connection to the validator.
 		connKey, err := LoadConnKey(cfgDir)
 		if err != nil {
-			return nil, fmt.Errorf("[ERR] signctrl: couldn't load conn.key: %v", err)
+			return nil, fmt.Errorf("couldn't load conn.key: %v", err)
 		}
 		return retryDialTCP(address, connKey, sigs, logger)
 

connection/dial_test.go

@@ -5,13 +5,13 @@ import (
 	"crypto/rand"
 	"fmt"
 	"io/ioutil"
-	"log"
 	"net"
 	"os"
 	"sync"
 	"testing"
 	"time"
 
+	"github.com/BlockscapeNetwork/signctrl/types"
 	"github.com/stretchr/testify/assert"
 	tm_ed25519 "github.com/tendermint/tendermint/crypto/ed25519"
 	tm_p2pconn "github.com/tendermint/tendermint/p2p/conn"
@@ -70,7 +70,7 @@ func TestRetryDialTCP_NoConnKey(t *testing.T) {
 		assert.NoError(t, err)
 	}()
 
-	conn, err := RetryDial(cfgDir, "tcp://"+laddr, log.New(ioutil.Discard, "", 0))
+	conn, err := RetryDial(cfgDir, "tcp://"+laddr, types.NewSyncLogger(ioutil.Discard, "", 0))
 	assert.Nil(t, conn)
 	assert.Error(t, err)
 }
@@ -92,7 +92,7 @@ func TestRetryDialTCP_WithConnKey(t *testing.T) {
 		assert.NoError(t, err)
 	}()
 
-	conn, err := RetryDial(cfgDir, "tcp://"+laddr, log.New(ioutil.Discard, "", 0))
+	conn, err := RetryDial(cfgDir, "tcp://"+laddr, types.NewSyncLogger(ioutil.Discard, "", 0))
 	assert.NotNil(t, conn)
 	assert.NoError(t, err)
 }
@@ -131,15 +131,15 @@ func TestRetryDialUnix(t *testing.T) {
 		assert.NoError(t, err)
 	}()
 
-	conn, err := RetryDial(cfgDir, "unix://"+sockAddr, log.New(ioutil.Discard, "", 0))
+	conn, err := RetryDial(cfgDir, "unix://"+sockAddr, types.NewSyncLogger(ioutil.Discard, "", 0))
 	assert.NotNil(t, conn)
 	assert.NoError(t, err)
 
 	wg.Wait()
 }
 
 func TestRetryDialUnknown(t *testing.T) {
-	conn, err := RetryDial(".", "invalid://127.0.0.1:3000", log.New(ioutil.Discard, "", 0))
+	conn, err := RetryDial(".", "invalid://127.0.0.1:3000", types.NewSyncLogger(ioutil.Discard, "", 0))
 	assert.Nil(t, conn)
 	assert.Error(t, err)
 }

docs/core/ds-protection.md

@@ -4,18 +4,24 @@ This page covers how SignCTRL's underlying ranking system provides protection ag
 
 ## SignCTRL Set
 
-A SignCTRL set consists of two or more validators that all share the same keys, and thus represent the same validator entity. Letting all of those validators sign blocks simultaneously is a sure-fire way of getting slashed for double-signing, so there needs to be some form of coordination in terms of which validator in the set has permission to sign at any given point in time. Thus, the idea is very simple - only one validator in the set should sign blocks while the others back it up if it becomes unavailable.
+A SignCTRL set consists of two or more validators that share the same keypair, and thus represent the same validator entity. Letting all of those validators sign blocks simultaneously is a sure-fire way of getting slashed for double-signing, so there needs to be some form of coordination in terms of which validator in the set has permission to sign at any given point in time. Thus, the idea is very simple - only one validator in the set should sign blocks while the others back it up if it becomes unavailable.
 
 Contrary to approaches that add a consensus layer, and therefore more communication overhead, to the set of redundant validators, like [Raft](https://raft.github.io/), SignCTRL uses the blockchain itself as a perfectly synchronous communication line that the validators use to coordinate signing permissions.
 
 ## Validator Ranking
 
-SignCTRL employs a ranking system for the validators in its set which essentially just ranks the validators in descending order - and this ranking system is actually the key factor enabling double-signing protection.
+SignCTRL employs a ranking system for the validators in its set that ranks the validators in descending order and it is this ranking system that is the key factor enabling double-signing protection.
 
-A node's rank determines which blocks exactly it has permission to sign and which not. Only the highest-ranked validator signs blocks while the others serve as backups. The validators can move up one rank at a time if one key criterion is met - and that is if too many blocks have been missed in a row. So, rank updates are triggered by too many blocks on the blockchain being missed in a row.
+### Ranks
+
+A node's rank determines which blocks exactly it has permission to sign and which not. Only the highest-ranked validator signs blocks while the others queue up as backups. The validators can move up one rank at a time if one key criterion is met - and that is if too many blocks have been missed in a row. So, rank updates are triggered by too many blocks on the blockchain being missed in a row.
 
 ![Rank Updates](../imgs/rank-update.gif)
 
-In order to detect missed blocks, the validators closely monitor every single block in the blockchain. This includes looking into every last block's commit signatures and checking for the own validator's signature. If the signature is missing, every validator in the set will see it and increment an internal counter for missed blocks in a row. If a certain threshold is exceeded, ranks 2..n will notice first and accordingly move up one rank each. Once rank 1 becomes available again, it will have to sync up its blockchain state. Eventually, while syncing, it will also notice that is has been replaced and needs to shut itself down. It can then later be readded to the set with the lowest rank, though.
+In order to detect missed blocks, the validators closely monitor every single block in the blockchain. This includes looking into every last block's commit signatures and checking for their own validator's signature. If the signature is missing, every validator in the set will see it and increment an internal counter. If a certain threshold is exceeded, ranks 2..n will notice first and accordingly move up one rank each. Once rank 1 becomes available again, it will have to sync up its blockchain state. Eventually, while syncing, it will also notice that is has been replaced and needs to shut itself down. It can then later be readded to the set with the lowest rank, though.
+
+### State
+
+Before the node shuts itself down, it persists its last rank and last height in a separate `signctrl_state.json` file. This file acts as a protection mechanism against launching a validator with an rank that has been rendered obsolete by a rank update in the set, which is the case if the requested height differs more than `threshold+1` from the last height persisted in the state file.
 
-Before the node shuts itself down, though, it persists its last rank in a separate `last_rank.json` file which indicates that its last rank was different than the rank specified in the `config.toml`. On startup it then checks for the last rank and starts up with that instead of the one specified in the configuration file.
+For now, the only way to recover from a deprecated state is to delete the `signctrl_state.json` and start the validator back up again with the correct `start_rank` in its `config.toml`.