HNS-Circulating-Coin-Supply.md

What is the coin supply of HNS at this moment?

$ hsd-cli info | jq .chain.state
{
  "tx": 1498491,
  "coin": 987885,
  "value": 307706949499305,
  "burned": 8282032802881
}

What this means is that the CIRCULATING supply of HNS is 307,706,949.499305 HNS ("value" in the above JSON). These are coins that are liquid, spendable, useable, controllable, etc. Although we'll see later this is not entirely real. But it is correct as far as the blockchain consensus rules is concerned.

The "burned" value is the amount of coins that are permanently locked by auction winners when they REGISTER a name. It's important to note that if a user wins an auction but never sends a REGISTER, the value of that name is not considered by the blockchain to be burned. It will never be spendable in any other context however so the coins are effectively burned, but they are not officially burned until that REGISTER covenant is confirmed. There is no time limit or deadline on when a REGISTER must be sent, however it is the REGISTER that also refunds the auction winner the difference between their bid and the second-highest bid. The second-highest bid is the official value of the name, and is the value that is burned.

value and burned are mutually exclusive

This means that the TOTAL SUPPLY of HNS is value + burned = 315,988,982.302186 HNS

This is the number that will ultimately approach MAX_MONEY, which in Handshake is 2,040,000,000 HNS

test

Using a regtest blockchain, we will generate 100 blocks to fund a wallet, open a name, send two equal bids, send the reveals, send the redeem and the register, and then check the chain statistics:

// START: genesis block only
hsd-cli info | jq .chain.state
{
  "tx": 1,
  "coin": 1,
  "value": 2002210000,
  "burned": 0
}

// generate 100 blocks
{
  "tx": 101,
  "coin": 101,
  "value": 202002210000,
  "burned": 0
}

// send open
// generate 10 blocks
{
  "tx": 112,
  "coin": 112,
  "value": 222002210000,
  "burned": 0
}

// send bid 100 200
// send bid 100 200
// generate 10 blocks
{
  "tx": 124,
  "coin": 124,
  "value": 242002210000,
  "burned": 0
}

// sendreveal
// generate 10 blocks
{
  "tx": 135,
  "coin": 135,
  "value": 262002210000,
  "burned": 0
}

// sendredeem
// sendupdate []
// generate 10 blocks
{
  "tx": 147,
  "coin": 145,
  "value": 281902210000,
  "burned": 100000000
}

These last two measurements are critical.

We start with a "value" of 262,002.210000 HNS, then generate 10 blocks (which adds 10 * 2000 HNS).

The new total should be:

(2000.000000 * 10) + 262002.210000 = 282002.210000

But it's not -- because the REGISTER has MOVED 100 HNS from "value" to "burned":

(2000.000000 * 10) + 262002.210000 - 100.000000 = 281902.210000

Caveats

The circulating supply aka "value" described here does not take into account BIDs that were not REVEALed. These coins are also permanently unspendable, but in this case it is more like someone losing their private keys -- the coins are there, sure, but they are never going to move.

Further reading

ChainDB "burned" value could be improved (hsd issue #380)

Read through chaindb.js connectBlock() where all TX inputs and outputs of a block are processed and covenant values are added or subtracted from the different properties of the ChainState