config

README

All go processes in the TEN ecosystem will use the config mechanism here to load their configuration.

Ten config has a hierarchical structure, so every field has a unique field name. Some fields are used by multiple processes, while others are only used by a single process.

For example, network.chainId is a field that might be used by multiple processes, but host.rpc.httpPort is only used by the host processes.

The fields are defined in a single place, in the Config structs declared in config.go. These declarations include their type, the mapstructure annotation that gives their yaml field name and any comments about their usage.

This library provides a loading mechanism powered by viper, it reads 0-base-config.yaml to initialise the config and then overrides fields with any other yaml files provided and finally overrides with environment variables.

Environment variable keys are the same as the yaml keys but are uppercased and have dots replaced with underscores. For example, network.chainId would be NETWORK_CHAINID, and host.rpc.httpPort would be HOST_RPC_HTTPPORT.

The ability to set them with environment variables is important, it allows for easy configuration of the system in a docker environment.

Loading the config

The loading method allows an ordered list of yaml files to be provided, values in later files will override values in earlier files.

The loading method will also apply environment variables, overriding any values set in the yaml files.

In practice for production deployments, we expect that the 0-base-config.yaml will be the only file that is always provided and config will be provided by the orchestration engine as env variables.

Defining a new field

Defining a new field requires adding it in 2 or 3 places:

1. The Config struct in config.go
2. The 0-base-config.yaml file
3. The enclave(-test).json file (if the field is used by the enclave process)

The config struct (1) is the source of truth for the field, it defines the type and the yaml field name. (2) and (3) are required because:

• Environment variable values are only applied by viper when the field is defined in at least one of the yaml files. For this reason, we want to make sure that all fields are defined in the base config file even if just with trivial or empty values.

• The ego enclave restricts the environment variables that can be accessed by the enclave process. This means that the enclave process will not be able to access environment variables that are not whitelisted. This is a security feature of the ego enclave.

  The enclave.json file used to produce the signed ego artifact allows environment variables to be specified, either with a hardcoded value which we will use for fixed constants that are not allowed to change or with a 'fromHost' flag which will allow the enclave to access the environment variable from the host process. This is useful for configuration values that are allowed to change between deployments.

  So any configuration value that is expected to be set by an environment variable should be whitelisted in the enclave.json file.

Documentation

Index

• type BatchConfig
• type CrossChainConfig
• type EnclaveConfig
• type EnclaveDB
• type EnclaveDebug
• type EnclaveL1
• type EnclaveLog
• type EnclaveRPC
• type GasConfig
• type HostConfig
• type HostDB
• type HostDebug
• type HostEnclave
• type HostL1
• type HostLog
• type HostP2P
• type HostRPC
• type L1Config
• type L1Contracts
• type NetworkConfig
• type NodeConfig
• type RollupConfig
• type Sequencer
• type TenConfig
  • func LoadTenConfig(files ...string) (*TenConfig, error)
  • func (t *TenConfig) PrettyPrint()
  • func (t *TenConfig) ToEnvironmentVariables() map[string]string

Types

type BatchConfig

type BatchConfig struct {
	// Interval is the time between batches being created
	Interval time.Duration `mapstructure:"interval"`
	// MaxInterval is the maximum time between batches being created (if this is set higher than Batch Interval, the host will
	// not create empty batches until the MaxBatchInterval is reached or a transaction is received)
	MaxInterval time.Duration `mapstructure:"maxInterval"`
	// MaxSize is the maximum bytes a batch can be uncompressed
	MaxSize uint64 `mapstructure:"maxSize"`
}

BatchConfig contains the configuration for the batch processing on the Ten network

yaml: `network.batch`

type CrossChainConfig

type CrossChainConfig struct {
	// Interval is the time between sequencer checking if it should produce cross chain messages
	Interval time.Duration `mapstructure:"interval"`
}

CrossChainConfig contains the configuration for the cross chain processing on the Ten network

yaml: `network.crossChain`

type EnclaveConfig

type EnclaveConfig struct {
	// EnableAttestation specifies whether the enclave will produce verified attestation report.
	EnableAttestation bool `mapstructure:"enableAttestation"`

	DB    *EnclaveDB    `mapstructure:"db"`
	Debug *EnclaveDebug `mapstructure:"debug"`
	L1    *EnclaveL1    `mapstructure:"l1"`
	Log   *EnclaveLog   `mapstructure:"log"`
	RPC   *EnclaveRPC   `mapstructure:"rpc"`
}

EnclaveConfig is the configuration struct for the enclave service.

yaml: `enclave`

type EnclaveDB

type EnclaveDB struct {
	// UseInMemory specifies whether the enclave should use an in-memory database.
	UseInMemory bool `mapstructure:"useInMemory"`
	// EdgelessDBHost is the host address for the edgeless DB instance (can be empty if using InMemory DB or if attestation is disabled).
	EdgelessDBHost string `mapstructure:"edgelessDBHost"`
	// SqliteDBPath is the filepath for the sqlite DB persistence file (can be empty if a throwaway file in /tmp/ is acceptable or
	// if using InMemory DB or if attestation is enabled).
	SqlitePath string `mapstructure:"sqlitePath"`
}

EnclaveDB contains the configuration for the enclave database.

yaml: `enclave.db`

type EnclaveDebug

type EnclaveDebug struct {
	EnableDebugNamespace bool `mapstructure:"enableDebugNamespace"`
	EnableProfiler       bool `mapstructure:"enableProfiler"`
}

EnclaveDebug contains the configuration for the enclave debug.

yaml: `enclave.debug`

type EnclaveL1

type EnclaveL1 struct {
	EnableBlockValidation bool `mapstructure:"enableBlockValidation"`
	// GenesisJSON is the genesis config for the L1 chain.
	GenesisJSON []byte `mapstructure:"genesisJSON"`
}

EnclaveL1 contains the configuration related to the L1 chain.

yaml: `enclave.l1`

type EnclaveLog

type EnclaveLog struct {
	Level int    `mapstructure:"level"`
	Path  string `mapstructure:"path"`
}

EnclaveLog contains the configuration for the enclave logger.

yaml: `enclave.log`

type EnclaveRPC

type EnclaveRPC struct {
	BindAddress string `mapstructure:"bindAddress"`
	// Timeout - calls that are longer than this will be cancelled, to prevent resource starvation
	// (normally, the context is propagated from the host, but in some cases like the evm, we have to create a context)
	Timeout time.Duration `mapstructure:"timeout"`
}

EnclaveRPC contains the configuration for the enclave RPC server.

yaml: `enclave.rpc`

type GasConfig

type GasConfig struct {
	BaseFee *big.Int `mapstructure:"baseFee"`
	// MinGasPrice is the minimum gas price for mining a transaction
	MinGasPrice         *big.Int           `mapstructure:"minGasPrice"`
	PaymentAddress      gethcommon.Address `mapstructure:"paymentAddress"`
	BatchExecutionLimit uint64             `mapstructure:"batchExecutionLimit"`
	LocalExecutionCap   uint64             `mapstructure:"localExecutionCap"`
}

GasConfig contains the gas configuration for the Ten network

yaml: `network.gas`

type HostConfig

type HostConfig struct {
	DB      *HostDB      `mapstructure:"db"`
	Debug   *HostDebug   `mapstructure:"debug"`
	Enclave *HostEnclave `mapstructure:"enclave"`
	L1      *HostL1      `mapstructure:"l1"`
	Log     *HostLog     `mapstructure:"log"`
	P2P     *HostP2P     `mapstructure:"p2p"`
	RPC     *HostRPC     `mapstructure:"rpc"`
}

HostConfig is the configuration struct for the host service.

yaml: `host`

type HostDB

type HostDB struct {
	// UseInMemory specifies whether the host should use an in-memory database.
	UseInMemory bool `mapstructure:"useInMemory"`
	// PostgresHost is the host address for Postgres DB instance (can be empty if using InMemory DB)
	PostgresHost string `mapstructure:"postgresHost"`
	// SqlitePath is the filepath for the sqlite DB persistence file (can be empty if a throwaway file in /tmp/ is acceptable or
	// if using InMemory DB)
	SqlitePath string `mapstructure:"sqlitePath"`
}

HostDB contains the configuration for the host database.

yaml: `host.db`

type HostDebug

type HostDebug struct {
	EnableMetrics        bool `mapstructure:"enableMetrics"`
	MetricsHTTPPort      uint `mapstructure:"metricsHTTPPort"`
	EnableProfiler       bool `mapstructure:"enableProfiler"`
	EnableDebugNamespace bool `mapstructure:"enableDebugNamespace"`
}

HostDebug contains the configuration for the host's debug settings.

yaml: `host.debug`

type HostEnclave

type HostEnclave struct {
	// RPCAddresses is a list of managed enclave RPC addresses.
	RPCAddresses []string      `mapstructure:"rpcAddresses"`
	RPCTimeout   time.Duration `mapstructure:"rpcTimeout"`
}

HostEnclave contains the configuration for the host's enclave(s)

yaml: `host.enclave`

type HostL1

type HostL1 struct {
	WebsocketURL string `mapstructure:"wsURL"`
	// L1BeaconUrl of the beacon chain to fetch blob data
	L1BeaconUrl string `mapstructure:"beaconURL"`
	// L1BlobArchiveUrl of the blob archive to fetch expired blob data
	L1BlobArchiveUrl string `mapstructure:"blobArchiveURL"`
	// RPCTimeout is the timeout for L1 client operations.
	RPCTimeout time.Duration `mapstructure:"rpcTimeout"`
}

HostL1 contains the configuration for the host's L1 client and interactions.

yaml: `host.l1`

type HostLog

type HostLog struct {
	Level int    `mapstructure:"level"`
	Path  string `mapstructure:"path"`
}

HostLog contains the configuration for the host logger.

yaml: `host.log`

type HostP2P

type HostP2P struct {
	// IsDisabled specifies whether the host's P2P server should be disabled for incoming connections.
	IsDisabled bool `mapstructure:"disabled"`
	// BindAddress is the address to bind the P2P server to
	// (note: this is not the publicly advertised host address, which is currently on node config).
	BindAddress string        `mapstructure:"bindAddress"`
	Timeout     time.Duration `mapstructure:"timeout"`
}

HostP2P contains the configuration for the host P2P server.

yaml: `host.p2p`

type HostRPC

type HostRPC struct {
	Address    string `mapstructure:"address"`
	EnableHTTP bool   `mapstructure:"enableHTTP"`
	HTTPPort   uint64 `mapstructure:"httpPort"`
	EnableWS   bool   `mapstructure:"enableWS"`
	WSPort     uint64 `mapstructure:"wsPort"`
}

HostRPC contains the configuration for the host RPC server.

yaml: `host.rpc`

type L1Config

type L1Config struct {
	ChainID   int64           `mapstructure:"chainId"`   // chainID for the L1 network
	BlockTime time.Duration   `mapstructure:"blockTime"` // average expected block time for the L1 network
	StartHash gethcommon.Hash `mapstructure:"startHash"` // hash of the first block on the L1 network relevant to the Ten network

	L1Contracts *L1Contracts `mapstructure:"contracts"`
}

L1Config contains config about the L1 network that the Ten network is rolling up to

yaml: `network.l1`

type L1Contracts

type L1Contracts struct {
	ManagementContract gethcommon.Address `mapstructure:"management"`
	MessageBusContract gethcommon.Address `mapstructure:"messageBus"`
	BridgeContract     gethcommon.Address `mapstructure:"bridge"`
}

L1Contracts contains the addresses of Ten contracts on the L1 network

yaml: `network.l1.contracts`

type NetworkConfig

type NetworkConfig struct {
	// ChainID is the chainID for the Ten network
	ChainID int64 `mapstructure:"chainId"`
	// GenesisJSON is a json string that specifies the prefunded addresses at the genesis of the Ten network
	GenesisJSON string `mapstructure:"genesis"`

	Batch      *BatchConfig      `mapstructure:"batch"`
	Gas        *GasConfig        `mapstructure:"gas"`
	L1         *L1Config         `mapstructure:"l1"`
	Rollup     *RollupConfig     `mapstructure:"rollup"`
	Sequencer  *Sequencer        `mapstructure:"sequencer"`
	CrossChain *CrossChainConfig `mapstructure:"crossChain"`
}

NetworkConfig contains the static configuration for this instance of the Ten network

yaml: `network`

type NodeConfig

type NodeConfig struct {
	NodeType common.NodeType `mapstructure:"nodeType"`
	// Name of the node, used by orchestrator to name the containers etc., mostly useful for local testnets
	Name string `mapstructure:"name"`
	// The host's identity derived from the L1 Private Key
	// todo: does node ID still need to exist? Look to remove in favour of enclave IDs
	ID gethcommon.Address `mapstructure:"id"`
	// The public peer-to-peer IP address of the host
	// todo: does host address still need to exist for the enclave to sign over or does the enclave ID cover the usages?
	HostAddress string `mapstructure:"hostAddress"`
	// The stringified private key for the host's L1 wallet
	PrivateKeyString string `mapstructure:"privateKey"`
	// Whether the host is the genesis Obscuro node
	IsGenesis bool `mapstructure:"isGenesis"`
}

NodeConfig contains the configuration for this Ten node (maybe relevant to multiple processes, host and enclave)

yaml: `node`

type RollupConfig

type RollupConfig struct {
	// Interval is the time between sequencer checking if it should produce rollups
	Interval time.Duration `mapstructure:"interval"`
	// MaxInterval is the max time between sequencer rollups (it will create even if the rollup won't be full)
	MaxInterval time.Duration `mapstructure:"maxInterval"`
	// MaxSize - (in bytes) configured to be close to what the ethereum clients
	// have configured as the maximum size a transaction can have. Note that this isn't
	// a protocol limit, but a miner imposed limit and it might be hard to find someone
	// to include a transaction if it goes above it
	MaxSize uint64 `mapstructure:"maxSize"`
}

RollupConfig contains the configuration for the rollup processing on the Ten network

yaml: `network.rollup`

type Sequencer

type Sequencer struct {
	// P2PAddress is the address that the sequencer will listen on for incoming P2P connections
	P2PAddress string `mapstructure:"p2pAddress"`
}

Sequencer contains the configuration for how the L2 sequencer will operate for the Ten network

yaml: `network.sequencer`

type TenConfig

type TenConfig struct {
	Network *NetworkConfig `mapstructure:"network"`
	Node    *NodeConfig    `mapstructure:"node"`
	Host    *HostConfig    `mapstructure:"host"`
	Enclave *EnclaveConfig `mapstructure:"enclave"`
}

TenConfig is the top-level configuration struct for all TEN services. Fields are organised hierarchically, not all fields and structures will be used by all services.

The default config is defined in yaml files formatted hierarchically like: ``` network:

chainId: 1234
l1Contracts:
  managementContract: "0x1234567890abcdef1234567890abcdef12345678"
  ...

node:

nodeType: "validator"
...

``` The config can be overridden by other yaml files formatted the same. But fields can also be overridden directly per yaml spec, e.g.: ``` network.chainId: 5678 node.nodeType: "sequencer" ```

Fields can also be overridden by environment variables, with the key being the flattened path of the field, like: ``` export NETWORK_CHAINID=5678 export NODE_NODETYPE=sequencer ``` For ease of reading only the top-level struct is defined in this file, the nested structs are defined in their own files.

func LoadTenConfig

func LoadTenConfig(files ...string) (*TenConfig, error)

LoadTenConfig reads the base config file and applying additional files provided as well as any env variables, returns a TenConfig struct

func (*TenConfig) PrettyPrint

func (t *TenConfig) PrettyPrint()

func (*TenConfig) ToEnvironmentVariables

func (t *TenConfig) ToEnvironmentVariables() map[string]string

ToEnvironmentVariables converts the config structure into environment variables map