Local River Stream Node
River Stream Nodes can run remotely or locally depending on the operator’s preferences. The following guide illustrates how to build and run a River Stream Node locally for development purposes. Diagnostic tools to gauge the health of local and remote nodes are also discussed here. It is assumed that the node is free standing and therefore not connected to the River protocol remote node registry on Base.
Running a River Stream Node in Development
Running a River Stream Node from source is easy to do with Go, Docker, and Foundry Ethereum toolkit installed. The following tutorial will show you how to run a River Stream Node with a Postgres backend.
Requirements
- Docker
- Yarn 1.22
- Go 1.22.2 (see
go.workfile for up-to-date version) - protobuf
- Buf tools (see README.md for installation)
- Anvil -
curl -L https://foundry.paradigm.xyz | bash
Setup
Once you’ve installed Docker, Go, protobuf, Anvil, and buf, you can proceed to setup your environment as follows.
# clone monorepo
git clone https://github.com/river-build/river.git
Run a River Stream Node Locally from Source using VSCode
There’s a VSCode task in tasks.json that is recommended to be used to multiple local stream nodes with attached postgres and local base, river chains, respectively running in different anvil ports.
Running ~Start Local Dev~ command from the river repo in VSCode will do the following in order:
Check dependency versions
Upgrade Foundry toolkit
Run yarn install
Build protobufs
Start Base Chain in anvil
Start River Chain in anvil
Configure stream nodes
Start stream nodes with and without entitlements (on separate ports)
Start xchain binary
Start protobuf and typescript package watcher
After the command completes, pick a river_node process running from localhost and run /status check to see if the node is running in a healthy manner. The following should be returned if the node is healthy:
# example with node running on port 5157
➜ docs git:(jt/update-local-node-setup) ✗ curl https://localhost:5157/status | jq '.[]'
% Total % Received % Transferred Average Speed Time Time Time Current
Download Upload Total Spent Left Speed
100 411 100 411 0 0 18441 0 --:--:-- --:--:-- --:--:-- 22833
"OK"
"7V531xRIw5t3"
"0xe168D010AdF93137a05F46F23053322726add166"
"dev_local/main/mainnet/2024-06-25-1-34-g522b463"
"2024-06-27T19:03:31Z"
"2m14.955190042s"
"River Node welcomes you!"
{
"result": "OK",
"chain_id": 31338,
"block": 399,
"latency": "405.25µs"
}
{
"result": "OK",
"chain_id": 31337,
"block": 457,
"latency": "450.875µs"
}
You can also ping health of nodes using /debug/multi and /debug/multi/json endpoints which return html and json respectively. These endpoints return latency connecting to node on loopback address as well as grpc, http and rpc provider health.
➜ docs git:(jt/update-local-node-setup) ✗ curl https://localhost:5157/debug/multi/json | jq '.[]'
% Total % Received % Transferred Average Speed Time Time Time Current
Download Upload Total Spent Left Speed
100 2010 100 2010 0 0 28733 0 --:--:-- --:--:-- --:--:-- 30000
[
{
"record": {
"address": "0xe168D010AdF93137a05F46F23053322726add166",
"url": "https://localhost:5157",
"operator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
"status": 2,
"status_text": "Operational"
},
"local": true,
"http11": {
"success": true,
"status": 200,
"status_text": "200 OK",
"elapsed": "24ms",
"elapsed_after_dns": "24ms",
"elapsed_after_conn": "2ms",
"response": {
"status": "OK",
"instance_id": "7V531xRIw5t3",
"address": "0xe168D010AdF93137a05F46F23053322726add166",
"version": "dev_local/main/mainnet/2024-06-25-1-34-g522b463",
"start_time": "2024-06-27T19:03:31Z",
"uptime": "3m13.453168292s",
"graffiti": "River Node welcomes you!",
"river": {
"result": "OK",
"chain_id": 31338,
"block": 458,
"latency": "332.833µs"
},
"base": {
"result": "OK",
"chain_id": 31337,
"block": 516,
"latency": "1.245042ms"
}
},
"protocol": "HTTP/1.1",
"used_tls": true,
"remote_address": "[::1]:5157",
"dns_addresses": [
"::1",
"127.0.0.1"
]
},
"http20": {
"success": true,
"status": 200,
"status_text": "200 OK",
"elapsed": "16ms",
"elapsed_after_dns": "15ms",
"elapsed_after_conn": "1ms",
"response": {
"status": "OK",
"instance_id": "7V531xRIw5t3",
"address": "0xe168D010AdF93137a05F46F23053322726add166",
"version": "dev_local/main/mainnet/2024-06-25-1-34-g522b463",
"start_time": "2024-06-27T19:03:31Z",
"uptime": "3m13.444571s",
"graffiti": "River Node welcomes you!",
"river": {
"result": "OK",
"chain_id": 31338,
"block": 458,
"latency": "332.916µs"
},
"base": {
"result": "OK",
"chain_id": 31337,
"block": 516,
"latency": "277.042µs"
}
},
"protocol": "HTTP/2.0",
"used_tls": true,
"remote_address": "[::1]:5157",
"dns_addresses": [
"::1",
"127.0.0.1"
]
},
"grpc": {
"success": true,
"status_text": "OK",
"elapsed": "25ms",
"elapsed_after_dns": "24ms",
"elapsed_after_conn": "3ms",
"version": "dev_local/main/mainnet/2024-06-25-1-34-g522b463",
"start_time": "2024-06-27T19:03:31Z",
"uptime": "3m13s",
"graffiti": "River Node welcomes you!",
"protocol": "grpc",
"x_http_version": "HTTP/2.0",
"remote_address": "[::1]:5157",
"dns_addresses": [
"::1",
"127.0.0.1"
]
},
"river_eth_balance": "10.000000000000000000"
}
]
"2024-06-27T19:06:44Z"
"26ms"
Run a River Stream Node in Info Mode against testnet or mainnet
Running a stream node in info mode to obtain diagnostics
If you’d like to run an unattached stream node in info mode to inspect the remote status of nodes in either testnet or mainnet, you can do so by running the following:
# from the river repo root
cd core/node
# run a node in info mode to proxy http, grpc connection health from either testnet or mainnet.
# testnet
./env/gamma/run.sh info
# mainnet
./env/omega/run.sh info
# navigate to the node url in your browser to see the status of the corresponding network's nodes
# open http://localhost:4040/debug/multi in a browser or curl the url to return html
# ping testnet or mainnet nodes
./env/gamma/run.sh ping
./env/omega/run.sh ping
Was this page helpful?