This document is the entry point for developers who wish to work on the Parallax client. Developers are people who are interested to build, develop, debug, submit a bug report or pull request or otherwise contribute to the Parallax client source code.
Please see Contributing for the Parallax client contribution guidelines.
Building and Testing
Developers should use a recent version of Go for building and testing. We use the go toolchain for development, which you can get from the Go downloads page. The Parallax client is a Go module, and uses the Go modules system to manage dependencies. Using GOPATH is not required to build the Parallax client.
Building Executables
Switch to the parallax repository root directory. All code can be built using the go tool, placing the resulting binary in $GOPATH/bin.
The Parallax executables can be built individually. To build just the Parallax client, use:
Cross compilation is not recommended, please build the Parallax client for the host architecture.
Testing
Testing a package:
Running an individual test:
go test -v ./eth -run TestMethod
Note: here all tests with prefix TestMethod will be run, so if TestMethod and TestMethod1 both exist then both tests will run.
go test -v -bench . -run BenchmarkJoin
Getting Stack Traces
A stack trace provides a very detailed look into the current state of the Parallax node. It helps us to debug issues easier as it contains information about what is currently done by the node. Stack traces can be created by running debug.stacks() in the Parallax client console. If the node was started without the console command or with a script in the background, the following command can be used to dump the stack trace into a file.
prlx attach <path-to-prlx.ipc> --exec "debug.stacks()" > stacktrace.txt
/home/user/.parallax/prlx.ipc or /tmp/prlx.ipc.
debug.stacks() also takes an optional filter argument. Passing a package name or filepath to filter restricts the output to stack traces involving only that package/file. For example:
returns data that looks like:
INFO [11-04|16:15:54.486] Expanded filter expression filter=enode expanded="`enode` in Value"
goroutine 121 [chan receive, 3 minutes]:
github.com/microstack-tech/parallax/p2p/enode.(*FairMix).nextFromAny(...)
github.com/microstack-tech/parallax/p2p/enode/iter.go:241
github.com/microstack-tech/parallax/p2p/enode.(*FairMix).Next(0xc0008c6060)
github.com/microstack-tech/parallax/p2p/enode/iter.go:215 +0x2c5
github.com/microstack-tech/parallax/p2p.(*dialScheduler).readNodes(0xc00021c2c0, {0x18149b0, 0xc0008c6060})
github.com/microstack-tech/parallax/p2p/dial.go:321 +0x9f
created by github.com/microstack-tech/parallax/p2p.newDialScheduler
github.com/microstack-tech/parallax/p2p/dial.go:179 +0x425
debug.stacks("consolecmd.go")
INFO [11-04|16:16:47.141] Expanded filter expression filter=consolecmd.go expanded="`consolecmd.go` in Value"
goroutine 1 [chan receive]:
github.com/microstack-tech/parallax/internal/jsre.(*JSRE).Do(0xc0004223c0, 0xc0003c00f0)
github.com/microstack-tech/parallax/internal/jsre/jsre.go:230 +0xf4
github.com/microstack-tech/parallax/internal/jsre.(*JSRE).Evaluate(0xc00033eb60?, {0xc0013c00a0, 0x1e}, {0x180d720?, 0xc000010018})
github.com/microstack-tech/parallax/internal/jsre/jsre.go:289 +0xb3
github.com/microstack-tech/parallax/console.(*Console).Evaluate(0xc0005366e0, {0xc0013c00a0?, 0x0?})
github.com/microstack-tech/parallax/console/console.go:353 +0x6d
github.com/microstack-tech/parallax/console.(*Console).Interactive(0xc0005366e0)
github.com/microstack-tech/parallax/console/console.go:481 +0x691
main.localConsole(0xc00026d580?)
github.com/microstack-tech/parallax/cmd/prlx/consolecmd.go:109 +0x348
github.com/microstack-tech/parallax/internal/flags.MigrateGlobalFlags.func2.1(0x20b52c0?)
github.com/microstack-tech/parallax/internal/flags/helpers.go:91 +0x36
github.com/urfave/cli/v2.(*Command).Run(0x20b52c0, 0xc000313540)
github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/command.go:177 +0x719
github.com/urfave/cli/v2.(*App).RunContext(0xc0005501c0, {0x1816128?, 0xc000040110}, {0xc00003c180, 0x3, 0x3})
github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:387 +0x1035
github.com/urfave/cli/v2.(*App).Run(...)
github.com/urfave/cli/v2@v2.17.2-0.20221006022127-8f469abc00aa/app.go:252
main.main()
github.com/microstack-tech/parallax/cmd/prlx/main.go:266 +0x47
goroutine 159 [chan receive, 4 minutes]:
github.com/microstack-tech/parallax/node.(*Node).Wait(...)
github.com/microstack-tech/parallax/node/node.go:529
main.localConsole.func1()
github.com/microstack-tech/parallax/cmd/prlx/consolecmd.go:103 +0x2d
created by main.localConsole
github.com/microstack-tech/parallax/cmd/prlx/consolecmd.go:102 +0x32e
--pprof option, a debugging HTTP server is made available on port 6060. Navigating to http://localhost:6060/debug/pprof displays the heap, running routines etc. By clicking “full goroutine stack dump” a trace can be generated that is useful for debugging.
Note that if multiple instances of the Parallax client exist, port 6060 will only work for the first instance that was launched. To generate stacktraces for other instances, they should be started up with alternative pprof ports. Ensure stderr is being redirected to a logfile.
prlx -port=30300 -verbosity 5 --pprof --pprof.port 6060 2>> /tmp/00.glog
prlx -port=30301 -verbosity 5 --pprof --pprof.port 6061 2>> /tmp/01.glog
prlx -port=30302 -verbosity 5 --pprof --pprof.port 6062 2>> /tmp/02.glog
-QUIT signal with kill:
This will dump stack traces for each instance to their respective log file.
Where to go next
Read the remaining pages in the Parallax client developer section, and get building! 
