Supply and Analytics

Value cannot appear from nowhere: every unit of a currency enters through a faucet wallet and leaves through a sink wallet or a hold capture. That discipline is what makes the analytics trustworthy. Everything on this page except the sink payment requires a platform admin token (or the treasury role).

Minting through a faucet

A faucet is a wallet of kind FAUCET (admin-created). Minting is an ordinary balanced transfer that debits the faucet - its balance goes negative - and credits a standard wallet:

FAUCET=wal_753da7921339b83190a3cb361a5643e3   # ids from wallets create
BUYER=wal_e625a4f3362f057632597e8fb5e52c2f
snug treasury transfer -d docs4-econ -k docs4-mint-1 \
  --debit $FAUCET:5000 --credit $BUYER:5000 --tag quest_reward

Debiting a faucet or sink wallet always requires admin. When the currency was created with --faucets-require-tag, an untagged transfer touching a system wallet is refused:

{
  "status": 400,
  "msg": "Missing required faucet/sink tag for transfer touching currency cur_gold",
  "error": "missing_faucet_tag"
}

Tag faucet and sink transfers with the reason (quest_reward, shop_purchase, ...) - the flow report below aggregates by exactly these tags.

Burning through a sink

A sink is a wallet of kind SINK. Crediting a sink needs no admin - only debit legs are permission-checked - so a regular user paying gold into a shop is just:

SINK=wal_0a3d1a5a25fce674b4a6b3741bcda013
snug treasury transfer -d docs4-econ -k docs4-shop-1 \
  --debit $BUYER:100 --credit $SINK:100 --tag shop_purchase

Verified: the sink credit shows up as burned supply and as a shop_purchase sink flow. Hold captures burn the same way, under the built-in hold_capture tag.

Supply caps

--max-supply bounds the circulating supply (minted minus burned), not the cumulative mint total, so burning frees room to mint again. A faucet transfer that would push circulating past the cap aborts whole - with circulating at 999650 of a 1000000 cap:

{
  "status": 409,
  "msg": "Supply cap exceeded for currency cur_gold",
  "error": "supply_cap_exceeded"
}

Supply counter

snug --output json treasury analytics supply -d docs4-econ -c cur_gold

{
  "currency_id": "cur_gold",
  "minted": 5000,
  "burned": 1300,
  "circulating": 3700
}

Captured live after one 5000 mint, hold captures of 700 and 500, and the 100 shop purchase: minted and burned are cumulative, circulating is their difference.

Flow report

Faucet and sink volume per tag over a trailing window (seconds; default 604800, one week), aggregated in one-hour buckets:

snug --output json treasury analytics flows -d docs4-econ -c cur_gold --window 3600

{
  "currency_id": "cur_gold",
  "window_seconds": 3600,
  "faucets": [{ "tag": "quest_reward", "total": 5000 }],
  "sinks": [
    { "tag": "hold_capture", "total": 1200 },
    { "tag": "shop_purchase", "total": 100 }
  ],
  "net_flow": 3700
}

A persistently positive net_flow is inflation: faucets are outrunning sinks.

Top holders

Ranked balances with a Gini-style concentration coefficient (0 = evenly spread, 1 = one wallet holds everything):

snug --output json treasury analytics top-holders -d docs4-econ -c cur_gold --limit 5

{
  "currency_id": "cur_gold",
  "holders": [
    {
      "rank": 1,
      "wallet_id": "wal_e625...c2f",
      "principal": { "kind": "auth_user", "id": "docs-wave" },
      "balance": 2500
    },
    {
      "rank": 2,
      "wallet_id": "wal_51eb...0e2",
      "principal": { "kind": "auth_user", "id": "docs4-other" },
      "balance": 1200
    }
  ],
  "concentration": 0.5657894736842105
}

System wallets rank too: the sink appears with what it has absorbed and the faucet at the bottom with its negative balance. The exact parameters for all three endpoints are in the Treasury API reference.