Network Runner & Testing Framework

Abstract

This LP specifies the Lux Network Runner and testing frameworks (for the netrunner repo). This LP defines how to instantiate and manage local networks for testing and development.

Specification

(This LP will outline a standard interface (CLI commands, config files, APIs) to spin up a multi-chain Lux network on a developer’s machine or CI environment.)

Rationale

By formalizing this in a LP, contributors will know how to test protocol changes and new applications in a controlled environment, which improves the overall quality and reliability of Lux’s ecosystem.

Motivation

A standard network runner removes ad‑hoc scripts and inconsistencies, enabling reliable local/CI testing, reproducible environments, and faster iteration for protocol and dApp developers.

Implementation

Network Runner Framework

Location: ~/work/lux/netrunner/ GitHub: github.com/luxfi/netrunner/tree/main

Core Components:

• local/ - Local network management (19 files)
  • network.go - Network orchestration (35.5 KB)
  • blockchain.go - Blockchain management (43.3 KB)
  • node_process.go - Node process control (6.4 KB)
• api/ - RPC and HTTP APIs (6 files)
• network/ - Network configuration (default topology, genesis)

Default Network:

• 5 validators, local network ID (1337)
• Pre-generated staking keys and certificates
• Automatic port assignment (9650+ API, 9651+ P2P)
• Bootstrap node configuration

Testing:

cd ~/work/lux/netrunner
go test -v ./...

Quick Start:

network, _ := local.NewDefaultNetwork(logger, "/path/to/luxd", true)
defer network.Stop(context.Background())

ctx, _ := context.WithTimeout(context.Background(), 2*time.Minute)
network.Healthy(ctx)  # Bootstrap all 4 chains

CLI Integration

Location: ~/work/lux/cli/cmd/network/ GitHub: github.com/luxfi/cli/tree/main/cmd/network

Commands:

• lux network start - Launch local network with specified node version
• lux network status - Check bootstrap status
• lux network stop - Gracefully shut down network

Test Cases

Unit Tests

1. Component Initialization

   • Verify correct initialization of all components
   • Test configuration validation
   • Validate error handling for invalid configurations

2. Core Functionality

   • Test primary operations under normal conditions
   • Verify expected outputs for standard inputs
   • Test edge cases and boundary conditions

3. Error Handling

   • Verify graceful handling of invalid inputs
   • Test recovery from transient failures
   • Validate error messages and codes

Integration Tests

1. Cross-Component Integration

   • Test interaction between related components
   • Verify data flow across module boundaries
   • Validate state consistency

2. Performance Tests

   • Benchmark critical operations
   • Verify performance under load
   • Test resource utilization limits

Copyright

Copyright and related rights waived via CC0.

Backwards Compatibility

Additive specification; no breaking changes to existing interfaces. Adoption is optional per component.

Security Considerations

Follow threat models relevant to this LP (input validation, replay/DoS protections, key handling). Implement recommended mitigations.