Node Operator Tutorials
System Requirements & Installation
The following guide describes system requirements, dependencies, and installation details recommended for running a Towns Stream Node. This guide applies to nodes running in either Testnet or Mainnet.
By adhering to the guidelines outlined in this guide, node operators can contribute to the stability and efficiency of the Towns Network. Effective node operation not only benefits the individual operator by ensuring optimal node performance but also supports the health and reliability of the entire network.
System Requirements & Dependencies
To run a Towns Stream Node, an operator will need to run a Node Frontend (FE) and Node Storage layer, postgres database, with a specific network configuration. Please read the below requirements carefully prior to proceeding with node setup.Node Frontend (FE) Requirements
Node Frontend (FE) Requirements
- CPU: Minimum 8 virtual CPUs.
- Memory: At least 32 GB of RAM. - Architecture: x64 or ARM64 supported.
- Network: Dedicated, static public IP address, capable of handling up to 1 Gbps ingress and egress for HTTP 1.1/2 traffic.
- Blockchain RPC Access: Access to blockchain RPC provider endpoints for Base Chain, Towns Chain, and cross-chain chain ids.
Node Storage Requirements
Node Storage Requirements
- Database Compatibility: Postgres 15.4 or newer.
- Transaction Processing: Capable of handling up to 10k IOps.
- Storage Capacity: Minimum 2 TB of storage.
- Keypair store: Location to store ECDSA keypair associated with the data stored in the database.
It is highly recommended to run a distinct Postgres instance for each Node FE to ensure resource isolation during upgrades.
Node Eth Balance Requirements
Node Eth Balance Requirements
- Towns Chain Eth Balance: Minimum 1 ETH on all stream node wallets in Towns Chain to support gas needed for miniblock validation.
- Base Chain Eth Balance: Minimum 0.5 ETH on all stream node wallets in Base Chain to support gas needed for cross-chain entitlement checks.
Set up alerts to monitor the balance of the node’s Eth balance on Towns Chain and Base Chain at a minimum alert threshold of 0.25 ETH and 0.1 ETH respectively.
Installation
Node FE’s can be installed either from docker with the Towns public ECR image registry or built from source code.Installation from Docker
Install Image from Towns Public Image Registry
Install Image from Towns Public Image Registry
The Towns Protocol maintains a public docker image registry
public.ecr.aws/h5v6m2x1/river for images that are built officially from source during CI/CD.
As such, node operators can easily install the latest Node FE software from images stored in the public ECR registry. Images are tagged during releases with the associated commit as well as mutable tags mainnet, testnet, for each network respectively.Images are tagged by their merge commit hash so to install a specific version of the Node FE software, use the commit hash from source instead of the
testnet or mainnet tag, which references the latest built image.The CI job that builds docker images to the river public ecr registry can be found
here.
Build Docker Image from Source
Build Docker Image from Source
As of October 2024, as an alternative to the public ECR registry, it is recommended to build the docker image from the source Dockerfile to ensure compatibility with the latest software version.
Node FE Environment Variables
Towns Stream Nodes run expecting certain environment variables to be present in the process environment and set at runtime. Config, which is described in config.go, is injected into the binary at runtime using viper.For the list of contracts required to run nodes and their addresses, see contracts.
| Environment Variable | Purpose | Required | Testnet Value | Secret |
|---|---|---|---|---|
| ARCHITECTCONTRACT__ADDRESS | SpaceFactory contract address in Base Network | Yes | 0x968696BC59431Ef085441641f550C8e2Eaca8BEd | - |
| ARCHITECTCONTRACT__VERSION | Contract interface version | Yes | v3 | - |
| BASECHAIN__CHAINID | Base ChainId | Yes | 84532 | - |
| BASECHAIN__NETWORKURL | Base Chain RPC Url | Yes | https://sepolia.base.org | Yes |
| CHAINSSTRING | List of chainIds and network RPC Urls supported | Yes | see Cross-chain Requirements | - |
| DATABASE__DATABASE | Postgres DB Name | Yes | river | - |
| DATABASE__EXTRA | Extra Postgres Options | Yes | ?sslmode=disable&pool_max_conns=1000 | - |
| DATABASE__HOST | Postgres DB Host Url | Yes | - | - |
| DATABASE__PASSWORD | Postgres DB Password | Yes | - | Yes |
| DATABASE__PORT | Postgres DB port | Yes | 5432 | - |
| DATABASE__USER | Postgres DB username | Yes | - | - |
| DD_TAGS | Used by Datadog for metrics collection | No | env: (gamma), node_url:(your complete node url) | No |
| DEBUGENDPOINTS__PPROF | Enable pprof endpoints | No | false | - |
| DEBUGENDPOINTS__PRIVATEDEBUGSERVERADDRESS | Private debug server address | No | :8080 | - |
| DEBUGENDPOINTS__MEMPROFILEDIR | Directory for memory profile files | No | ./mem_profile | - |
| ENTITLEMENT_CONTRACT__ADDRESS | Entitlement contract address in Base Network | Yes | 0x08cC41b782F27d62995056a4EF2fCBAe0d3c266F | - |
| LOG__FORMAT | Log format option | No | text | - |
| LOG__LEVEL | Default log level | No | info | - |
| LOG__NOCOLOR | Logging without color | No | true | - |
| METRICS__ENABLED | Metrics exporter enabled | No | true | - |
| METRICS__PORT | Metrics export port | No | 8081 | - |
| PERFORMANCETRACKING__PROFILINGENABLED | Used by Datadog for cpu profiling | no | true | No |
| PERFORMANCETRACKING__TRACINGENABLED | Used by Datadog for tracing | no | true | No |
| PORT | Port RPC service listens on | Yes | 443 | - |
| REGISTRYCONTRACT__ADDRESS | River Registry contract address in Towns Chain Network | Yes | 0xf18E98D36A6bd1aDb52F776aCc191E69B491c070 | - |
| RIVERCHAIN__CHAINID | Towns Chain chainId | Yes | 6524490 | - |
| RIVERCHAIN__NETWORKURL | Towns Chain RPC Url | Yes | https://testnet.rpc.towns.com/http | Yes |
| RUN_MODE | Stream Node Run Mode (full, archive) | No | full | - |
| SKIP_GENKEY | Skip generating node ECDSA wallet keypair | Yes | true | - |
| STANDBYONSTART | Start node in standby mode | No | false | - |
| STORAGE_TYPE | postgres or in-memory | No | postgres | - |
| TLSCONFIG__CERT | TLS certificate value for node hostname | Yes | - | Yes |
| TLSCONFIG__KEY | TLS certificate key for node hostname | Yes | - | Yes |
| WALLETPRIVATEKEY | Node ECDSA private key string | Yes | - | Yes |
Testnet Values provided above are as of May 2024. New contract addresses can
be found in
packages/generated/** of river repo.Environment variables marked as Secret require proper encrypted storage and
management. It is up to node operators to choose a secure store for such
secrets depending on their runtime operating environment be it cloud or
on-premise.
Cross-chain Requirements
CHAINSSTRING environment variable is a comma-separated, colon delimited list of chain ID’s and RPC Urls that is required for nodes to support cross-chain entitlement checks.
As of June 2024, the Towns network must support the following chainIds listed in the below table for testnet, mainnet, respectively.
As an example, using redacted RPC urls from Web3 providers, the CHAINSSTRING environment variable for Mainnet would look like:
Testnet Cross-Chain Chain Ids Required
On testnet, nodes should support the following chain ids with configured RPC endpoints for cross-chain entitlement checks.| Chain Id | Network |
|---|---|
| 1 | Ethereum Mainnet |
| 11155111 | Ethereum Sepolia |
| 8453 | Base Mainnet |
| 84532 | Base Sepolia |
| 42161 | Arbitrum One |
| 137 | Polygon Mainnet |
| 10 | Optimism Mainnet |
| 10200 | Gnosis Chiado |
Mainnet Cross-Chain Chain Ids Required
On mainnet, nodes should support the following 6 chain ids for cross-chain entitlement checks.| Chain Id | Network |
|---|---|
| 1 | Ethereum Mainnet |
| 8453 | Base Mainnet |
| 42161 | Arbitrum One |
| 137 | Polygon Mainnet |
| 10 | Optimism Mainnet |
| 100 | Gnosis |