QUACDocs

Tools

Faucet

The faucet hands out free testnet QUAC, 100 QUAC per claim. It has two parts:

  • quacfaucet (cmd/quacfaucet/main.go): a small HTTP service that runs next to a node and sends coins.
  • The faucet page (website/public/faucet/index.html): the form at quantcoin.world/faucet.

API

POST /claim     {"address":"quac1…"}
GET  /healthz   → "ok"
Response Meaning
200 {"txhash":"…","amount":"100 QUAC","address":"quac1…"} Sent. The coins arrive in the next block.
400 {"error":"that isn't a quac1... address"} Bad address or body
429 {"error":"already claimed recently; try again in 23h58m0s","retry_after":86280} Cooldown. A Retry-After header is set.
502 {"error":"the faucet couldn't send right now; try again shortly"} The node rejected or timed out the send

How it sends

The faucet doesn't reimplement transaction building. It calls quacd itself, so every payout is built, signed and broadcast by the same code users run:

cmd := exec.CommandContext(ctx, f.cfg.quacd, "tx", "bank", "send", f.cfg.from, to, f.cfg.amount,
    "--home", f.cfg.home, "--keyring-backend", f.cfg.keyring, "--chain-id", f.cfg.chainID,
    "--node", f.cfg.node, "--gas", "auto", "--gas-adjustment", "1.4", "--gas-prices", f.cfg.gasPrices,
    "--broadcast-mode", "sync", "--yes", "--output", "json")

The faucet account's key is an ML-DSA-65 key in the node's keyring, so every payout is a post-quantum transaction. A 45-second timeout bounds each send.

Sends are serialized with a mutex. One faucet account has one sequence number, and two concurrent sends would race for it.

Abuse limits

Address validation

func validAddress(addr string) bool {
    hrp, data, err := bech32.DecodeAndConvert(addr)
    return err == nil && hrp == "quac" && (len(data) == 20 || len(data) == 32)
}

The address must decode as Bech32 with the quac prefix and a valid checksum, and be 20 bytes (a key-derived account) or 32 bytes (a module or derived account). Request bodies are capped at 1 KB.

Cooldowns

A claim is refused if either the address or the client IP received a payout within the cooldown (24 hours by default). Both are recorded on every payout, and expired entries are dropped. The record is saved to a JSON file (-state) with a write-then-rename, so a restart doesn't reset cooldowns and a crash can't leave a half-written file.

Client IP behind the tunnel

On the testnet, requests reach the faucet through cloudflared on the same server, so the TCP peer is always 127.0.0.1. The faucet trusts forwarding headers only from a loopback peer:

if ip := net.ParseIP(host); ip != nil && ip.IsLoopback() {
    if cf := r.Header.Get("CF-Connecting-IP"); cf != "" { return cf }
    if xff := r.Header.Get("X-Forwarded-For"); xff != "" { return first(xff) }
}
return host

A client connecting directly can't spoof its IP with a header. The faucet listens on 127.0.0.1 anyway, so no client can connect directly.

CORS

Only the origins in -allow-origins (default https://quantcoin.world,https://www.quantcoin.world) get CORS headers, so other websites can't drive the faucet from visitors' browsers.

Flags

Flag Default Meaning
-listen 127.0.0.1:8000 HTTP address
-quacd /usr/local/bin/quacd Path to the node binary
-home /var/lib/quac/.quacd Node home with the faucet key
-keyring-backend test Keyring backend
-from faucet Key name to send from
-chain-id quac-testnet-1 Chain ID
-node tcp://127.0.0.1:26657 Local node RPC
-amount 100000000uquac Amount per claim (100 QUAC)
-gas-prices 0.0025uquac Fee price
-cooldown 24h Per-address and per-IP cooldown
-state /var/lib/quac/faucet-claims.json Cooldown record
-allow-origins https://quantcoin.world,https://www.quantcoin.world CORS allowlist

Running against a devnet

build/quacfaucet -listen 127.0.0.1:8001 -quacd build/quacd -home .devnet \
  -from alice -chain-id quac-devnet-1 -state ./claims.json \
  -allow-origins http://localhost:5180

Served from localhost, the faucet page calls http://127.0.0.1:8001/claim automatically.

Edit this page on GitHub