Register Node
The following guide illustrates how to register a new Stream Node instance on River Chain. This guide uses Testnet as an example. The Mainnet guide follows from this guide with modifications to contract addresses and rpc url for River Chain.
Requirements & Dependencies
- Foundry Toolkit: To install follow this guide.
- Node Operator delegation: address migrated to River Chain by DAO (see below).
- Warm wallet access to Node Operator wallet.
- Node URL pointing via DNS to Node FE attached to Node Storage.
- Access to Base over RPC endpoint
- Access to River Chain over RPC endpoint
- Sufficient gas on Node Operator wallet on both Base and River Chain to register
- Sufficient gas on Node FE wallet on River Chain and Base for validation and cross-chain transactions once node is operational.
Node FE’s are stateful and as such require consistent resolution of hostnames to active instance. To avoid unintended bad consequences, it is strongly encouraged to configure DNS for Node URL with exactly 1 A Record per domain name. Put differently, each Node URL should point to at most 1 IP address.
The node operator wallet registered on Base must be bridged to River Chain by the DAO prior to proceeding with node registration. Furthermore, the node operator needs warm access to this wallet to perform node operations to register, and update a fleet of node instances.
All contract addresses for testnet and mainnet needed to register nodes can be found in the contracts section.
Registration Outline
The following outlines the logical steps to onboarding a Node FE with attached storage from 0 to 1. Instructions are applicable to testnet and mainnet.
Instructions with specific calling signatures can be found below in the Node FE Registration sections.
Please ensure you have completed Node Operator registration before proceeding with node registration.
Start Stream Node in Info Mode
Register Node in River Chain
Register Node in Base
Start Stream Node
Node FE Registration
Once a node operator has registered their operator address on River Chain, they can proceed to register their nodes. Nodes are registered individually on River Chain and Base.
Node Operator addresses must be registered on River Chain before below actions can be undertaken to register a new stream node. DAO will migrate operator address to River Chain once sufficient delegations are received.
Once a node is setup, attached to postgres storage, network configured with a public IP, and passing health checks (see System Requirements & Installation), the node is ready to enter the River Network and begin accepting stream writes.
Registering a node on River Chain, can be accomplished by calling the registerNode(address,string,uint8)
method on the RiverRegistry diamond contract.
Registering a node and operating a stream node in general requires that the node wallet has Eth for the target network (Sepolia Eth for testnet, Eth for mainnet) to pay for gas. On testnet, sepolia eth can be obtained from a faucet. Stream nodes should also have a wallet on Base with Base Eth (mainnet) or Base Sepolia Eth (testnet) to pay for gas when committing cross-chain transactions.
The below steps describe how to register a new node URL in Operational
status using cast
, a command-line tool that is part of Foundry for reading / writing to EVM chains over RPC url’s.
Setting a Node to Operational
status will allow the node to begin accepting stream writes and signal to the network that the node is healthy and ready to be connected to by clients. See all possible node statuses that a node can assume in RegistryStorage.
Setup Variables for Registration
# checkout repo and extract RiverRegistry deployed address
$ git clone git@github.com:river-build/river.git
$ cd river
$ JSON_FILE="packages/generated/deployments/testnet/river/addresses/riverRegistry.json"
$ RIVER_REGISTRY_ADDRESS=$(jq -r '.address' "$JSON_FILE")
# set node address, which is wallet address of node's ECDSA wallet created on configuration.
NODE_ADDRESS=<Node FE Wallet Address>
PRIVATE_KEY=<Node Operator private key>
# node url
NODE_URL=<public node url pointing to a single public IP address that represents running Node FE pid>
# set RPC_URL to point to testnet
RPC_URL=https://devnet.rpc.river.build
# set BASE_RPC_URL to point to base testnet
BASE_RPC_URL=https://base-sepolia.g.alchemy.com/v2/${RPC_KEY}
Register Node on Base and River Chain
Using cast
let’s register our new node. First let’s check that the Node FE does not already exist. Node FE’s are identified in River Registry by their address so let’s check getNode
to ensure the view reverts with NODE_NOT_FOUND
before proceeding.
cast call --rpc-url $RPC_URL \
$RIVER_REGISTRY_ADDRESS \
"getNode(address)" \
$NODE_ADDRESS
Assuming the above reverts with NODE_NOT_FOUND
, let’s proceed to register the new node with the Node Operator’s wallet.
# Register a new node with EntitlementChecker in Base to ensure xchain entitlements are in place when running stream node.
# Note: EntitlementChecker is a facet and so call it's interface from Base Registry diamond contract (for address see baseRegistry.json under packages/generated/deployments in river repo).
# Ensure you call the below with the Node Operator wallet you have registered on Base. NODE_ADDRESS is the wallet address of the Node FE.
cast send \
--rpc-url $BASE_RPC_URL \
--private-key $PRIVATE_KEY \
$BASE_REGISTRY_ADDRESS \
"registerNode(address)" \
$NODE_ADDRESS
# Register a new node in Operational (2) Status in River Chain to signal to the network the node is ready to accept reads and writes.
cast send \
--rpc-url $RPC_URL \
--private-key $PRIVATE_KEY \
$RIVER_REGISTRY_ADDRESS \
"registerNode(address,string,uint8)" \
$NODE_ADDRESS \
$NODE_URL \
2
getNode(address)
to confirm the node now exists in the network.Check Node Health from Debug Multi Dashboard
To check that your node is included in the network and healthy, you can navigate to:
$NODE_URL/debug/multi
in a browser to see the node’s http1/2, grpc ping status and related health metrics.
As an example, see https://ohare-3.staking.production.figment.io/debug/multi.
Was this page helpful?