Testnet4 Onboarding


Testnet4 Onboarding

This thread is meant to be a living document that includes important information for community members regarding testnet4. If you see anything that is incorrect or out of date, please let me know.

Getting Started

The software can be found at https://github.com/handshake-org/hsd. The README should be enough to get going, if not let us know how we can improve it. It includes a full node implementation along with a SPV client.

Community Chat

If you would like to discuss things more in depth or have questions, you can find us on Freenode at #handshake or on telegram at t.me/handshake_hns

Claiming Your Airdrop

To prevent initial centralization of the network, coins are being distributed via an airdrop mechanism. It was first planned to do the airdrop through a website and participants could receive coins based on registering their Github account or their Freenode nick. This changed when it was determined that a new cryptographic scheme could allow a private spending of airdropped coins to public keys collected from the internet. Github was scraped for individuals who had more than 15 followers and valid SSH/PGP keys. The keys were assigned coins and added to the Handshake genesis block. Without a way to allow people to privately spend these coins, the blockchain UTXO graph would be initially seeded with real world identities, which decreases the fungibility of the native HNS coins. These airdropped coins can be claimed using the hs-airdrop tool.

To learn more about the cryptographic scheme that allows such an airdrop to work, see:

Block Explorers

If a tree falls in a forest and no one is around to hear it, does it make a sound?

Please post here if you would like your block explorer added to the list.
hnsxplorer and dollarydoo.me are still on the old testnet


An on chain auction system was implemented to allow for permissionless participation. A guide on how to participate in auctions is here.

Seeder Nodes

If you would like to run a well known node to increase the size of the network, post here and I will add you to the list:

  • anowdmaynjdigtmdjfeppmvqxdyu74rvfna6rtfuu7o2mneshubze@


The mining algorithm is cBlake or KMAC/blake2b.

The easiest way to mine currently is with the built in CPU miner. This is possible using the mining RPC commands. You can set the coinbase address with a --coinbase-address flag at runtime

Public Resolvers

Public Handshake resolvers can be found at hs.zone and hs.run. Any Handshake name can be resolved as a subdomain of either of those zones.


This will be updated with common questions over time.

My node has trouble connecting to the network with the error message Error: Socket hangup.

This likely means that your peers have banned you. Try connecting to a different well known node or ask someone on IRC to unban you. Be sure that you are on the latest master branch of https://github.com/handshake-org/hsd

My node crashes with the error message Error: Network not found for magic number

Be sure to delete chain data associated with previous testnets. The magic numbers are updated for each testnet, so the magic number in the database may not match the expected value in the software.

The miner gives the error message Error: Bad header size.

The Proof of Work algorithm was switched away from Cuckoo Cycle to cBlake and the hs-miner software is no longer up to date. It is possible to CPU mine using hsd with the RPC command setgenerate. Some community members are working on a GPU miner.

When does mainnet launch?

When its ready. See this GitHub issue for remaining TODOs before mainnet:


Thanks for the breakdown, Mark! All this will be even easier once the HandyMiner/HandyGUI are live!


Two questions that may be worth adding to FAQ:

  • how to properly recover the key and access funds on address generated by faucet-tool?

  • do I understand it correctly that if somebody already had a GitHub account connected to the faucet with handshake address filled in, their ssh keys won’t be included in the tree?


For your first question, you’ll just need to import your backup phrase into a Handshake wallet to get your funds that are sent via the faucet. If you already filled in your Handshake address and confirmed yourself via the faucet, your funds will be available at the address you provided upon launch and there’s nothing further for you to do but to ensure you keep your backup safe till then :).



do I understand it correctly that if somebody already had a GitHub account connected to the faucet with handshake address filled in, their ssh keys won’t be included in the tree?

This is true, if you signed up for the original faucet through the website and registered your Github account, then you have been deduplicated so that you are not included in the airdrop twice.


Thanks! So looks like everything’s fine there. I was able to get everything I was supposed to on my address.

I still need to figure out how to access that though. Is there anything I miss in this process?

  1. Get the proof with hs-airdrop and publish it on the network
  2. Wait for it to get mined and verify with blockchain explorer that the funds are on my address
  3. Restore the key with hsw-cli mkwallet wallet --mnemonic="<MNEMONIC_FROM_FAUCET-TOOL>"
  4. Rescan the chain with hsw-cli rescan 0 --id=wallet
  5. …?

All I get from commands like get or balance are:

  "balance": {
    "account": -1,
    "tx": 0,
    "coin": 0,
    "unconfirmed": 0,
    "confirmed": 0,
    "lockedUnconfirmed": 0,
    "lockedConfirmed": 0

and hsw-cli account default get doesn’t show the address I got from the faucet-tool.

What am I missing?



That looks like the correct way to go about indexing your funds. The problem may be that your real funds were derived from the account m/44'/5353'/0' while testnet will derive at the account m/44'/5354'/0'.

Handshake uses different coin types depending on the network. See mainnet cointype vs testnet cointype

The wallet automatically does the derivation differently based on the network.

This code should help, omitting the async anonymous function for brevity. I didn’t test this code beforehand but I believe it should work.

const {Network, Mnemonic, HDPrivateKey} = require('hsd');
const {WalletClient} = require('hs-client');

const network = Network.get('testnet');
const phrase = '...';
const mnemonic = Mnemonic.fromPhrase(phrase);

// m
const priv = HDPrivateKey.fromMnemonic(mnemonic);

// note that the second argument is a bool and
// will harden the derivation
// m/44'
const bip44Key = priv.derive(44, true);

// normally use network.keyPrefix.coinType, but
// not in this case
// m/44'/5353'
const handshakeKey = bip44Key.derive(5353, true);

// m'/44'/5353'/0'
const accountHDKey = handshakeKey.derive(0, true);

// turn to public key
const xpub = accountHDKey.toPublic();

// turn into extended public key string
const accountKey = xpub.xpubkey(network.type);

const walletClient = new WalletClient({
  network: network.type,
  port: network.walletPort

const result = await walletClient.createWallet('my-wallet', {
  watchOnly: true,
  accountKey: accountKey

This should derive the key at the proper index and create a watch only wallet that should be able to index your funds. You can also try to derive your address locally like so:

const address = xpub.derive(0).derive(0);



I was able to watch my faucet address on testnet using the public key produced by the faucet tool.

The faucet tool created a file with a mnemonic phrase, xpub, private key in Wallet-Import-Format, and a public key in hex. That public key can be imported into a watch-only wallet like so:

hsw-cli mkwallet --id=watch1 --watch=true --key=<any xpub, doesn't matter>
hsw-cli --id=watch1 import <public key hex string>
hsw-cli --id=watch1 rescan 0