Orbs is a public blockchain infrastructure built for the needs of decentralized apps with millions of users. For more information, please check https://orbs.com and read the white papers.
This repo contains the node core reference implementation in golang.
The project is thoroughly tested with unit tests, component tests per microservice, acceptance tests, E2E tests and E2E stress tests running the system under load.
If you only want to build the Docker images containing the node binaries, you don't need to have golang on your own machine (the node will be compiled inside the image).
-
Make sure Docker is installed.
Verify with
docker version -
Run
./docker/build/build-docker-node.shto create node imageorbs:export. -
Run
./docker/build/build-gamma.shto create gamma image:orbs:gamma-servercontains self-sufficient development binary (similar to Ethereum's Ganache) and gamma-cli to communicate with its server counterpart.
-
Make sure Go is installed (version 1.10 or later).
Verify with
go version -
Make sure Go workspace bin is in your path.
Install with
export PATH=$PATH:`go env GOPATH`/binVerify with
echo $PATH -
Make sure Git is installed (version 2 or later).
Verify with
git --version -
If you're interested in building Docker images as well, install Docker.
Verify with
docker version
-
Clone the repo to your Go workspace:
cd `go env GOPATH` go get github.com/orbs-network/orbs-network-go cd src/github.com/orbs-network/orbs-network-go git checkout master -
Install dependencies with
./git-submodule-checkout.sh. To understand dependency management flow please refer to the dependency documentation. -
Build with
go install -
You can build all the binaries (
orbs-node,gamma-cliandgamma-server) with./build-binaries.sh.
-
To run the pre-built binary (should be in path):
orbs-network-go -
To rebuild from source and run (this will take you to project root):
cd `go env GOPATH` cd src/github.com/orbs-network/orbs-network-go go run *.go
We use the official go test runner go test. It has minimal UI and result caching.
Please install go-junit-reporter prior to running tests for the first time:
go get -u github.com/orbs-network/go-junit-report
-
Run all tests using a script:
./test.sh -
Manually run all tests from project root:
go test ./... -
Manually run only fast tests (no E2E and similar):
go test -short ./... -
Check unit test coverage:
go test -cover `go list ./...`
End-to-end tests check the entire system in a real life scenario mimicking real production with multiple nodes. It runs on docker with several nodes connected in a cluster. Due to their nature, E2E tests are slow to run.
- The tests are found in
/test/e2e - Run the suite from project root with
go test ./test/e2e
Integration tests check the system adapters and make sure they meet the interface contract they implement. For example connection to a database or network sockets.
- The tests are found per adapter (per service), eg.
/services/gossip/adapter
Acceptance tests check the internal hexagon of the system (it's logic with all microservices) with faster adapters that allow the suite to run extremely fast.
- The tests are found in
/test/acceptance - Run the suite from project root with
go test ./test/acceptance
Component tests check that a single service meets its specification while mocking the other services around it. They allow development of a service in isolation.
- The tests are found per service in the
testdirectory, eg./services/transactionpool/test
Unit tests are very specific tests that check a single unit or two. They test the unit in isolation and stub/mock everything around it.
- The tests are found next to the actual unit in a file with
_test.gosuffix, eg.sha256_test.gositting next tosha256.go
For Troubleshooting, see the Docker Guide
All tests run automatically when the Docker images are built. The script ./test.sh is part of the Docker build.
-
Run
./docker/build/build.sh && ./docker/test/test.shto build all images and run E2E tests in a dockerized environment. -
The logs for all E2E nodes will be placed on your machine under the
./_logsdirectory of the project (and will be overridden on every E2E run).
To detect flaky tests of specific components, run component tests multiple times on Docker:
- To enable running component tests multiple times, edit
test.shand uncomment the line./test.components.sh - To modify the number of times each component test runs, edit
test.components.shand modify the value of the COUNT variable (you may also need to modify the various timeouts) - optional To run a specific test (component, unit, of any other) multiple times (useful when debugging a specific scenario for flakiness), edit
test.components.sh, comment the linerun_component_tests, then uncomment the line starting withrun_specific_testand modify the test name to run that one specific test multiple times on Docker.
After you've finished editing, run ./docker/build/build.sh && ./docker/test/test.sh
You should probably not commit any of these edits you've made for testing, as they are transient in nature.
Please run git config --local core.hooksPath .githooks after cloning the repository.
Occasionally, local tests with go test will pass but the same tests on Docker will fail. This usually happens when tests are flaky and sensitive to timing (we do our best to avoid this).
-
Run
./docker/build/build.shand./docker/test/test.sh. -
If the E2E test gets stuck or
docker-composestops working properly, try to remove all containers with this handy command:docker rm -f $(docker ps -aq). But remember that ALL YOUR LOCAL CONTAINERS WILL BE GONE (even from other projects). -
Debugging the acceptance suite is problematic out of the box, since the debugger (Delve) doesn't support any code importing the
pluginpackage. Luckily, the acceptance suite relies on a fake compiler; to enable debugging:- in Goland
- Go to Preferences -> Go -> Vendoring & Build Tags
- Add the tag
nonativecompilerunder 'custom tags' - Create a run configuration for the desired test (by clicking the "play" icon to the left of the test name)
- Run it once (to create the run config)
- Edit the run config and check "use all custom build tags"
- Debug your test
- in Goland
-
We recommend working on the project with GoLand IDE. Recommended settings:
- Under
Preferences | Editor | Code Style | Gomake sureUse tab characteris checked
- Under
-
We reccommend using the same version of Go as per our CI (1.12.9 at the time this line is written)
- To change Go SDK version in GoLand, go to
Preferences | Go | GOROOT, click the+button, chooseDownload, and choose the version you want to use for this project. As soon as the selected SDK version is installed, GoLand will notify you in the Event Log window. Then go toPreferences | Go | GOPATHand underProject GOPATHchoose the location of the SDK you have installed.
- To change Go SDK version in GoLand, go to
-
For easy testing, under
Run | Edit Configurationsadd theseGo Testconfigurations:- "Fast" with
Directoryset to project root and-shortflag added toGo tool arguments - "All" with
Directoryset to project root - It's also recommended to uncheck
Show Ignoredtests and checkShow Passedin the test panel after running the configuration - If you have a failed test which keeps failing due to cache click
Rerun Failed Testsin the test panel (it will ignore cache)
- "Fast" with
-
Running some tests that are unsafe for production deployments requires a special build flag, enable it if you're a core developer:
- Under
Preferences | Go | Vendoring & Build Tags | Custom tagsadd the tagunsafetests
- Under
-
You may enable the following automatic tools that run on file changes:
- "go fmt" in
Preferences | Tools | File Watchers, add with+thego fmtwatcher - To run tests automatically on save, check
Toggle auto-testin the test panel (it's now a core feature of GoLand)
- "go fmt" in
-
Debugging tests may contain very verbose logs, increase console buffer size in
Preferences | Editor | General | Console | Override console cycle buffer size = 10024 KB -
If you experience lags or Low Memory warnings while working with GoLand, increasing its default VM heap size can help:
-
Go to
Help | Edit Custom VM Options...and set:-Xms256m -Xmx1536m
To enable profiling: put "profiling": true in your config.json.
It will enable net/http/pprof package, and you will be able to query pprof via http just as described in the docs.
By default, log output is filtered to only errors and metrics. To enable full log, put "logger-full-log": true in your node configuration. It will permanently remove the filter.
If you want to enable or disable this filter in production, there is a way to do that via HTTP API:
curl -XPOST http://$NODE_IP/vchains/$VCHAIN/debug/logs/fiter-on
Or
curl -XPOST http://$NODE_IP/vchains/$VCHAIN/debug/logs/fiter-off
Refer to the Contributor's Guide (work in progress)
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent