System Requirements & Installation

By adhering to the guidelines outlined in this guide, node operators can contribute to the stability and efficiency of the River 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 River 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.

Installation

Node FE’s can be installed either from docker with the River public ECR image registry or built from source code.

Installation from Docker

The River Association 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.

 docker pull public.ecr.aws/h5v6m2x1/river:testnet
 docker tag public.ecr.aws/h5v6m2x1/river:testnet river-node

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.

git clone git@github.com:river-build/river.git
# print out shorthand commit hashes
git log --pretty=format:'%h' | cut -c 1-7
# choose one to pull
COMMIT_HASH=1dd452a
docker pull public.ecr.aws/h5v6m2x1/river:$COMMIT_HASH

The CI job that builds docker images to the river public ecr registry can be found here.

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.

git clone git@github.com:river-build/river.git
cd river/core
docker build -t river-node .

Node FE Environment Variables

River 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
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 River Chain Network	Yes	0xf18E98D36A6bd1aDb52F776aCc191E69B491c070	-
RIVERCHAIN__CHAINID	River Chain chainId	Yes	6524490	-
RIVERCHAIN__NETWORKURL	River Chain RPC Url	Yes	https://towns-devnet.rpc.caldera.xyz/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 River 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:

1:https://eth-mainnet.g.alchemy.com/v2/$ETHEREUM_API_KEY,8453:https://base-mainnet.g.alchemy.com/v2/$BASE_API_KEY,42161:https://arb-mainnet.g.alchemy.com/v2/$ARBITRUM_MAINNET_API_KEY,137:https://polygon-mainnet.g.alchemy.com/v2/$POLYGON_API_KEY,10:https://opt-mainnet.g.alchemy.com/v2/$OPTIMISM_API_KEY

Do not use public RPC provider urls found on chainlist or elsewhere as these are notoriously unstable. Node Operators are encouraged to provision RPC Urls for high availability for each supported chainId by using custom provisioned provider urls from Alchemy or Infura.

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

Learn

Run

Build

React SDK

System Requirements & Installation

System Requirements & Dependencies

Installation

Installation from Docker

Node FE Environment Variables

Cross-chain Requirements

Testnet Cross-Chain Chain Ids Required

Mainnet Cross-Chain Chain Ids Required

Learn

Run

Build

React SDK

​System Requirements & Dependencies

​Installation

​Installation from Docker

​Node FE Environment Variables

​Cross-chain Requirements

​Testnet Cross-Chain Chain Ids Required

​Mainnet Cross-Chain Chain Ids Required

System Requirements & Dependencies

Installation

Installation from Docker

Node FE Environment Variables

Cross-chain Requirements

Testnet Cross-Chain Chain Ids Required

Mainnet Cross-Chain Chain Ids Required