Testnet Faucet

The testnet faucet (ghost-faucet, port 3005) distributes GHOST tokens to developers and users on the Specter testnet. It dispenses 100 GHOST per request with a 24-hour cooldown per recipient address.

Overview

GHOST is the native gas token of the Specter chain. Without GHOST, users cannot submit transactions — including the reveal transactions that complete a Ghost Protocol flow. The faucet provides a frictionless way for new users and developers to obtain testnet GHOST for experimentation.

Current State

Metric	Value
Faucet balance	56.9M GHOST
Drip amount	100 GHOST
Cooldown period	24 hours per address

API

POST /drip

Sends 100 GHOST to the specified recipient address.

Request:

{
  "address": "0x1234567890abcdef1234567890abcdef12345678"
}

Response (success):

{
  "success": true,
  "txHash": "0xabc123...",
  "amount": "100",
  "recipient": "0x1234567890abcdef1234567890abcdef12345678"
}

Response (cooldown active):

{
  "error": "Address is in cooldown period",
  "nextAvailable": "2026-03-17T14:30:00Z",
  "remainingSeconds": 43200
}

Response (invalid address):

{
  "error": "Invalid Ethereum address"
}

GET /health

Returns faucet status and balance.

{
  "status": "healthy",
  "balance": "56900000",
  "dripAmount": "100",
  "cooldownHours": 24,
  "totalDrips": 1250,
  "uptime": 864000
}

Cooldown Mechanism

The faucet tracks the last drip timestamp for each recipient address in an in-memory map backed by periodic disk persistence. When a drip request arrives:

1. Look up the recipient address in the cooldown map.
2. If no entry exists, or the entry's timestamp is more than 24 hours old, proceed with the drip.
3. If the cooldown is still active, reject the request with the time remaining.
4. After a successful drip, update the cooldown map with the current timestamp.

The cooldown is enforced per recipient address, not per requesting IP. This means a single user cannot circumvent the cooldown by switching IP addresses (they would need a different wallet address).

Rate Limiting

In addition to the per-address cooldown, the faucet enforces global rate limits to prevent abuse:

Limit	Value
Global request rate	30 requests/minute
Per-IP request rate	5 requests/minute
Max payload size	1 KB

These limits protect the faucet from automated draining attacks where an adversary generates many fresh addresses to bypass the per-address cooldown.

Transaction Submission

The faucet submits native GHOST transfers using an operator wallet:

1. Construct a simple value transfer transaction to the recipient address with value = 100 * 10^18 (100 GHOST in wei).
2. Estimate gas and set a gas price based on current network conditions.
3. Sign the transaction with the operator private key.
4. Submit the transaction and return the transaction hash to the caller.

The faucet does not wait for transaction confirmation before responding — it returns the transaction hash immediately. The client can poll the chain for confirmation if needed.

Nonce Management

The faucet maintains a local nonce counter to handle rapid sequential drip requests without waiting for each transaction to be mined. This prevents nonce collision errors when multiple drip requests arrive within the same block time.

If a transaction fails due to a nonce mismatch (e.g., after a service restart), the faucet resynchronizes its nonce from the chain and retries.

Balance Monitoring

The faucet periodically checks its on-chain GHOST balance and logs warnings when the balance drops below configurable thresholds:

Threshold	Action
< 1,000,000 GHOST	Warning logged
< 100,000 GHOST	Alert logged, reduced drip amount considered
< 10,000 GHOST	Critical alert, faucet may pause drips

At the current drip rate of 100 GHOST per request with a 24-hour cooldown per address, the 56.9M GHOST balance is sufficient for hundreds of thousands of unique addresses.

Configuration

Parameter	Default	Description
PORT	3005	HTTP server port
RPC_URL	—	Specter chain RPC endpoint
OPERATOR_PRIVATE_KEY	—	Faucet operator wallet private key
DRIP_AMOUNT	100	GHOST tokens per drip (in whole units)
COOLDOWN_HOURS	24	Cooldown period between drips for the same address