Configuration Reference

This reference covers all configuration options available in tmpnet for networks, nodes, subnets, and chains.

Network Configuration

The Network type represents a complete temporary network.

Basic Properties

type Network struct {
    // Owner identifier for the network
    Owner string

    // UUID for unique identification across hosts
    UUID string

    // Genesis configuration for the network
    Genesis *genesis.UnparsedConfig

    // Network ID. If zero, the genesis sets it (88888 for a generated genesis)
    NetworkID uint32

    // Configuration for the Primary Network and its chains (P, X, C)
    PrimarySubnetConfig ConfigMap
    PrimaryChainConfigs map[string]ConfigMap

    // Collection of nodes in the network
    Nodes []*Node

    // Subnets to create on the network
    Subnets []*Subnet

    // Keys pre-funded in genesis
    PreFundedKeys []*secp256k1.PrivateKey

    // Default flags applied to all nodes
    DefaultFlags FlagsMap

    // Default runtime configuration for nodes
    DefaultRuntimeConfig NodeRuntimeConfig

    // Network directory path
    Dir string
}

Example flags that you can set for all nodes. tmpnet already applies its own defaults (DefaultTmpnetFlags): network-peer-list-pull-gossip-frequency=250ms, network-max-reconnect-delay=1s, health-check-frequency=2s, api-admin-enabled=true, index-enabled=true, and 0 for both disk-space percentage checks. A node or network value overrides a tmpnet default:

network.DefaultFlags = tmpnet.FlagsMap{
    // Logging
    "log-level":         "info",      // trace, debug, info, warn, error, fatal
    "log-display-level": "info",
    "log-format":        "auto",      // auto, plain, colors, json

    // Network
    // Do not set "network-id". tmpnet sets it to the genesis network ID (88888 by default).
    "network-max-reconnect-delay":   "1s",
    "public-ip":                     "127.0.0.1",
    "public-ip-resolution-service":  "",

    // Staking
    "sybil-protection-enabled":      "true",
    // tmpnet generates each node's TLS and BLS keys and passes them as
    // staking-tls-cert-file-content, staking-tls-key-file-content and
    // staking-signer-key-file-content. Do not set the file flags.

    // API
    "http-host":                     "127.0.0.1", // tmpnet default for the process runtime
    "http-port":                     "0", // Dynamic port
    "staking-port":                  "0", // Dynamic port

    // Performance
    "snow-sample-size":              "2",
    "snow-quorum-size":              "2",
    "proposervm-use-current-height": "true",
}

Configuration on Disk

Network configuration is stored at [network-dir]/config.json:

{
  "owner": "test-owner",
  "uuid": "abc-123-def-456",
  "defaultFlags": {
    "log-level": "info"
  },
  "defaultRuntimeConfig": {
    "process": {
      "avalancheGoPath": "/path/to/avalanchego",
      "pluginDir": "/path/to/plugins"
    }
  },
  "preFundedKeys": ["PrivateKey-..."]
}

Node Configuration

The Node type represents a single AvalancheGo node.

Basic Properties

type Node struct {
    // Node identifier derived from staking certificate
    NodeID ids.NodeID

    // Node-specific flags (override network defaults)
    Flags FlagsMap

    // Optional node-specific runtime configuration
    RuntimeConfig *NodeRuntimeConfig

    // URI of the node's API endpoint (set at runtime)
    URI string

    // Staking address for P2P (set at runtime)
    StakingAddress netip.AddrPort

    // Data directory (defaults to [network-dir]/[node-id])
    DataDir string

    // Whether this is a temporary/ephemeral node
    IsEphemeral bool
}

Node-Specific Flags

Override network defaults for individual nodes:

node.Flags = tmpnet.FlagsMap{
    "log-level":  "debug",        // More verbose than network default
    "http-port":  "9650",          // Fixed port instead of dynamic
    "track-subnets": "subnet-id",  // Track specific subnet
}

Node Configuration Files

Node Config ([node-dir]/config.json):

{
  "flags": {
    "staking-signer-key-file-content": "...",
    "staking-tls-cert-file-content": "...",
    "staking-tls-key-file-content": "..."
  },
  "runtimeConfig": {
    "process": {
      "avalancheGoPath": "/path/to/avalanchego",
      "pluginDir": "/path/to/plugins"
    }
  }
}

The file holds the node's own flags, including its generated keys. runtimeConfig is present only when the node does not use the network default, and isEphemeral only when it is true.

Flags ([node-dir]/flags.json), written by tmpnet each time the node starts (process runtime):

{
  "api-admin-enabled": "true",
  "bootstrap-ids": "NodeID-...",
  "bootstrap-ips": "127.0.0.1:56396",
  "chain-config-content": "...",
  "data-dir": "/home/user/.tmpnet/networks/20240312-143052.123456/NodeID-...",
  "genesis-file-content": "...",
  "health-check-frequency": "2s",
  "http-host": "127.0.0.1",
  "http-port": "0",
  "index-enabled": "true",
  "network-id": "88888",
  "network-max-reconnect-delay": "1s",
  "network-peer-list-pull-gossip-frequency": "250ms",
  "plugin-dir": "/home/user/.avalanchego/plugins",
  "public-ip": "127.0.0.1",
  "staking-host": "127.0.0.1",
  "staking-port": "0",
  "staking-signer-key-file-content": "...",
  "staking-tls-cert-file-content": "...",
  "staking-tls-key-file-content": "...",
  "system-tracker-disk-required-available-space-percentage": "0",
  "system-tracker-disk-warning-available-space-percentage": "0"
}

Note

Port 0 lets the OS pick a free port

The "http-port": "0" and "staking-port": "0" values tell the OS to allocate available ports dynamically. The actual allocated ports are written to process.json by avalanchego at startup.

Process Info ([node-dir]/process.json):

This file is created by avalanchego itself (not tmpnetctl) when the node starts. tmpnet sets --data-dir to the node directory, and avalanchego writes this file to the default --process-context-file path, [data-dir]/process.json. avalanchego deletes the file when the node stops.

{
  "pid": 12345,
  "uri": "http://127.0.0.1:56395",
  "stakingAddress": "127.0.0.1:56396"
}

Field	Description
`pid`	Process ID of the running avalanchego instance
`uri`	HTTP API endpoint with the dynamically allocated port
`stakingAddress`	Staking/P2P address with the dynamically allocated port

Warning

A node that you start by hand writes process.json too

If you run avalanchego manually (not via tmpnetctl), it writes this file to [data-dir]/process.json by default. Set --process-context-file only to write it to a different path.

Runtime Configuration

Runtime configuration controls how nodes are executed.

Process Runtime

For local process-based nodes:

type ProcessRuntimeConfig struct {
    // Path to avalanchego binary
    AvalancheGoPath string

    // Plugin directory for custom VMs
    PluginDir string

    // Whether to reuse dynamic ports across restarts
    ReuseDynamicPorts bool
}

Usage:

network.DefaultRuntimeConfig = tmpnet.NodeRuntimeConfig{
    Process: &tmpnet.ProcessRuntimeConfig{
        AvalancheGoPath:   "/path/to/avalanchego",
        PluginDir:         "~/.avalanchego/plugins",
        ReuseDynamicPorts: true,
    },
}

Kubernetes Runtime

For Kubernetes-based deployment:

type KubeRuntimeConfig struct {
    // Kubeconfig file path
    ConfigPath string

    // Kubeconfig context to use
    ConfigContext string

    // Target namespace
    Namespace string

    // Docker image for nodes
    Image string

    // Persistent volume size in GB
    VolumeSizeGB uint // Minimum 2

    // Use exclusive scheduling (one pod per k8s node)
    UseExclusiveScheduling bool

    // Custom scheduling labels
    SchedulingLabelKey   string
    SchedulingLabelValue string

    // Ingress configuration
    IngressHost   string
    IngressSecret string
}

FlagsMap

FlagsMap is a string map for avalanchego flags with special handling for defaults.

Operations

flags := tmpnet.FlagsMap{
    "log-level": "info",
}

// Set a value
flags["log-level"] = "debug"

// Set only if not already set
flags.SetDefault("log-level", "warn") // No effect, already set

// Set multiple defaults
flags.SetDefaults(tmpnet.FlagsMap{
    "log-display-level": "info",
    "http-port":         "0",
})

// Get a value
logLevel := flags["log-level"]

Common Flags

Logging:

log-level - Minimum log level (trace, debug, info, warn, error, fatal)
log-display-level - Level to display
log-format - Format (auto, plain, colors, json)

Network:

network-id - Network identifier
bootstrap-ips - Bootstrap node IPs (auto-configured)
bootstrap-ids - Bootstrap node IDs (auto-configured)
public-ip - Node's public IP

API:

http-host - HTTP host for API
http-port - HTTP port (0 for dynamic)
http-allowed-hosts - Allowed hosts for API

Staking:

sybil-protection-enabled - Enable sybil protection (staking)
staking-port - Staking port (0 for dynamic)
staking-tls-cert-file - TLS certificate path
staking-tls-key-file - TLS key path

Consensus:

snow-sample-size - Sample size for consensus
snow-quorum-size - Quorum size
snow-concurrent-repolls - Concurrent repolls

Subnets:

track-subnets - Comma-separated list of subnet IDs to track

Advanced:

proposervm-use-current-height - Use current height in proposervm
throttler-inbound-validator-alloc-size - Validator bandwidth allocation
network-peer-list-pull-gossip-frequency - Peer list gossip frequency (tmpnet default 250ms)

Subnet Configuration

The Subnet type represents a custom subnet.

Basic Properties

type Subnet struct {
    // User-defined name
    Name string

    // Subnet ID (set after creation)
    SubnetID ids.ID

    // Nodes that validate this subnet
    ValidatorIDs []ids.NodeID

    // Chains on this subnet
    Chains []*Chain

    // Subnet-specific configuration
    Config ConfigMap
}

Subnet Config Options

subnet.Config = tmpnet.ConfigMap{
    // Historical blocks to keep
    "proposerNumHistoricalBlocks": 50000,

    // Consensus parameters (snowParameters replaces the deprecated consensusParameters)
    "snowParameters": map[string]interface{}{
        "k":                     20,
        "alphaPreference":       15,
        "alphaConfidence":       15,
        "beta":                  20,
        "concurrentRepolls":     4,
        "optimalProcessing":     10,
        "maxOutstandingItems":   256,
        "maxItemProcessingTime": 30000000000, // nanoseconds (30s)
    },
}

Subnet Configuration File

Stored at [network-dir]/subnets/[subnet-name].json:

{
  "Name": "my-subnet",
  "Config": {
    "proposerNumHistoricalBlocks": 50000
  },
  "SubnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
  "OwningKey": "PrivateKey-...",
  "ValidatorIDs": ["NodeID-..."],
  "Chains": [...]
}

Chain Configuration

The Chain type represents a blockchain on a subnet.

Basic Properties

type Chain struct {
    // Chain ID (set after creation)
    ChainID ids.ID

    // Virtual Machine ID
    VMID ids.ID

    // Genesis bytes for the chain
    Genesis []byte

    // Chain-specific configuration (JSON string)
    Config string

    // Pre-funded key for the chain
    PreFundedKey *secp256k1.PrivateKey

    // Arguments to get VM version
    VersionArgs []string
}

Chain Configuration Example

chain := &tmpnet.Chain{
    VMID:    myVMID,
    Genesis: genesisBytes,
    Config:  `{
        "blockGasLimit": 8000000,
        "minGasPrice": 25000000000,
        "priorityRegossipFrequency": 1000000000
    }`,
    PreFundedKey: testKey,
    VersionArgs:  []string{"--version-json"}, // The VM must print JSON with an "rpcchainvm" field
}

Directory Structure

Complete directory layout for a tmpnet network:

~/.tmpnet/
├── prometheus/                          # Prometheus working directory
│   └── file_sd_configs/
│       └── [network-uuid]-[node-id].json
├── promtail/                            # Promtail working directory
│   └── file_sd_configs/
│       └── [network-uuid]-[node-id].json
└── networks/
    └── [timestamp]/                     # Network directory
        ├── config.json                  # Network configuration
        ├── genesis.json                 # Genesis file
        ├── network.env                  # Shell environment
        ├── metrics.txt                  # Grafana link
        ├── subnets/
        │   └── [subnet-name].json       # Subnet configuration
        └── [node-id]/                   # Node directory
            ├── config.json              # Runtime configuration
            ├── flags.json               # Node flags
            ├── process.json             # Process info
            ├── chainData/               # Chain data
            ├── logs/
            │   └── main.log
            ├── db/                      # Node database
            └── plugins/                 # VM plugins

Environment Variables

tmpnet uses these environment variables:

Variable	Purpose	Default
`TMPNET_NETWORK_DIR`	Target network directory	None (must specify)
`TMPNET_ROOT_NETWORK_DIR`	Root for new networks	`~/.tmpnet/networks`
`AVALANCHEGO_PATH`	Path to avalanchego binary	None (must specify)
`AVAGO_PLUGIN_DIR`	Plugin directory	`~/.avalanchego/plugins`
`STACK_TRACE_ERRORS`	Enable stack traces	Not set
`PROMETHEUS_URL`	Prometheus backend URL	None
`PROMETHEUS_PUSH_URL`	Prometheus push URL	None
`PROMETHEUS_USERNAME`	Prometheus username	None
`PROMETHEUS_PASSWORD`	Prometheus password	None
`LOKI_URL`	Loki backend URL	None
`LOKI_PUSH_URL`	Loki push URL	None
`LOKI_USERNAME`	Loki username	None
`LOKI_PASSWORD`	Loki password	None
`GRAFANA_URI`	Custom Grafana dashboard URI	Default Grafana instance

Configuration Precedence

A flag value comes from the first source that sets it:

Node-specific - node.Flags
Network defaults - network.DefaultFlags
tmpnet defaults - DefaultTmpnetFlags()
Generated values - network-id, bootstrap-ips, bootstrap-ids, genesis-file-content, subnet-config-content and chain-config-content. For the process runtime, also data-dir, plugin-dir, the ports and the hosts. tmpnet sets these only when no other source sets them.

The kube runtime is an exception: it always sets data-dir to /data and http-host to 0.0.0.0.

Example:

// 1. avalanchego default: log-level = "info" (tmpnet does not set log-level)
// 2. Network default:
network.DefaultFlags["log-level"] = "debug"

// 3. Node-specific override:
node.Flags["log-level"] = "trace"

// Final result: node runs with log-level = "trace"

Best Practices

Use defaults for common settings - Set network.DefaultFlags for settings shared by all nodes
Override per-node when needed - Use node.Flags only for node-specific configuration
Use dynamic ports - Set ports to "0" for automatic allocation
Enable verbose logging during development - Use "debug" or "trace" log levels
Configure subnet tracking - Set track-subnets for nodes that need to sync subnets
Use environment variables - Store credentials in environment variables, not in code

Network Configuration

Basic Properties

Default Flags

Configuration on Disk

Node Configuration

Basic Properties

Node-Specific Flags

Node Configuration Files

Runtime Configuration

Process Runtime

Kubernetes Runtime

FlagsMap

Operations

Common Flags

Subnet Configuration

Basic Properties

Subnet Config Options

Subnet Configuration File

Chain Configuration

Basic Properties

Chain Configuration Example

Directory Structure

Environment Variables

Configuration Precedence

Best Practices

See Also

On this page