go-lachesis

README

Lachesis

aBFT Consensus platform for distributed applications.

Build Details

Code Quality

Documentation.

GitHub

Social

Features

• k-node selection
• k-parent EventBlock
• EventBlock merge
• Lachesis consensus
  • Dominators
  • Self Dominators
  • Atropos
  • Clotho
  • Frame
  • Frame Received
  • Dominated
  • Lamport Timestamp
  • Atropos Consensus Time
  • Consensus Timestamp
  • Ordering on same Consensus Timestamp (Lamport Timestamp)
  • Ordering on same Lamport Timestamp (Flag Table)
  • Ordering on same Flag Table (Signature XOR)
  • Transaction submit
  • Consensus Transaction output
  • Dynamic participants
    • Peer add
    • Peer Remove
• Caching for performances
• Sync
• Event Signature
• Transaction validation
• Optimum Network pruning

Dev

Docker

Create an 3 node lachesis cluster with:

n=3 BUILD_DIR="$PWD" ./scripts/docker/scale.bash

Dependencies

• Docker
• jq
• Bash
• git
• Go
• Glide
• batch-ethkey with: go get -u github.com/SamuelMarks/batch-ethkey
• protocol buffers 3, with: installation of a release & go get -u github.com/golang/protobuf/protoc-gen-go

Protobuffer 3

This project uses protobuffer 3 for the communication between posets. To use it, you have to install both protoc and the plugin for go code generation.

Once the stack is setup, you can compile the proto messages by running this command:

make proto

Lachesis and dependencies

Clone the repository in the appropriate GOPATH subdirectory:

$ d="$GOPATH/src/github.com/Fantom-foundation"
$ mkdir -p "$d"
$ git clone https://github.com/Fantom-foundation/go-lachesis.git "$d"

Lachesis uses Glide to manage dependencies.

$ curl https://glide.sh/get | sh
$ cd "$GOPATH/src/github.com/Fantom-foundation" && glide install

This will download all dependencies and put them in the vendor folder.

Other requirements

Bash scripts used in this project assume the use of GNU versions of coreutils. Please ensure you have GNU versions of these programs installed:-

example for macos:

# --with-default-names makes the `sed` and `awk` commands default to gnu sed and gnu awk respectively.
brew install gnu-sed gawk --with-default-names

Testing

Lachesis has extensive unit-testing. Use the Go tool to run tests:

[...]/lachesis$ make test

If everything goes well, it should output something along these lines:

?   	github.com/Fantom-foundation/go-lachesis/cmd/dummy	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/cmd/dummy/commands	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/cmd/dummy_client	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/cmd/lachesis	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/cmd/lachesis/commands	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/tester	[no test files]
ok  	github.com/Fantom-foundation/go-lachesis/src/common	(cached)
ok  	github.com/Fantom-foundation/go-lachesis/src/crypto	(cached)
ok  	github.com/Fantom-foundation/go-lachesis/src/difftool	(cached)
ok  	github.com/Fantom-foundation/go-lachesis/src/dummy	0.522s
?   	github.com/Fantom-foundation/go-lachesis/src/lachesis	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/log	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/mobile	[no test files]
ok  	github.com/Fantom-foundation/go-lachesis/src/net	(cached)
ok  	github.com/Fantom-foundation/go-lachesis/src/node	9.832s
?   	github.com/Fantom-foundation/go-lachesis/src/pb	[no test files]
ok  	github.com/Fantom-foundation/go-lachesis/src/peers	(cached)
ok  	github.com/Fantom-foundation/go-lachesis/src/poset	9.627s
ok  	github.com/Fantom-foundation/go-lachesis/src/proxy	1.019s
?   	github.com/Fantom-foundation/go-lachesis/src/proxy/internal	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/proxy/proto	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/service	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/utils	[no test files]
?   	github.com/Fantom-foundation/go-lachesis/src/version	[no test files]

New test creation

Lachesis is a multi-thread application and therefore it is important to check for leaking goroutines when creating new modules. To facilitate such testing we use github.com/fortytw2/leaktest package. Please see the following example how to integrate leaktest into your tests:

package newone
import (
     "testing"
     "time"
     ...
	 "github.com/fortytw2/leaktest"
)

func TestNewOne(t *testing.T) {
    // you may adjust 30 seconds timeout below to a reasonable value
    // according to operations of your test. Usually timeout of 1 second is enough
    defer leaktest.CheckTimeout(t, 30 * time.Second)()

    // put your testing code here
}

Cross-build from source

The easiest way to build binaries is to do so in a hermetic Docker container. Use this simple command:

[...]/lachesis$ make dist

This will launch the build in a Docker container and write all the artifacts in the build/ folder.

[...]/lachesis$ tree --charset=nwildner build
build
|-- dist
|   |-- lachesis_0.4.3_SHA256SUMS
|   |-- lachesis_0.4.3_darwin_386.zip
|   |-- lachesis_0.4.3_darwin_amd64.zip
|   |-- lachesis_0.4.3_freebsd_386.zip
|   |-- lachesis_0.4.3_freebsd_arm.zip
|   |-- lachesis_0.4.3_linux_386.zip
|   |-- lachesis_0.4.3_linux_amd64.zip
|   |-- lachesis_0.4.3_linux_arm.zip
|   |-- lachesis_0.4.3_windows_386.zip
|   `-- lachesis_0.4.3_windows_amd64.zip
|-- lachesis
`-- pkg
    |-- darwin_386
    |   `-- lachesis
    |-- darwin_386.zip
    |-- darwin_amd64
    |   `-- lachesis
    |-- darwin_amd64.zip
    |-- freebsd_386
    |   `-- lachesis
    |-- freebsd_386.zip
    |-- freebsd_arm
    |   `-- lachesis
    |-- freebsd_arm.zip
    |-- linux_386
    |   `-- lachesis
    |-- linux_386.zip
    |-- linux_amd64
    |   `-- lachesis
    |-- linux_amd64.zip
    |-- linux_arm
    |   `-- lachesis
    |-- linux_arm.zip
    |-- windows_386
    |   `-- lachesis.exe
    |-- windows_386.zip
    |-- windows_amd64
    |   `-- lachesis.exe
    `-- windows_amd64.zip

11 directories, 29 files