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.