Development Tools

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.

Category	Entry Point	Primary Use Cases
Build Automation	build/ci.go, Makefile	Executable builds, cross-compilation, release packaging
CI/CD Pipelines	.travis.yml, appveyor.yml	Automated testing, builds, deployment
Network Tools	cmd/devp2p/	P2P network diagnostics, DNS discovery management
Chain Management	cmd/utils/cmd.go	Chain import/export, Era1, snapshot management
Code Quality	.golangci.yml, build/ci.go	Static analysis, linting
Testing	internal/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.

Command	Purpose	Implementation
make gstable	Build main node	go run build/ci.go install ./cmd/gstable
make genesis_generator	Build genesis generator	go run build/ci.go install ./cmd/genesis_generator
make all	Build all executables	go run build/ci.go install
make test	Run tests	go run build/ci.go test
make lint	Static analysis	Runs golangci-lint
make devtools	Install dev tools	stringer, gencodec, abigen, etc.

Quick Reference: Available Tools

Build and Release Tools

Tool	Location	Command	Description
Main build script	build/ci.go	go run build/ci.go <cmd>	Build orchestration
Makefile	Makefile	make <target>	Developer convenience wrapper

Network and Discovery Tools

Tool	Location	Description
devp2p	cmd/devp2p/	P2P network diagnostics
DNS discovery	cmd/devp2p/dnscmd.go	DNS-based node discovery management
Discovery v4/v5	cmd/devp2p/discv4cmd.go, discv5cmd.go	DHT-based discovery protocol testing
Node crawler	cmd/devp2p/crawl.go	Network topology collection

Chain Management Tools

Tool	Location	Description
Chain import/export	cmd/utils/cmd.go	Chain data migration
Era1 archive	cmd/utils/cmd.go	Historical block management
Preimage tools	cmd/utils/cmd.go	Hash preimage management
Snapshot export	cmd/utils/cmd.go	State snapshot preimages

Testing and Verification Tools

Tool	Location	Description
Unit tests	Entire codebase	Go standard tests
P2P protocol tests	cmd/devp2p/internal/v4test/	Discovery v4 compliance tests
Test utilities	internal/utesting/	TAP-compatible test runner
Linter	.golangci.yml	golangci-lint-based static analysis

Build Flags and Configuration

Cross-Compilation Flags

Flag	Description
-arch	Target architecture
-cc	C compiler for cgo
-static	Static binary linking
-dlgo	Download 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.

Tool	Version	Purpose
Go compiler	1.21.6	Build toolchain
golangci-lint	1.55.2	Linting
execution-spec-tests	2.1.0	Execution 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