Presearch Node Updates — How to set URL, Description, Stake, and the Presearch API

Presearch
6 min readJun 8, 2021

Hey Presearchers,

We wanted to let you know of a few awesome updates to the Presearch Nodes! We have mentioned these in our telegram channels, so if you want to be the first to know, make sure to join!

A few months ago, we launched the Node Statistics dashboard for our node operators, and we’ve now gone a step further to release the Node Status API that will allow you to programmatically manage monitoring your node operations.

For easier node management, we’ve also released another update allowing you to specify your PRE stake, Node Description, and Node URL as part of the node startup parameters, removing the need to manually log in to the nodes dashboard to initially configure your node.

Configuring your node from the command line

If you’d like to programmatically specify your node’s description, url, and stake, you just need to pass the following additional parameters when starting your node:

-e DESCRIPTION="Your_Description" 
-e URL="Your_URL"
-e STAKE="Your_Stake"

The Description and Url will then show up automatically in your dashboard (so no need to manually log in and identify your node) and they will be repopulated every time you restart your node, in case you ever need to change them again from the node.

The Stake can ONLY be set the first time you fire up your node, however, and it will stake the specified number of tokens if they are available in your Savings wallet. For security reasons, you’ll have to manually log into your dashboard if you want to change your staked amount after the initial node setup.

Note that it is still possible to also set a manually-entered Description and Url in the dashboard. If you specify both the server version and the manual version then they’ll both show up currently, though practically we expect most people to only use one or the other.

It should also be noted that if you don’t have enough PRE in your account, the full amount specified won’t be staked when the node starts.

To insert these new parameters into the node start command, this is the command you would run, replacing $REGISTRATION_CODE, $DESCRIPTION, $URL, & $STAKE with your respective parameters:

docker run -dt --name presearch-node --restart=unless-stopped -v presearch-node-storage:/app/node -e REGISTRATION_CODE="$REGISTRATION_CODE" -e DESCRIPTION="$DESCRIPTION" -e URL="$URL" -e STAKE=$STAKE presearch/node

An example with data you might put in:

docker run -dt --name presearch-node --restart=unless-stopped -v presearch-node-storage:/app/node -e REGISTRATION_CODE="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -e DESCRIPTION="My Favorite Node" -e URL="https://my-hosting-provider.com/my-node-admin-page" -e STAKE=10000 presearch/node

IMPORTANT: Please note the above commands only modify the “node startup” portion of the node installation script for simplicity. The FULL installation command (including the node auto-updater) which we recommend you insert these new parameters into can be found here:
https://docs.presearch.org/nodes/setup

An example for how this could be used in AWS to populate associated server metadata:

docker run -dt --name presearch-node -e DESCRIPTION="AWS:[$(ec2metadata --instance-id), $(ec2metadata --availability-zone), $(ec2metadata --public-ipv4)]" -e URL="https://$(ec2metadata --availability-zone | sed 's/.$//').console.aws.amazon.com/ec2/v2/home?region=$(ec2metadata --availability-zone | sed 's/.$//')#InstanceDetails:instanceId=$(ec2metadata --instance-id)" -e REGISTRATION_CODE="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" presearch/node

That should give you something that looks like this when you log into your dashboard!

We know this will help save you manual effort and time when launching your nodes to power the Presearch Decentralized Search Engine, and we’re excited to see you using it out in the wild!

Onto the Node Status API — As a refresher, what are Presearch Node Statistics?

The Nodes Dashboard provides our Presearch node operators with detailed insights into how their nodes are performing, including information about number of connections, uptime, latency, and search success rates. Each node also receives a rating from 1 to 100 showing how it compares on each of these measures versus all other nodes on the network, which is incorporated into a node’s overall reliability score. This detailed information provides node operators with insights into how their node rewards payouts are calculated, and allows node operators to better optimize both their nodes’ performance and costs relative to their node rewards payouts.

The node statistics page shows a summary section with your node’s identifying information, connection status, registration date, and other high-level details.

In addition to this summary information, node operators can also view aggregate statistics for any time period during which their node was running and see number of connections, requests, uptime, latency, and success rate at resolving queries.

The node reliability score, staked capacity (based on the number of PRE tokens staked to the node), and overall utilization percentage are displayed, which are the key node-specific inputs the the Presearch node rewards calculation.

Using the Presearch Node Status API

The Presearch Node Stats API now allows node operators to programmatically access all of the same information available in the nodes dashboard showing their nodes and associated performance. By default, when you hit the API it tells you if your node(s) are connected or disconnected, making it simple to setup monitoring scripts to alert you of any issues with your node. The API can also be used to pull in historical uptime, latency, success rates, reliability scores, etc.

Think of it like the nodes dashboard, but where node operators can programmatically check on their nodes’ status and pull in the data into their own applications or dashboards, and thus monitor their nodes and metadata better. Basically it’s telling you about the state of your node from Presearch’s perspective.

What are the Components?

The first piece you will need to access this api is an API key, this can be found on the node dashboard page under the “API Access” section: https://nodes.presearch.org/dashboard

That is the only required piece to access your node’s information through the node status API, which you can access by replacing “:api_key” in the following URL:
https://nodes.presearch.org/api/nodes/status/:api_key

By default, the node status API’s response shows how many nodes you have, how many of your nodes are connected, descriptions that you may have put in about your node, its IP address and more.

If you’re looking to get more granular results, you can also specify, start_date , which is by default 24 hours prior to the the end_date & end_date which is by default the time of your request. You can also request specific nodes through the public_keys query parameter which is a comma-separated list of url-encoded node public keys. If the public_keys parameter is specified, only those nodes will be returned. There are a few more advanced parameters that you can send to the API to filter to connected, disconnected, and active nodes, so make sure to check them out in our docs.

One basic example of querying through the command line is simply checking to see which of your nodes are offline. You can grab your API access key by clicking the ‘copy’ button next to the “Your node API key button” in your node dashboard.

After grabbing your API Key, you can insert it into a shell script or run on the command line (Linux/Mac) as follows:

curl — silent "https://nodes.presearch.org/api/nodes/status/YOUR_API_KEY?connected=false" | grep -q "NODE_DESCRIPTION" && echo "a node is offline"

An example response:

Node Status API Documentation: https://docs.presearch.org/nodes/api

We’re excited share these additional technical enhancements with you to further enhance the node operator experience within the Presearch ecosystem!

PS: Want to start running a node?

Head to https://nodes.presearch.org to learn more and join our Nodes Telegram Community

For more information about Presearch, head to our Company Website.

--

--