Skip to main content

​
Purpose and Scope

This document provides an overview of all development tools available in the go-stablenet codebase.
The tools covered here support the entire lifecycle of building, testing, debugging, operating, and maintaining StableNet nodes and networks. The development tools are organized into four major categories, each of which is described in detail in its own subdocument.
  • Building and CI/CD
    Build system, cross-compilation, and CI/CD pipeline
  • devp2p CLI Tools
    DNS-based discovery, P2P network diagnostics, and testing tools
  • Data Import and Export Utilities
    Blockchain data management tools (chain, history, snapshots)
  • Testing and Debugging
    Test frameworks, protocol validation, and static analysis tools
Rather than describing individual commands in detail, this document serves as a high-level guide to understanding the overall tool ecosystem and how the tools relate to each other.

​
Tool Categories

Development tools are distributed across the codebase, with the following primary entry points.
CategoryEntry PointPrimary Use Cases
Build Automationbuild/ci.go, MakefileExecutable builds, cross-compilation, release packaging
CI/CD Pipelines.travis.yml, appveyor.ymlAutomated testing, builds, deployment
Network Toolscmd/devp2p/P2P network diagnostics, DNS discovery management
Chain Managementcmd/utils/cmd.goChain import/export, Era1, snapshot management
Code Quality.golangci.yml, build/ci.goStatic analysis, linting
Testinginternal/utesting/, cmd/devp2p/internal/v4test/Unit tests, P2P protocol tests

​
Build System Architecture

The core of the build system is build/ci.go, which acts as the single control point for all build, test, and release tasks.

​
Key Components

  • build/ci.go
    Main orchestrator for building, testing, archiving, and uploading
  • build.GoToolchain
    Manages Go compiler configuration, including cross-compilation
  • build.Environment
    Collects commit, date, branch, and tag metadata from CI or local Git environments
  • build.ChecksumDB
    Verifies external dependency integrity using build/checksums.txt
This build system supports the following via -arch and -cc flags:
  • Architectures: amd64, 386, arm, arm64
  • Platforms: linux, darwin, windows, freebsd

​
CI/CD Pipeline Architecture

Continuous Integration (CI) is split by platform characteristics.
  • Travis CI: Linux / macOS
  • AppVeyor: Windows
This separation ensures consistent multi-platform release quality from a single codebase.

​
Pipeline Stages

  1. Code Push Trigger
    Triggered on pushes to the master branch or version tags
  2. Parallel Builds
    Parallel jobs per platform and architecture
  3. Test Execution
    Basic tests on all builds, race detection in scheduled jobs
  4. Artifact Generation
    Creation of signed binary archives in zip / tar.gz formats

​
Development Tool Invocation Flow

The following shows how developers typically interact with tools locally and in CI environments.
CommandPurposeImplementation
make gstableBuild main nodego run build/ci.go install ./cmd/gstable
make genesis_generatorBuild genesis generatorgo run build/ci.go install ./cmd/genesis_generator
make allBuild all executablesgo run build/ci.go install
make testRun testsgo run build/ci.go test
make lintStatic analysisRuns golangci-lint
make devtoolsInstall dev toolsstringer, gencodec, abigen, etc.

​
Quick Reference: Available Tools

​
Build and Release Tools

ToolLocationCommandDescription
Main build scriptbuild/ci.gogo run build/ci.go <cmd>Build orchestration
MakefileMakefilemake <target>Developer convenience wrapper

​
Network and Discovery Tools

ToolLocationDescription
devp2pcmd/devp2p/P2P network diagnostics
DNS discoverycmd/devp2p/dnscmd.goDNS-based node discovery management
Discovery v4/v5cmd/devp2p/discv4cmd.go, discv5cmd.goDHT-based discovery protocol testing
Node crawlercmd/devp2p/crawl.goNetwork topology collection

​
Chain Management Tools

ToolLocationDescription
Chain import/exportcmd/utils/cmd.goChain data migration
Era1 archivecmd/utils/cmd.goHistorical block management
Preimage toolscmd/utils/cmd.goHash preimage management
Snapshot exportcmd/utils/cmd.goState snapshot preimages

​
Testing and Verification Tools

ToolLocationDescription
Unit testsEntire codebaseGo standard tests
P2P protocol testscmd/devp2p/internal/v4test/Discovery v4 compliance tests
Test utilitiesinternal/utesting/TAP-compatible test runner
Linter.golangci.ymlgolangci-lint-based static analysis

​
Build Flags and Configuration

​
Cross-Compilation Flags

FlagDescription
-archTarget architecture
-ccC compiler for cgo
-staticStatic binary linking
-dlgoDownload specified Go version

​
CI Environment Variables

In CI environments, commit metadata, signing keys, and upload tokens are injected via environment variables.
  • TRAVIS_COMMIT, APPVEYOR_REPO_COMMIT
  • AZURE_BLOBSTORE_TOKEN
  • LINUX_SIGNING_KEY, OSX_SIGNING_KEY
  • AWS_ACCESS_KEY_ID (for DNS management)

​
Tool Dependencies and Versions

All external tool dependencies have pinned versions and SHA256 checksums in build/checksums.txt.
ToolVersionPurpose
Go compiler1.21.6Build toolchain
golangci-lint1.55.2Linting
execution-spec-tests2.1.0Execution spec tests
When required, tools are automatically downloaded and verified via build.ChecksumDB.
For practical usage examples and detailed instructions, refer to the following subdocuments:
  • Building and CI/CD
  • devp2p CLI Tools
  • Data Import and Export Utilities
  • Testing and Debugging