​
Running a Towns Stream Node in Development

Running a Towns 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 Towns Stream Node with a Postgres backend.

​
Requirements

  • Docker
  • Yarn 1.22
  • Go 1.22.2 (see go.work file 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/towns-protocol/towns.git

​
Run a Towns 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:
1

Check dependency versions

2

Upgrade Foundry toolkit

3

Run yarn install

4

Build protobufs

5

Start Base Chain in anvil

6

Start Towns Chain in anvil

7

Configure stream nodes

8

Start stream nodes with and without entitlements (on separate ports)

9

Start xchain binary

10

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"
"Towns 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 Towns Stream Node in Info Mode against testnet or mainnet

To run a stream node within the remote testnet or mainnet networks, the node needs to be first registered on Towns Chain. See onboarding instructions here.

​
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