HomeCoinsHathor (HTR)Use case integration best practices | by Hathor Labs | Nov, 2022

Use case integration best practices | by Hathor Labs | Nov, 2022

- Advertisement -

This post describes security best practices for use cases that integrate with Hathor Network to improve the reliability of their operations.

There are multiple ways that a use case can integrate with Hathor. Below is a common architecture compliant with our recommendations:

  • You have software that runs operations off-chain and is used by your customers.
  • Your software connects to a headless wallet that communicates with a full node. The full node is connected to Hathor’s P2P network.
  • The headless wallet will handle all events from the full node to keep its balance and transaction history updated. The headless software has APIs to manage a wallet, i.e., get addresses, create and push transactions to the network, create new tokens, and some other features described in the project repository.

Run more than one node

We strongly recommend use cases to run two or more full nodes as protection against direct attacks on their full nodes.

Your full nodes should not be connected to each other (node1 must have node2 in the blacklist and vice versa. See below for instructions on how to create a blacklist). This is important to mitigate some attack vectors. Remember that the transactions will be propagated by the P2P network, and all your full nodes will receive the transactions eventually during regular network activity.

Validate new transactions on more than one full node before accepting them

Let’s assume an exchange wants to run nodes to identify deposits. A recommended approach for the integration would be to run at least two full nodes (node1 and node2), which are not connected to each other. With this architecture, if any deposit is identified in node1, then the exchange must check that the transaction is also valid in node2 and in one of the public nodes. With this approach, if an attacker successfully compromises one of your full nodes, your validation would fail and the deposit wouldn’t be accepted.

Validate that all your full nodes have the same best block

You should perform a regular check to validate that the best block is the same on all your full nodes. If full nodes have different best blocks, the validation must be done again a few seconds later because this might happen depending on the network block propagation time. If the difference continues, the nodes might be under attack, and you should consider blocking deposits.


The peer-id is a unique identifier of your full nodes in Hathor’s P2P network. You must keep your peer-id secret to prevent attackers from directly targeting your full nodes. Don’t share your peer-ids with anyone, and don’t publish them on public channels. If you think your peer-id has been exposed, you should generate a new one and replace the exposed peer-ids.

How to validate a new transaction

The transactions in Hathor Network have many fields that must be checked to guarantee that a transaction is valid for your use case. For more details about the fields of a transaction, check the Transaction Anatomy RFC.


Version identifies the type of vertex. The possible choices are:

  • Block: 0
  • Regular Transaction: 1
  • Token Creation Transaction: 2
  • Merged Mined Block: 3

Depending on your use case, you must accept one or more version types.

Voided state

A voided transaction is canceled and should never be accepted. You must validate that the transaction is not voided, asserting that is_voided == false.


Hathor supports multi-token transactions. You must confirm that your outputs are correctly placed as follows:

  • Token id is correct. If you accept only HTR token, token id must be “00”.
  • Token data is equal to 0 if it’s HTR token.
  • Value matches the expected value. Note that it is an integer, and 12.34 is represented by 1234.
  • Timelock must be null; otherwise, your funds might be locked.

Number of confirmations

Some use cases might handle transactions with huge amounts, so it’s essential to wait for some blocks to confirm the transaction before accepting it as a valid one. The more blocks confirm a transaction, the more guarantee there is that this transaction won’t become voided in the future. As a reference, Bitcoin’s use cases usually require six confirmations before accepting a new deposit.

Check if an unusual amount of deposits or withdrawals are being made

Many use cases handle withdrawals and deposits through blockchain transactions. It’s important to check for unusual levels of deposits and withdrawals, as this could be caused by an attack.

In such a situation, it’s crucial to have an easy way of blocking specific accounts that show unusual behavior and that might be part of an attack.

You might also consider limiting the number of operations a user can perform during a time window. This validation and user throttling must be done in your software application.

Check if one of your full nodes gets out of sync

Always check for strange behavior in the synchronization among full nodes. We recommend that you regularly validate that all your full nodes are in sync between each other and with at least one public node.

This validation is important to guarantee the node has not been isolated from the rest of the network with a fork of the blockchain. It’s also important to validate that the timestamp of the best block of the node is recent, which means that the node’s blockchain hasn’t been halted in the past.

Run a full node with a blacklist of peer-ids

Following the recommended architecture described above, you will need to run more than one full node, and they shouldn’t be connected to each other. To achieve this, each of your nodes must have a blacklist of peer-ids containing the ids of the other nodes.

For example, you run node1 (peerid1), node2 (peerid2), and node3 (peerid3). Node1 should have peerid2 and peerid3 in the blacklist, node2 should have peerid1 and peerid3 in the blacklist, and node3 should have peerid1 and peerid2 in the blacklist.

There are a few different approaches to create this blacklist in the full node:

CLI command

If you use the full node parameters directly in the command line, you should add:
— peer-id-blacklist peerid1 peerid2

Environment variables

If you use the full node parameters using env vars you should add:
export HATHOR_PEER_ID_BLACKLIST=[peerid1, peerid2]


There is also an API to add a peer-id to the blacklist while the node is running, however, this is not recommended as if you restart your node you will lose this blacklist.
POST to /v1a/p2p/netfilter

"chain": {
"name": "post_peerid",
"target": {
"type": "NetfilterReject",
"target_params": {}
"match": {
"type": "NetfilterMatchPeerId",
"match_params": {
"peer_id": "peerid1"

Source link

- Advertisement -
Mr Bitcointe
Mr Bitcointehttps://www.bitcointe.com/
“Fact You Need To Know About Cryptocurrency - The first Bitcoin purchase was for pizza.” ― Mohsin Jameel

Most Popular

Bitcoin (BTC) $ 23,022.17
Ethereum (ETH) $ 1,642.00
Tether (USDT) $ 1.00
Bitcoin Cash (BCH) $ 133.62
Litecoin (LTC) $ 99.53
EOS (EOS) $ 1.08
OKB (OKB) $ 44.28
Tezos (XTZ) $ 1.17
LEO Token (LEO) $ 3.38
Cardano (ADA) $ 0.390315
Monero (XMR) $ 167.10
Stellar (XLM) $ 0.090316
Chainlink (LINK) $ 7.03
Huobi (HT) $ 5.51
TRON (TRX) $ 0.064606
USD Coin (USDC) $ 1.00
Dash (DASH) $ 65.09
NEO (NEO) $ 8.86
IOTA (MIOTA) $ 0.241722
NEM (XEM) $ 0.041645
Zcash (ZEC) $ 46.20
Maker (MKR) $ 728.33
Pax Dollar (USDP) $ 0.994596
Ethereum Classic (ETC) $ 22.61
VeChain (VET) $ 0.024673
TrueUSD (TUSD) $ 1.00
KuCoin (KCS) $ 8.60
Waves (WAVES) $ 2.75