Interacting with a HOPR node
Once you have your HOPR cluster up and running, you are ready to connect to a single HOPR node and listen to messages sent to it by other HOPR nodes. The following guide will show you how to connect to a running HOPR node, and verify some basic functionality using both the REST and WebSocket endpoints.
Requirements
1. Get the node security credentials
To avoid unsecured access to your HOPR node, all HOPR node's WebSocket and REST calls require an apiToken
. Your API token needs to be appended as a
query
parameter for WebSocket connections and as an encoded token via the Authorization
header for you to be able to connect to it. You will not be
able to connect to your HOPR node without its apiToken
.
The flag used to set this value in a HOPR node via hoprd
is --apiToken
. The default apiToken
used across our documentation is the following one,
so make sure to change it when running your own node in a public network.
^^LOCAL-testing-123^^
Make sure to export your apiToken
to be used in the incoming commands, and every time you open a new terminal.
export apiToken="^^LOCAL-testing-123^^"
2. Export your HOPR node REST/WebSocket endpoints
If you followed the guide in the "HOPR Cluster Development Setup" section, these will be already exported in your current terminal. Otherwise, you can run the following commands to ensure at least your first node's endpoints are exported.
As an alternative, you an also run a single HOPR node following our monorepo instructions.
Export REST and WebSocket endpoints (from local HOPR cluster)
Node 1
export HOPR_NODE_1_HTTP_URL=http://127.0.0.1:13301 HOPR_NODE_1_WS_URL=ws://127.0.0.1:19501
API token & Node 1
export apiToken=^^LOCAL-testing-123^^ HOPR_NODE_1_HTTP_URL=http://127.0.0.1:13301 HOPR_NODE_1_WS_URL=ws://127.0.0.1:19501
Export REST and WebSocket endpoints (from a single localhost HOPR node)
Node 1
export HOPR_NODE_1_HTTP_URL=http://127.0.0.1:3001 HOPR_NODE_1_WS_URL=ws://127.0.0.1:3000
API token & Node 1
export apiToken=^^LOCAL-testing-123^^ HOPR_NODE_1_HTTP_URL=http://127.0.0.1:3001 HOPR_NODE_1_WS_URL=ws://127.0.0.1:3000
We use 127.0.0.1
instead of localhost
as some tools like websocat
(described below) struggle to resolve localhost
properly.
3. Install a WebSocket and REST client
To properly1 interact with a HOPR node, you'll need both REST and WebSocket client software. A REST client is used to give instructions to your HOPR node via its REST API, and the WebSocket client is to listen to these interactions, usually given by other nodes.
We recommend using curl
and websocat
to interact with both endpoints. These tools are terminal only and supported by any Unix
-based OS.
If you would like to use a UI-based alternative, please check the Additional REST/WebSocket clients section.
For the purposes of this guide, curl
and websocat
will be assumed.
Installing curl
Most Unix
-based systems already have curl
installed, but if you don't have it you can always use the default package manager to do so. For instance, here’s how you install curl
in Ubuntu:
sudo apt-get install curl
You can see if curl
is installed in your system by running which curl
or simply running curl
, which will output a message like the following:
curl: try 'curl --help' or 'curl --manual' for more information
Installing websocat
Our suggested client is websocat, which you can install by running our
./install-websocat.sh
script from our monorepo. To install, make sure to run it from the scripts
folder, as by default it will install it in the parent folder under a .bin
folder, and will not export it to your $PATH
.
Go to the scripts folder within the monorepo
Install scriptcd scripts
./install-websocat.sh
You can see if websocat
has been installed by running .bin/websocat
.
Connect to a HOPR node
1. Test REST API connectivity
Accessing our HOPR node REST API documentation
Your HOPR node comes with Swagger UI documentation showcasing all the exposed API methods available to your node, and the expected parameters and format to use them.
You can access the UI by visiting HOPR_NODE_1_HTTP_URL/api/v2/_swagger/#
in your browser.
You can also click here to open 127.0.0.1:3001 for an individual node or 127.0.0.1:13301 for the first node in a HOPR cluster.
If your node is running properly, you should see an image similar to this one:
Testing the REST API with curl
Using your node's apiToken
and your HOPR_NODE_1_HTTP_URL
from the "Running a local HOPR Cluster" section (likely 127.0.0.1:3001
or 127.0.0.1:13301
), try to send a REST command to query its address with the following curl
command. If you don’t have jq
installed, just remove it from the end of the command.
echo -n $apiToken | base64 | xargs -I {} curl -s -H "Authorization: Basic {}" $HOPR_NODE_1_HTTP_URL/api/v2/account/addresses | jq
If successful, you should get a response similar to this one:
{
"nativeAddress": "0x3a54dDE3ee5ACfd43C902cbecC8ED0CBA10Ff326",
"native": "0x3a54dDE3ee5ACfd43C902cbecC8ED0CBA10Ff326",
"hoprAddress": "16Uiu2HAmE9b3TSHeF25uJS1Ecf2Js3TutnaSnipdV9otEpxbRN8Q",
"hopr": "16Uiu2HAmE9b3TSHeF25uJS1Ecf2Js3TutnaSnipdV9otEpxbRN8Q"
}
If you've made a mistake, for example forgotting to use -n
in your echo
or using the wrong apiToken
, you’ll see the following instead:
{
"status": 403,
"challenge": "Basic realm=hoprd",
"message": "You must authenticate to access hoprd."
}
2. Test WebSocket connectivity
Unlike our REST API endpoint, seeing interactions with your HOPR node WebSocket server requires a WebSocket client that will remain open to listen to all messages sent to our HOPR node.
Connecting to your HOPR node WebSocket server
With websocat
installed, please go up one directory: cd ..
and run the following command to connect to your HOPR node WebSocket server.
./.bin/websocat ${HOPR_NODE_1_WS_URL}?apiToken=${apiToken}
Please note that you need to use your HOPR_NODE_1_WS_URL
(likely 127.0.0.1:3000
or 127.0.0.1:19501
) instead of the HOPR_NODE_1_HTTP_URL
from the previous step. Your HOPR_NODE_1_WS_URL
is also referred as Admin URL
in our tools.
If everything worked correctly, you should see a dump of messages, the last one being:
{ "type": "log", "msg": "ws client connected [ authentication ENABLED ]", "ts": "2022-02-01T19:42:34.152Z" }
Now that you are connected, try typing balance
in the same terminal, which should output as follows:
{"type":"log","msg":"admin > balance\n","ts":"2022-02-01T19:42:35.417Z"}
{"type":"log","msg":"HOPR Balance: 9.6 txHOPR\nETH Balance: 0.99871794476851171 xDAI","ts":"2022-02-01T19:42:35.421Z"}
With the connection verified to both our REST and WebSocket endpoints, we can now go ahead and go through the basic functions of the API to send messages across nodes.
Additional REST/WebSocket clients
In addition to curl
and websocat
, the following clients can also help you connect to your HOPR node fully. Be aware that you will still
need to know your apiToken
.
WebSocket clients
- Piesocket WebSocket Tester: This is a great tool to debug both listening to and sending
messages from/to your HOPR node. Make sure to paste your
HOPR_NODE_1_WS_URL
and append yourapiToken
as a query parameter. Also, you'll need to change thehttp
protocol tows
. For instance, here's how this would look in aGitpod.io
instance. After it's connected, you can typebalance
to see your node response.
ws://127.0.0.1:19501/?apiToken=^^LOCAL-testing-123^^
If you are using a Gitpod public URL, you can simply use the output of gp url
for that particular port (19501
) and paste it in the website.
gp url 19501
The output should look something like this: wss://19501-hoprnet-mynechat-7x6h2ghc17f.ws-us30.gitpod.io/?apiToken=^^LOCAL-testing-123^^
.
REST client
- ReqBin: Using their
Custom
header option, you can send the properAuthorization
request so you can test your HOPR node endpoint. For testing, we suggest usingHOPR_NODE_1_HTTP_URL
and theapi/v2/account/addresses
endpoint. Make sure to use thebase64
encoded version of yourapiToken
and add the prefixBasic
.
For the standard apiToken
^^LOCAL-testing-123^^
, the base64
encoded value is Xl5MT0NBTC10ZXN0aW5nLTEyM15e
. To use ReqBin
with a Gitpod exposed URL (e.g. https://13302-hoprnet-mynechat-7x6h2ghc17f.ws-us30.gitpod.io/api/v2/account/addresses
), you can use gp url
.
For a different apiToken
value, you can use the btoa
function of your browser developer tools to figure it out.
Gitpod command (paste output in the URL section of reqbin
)
gp url 13302
Custom Header
Basic Xl5MT0NBTC10ZXN0aW5nLTEyM15e
Footnotes
-
Although you can successfully interact with a HOPR node only using a WebSocket client, it is recommended to always use the REST API to send commands to the HOPR node. This is because the API is optimized for applications, whereas the WebSocket commands are mostly used within the
hopr-admin
UI, an operator-targeted tooling used to verify the functionality of the node. In other words, only use the WebSocket server when you need to process information sent to a node, and use the REST API when you need to write actions to a node. ↩