Lux Netrunner

                    ┌──────────────────────────────────┐
                    │        CLI / Client SDK           │
                    └──────────┬───────────────────────┘
                               │ gRPC / REST
                    ┌──────────▼───────────────────────┐
                    │      Control Server (server/)     │
                    │  PingService + ControlService     │
                    └──┬───────────┬───────────────────┘
                       │           │
          ┌────────────▼──┐  ┌─────▼──────────────────┐
          │  Local Network │  │  Multi-Engine Host     │
          │  (local/)      │  │  (orchestrator/)       │
          │  Lux nodes     │  │  Lux/Geth/OP/Eth2     │
          └────────┬───────┘  └──────┬─────────────────┘
                   │                 │
          ┌────────▼───────┐  ┌──────▼─────────────────┐
          │  Snapshot Mgr  │  │  MultiNet Manager      │
          │  BadgerDB/zstd │  │  (multinet/)           │
          └────────────────┘  │  Cross-chain ACID txs  │
                              └────────────────────────┘

message StartRequest {
  string network_name = 1;    // "mainnet", "testnet", "devnet", "custom"
  string node_type = 2;       // "luxd", "luxgo", "geth", "op-node", "custom"
  string exec_path = 4;
  optional uint32 num_nodes = 5;
  optional string global_node_config = 7;
  optional string root_data_dir = 8;
  string plugin_dir = 9;
  repeated BlockchainSpec blockchain_specs = 10;
  map<string, string> custom_node_configs = 11;
  map<string, string> chain_configs = 12;
  map<string, string> upgrade_configs = 13;
  optional bool reassign_ports_if_used = 14;
  optional bool dynamic_ports = 15;
}

cli, _ := client.New(client.Config{
    Endpoint:    "localhost:8080",
    DialTimeout: 10 * time.Second,
}, logger)
defer cli.Close()

// Start 5-node local network
resp, _ := cli.Start(ctx, "/usr/local/bin/luxd",
    client.WithNumNodes(5),
    client.WithDynamicPorts(true),
    client.WithPluginDir("/path/to/plugins"),
    client.WithChainSpecs([]*rpcpb.BlockchainSpec{{
        VmName:  "chainevm",
        Genesis: "/path/to/genesis.json",
    }}),
)

// Wait for health
cli.WaitForHealthy(ctx)

// Get node URIs
uris, _ := cli.URIs(ctx)

// Manage nodes
cli.PauseNode(ctx, "node3")
cli.ResumeNode(ctx, "node3")
cli.RestartNode(ctx, "node1", client.WithExecPath("/new/luxd"))
cli.AddNode(ctx, "node6", "/usr/local/bin/luxd")
cli.RemoveNode(ctx, "node6")

// Snapshots (incremental BadgerDB + zstd compression)
cli.SaveSnapshot(ctx, "pre-upgrade")
cli.SaveHotSnapshot(ctx, "live-backup")  // No network stop
cli.LoadSnapshot(ctx, "pre-upgrade")

// P2P testing
attachResp, _ := cli.AttachPeer(ctx, "node1")
cli.SendOutboundMessage(ctx, "node1", attachResp.AttachedPeerInfo.Id, 0, msgBytes)

// Elastic chains
cli.TransformElasticChains(ctx, []*rpcpb.ElasticChainSpec{{
    ChainId:          "chain-id",
    AssetName:        "TEST",
    AssetSymbol:      "TST",
    MinValidatorStake: 1000,
}})
cli.AddPermissionlessValidator(ctx, []*rpcpb.PermissionlessValidatorSpec{{
    ChainId:           "chain-id",
    NodeName:          "node1",
    StakedTokenAmount: 5000,
}})

cli.Stop(ctx)

type Engine interface {
    Name() string
    Type() EngineType
    Start(ctx context.Context, config *NodeConfig) error
    Stop(ctx context.Context) error
    Restart(ctx context.Context) error
    Health(ctx context.Context) (*HealthStatus, error)
    IsRunning() bool
    Uptime() time.Duration
    NetworkID() uint32
    ChainID() ids.ID
    RPCEndpoint() string
    WSEndpoint() string
    P2PEndpoint() string
    ParentChain() *ChainInfo  // nil for L1s
    Metrics() map[string]interface{}
}

# stacks/lux-local.yaml
name: lux-local
version: 1.0.0
description: Local Lux L1 for testing

engines:
  - name: lux-node-1
    type: lux
    network_id: 96369
    http_port: 9650
    staking_port: 9651
    log_level: info
    wait_healthy: true
    extra:
      dev-mode: true

networks:
  - name: lux-local
    type: l1
    engine: lux-node-1
    chain_id: 96369

mgr, _ := multinet.NewMultiNetworkManager(logger, "/tmp/shared-db")
defer mgr.Shutdown()

mgr.AddNetwork(multinet.NetworkConfig{
    NetworkID: 1, Name: "mainnet", Type: multinet.NetworkTypePrimary,
    Validators: 5,
})
mgr.AddNetwork(multinet.NetworkConfig{
    NetworkID: 2, Name: "chain-a", Type: multinet.NetworkTypeChain,
    ParentID: 1,
})
mgr.StartAll()

// Cross-chain ACID transaction
mgr.SubmitCrossChainTx(&multinet.CrossChainTx{
    ID: "tx-1", SourceNet: 1, DestNet: 2,
    Amount: 1000, Asset: "LUX",
})

make build        # Build netrunner binary
make test         # Run tests
make test-race    # Tests with race detector
make bench        # Run benchmarks
make build-all    # Cross-compile (linux/darwin/windows, amd64/arm64)
make install      # Install to /usr/local/bin
make lint         # golangci-lint
make release      # Generate release artifacts

netrunner/
  main.go              # Entry point
  cmd/                  # CLI commands (server, control, ping, genkeys)
  server/               # gRPC + HTTP gateway server
  client/               # Go client SDK
  rpcpb/                # Protobuf definitions
  local/                # Local network implementation (process management)
  network/              # Network interface + config + genesis generation
  orchestrator/         # Multi-engine host (Lux/Geth/OP/Eth2)
  engines/              # Engine interface + implementations (lux, geth, k8s, opstack, eth2)
  multinet/             # Multi-network manager with shared BadgerDB
  stacks/               # YAML stack manifests
  api/                  # API client wrapper
  utils/                # Utilities (color picker, JSON helpers)
  tests/                # Integration tests
  examples/             # Usage examples
  build/                # Build output