Home

Awesome

Handshake Airdrop

Redemption tool for the Handshake network's decentralized airdrop to open source developers.

A word of warning

In past weeks, it's become apparent that there are now various scams and phishing attempts targeting GitHub users. Handshake contributors will never ask you for your private keys, and revealing your private key to anyone is not necessary to redeem the airdrop.

hs-airdrop is the only tool recommended for airdrop redemption. Use anything else at your own risk.

How It Works

The Handshake airdrop is a merkle tree whose root is added to the consensus rules of the Handshake protocol. This allows the owner of an eligible private key to publish a signed merkle proof on chain in order to redeem their airdrop. If your private key is not found by this tool in the merkle tree, you are not eligible to claim HNS coins. A blinding factor (or nonce) was generated for each recipient to allow recipients to claim their coins anonymously. For a detailed description of the airdrop tree construction process, read this comment.

Public keys from open source developers were collected in the following ways. If you are an open source developer that meets the requirements listed below you may be able to claim 4,246.994314 HNS from this airdrop:

There are a few gotchas:

Privacy

An airdrop to GitHub and PGP users presents an obvious privacy concern: GitHub and PGP keys are generally tied to a person's real identity. While impractical, a determined analyst could link an on-chain airdrop redemption to a person's identity.

To solve the privacy issue in a non-interactive way, a 32 byte nonce has been encrypted to your public key (you will have to grind a file full of many ciphertexts to find it). For EC keys, this nonce is treated as a scalar and is used to derive a new key from your old one. For RSA keys, a much more complicated setup is necessary. In either case, once your new key is derived using this nonce, you will be able to find its corresponding leaf in the merkle tree published above.

Publishing a signed airdrop proof using this method does not leak any information about your actual identity.

The full list of keys will be destroyed upon mainnet launch. Plaintext nonces are not saved at all during the generation phase. The ephemeral keys used for the ECIES key exchanges are also not saved.

NOTE: since block height 52590 (29 January, 2021) the goosig feature is DISABLED. Read the discussion here. If your airdrop key is RSA, you will have to claim with --bare (see below)

Security

If you're uncomfortable having third party software access your PGP and SSH keys, you are always able to generate this proof on an air-gapped machine. QR code generation will be added to this tool for convenience (eventually).

A community member created instructions for how to use Docker as a pseudo-airgap when claiming. These instructions may be helpful for you but have not been verified by project maintainers.

Fallback for HSMs

Not everyone keeps their SSH and PGP keys on their laptop. In the event that your key is not accessible by the signing tool, the signing tool can present you with the raw data needed to be signed. Your regular key is also included in the merkle tree (concatenated with a random nonce, seeded by the encrypted scalar to preserve privacy). Unfortunately, this will forgo the privacy preservation mechanism described above.

Accepted Key Algorithms

To simplify consensus implementation, we only allow the top 3 most popular key algorithms used on github:

Faucet Participants and Sponsors

This tool also allows for the creation of proofs for faucet recipients and sponsors. See the usage below for details.

Usage

If you are unfamiliar with sending blockchain transactions, you can learn what "transactions" are and what "fees" mean on bitcoin.org. The --fee argument sends an exact amount of HNS coins (default 0.1 HNS) to the Handshake network to include your claim into the blockchain. You will receive 4,246.994314 HNS coins (minus fee amount) to your address.

The passphrase requested during the claiming process is for decrypting your SSH/PGP key.

$ hs-airdrop -h

  hs-airdrop (v0.7.0)

  This tool will create the proof necessary to
  collect your faucet reward, airdrop reward, or
  sponsor reward on the Handshake blockchain.

  Usage: $ hs-airdrop [key-file] [id] [addr] [options]
         $ hs-airdrop [key-file] [addr] [options]
         $ hs-airdrop [addr]

  Options:

    -v, --version         output the version number
    -b, --bare            redeem airdrop publicly (i.e. without goosig)
    -f, --fee <amount>    set fee for redemption (default: 0.1)
    -d, --data <path>     data directory for cache (default: ~/.hs-tree-data)
    -h, --help            output usage information

  [key-file] can be:

    - An SSH private key file.
    - An exported PGP armor keyring (.asc).
    - An exported PGP raw keyring (.pgp/.gpg).

  [id] is only necessary for PGP keys.

  [addr] must be a Handshake bech32 address.

  The --bare flag will use your existing public key.
  This is not recommended as it makes you identifiable
  on-chain.

  This tool will provide a JSON representation of
  your airdrop proof as well as a base64 string.

  The base64 string must be passed to:
    $ hsd-rpc sendrawairdrop "base64-string"

  Examples:

    $ hs-airdrop ~/.gnupg/secring.gpg 0x12345678 hs1q5z7yyk8xrh4quqg3kw498ngy7hnd4sruqyxnxd -f 0.5
    $ hs-airdrop ~/.ssh/id_rsa hs1q5z7yyk8xrh4quqg3kw498ngy7hnd4sruqyxnxd -f 0.5
    $ hs-airdrop ~/.ssh/id_rsa hs1q5z7yyk8xrh4quqg3kw498ngy7hnd4sruqyxnxd -f 0.5 --bare
    $ hs-airdrop hs1q5z7yyk8xrh4quqg3kw498ngy7hnd4sruqyxnxd

Update: Since block height 52590 (29 January, 2021) the goosig feature is DISABLED.

Read the discussion here. If your airdrop key is RSA, you MUST generate your claim with --bare. Otherwise, you will get the error bad-goosig-disabled.

Notes

Note that if you ran hs-airdrop before mainnet, you will need to upgrade to the latest version of hs-airdrop and clear the cache (rm -rf ~/.hs-tree-data). The usual error thrown in this case is Invalid checksum: tree.bin.

The JSON returned by this tool will include your HNS address encoded as separate hash and version values. These values can be encoded back into an HNS address for verification before broadcast.

Users have occasionally reported issues downloading the tree data from GitHub. If you get an error like the following, you may just need to wait a few minutes and try again:

Attempting to create proof.
This may take a bit.
Decrypting nonce...
Downloading: https://github.com/handshake-org/hs-tree-data/raw/master/nonces/111.bin...
Error: Client network socket disconnected before secure TLS connection was established
at TLSSocket.onConnectEnd (_tls_wrap.js:1084:19)
at Object.onceWrapper (events.js:273:13)
at TLSSocket.emit (events.js:187:15)
at endReadableNT (_stream_readable.js:1085:12)
at process._tickCallback (internal/process/next_tick.js:63:19)

License

MIT License.

See LICENSE for more info.