Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,24 +1,27 @@
# Konstellation testnet-1 faucet — copy to .env (git-ignored) and fill in.
# Konstellation devnet-1 / testnet-1 faucet — copy to .env (git-ignored) and fill in.
# Every value is read from the environment; nothing is read from a file.

# --- required ---------------------------------------------------------------
# 32-byte hex private key of the faucet account (the testnet "liquidity"
# 32-byte hex private key of the faucet account (this network's "liquidity"
# bucket, TOKENOMICS.md §7 / ENGINEERING.md §18). Inject as a secret in
# deployment; never commit it. The public dev0 key below works ONLY against a
# local `./local_node.sh` chain (chain id 56670).
FAUCET_PRIVATE_KEY=
# Ethereum JSON-RPC endpoint of a testnet-1 node (the infra RPC node, not a validator).
RPC_URL=https://rpc.testnet-1.konstellation.network
# Ethereum JSON-RPC endpoint of a node on the faucet's network (the infra RPC
# node, not a validator).
RPC_URL=https://rpc.devnet-1.konstellation.network

# --- chain --------------------------------------------------------------------
# EIP-155 id. Default 56671 = testnet-1. 56670 = local dev chain. 5667 (mainnet) is refused.
CHAIN_ID=56671
# Human name shown on the page. Defaults to "testnet-1" for 56671.
#NETWORK_NAME=testnet-1
# EIP-155 id. One deployment per network. Default 56672 = devnet-1, the primary
# faucet (dapp developers). 56671 = testnet-1 (validator/ops rehearsal).
# 56670 = local dev chain. 5667 (mainnet) is refused.
CHAIN_ID=56672
# Human name shown on the page. Defaults to "devnet-1" / "testnet-1" / "local".
#NETWORK_NAME=devnet-1
#BECH32_PREFIX=kons

# --- payout policy ------------------------------------------------------------
# KASH per request. Default 10 (placeholder until a real testnet-1 policy is set);
# KASH per request. Default 10 (placeholder until a real devnet-1/testnet-1 policy is set);
# hard-capped at 1000 by the service regardless of this value.
AMOUNT_KASH=10
# Per-address and per-IP cooldown, seconds. Default 86400 (24 h).
Expand Down Expand Up @@ -50,9 +53,9 @@ TRUST_PROXY=false
#LOOKUP_WINDOW_SECONDS=3
# The origin the page is served from. Only needed when the proxy rewrites Host
# and sends no X-Forwarded-Host; otherwise the request Host is enough.
#PUBLIC_ORIGIN=https://faucet.testnet-1.konstellation.network
#PUBLIC_ORIGIN=https://faucet.devnet-1.konstellation.network
# Explorer link template for the result, "{hash}" is replaced.
#EXPLORER_TX_URL=https://explorer.testnet-1.konstellation.network/tx/{hash}
#EXPLORER_TX_URL=https://explorer.devnet-1.konstellation.network/tx/{hash}

# --- rate-limit store ---------------------------------------------------------
# memory (default, single replica) or redis (shared across replicas; needs an
Expand Down
2 changes: 1 addition & 1 deletion CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
* @defidevrel @Evangel90 @Levi-Ojukwu @OlolaJaco @Psalmuel01

# The send path and the blocked-recipient list are where a bug spends the
# testnet liquidity bucket or sends it somewhere unspendable. Same owners,
# devnet/testnet liquidity bucket or sends it somewhere unspendable. Same owners,
# listed separately so a stricter rule (e.g. two reviewers) can be attached
# without touching the catch-all above. CODEOWNERS is last-match-wins.
/src/sender.ts @defidevrel @Evangel90 @Levi-Ojukwu @OlolaJaco @Psalmuel01
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Konstellation testnet-1 faucet. Deployment image only — this repo produces
# Konstellation devnet-1 / testnet-1 faucet. Deployment image only — this repo produces
# no release binary (ENGINEERING.md §5: `konstellation` is the one repo that
# does). The faucet key is NOT baked in: pass FAUCET_PRIVATE_KEY at runtime
# as a secret (see README.md "Key handling").
Expand Down
36 changes: 24 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,25 @@
# faucet

Token faucet for **Konstellation testnet-1**. Sends a fixed amount of test KASH
to an address, once per address and once per IP per cooldown.
Token faucet for the Konstellation test networks. Sends a fixed amount of test
KASH to an address, once per address and once per IP per cooldown.

**Testnet-only.** `ENGINEERING.md §18`: "Faucet — required (`faucet` repo) /
does not exist on mainnet". The service refuses to start with `CHAIN_ID=5667`
(konstellation-1). The account it spends from is the testnet "liquidity"
bucket of the genesis allocation (`TOKENOMICS.md §7`, `ENGINEERING.md §18`),
which on testnet-1 is a test address with no value behind it.
**Which network.** There are two faucet deployments, one per network, from the
same code (decided 2026-09-29):

| Network | `CHAIN_ID` | Role |
|---|---|---|
| **devnet-1** | `56672` (default) | **the primary faucet** — devnet-1 is where dapp developers start: one foundation-run validator, same release as mainnet, rarely reset |
| testnet-1 | `56671` | validator/operations rehearsal network (upgrade drills, chaos tests, D16 admissions); new releases land here first and it may be disrupted. Kept for operators and anyone rehearsing an upgrade |

Point dapp developers at the devnet-1 faucet. Each deployment has its own
key, funded by its own network's genesis allocation.

**Never on mainnet.** `ENGINEERING.md §18`: "Faucet — required (`faucet`
repo) / does not exist on mainnet". The service refuses to start with
`CHAIN_ID=5667` (konstellation-1). The account it spends from is the
"liquidity" bucket of that network's genesis allocation (`TOKENOMICS.md §7`,
`ENGINEERING.md §18`), which on devnet-1 and testnet-1 is a test address with
no value behind it.

This repo is a service, not a binary: `konstellation` is the only repo that
produces an executable (`ENGINEERING.md §5`). It ships as TypeScript run by
Expand Down Expand Up @@ -89,14 +101,14 @@ that matter:
| Variable | Default | |
|---|---|---|
| `FAUCET_PRIVATE_KEY` | — (required) | 32-byte hex. **Secret. Never in a file in this repo.** |
| `RPC_URL` | — (required) | Ethereum JSON-RPC of a testnet-1 RPC node |
| `CHAIN_ID` | `56671` | testnet-1. `56670` = local dev chain. `5667` refused. Startup also checks `eth_chainId` against it and refuses to start on a mismatch. |
| `AMOUNT_KASH` | `10` | **placeholder** until a testnet-1 payout policy is decided. Hard-capped at 1 000 by the service. |
| `RPC_URL` | — (required) | Ethereum JSON-RPC of an RPC node on the faucet's network (devnet-1 or testnet-1) |
| `CHAIN_ID` | `56672` | devnet-1 (the primary faucet). `56671` = testnet-1, `56670` = local dev chain. `5667` refused. Startup also checks `eth_chainId` against it and refuses to start on a mismatch. |
| `AMOUNT_KASH` | `10` | **placeholder** until a devnet-1 / testnet-1 payout policy is decided. Hard-capped at 1 000 by the service. |
| `COOLDOWN_SECONDS` | `86400` | per address *and* per IP |
| `LOW_BALANCE_KASH` | `100 × AMOUNT_KASH` | `/healthz` reports `degraded` below this |
| `PORT` / `HOST` | `8080` / `0.0.0.0` | |
| `ALLOWED_ORIGINS` | empty | comma-separated origins for cross-origin API calls. The built-in page is same-origin and needs none. A `POST` carrying any other `Origin` is refused (403). `*` is refused unless `NODE_ENV=development`. |
| `PUBLIC_ORIGIN` | — | the origin the page is served from, e.g. `https://faucet.testnet-1.konstellation.network`. Needed only when the proxy rewrites `Host` and does not send `X-Forwarded-Host` (with `TRUST_PROXY` the first `X-Forwarded-Host` entry is also accepted); otherwise "own origin" is judged by the request `Host`. |
| `PUBLIC_ORIGIN` | — | the origin the page is served from, e.g. `https://faucet.devnet-1.konstellation.network`. Needed only when the proxy rewrites `Host` and does not send `X-Forwarded-Host` (with `TRUST_PROXY` the first `X-Forwarded-Host` entry is also accepted); otherwise "own origin" is judged by the request `Host`. |
| `TRUST_PROXY` | `false` | take the client IP from `X-Forwarded-For` — but only for connections whose socket peer is inside `TRUSTED_PROXY_CIDRS`. Any other peer is treated as the client itself and a warning is logged once per peer, so a directly reachable port cannot be spoofed. |
| `TRUSTED_PROXY_CIDRS` | — (required with `TRUST_PROXY`) | comma-separated IPs/CIDRs of the proxies, e.g. `172.16.0.0/12`. Startup refuses `TRUST_PROXY=true` without it. |
| `TRUSTED_PROXY_HOPS` | `1` | how many proxies append to `X-Forwarded-For`; the client is that many entries from the *right* (everything further left is client-supplied and ignored). A non-IP in that slot is a 400. |
Expand Down Expand Up @@ -161,7 +173,7 @@ sentry.

Checklist before it is public:

- [ ] a dedicated faucet key, funded from the testnet liquidity bucket
- [ ] a dedicated faucet key **per network** (devnet-1, testnet-1), each funded from that network's liquidity bucket
- [ ] `CAPTCHA_PROVIDER` on, keys set (the service will not start publicly without it)
- [ ] `TRUST_PROXY=true` only if the proxy sets `X-Forwarded-For`, with `TRUSTED_PROXY_CIDRS` = the proxy's addresses and `TRUSTED_PROXY_HOPS` = the number of proxies in front; `PUBLIC_ORIGIN` if it rewrites `Host` without `X-Forwarded-Host`
- [ ] `ALLOWED_ORIGINS` set only if `docs` or another site will call the API directly
Expand Down
5 changes: 3 additions & 2 deletions docker-compose.example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
# cp .env.example .env && $EDITOR .env # set FAUCET_PRIVATE_KEY, RPC_URL, ...
# docker compose -f docker-compose.example.yml up -d --build
#
# Testnet-only (ENGINEERING.md §18): there is no faucet on konstellation-1 and
# the service refuses CHAIN_ID=5667 at startup.
# Test networks only (ENGINEERING.md §18): run one copy per network — devnet-1
# (CHAIN_ID=56672, the primary faucet) and testnet-1 (56671), each with its own
# key. There is no faucet on konstellation-1; the service refuses CHAIN_ID=5667.

services:
faucet:
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "@konstellation-network/faucet",
"version": "0.1.0",
"private": true,
"description": "Konstellation testnet-1 KASH faucet (testnet-only, ENGINEERING.md §18)",
"description": "Konstellation devnet-1 / testnet-1 KASH faucet (test networks only, ENGINEERING.md §18)",
"license": "Apache-2.0",
"type": "module",
"engines": {
Expand Down
20 changes: 16 additions & 4 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,21 @@ import { parseEther } from "viem";
import { parseCidr, type Cidr } from "./ip.ts";

export const MAINNET_CHAIN_ID = 5667; // ENGINEERING.md §1 — the faucet must never run here
export const TESTNET_CHAIN_ID = 56671;
export const DEVNET_CHAIN_ID = 56672; // devnet-1 — the primary faucet (dapp developers)
export const TESTNET_CHAIN_ID = 56671; // testnet-1 — validator/ops rehearsal network
export const LOCAL_CHAIN_ID = 56670;

/**
* Display names of the networks a faucet may run on (ENGINEERING.md §1, §18).
* One deployment serves one network, selected by CHAIN_ID; devnet-1 and
* testnet-1 each get their own deployment, key and genesis allocation.
*/
export const KNOWN_NETWORKS: Readonly<Record<number, string>> = Object.freeze({
[DEVNET_CHAIN_ID]: "devnet-1",
[TESTNET_CHAIN_ID]: "testnet-1",
[LOCAL_CHAIN_ID]: "local",
});

/**
* Ceiling on AMOUNT_KASH. Not a policy number — a guard against a fat-fingered
* env var (e.g. an esp value pasted where KASH was meant) draining the
Expand Down Expand Up @@ -105,10 +117,10 @@ export function loadConfig(env: Env = process.env): FaucetConfig {
const rpcUrl = str(env, "RPC_URL");
if (!/^https?:\/\//.test(rpcUrl)) throw new ConfigError("RPC_URL must be an http(s) URL");

const chainId = int(env, "CHAIN_ID", TESTNET_CHAIN_ID, 1, 2 ** 32);
const chainId = int(env, "CHAIN_ID", DEVNET_CHAIN_ID, 1, 2 ** 32);
if (chainId === MAINNET_CHAIN_ID) {
// ENGINEERING.md §18: the faucet does not exist on konstellation-1.
throw new ConfigError(`CHAIN_ID ${MAINNET_CHAIN_ID} is konstellation-1 (mainnet); the faucet is testnet-only`);
throw new ConfigError(`CHAIN_ID ${MAINNET_CHAIN_ID} is konstellation-1 (mainnet); the faucet is testnet-only (devnet-1, testnet-1)`);
}

const amountKash = str(env, "AMOUNT_KASH", "10");
Expand Down Expand Up @@ -226,7 +238,7 @@ export function loadConfig(env: Env = process.env): FaucetConfig {
redisUrl,
captcha: { provider: captchaProvider, secret: captchaSecret, siteKey: captchaSiteKey },
allowNoCaptcha,
networkName: str(env, "NETWORK_NAME", chainId === TESTNET_CHAIN_ID ? "testnet-1" : `chain ${chainId}`),
networkName: str(env, "NETWORK_NAME", KNOWN_NETWORKS[chainId] ?? `chain ${chainId}`),
explorerTxUrl: env["EXPLORER_TX_URL"]?.trim() || undefined,
};
}
Expand Down
2 changes: 1 addition & 1 deletion src/page.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ ${captchaScript}
<button id="go" type="submit">Request ${esc(o.amountKash)} KASH</button>
</form>
<div id="result" role="status" aria-live="polite"></div>
<footer>Testnet only — there is no faucet on konstellation-1. Status: <a href="/healthz">/healthz</a>.</footer>
<footer>Devnet and testnet only — there is no faucet on konstellation-1 (mainnet). Status: <a href="/healthz">/healthz</a>.</footer>
</main>
<script id="cfg" type="application/json">${cfg.replace(/</g, "\\u003c")}</script>
<script src="/app.js"></script>
Expand Down
15 changes: 13 additions & 2 deletions test/config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ const CIDRS = { TRUSTED_PROXY_CIDRS: "10.0.0.0/8" };
describe("loadConfig", () => {
it("applies the documented defaults", () => {
const c = loadConfig(base);
expect(c.chainId).toBe(56671);
expect(c.chainId).toBe(56672);
expect(c.amountKash).toBe("10");
expect(c.amountWei).toBe(parseEther("10"));
expect(c.cooldownSeconds).toBe(86_400);
Expand All @@ -19,7 +19,7 @@ describe("loadConfig", () => {
expect(c.trustProxy).toBe(false);
expect(c.rateLimitStore).toBe("memory");
expect(c.captcha.provider).toBe("off");
expect(c.networkName).toBe("testnet-1");
expect(c.networkName).toBe("devnet-1");
expect(c.bech32Prefix).toBe("kons");
});

Expand All @@ -38,6 +38,17 @@ describe("loadConfig", () => {
expect(loadConfig({ ...base, CHAIN_ID: "56670" }).chainId).toBe(56670);
});

it("serves devnet-1 (primary) and testnet-1, one network per deployment", () => {
const dev = loadConfig({ ...base, CHAIN_ID: "56672" });
expect(dev.chainId).toBe(56672);
expect(dev.networkName).toBe("devnet-1");
const test = loadConfig({ ...base, CHAIN_ID: "56671" });
expect(test.chainId).toBe(56671);
expect(test.networkName).toBe("testnet-1");
expect(loadConfig({ ...base, CHAIN_ID: "56670" }).networkName).toBe("local");
expect(loadConfig({ ...base, CHAIN_ID: "56671", NETWORK_NAME: "rehearsal" }).networkName).toBe("rehearsal");
});

it("caps the per-request amount", () => {
expect(() => loadConfig({ ...base, AMOUNT_KASH: "1001" })).toThrow(/hard cap/);
expect(() => loadConfig({ ...base, AMOUNT_KASH: "10000000000000000000" })).toThrow(/hard cap/);
Expand Down
Loading